# Wire Type Reference

```ts
/** Online state for an agent based on heartbeat recency. */
export type AgentStatus = 'idle' | 'busy' | 'suspended' | 'offline';

/** Agent identity and profile. */
export interface Agent {
  /** Full stable ID: name@owner. */
  agentId: string;
  /** Owner namespace. */
  owner: string;
  /** Optional display label. */
  displayName?: string | null;
  /** Optional summary text. */
  description?: string | null;
  /** Optional signing public key. */
  publicKey?: string | null;
  /** Optional encryption public key. */
  encryptionPublicKey?: string | null;
  /** Liveness state. */
  status: AgentStatus;
  /** Derived online indicator from heartbeat. */
  online: boolean;
  /** Last heartbeat timestamp (ISO8601). */
  lastSeenAt?: string | null;
  /** Whether agent record is active. */
  active: boolean;
  /** Agent capability declarations. */
  capabilities?: Capability[];
  /** Created timestamp (ISO8601). */
  createdAt: string;
  /** Updated timestamp (ISO8601). */
  updatedAt: string;
}

/** Health summary used for dashboards and auto-remediation. */
export interface AgentHealth {
  /** Current status enum. */
  status: AgentStatus;
  /** Whether agent is considered online. */
  online: boolean;
  /** Last seen timestamp. */
  lastSeen?: string | null;
  /** Number of active tasks assigned. */
  activeTasks: number;
  /** 24h error ratio between 0 and 1. */
  errorRate24h: number;
  /** Unacknowledged alert count. */
  alertCount: number;
}

/** Lifecycle status for tasks. */
export type TaskStatus =
  | 'pending'
  | 'assigned'
  | 'running'
  | 'awaiting_approval'
  | 'done'
  | 'failed'
  | 'cancelled';

/** Task object returned by task endpoints. */
export interface Task {
  /** Unique task ID. */
  id: string;
  /** Human-readable title. */
  title: string;
  /** Optional task description. */
  description?: string | null;
  /** Lifecycle state. */
  status: TaskStatus;
  /** Priority from 1-10. */
  priority: number;
  /** Assigned agent ID if assigned. */
  assignedTo?: string | null;
  /** Actor that created the task. */
  createdBy: string;
  /** Creator kind (human/agent/system). */
  creatorType: string;
  /** Owner namespace for routing and policy checks. */
  ownerId: string;
  /** Pipeline run ID when task belongs to a pipeline run. */
  pipelineRunId?: string | null;
  /** Pipeline step index when task belongs to a pipeline run. */
  pipelineStep?: number | null;
  /** Parent task for spawned sub-task chains. */
  parentTaskId?: string | null;
  /** Input payload. */
  input: Record<string, unknown>;
  /** Output payload when completed. */
  output?: Record<string, unknown> | null;
  /** Failure reason for failed tasks. */
  error?: string | null;
  /** Optional due epoch millis. */
  dueAt?: number | null;
  /** Start timestamp epoch millis. */
  startedAt?: number | null;
  /** Completion timestamp epoch millis. */
  completedAt?: number | null;
  /** Created timestamp epoch millis. */
  createdAt: number;
  /** Updated timestamp epoch millis. */
  updatedAt: number;
}

/** DTO for creating a task. */
export interface CreateTaskDto {
  /** Task title. */
  title: string;
  /** Optional details. */
  description?: string;
  /** Priority (1-10). */
  priority?: number;
  /** Agent ID to assign immediately. */
  assignTo?: string;
  /** Input payload for assignee. */
  input?: Record<string, unknown>;
  /** Optional due timestamp (epoch millis). */
  dueAt?: number;
  /** Capability to execute (policy aware). */
  capability?: string;
}

/** DTO used when marking a task complete. */
export interface CompleteTaskDto {
  /** Structured output emitted by the assignee. */
  output: Record<string, unknown>;
}

/********************************
 * Pipelines
 ********************************/

/** One pipeline definition. */
export interface Pipeline {
  /** Pipeline ID. */
  id: string;
  /** Owner-defined pipeline name. */
  name: string;
  /** Optional description. */
  description?: string | null;
  /** Owner namespace. */
  ownerId: string;
  /** Ordered step list. */
  steps: PipelineStep[];
  /** Created timestamp (epoch millis). */
  createdAt: number;
  /** Updated timestamp (epoch millis). */
  updatedAt: number;
}

/** One executable pipeline step. */
export interface PipelineStep {
  /** Step index (0-based). */
  index: number;
  /** Assigned agent for this step. */
  agentId: string;
  /** Step title. */
  title: string;
  /** Optional step description. */
  description?: string;
  /** Optional input mapping paths. */
  inputMapping?: Record<string, string>;
}

/** Runtime for one pipeline execution. */
export interface PipelineRun {
  /** Run ID. */
  id: string;
  /** Source pipeline ID. */
  pipelineId: string;
  /** Runtime status. */
  status: 'running' | 'done' | 'failed';
  /** Current step index pointer. */
  currentStep: number;
  /** Mutable run context. */
  context: Record<string, unknown>;
  /** Start timestamp (epoch millis). */
  startedAt: number;
  /** Completion timestamp if ended. */
  completedAt?: number | null;
  /** Created timestamp (epoch millis). */
  createdAt: number;
}

/********************************
 * Approvals
 ********************************/

/** Approval workflow status. */
export type ApprovalStatus = 'pending' | 'approved' | 'rejected';

/** Approval request record. */
export interface Approval {
  /** Approval ID. */
  id: string;
  /** Requesting agent. */
  agentId: string;
  /** Optional linked task ID. */
  taskId?: string | null;
  /** Action label (deploy/delete/etc). */
  action: string;
  /** Human-facing description. */
  description: string;
  /** Arbitrary metadata payload. */
  metadata: Record<string, unknown>;
  /** Decision status. */
  status: ApprovalStatus;
  /** Owner namespace that must decide. */
  ownerId: string;
  /** Decider ID when resolved. */
  decidedBy?: string | null;
  /** Decision timestamp when resolved. */
  decidedAt?: number | null;
  /** Created timestamp. */
  createdAt: number;
  /** Updated timestamp. */
  updatedAt: number;
}

/********************************
 * Events
 ********************************/

/** Event published into the topic bus. */
export interface Event {
  /** Event ID. */
  id: string;
  /** Topic key (supports wildcard subscriptions). */
  topic: string;
  /** Event payload. */
  payload: Record<string, unknown>;
  /** Publisher agent ID. */
  publisherAgentId: string;
  /** Creation timestamp. */
  createdAt: number;
  /** Optional expiration timestamp. */
  expiresAt?: number | null;
}

/** Topic subscription mapping for one agent. */
export interface Subscription {
  /** Subscription ID. */
  id: string;
  /** Subscriber agent ID. */
  agentId: string;
  /** Topic pattern. */
  topic: string;
  /** Creation timestamp. */
  createdAt: number;
}

/********************************
 * Scheduling
 ********************************/

/** Scheduled task template executed by cron. */
export interface ScheduledJob {
  /** Job ID. */
  id: string;
  /** Job name. */
  name: string;
  /** Cron expression. */
  cronExpr: string;
  /** Agent assigned when triggered. */
  agentId: string;
  /** Task template used per trigger. */
  taskTemplate: Record<string, unknown>;
  /** Enabled switch. */
  enabled: boolean;
  /** Owner namespace. */
  ownerId: string;
  /** Last run timestamp. */
  lastRunAt?: number | null;
  /** Next run timestamp. */
  nextRunAt?: number | null;
  /** Created timestamp. */
  createdAt: number;
  /** Updated timestamp. */
  updatedAt: number;
}

/********************************
 * Context
 ********************************/

/** One lineage write record for context mutation history. */
export interface LineageEntry {
  /** Mutation timestamp. */
  at: number;
  /** Actor type (agent/human/system). */
  actorType: string;
  /** Actor ID. */
  actorId: string;
  /** Version created by this mutation. */
  version: number;
}

/** One scoped context entry. */
export interface ContextEntry {
  /** Stable ID for storage row. */
  id: string;
  /** Scope key (`shared` or `agent:<id>`). */
  scope: string;
  /** Context key. */
  key: string;
  /** Structured value. */
  value: Record<string, unknown>;
  /** Full lineage history. */
  lineage: LineageEntry[];
  /** Monotonic version. */
  version: number;
  /** Created timestamp. */
  createdAt: number;
  /** Updated timestamp. */
  updatedAt: number;
}

/********************************
 * Alerts
 ********************************/

/** Alert category. */
export type AlertType = 'task_failed' | 'offline' | 'approval_timeout' | string;

/** Alert generated by agents/system. */
export interface Alert {
  /** Alert ID. */
  id: string;
  /** Related agent. */
  agentId: string;
  /** Alert type. */
  type: AlertType;
  /** Alert message. */
  message: string;
  /** Additional structured data. */
  metadata: Record<string, unknown>;
  /** Ack flag. */
  acknowledged: boolean;
  /** Owner namespace receiving alert. */
  ownerId: string;
  /** Created timestamp. */
  createdAt: number;
}

/********************************
 * Capability + policy
 ********************************/

/** Capability descriptor for an agent skill. */
export interface Capability {
  /** Capability row ID. */
  id?: string;
  /** Agent owning this capability. */
  agentId?: string;
  /** Capability name (unique per agent). */
  name: string;
  /** Optional free text description. */
  description?: string | null;
  /** Optional JSON schema for input payload. */
  inputSchema?: Record<string, unknown> | null;
  /** Optional JSON schema for output payload. */
  outputSchema?: Record<string, unknown> | null;
  /** Created timestamp. */
  createdAt?: number;
  /** Updated timestamp. */
  updatedAt?: number;
}

/** Policy rule controlling one capability. */
export interface Policy {
  /** Policy row ID. */
  id?: string;
  /** Agent ID policy applies to. */
  agentId: string;
  /** Capability name. */
  capability: string;
  /** Whether execution is allowed. */
  allowed: boolean;
  /** Whether human approval is required first. */
  requiresApproval: boolean;
  /** Created timestamp. */
  createdAt?: number;
  /** Updated timestamp. */
  updatedAt?: number;
}

/********************************
 * Sessions + KB
 ********************************/

/** Runtime session for logging an agent execution window. */
export interface Session {
  /** Session ID. */
  id: string;
  /** Agent ID owning session. */
  agentId: string;
  /** Running/ended state. */
  status: 'running' | 'ended';
  /** Optional linked task ID. */
  taskId?: string | null;
  /** Aggregated plain text log. */
  log: string;
  /** Start timestamp. */
  startedAt: number;
  /** End timestamp if ended. */
  endedAt?: number | null;
  /** Created timestamp. */
  createdAt: number;
}

/** Knowledge-base entry. */
export interface KbEntry {
  /** Entry ID. */
  id: string;
  /** Namespace for multi-tenant partitioning. */
  namespace: string;
  /** Visibility scope (`private` or shared). */
  scope: string;
  /** Entry key. */
  key: string;
  /** Entry value text. */
  value: string;
  /** Monotonic version number. */
  version: number;
  /** Optional expiry timestamp. */
  expiresAt?: string | null;
  /** Creator agent/human ID. */
  createdBy: string;
  /** Created timestamp (ISO8601). */
  createdAt: string;
  /** Updated timestamp (ISO8601). */
  updatedAt: string;
}

/** Message envelope for inbox/stream APIs. */
export interface Message {
  /** Message ID. */
  id: string;
  /** Sender agent ID. */
  sender: string;
  /** Recipient agent ID. */
  recipient: string;
  /** Ciphertext or plaintext payload string. */
  encryptedPayload: string;
  /** Optional expiry timestamp. */
  expiresAt?: string | null;
  /** Delivery timestamp. */
  deliveredAt?: string | null;
  /** Read timestamp when acknowledged. */
  readAt?: string | null;
  /** Created timestamp. */
  createdAt: string;
  /** Thread correlation ID. */
  threadId?: string | null;
  /** Reply target message ID. */
  replyTo?: string | null;
  /** Message type discriminator. */
  messageType: string;
}

/********************************
 * Trust + metrics + activity
 ********************************/

/** Trust relationship between two agents. */
export interface TrustGrant {
  /** Grant row ID. */
  id: number;
  /** Agent granting trust. */
  grantor: string;
  /** Agent receiving trust. */
  grantee: string;
  /** Trust level. */
  level: 'trusted' | string;
  /** Grant timestamp. */
  grantedAt: string;
  /** Revoke timestamp when revoked. */
  revokedAt?: string | null;
}

/** Owner-level aggregated metrics. */
export interface Metrics {
  /** Number of active agents (online + active). */
  activeAgents: number;
  /** Total registered agents. */
  totalAgents: number;
  /** Pending task count. */
  pendingTasks: number;
  /** Running task count. */
  runningTasks: number;
  /** Pending approvals count. */
  pendingApprovals: number;
  /** Unacknowledged alert count. */
  unacknowledgedAlerts: number;
  /** 24h completed task count. */
  completedTasks24h: number;
  /** 24h failed task count. */
  failedTasks24h: number;
}

/** Immutable audit record for operations. */
export interface ActivityLog {
  /** Log ID. */
  id: string;
  /** Event type (`task.created`, `agent.suspended`, etc). */
  type: string;
  /** Actor type (human/agent/system). */
  actorType: string;
  /** Actor identifier. */
  actorId: string;
  /** Optional target object type. */
  targetType?: string | null;
  /** Optional target object ID. */
  targetId?: string | null;
  /** Structured event metadata. */
  metadata: Record<string, unknown>;
  /** Event timestamp. */
  createdAt: number;
}
```