# TypeScript data types

Complete public input, result, event and configuration fields.

These declarations come from the shipped SDK. Optional fields and defaults are explicit in the declarations; required fields must be supplied. Server-generated fields describe responses and should not be invented by clients.

## Target



```typescript
export type Target = {
  kind: "person" | "agent" | "service" | "group" | "instance";
  id: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `kind` | `"person" \| "agent" \| "service" \| "group" \| "instance"` | Resource or operation kind. Use one of the listed values, not a display label. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |

## Person



```typescript
export type Person = {
  id: string;
  name: string;
  external_id: string;
  metadata: Record<string, unknown>;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `external_id` | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `metadata` | `Record<string, unknown>` | Application-supplied JSON metadata. Do not put credentials here. |

## Agent



```typescript
export type Agent = {
  id: string;
  name: string;
  external_id: string;
  metadata: Record<string, unknown>;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `external_id` | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `metadata` | `Record<string, unknown>` | Application-supplied JSON metadata. Do not put credentials here. |

## Action



```typescript
export type Action = {
  name: string;
  executor_id: string;
  resource: string;
  resource_version: string;
  arguments: Record<string, unknown>;
  operation_key: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `executor_id` | `string` | Identity allowed to redeem the exact approved action. |
| `resource` | `string` | Customer-defined resource identifier. The engine does not control the external resource. |
| `resource_version` | `string` | Customer-defined version fence that the external tool must also enforce. |
| `arguments` | `Record<string, unknown>` | JSON action arguments covered by the exact approval binding. |
| `operation_key` | `string` | Stable identity of the external business operation, separate from the HTTP retry key. |

## Response



```typescript
export type Response = {
  outcome:
    | "answered"
    | "approved"
    | "denied"
    | "completed"
    | "failed"
    | "rejected";
  answer?: unknown;
  version: number;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `outcome` | `"answered" \| "approved" \| "denied" \| "completed" \| "failed" \| "rejected"` | Typed final result: answered; approved/denied; or completed/failed/rejected according to request kind. |
| `answer` | `unknown` (optional) | JSON response value; for choices, the selected exact string. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |

## RequestItem



```typescript
export type RequestItem = {
 attachments?:Attachment[];
 mentions?:Mention[];
 blocking?:boolean;
  requester_instance_id?: string;
  id: string;
  requester_id: string;
  conversation_id: string;
  kind: "question" | "approval" | "task";
  title: string;
  body: string;
  choices: string[];
  action?: Action;
  state: "open" | "resolved" | "cancelled" | "expired" | "superseded";
  version: number;
  response?: Response & {
    responder_instance_id?: string;
    source_answer_id?: string;
    source_invalidated?: boolean;
    reuse_method?: string;
    reuse_reason?: string;
  };
  expires_at: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `attachments` | `Attachment[]` (optional) | Currently visible attachment metadata. |
| `mentions` | `Mention[]` (optional) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `blocking` | `boolean` (optional) | Explicit requester-declared agent dependency. Ordinary pending questions are not automatically blocking. |
| `requester_instance_id` | `string` (optional) | Runtime that initiated the request, when applicable. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `requester_id` | `string` | Identity that opened the requested decision. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `kind` | `"question" \| "approval" \| "task"` | Resource or operation kind. Use one of the listed values, not a display label. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `choices` | `string[]` | Optional exact answer strings. A chosen answer must match an offered value. |
| `action` | `Action` (optional) | Optional exact bound-action descriptor for the advanced execution contract. |
| `state` | `"open" \| "resolved" \| "cancelled" \| "expired" \| "superseded"` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `response` | `Response & { responder_instance_id?: string; source_answer_id?: string; source_invalidated?: boolean; reuse_method?: string; reuse_reason?: string; }` (optional) | Recorded final typed decision, absent while pending. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |

## Execution

An authorized intent and worker-reported state, not proof of an external effect.

```typescript
export type Execution = {
  id: string;
  request_id: string;
  executor_id: string;
  operation_key: string;
  action: Action;
  state: "authorized" | "running" | "succeeded" | "failed" | "unknown";
  result: unknown;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `request_id` | `string` | Canonical durable request ID. This is not a worker delivery ID. |
| `executor_id` | `string` | Identity allowed to redeem the exact approved action. |
| `operation_key` | `string` | Stable identity of the external business operation, separate from the HTTP retry key. |
| `action` | `Action` | Optional exact bound-action descriptor for the advanced execution contract. |
| `state` | `"failed" \| "authorized" \| "running" \| "succeeded" \| "unknown"` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |
| `result` | `unknown` | Executor-reported JSON result. It is not independent proof of an external effect. |

## AskInput



```typescript
export type AskInput = {
 attachment_ids?:string[];
 mentions?:Mention[];
 blocking?:boolean;
 reuse_direct?:boolean;
  preview_token?: string;
  /** Omit when asking the current participants of conversation_id. */
  target?: Target;
  title?: string;
  body?: string;
  kind?: "question" | "approval" | "task";
  conversation_id?: string;
  choices?: string[];
  action?: Action;
  expires_at?: string;
  shared_key?: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `attachment_ids` | `string[]` (optional) | IDs of staged private drafts to claim in the initial operation; at most five. |
| `mentions` | `Mention[]` (optional) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `blocking` | `boolean` (optional) | Explicit requester-declared agent dependency. Ordinary pending questions are not automatically blocking. |
| `reuse_direct` | `boolean` (optional) | Opt into reusing exact authorized two-person history. False by default; does not merge shared chats. |
| `preview_token` | `string` (optional) | Dispatch preview token. A stale audience or route requires a fresh preview. |
| `target` | `Target` (optional) | Omit when asking the current participants of conversation_id. |
| `title` | `string` (optional) | Optional short label. A normal message does not require a title. |
| `body` | `string` (optional) | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `kind` | `"question" \| "approval" \| "task"` (optional) | Resource or operation kind. Use one of the listed values, not a display label. |
| `conversation_id` | `string` (optional) | Canonical conversation ID. Use it to continue the same authorized history. |
| `choices` | `string[]` (optional) | Optional exact answer strings. A chosen answer must match an offered value. |
| `action` | `Action` (optional) | Optional exact bound-action descriptor for the advanced execution contract. |
| `expires_at` | `string` (optional) | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `shared_key` | `string` (optional) | Explicit reusable-answer key; reuse also requires exact matching question context and current authority. |

## Mention



```typescript
export type Mention = {principal_id:string;start:number;end:number};
```

| Field | Type | Usage |
| --- | --- | --- |
| `principal_id` | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `start` | `number` | Inclusive Unicode code-point offset of the mention, not a byte or UTF-16 index. |
| `end` | `number` | Exclusive Unicode code-point offset of the mention. |

## Message



```typescript
export type Message = {
 received_by?:string[];
 attachments?:Attachment[];
 mentions?:Mention[];
  id: string;
  conversation_id: string;
  sender_id: string;
  instance_id?: string;
  body: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `received_by` | `string[]` (optional) | Agent IDs whose current native deliveries have been acknowledged, projected only for an authorized sender. This is durable receipt, not proof of model reading or task completion. |
| `attachments` | `Attachment[]` (optional) | Currently visible attachment metadata. |
| `mentions` | `Mention[]` (optional) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `sender_id` | `string` | Identity that sent the message, independent of the delivering channel. |
| `instance_id` | `string` (optional) | Exact connected runtime ID, separate from the logical agent identity. |
| `body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |

## StartChatInput



```typescript
export type StartChatInput = { targets:Target[]; body:string; title?:string; approval?:boolean; choices?:string[]; mentions?:Mention[]; attachment_ids?:string[] };
```

| Field | Type | Usage |
| --- | --- | --- |
| `targets` | `Target[]` | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `title` | `string` (optional) | Optional short label. A normal message does not require a title. |
| `approval` | `boolean` (optional) | Attach a typed approval request to the initial shared chat message. False by default. |
| `choices` | `string[]` (optional) | Optional exact answer strings. A chosen answer must match an offered value. |
| `mentions` | `Mention[]` (optional) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `attachment_ids` | `string[]` (optional) | IDs of staged private drafts to claim in the initial operation; at most five. |

## Attachment



```typescript
export type Attachment = { id:string; conversation_id:string; message_id?:string; request_id?:string; file_name:string; media_type:string; size:number; sha256:string; created_at:string };
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `message_id` | `string` (optional) | Canonical message ID for deduplication and correlation. |
| `request_id` | `string` (optional) | Canonical durable request ID. This is not a worker delivery ID. |
| `file_name` | `string` | Safe file name shown with the attachment. |
| `media_type` | `string` | Declared media type, for example application/pdf. |
| `size` | `number` | File length in bytes, from 1 byte through 5 MiB. |
| `sha256` | `string` | SHA-256 digest of the stored file bytes. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |

## ChatMembershipInput



```typescript
export type ChatMembershipInput = {operation:"rename"|"add"|"remove"|"leave";version:number;title?:string;members?:string[];share_history?:boolean;next_manager?:string};
```

| Field | Type | Usage |
| --- | --- | --- |
| `operation` | `"rename" \| "add" \| "remove" \| "leave"` | Requested operation, with values defined by that endpoint. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `title` | `string` (optional) | Optional short label. A normal message does not require a title. |
| `members` | `string[]` (optional) | Directory-group or chat member identity IDs. Membership never substitutes for contact authority. |
| `share_history` | `boolean` (optional) | Explicitly disclose earlier history to additions. False by default. |
| `next_manager` | `string` (optional) | Existing participant to manage the chat when the current manager leaves. |

## ChatMembershipResult



```typescript
export type ChatMembershipResult = {conversation_id:string;version:number;left?:boolean};
```

| Field | Type | Usage |
| --- | --- | --- |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `left` | `boolean` (optional) | True when the membership operation removed the caller from the shared conversation. |

## Conversation



```typescript
export type Conversation = {id:string;title:string;messages?:Message[];participants:unknown[];shared?:boolean;version?:number;manager_id?:string;history_start?:number;past_participants?:unknown[]};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `messages` | `Message[]` (optional) | Canonical message records in this response, not worker delivery envelopes. |
| `participants` | `unknown[]` | Current participants in the authorized history projection. |
| `shared` | `boolean` (optional) | True for a shared chat, distinct from private histories created by a batch. |
| `version` | `number` (optional) | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `manager_id` | `string` (optional) | Manager identity for a person, or current shared-chat manager according to the resource. |
| `history_start` | `number` (optional) | Earliest event boundary disclosed to this participant. |
| `past_participants` | `unknown[]` (optional) | Former participant metadata visible to the caller; does not restore their access. |

## SendInput



```typescript
export type SendInput = {
 attachment_ids?:string[];
 mentions?:Mention[];
 reuse_direct?:boolean;
  preview_token?: string;
  target?: Target;
  conversation_id?: string;
  body: string;
  title?: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `attachment_ids` | `string[]` (optional) | IDs of staged private drafts to claim in the initial operation; at most five. |
| `mentions` | `Mention[]` (optional) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. |
| `reuse_direct` | `boolean` (optional) | Opt into reusing exact authorized two-person history. False by default; does not merge shared chats. |
| `preview_token` | `string` (optional) | Dispatch preview token. A stale audience or route requires a fresh preview. |
| `target` | `Target` (optional) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `conversation_id` | `string` (optional) | Canonical conversation ID. Use it to continue the same authorized history. |
| `body` | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `title` | `string` (optional) | Optional short label. A normal message does not require a title. |

## Delivery



```typescript
export type Delivery = {
  id: string;
  generation: number;
  payload: {
    type: string;
    conversation_id: string;
    message?: Message;
    request?: RequestItem;
  };
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `generation` | `number` | Current inbox lease generation. Ack must echo this generation. |
| `payload` | `{ type: string; conversation_id: string; message?: Message; request?: RequestItem; }` | Canonical message/request information inside a delivery envelope. |

## Credential



```typescript
export type Credential = {id:string;principal_id:string;owner_name:string;name:string;kind:string;prefix:string;token_hint:string;created_at:string;last_used_at:string|null;expires_at:string|null;renewable_until:string|null;previous_until:string|null;permissions:string[]|null;version:number;revoked:boolean;parent_credential_id?:string};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `principal_id` | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `owner_name` | `string` | Display name of the identity that owns the credential. |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `prefix` | `string` | Permitted enrollment namespace prefix for a bounded launcher. |
| `token_hint` | `string` | Non-secret token suffix used to identify a credential. It cannot authenticate. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `last_used_at` | `string` | Most recently recorded authenticated use, or null. Updates are throttled and are not an exact per-request audit trail. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `renewable_until` | `string` | Hard deadline for a renewable worker credential, or null when it is not renewable. |
| `previous_until` | `string` | Deadline for the previous token during rotation overlap, or null when no previous token remains valid. |
| `permissions` | `string[]` | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `revoked` | `boolean` | Whether the credential has been revoked and can no longer authenticate. |
| `parent_credential_id` | `string` (optional) | Credential that enrolled this worker, when applicable; used for optional worker revocation with the parent. |

## CredentialInput



```typescript
export type CredentialInput = {never_expires?:boolean;principal_id:string;kind:"api"|"enrollment";name?:string;prefix?:string;expires_at?:string;permissions?:Array<"read"|"message"|"request"|"respond"|"execute"|"manage">};
```

| Field | Type | Usage |
| --- | --- | --- |
| `never_expires` | `boolean` (optional) | Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease. |
| `principal_id` | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `kind` | `"api" \| "enrollment"` | Resource or operation kind. Use one of the listed values, not a display label. |
| `name` | `string` (optional) | Human-readable name. It is not necessarily unique. |
| `prefix` | `string` (optional) | Permitted enrollment namespace prefix for a bounded launcher. |
| `expires_at` | `string` (optional) | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `permissions` | `("read" \| "message" \| "request" \| "respond" \| "execute" \| "manage")[]` (optional) | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |

## CredentialEdit



```typescript
export type CredentialEdit = {never_expires?:boolean;version:number;name?:string;expires_at?:string;permissions?:string[];clear_permissions?:boolean};
```

| Field | Type | Usage |
| --- | --- | --- |
| `never_expires` | `boolean` (optional) | Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `name` | `string` (optional) | Human-readable name. It is not necessarily unique. |
| `expires_at` | `string` (optional) | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `permissions` | `string[]` (optional) | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |
| `clear_permissions` | `boolean` (optional) | Remove the credential-specific permission restriction. This does not grant permissions absent from the underlying identity. |

## IssuedCredential



```typescript
export type IssuedCredential = {id:string;token:string;kind:string;expires_at:string|null};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |

## CredentialReplacement



```typescript
export type CredentialReplacement = {token:string;credential:Credential};
```

| Field | Type | Usage |
| --- | --- | --- |
| `token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `credential` | `Credential` | Non-secret credential metadata returned with a newly rotated bearer token. |

## Session



```typescript
export type Session = {
  token: string;
  agent: Agent;
  instance_id: string;
  expires_at: string | null;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `agent` | `Agent` | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `instance_id` | `string` | Exact connected runtime ID, separate from the logical agent identity. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |

## AssistanceSettings



```typescript
export type AssistanceSettings = {
  overseer: boolean;
  version: number;
  overseer_configured: boolean;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `overseer` | `boolean` | Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `overseer_configured` | `boolean` | Whether the engine has a configured Coordinator provider; not the enablement switch. |

## OverseerInput



```typescript
export type OverseerInput = { prompt: string; target?: Target; previous_plan_id?: string };
```

| Field | Type | Usage |
| --- | --- | --- |
| `prompt` | `string` | Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
| `target` | `Target` (optional) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `previous_plan_id` | `string` (optional) | Optional prior plan belonging to the caller for continuing permitted context. |

## FleetAgent



```typescript
export type FleetAgent = {
  agent: Agent;
  fresh: boolean;
  instances: {
    id: string;
    agent_id: string;
    presence: string;
    last_seen: string;
    capabilities: string[];
    progress: Record<string, unknown>;
  }[];
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `agent` | `Agent` | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `fresh` | `boolean` | Whether the reported runtime evidence is current. |
| `instances` | `{ id: string; agent_id: string; presence: string; last_seen: string; capabilities: string[]; progress: Record<string, unknown>; }[]` | Runtime connections and their observed presence. |

## OverseerPlan



```typescript
export type OverseerPlan = {
  automatic?: boolean;
  instructions?: {agent_id:string;operation:"message"|"question"|"task";body:string}[];
  summary_error?: string;
  previous_plan_id?: string;
  id: string;
  prompt: string;
  context_agent_ids: string[];
  target?: Target;
  operation: "status" | "message" | "question" | "task";
  summary: string;
  body?: string;
  sources: FleetAgent[];
  requires_confirmation: boolean;
  created_at: string;
  expires_at: string;
  dispatches: {
    agent_id: string;
    conversation_id: string;
    request_id?: string;
  }[];
  replies: RequestItem[];
  reply_summary?: string;
  reply_digest?: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `automatic` | `boolean` (optional) | True when Coordinator delegated without a separate review step. |
| `instructions` | `{ agent_id: string; operation: "question" \| "task" \| "message"; body: string; }[]` (optional) | Per-agent communication instructions, when different specialists need different tasks. |
| `summary_error` | `string` (optional) | Safe model-summary error. Existing durable instructions remain separately inspectable. |
| `previous_plan_id` | `string` (optional) | Optional prior plan belonging to the caller for continuing permitted context. |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `prompt` | `string` | Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
| `context_agent_ids` | `string[]` | Agent IDs included in the current permitted plan context. |
| `target` | `Target` (optional) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `operation` | `"question" \| "task" \| "message" \| "status"` | Requested operation, with values defined by that endpoint. |
| `summary` | `string` | Plan explanation or status answer, as defined by its operation. |
| `body` | `string` (optional) | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `sources` | `FleetAgent[]` | Authorized specialist context used for this plan, not omniscient agent execution state. |
| `requires_confirmation` | `boolean` | Whether this saved plan needs explicit confirmation before dispatch. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `dispatches` | `{ agent_id: string; conversation_id: string; request_id?: string; }[]` | Attributed conversation/request IDs created by a confirmed or automatic plan. |
| `replies` | `RequestItem[]` | Specialist requested decisions visible to the current caller. |
| `reply_summary` | `string` (optional) | Model-generated summary of the authorized replies, including pending/missing evidence. |
| `reply_digest` | `string` (optional) | Digest identifying the reply evidence used by the summary. |

## ChannelPolicy



```typescript
export type ChannelPolicy = { mode: "preferred" | "all"; destinations: string[]; followup_seconds: number };
```

| Field | Type | Usage |
| --- | --- | --- |
| `mode` | `"preferred" \| "all"` | primary, copy or fallback routing mode. |
| `destinations` | `string[]` | Recipient-owned delivery destination IDs in preference order. An empty list keeps delivery in the workspace only. |
| `followup_seconds` | `number` | Delay before trying the next channel for an unanswered question or approval after provider acceptance. Zero disables follow-ups; new delays are 5 to 900 seconds. |

## ChannelOverride



```typescript
export type ChannelOverride = { source: { kind: "agent" | "group"; id: string }; policy: ChannelPolicy };
```

| Field | Type | Usage |
| --- | --- | --- |
| `source` | `{ kind: "agent" \| "group"; id: string; }` | Sender selector for a channel override: an exact Agent or an Agent role group. |
| `policy` | `ChannelPolicy` | Channel delivery policy. It changes delivery destinations without granting contact or decision authority. |

## DeliveryPreferences



```typescript
export type DeliveryPreferences = { person_id: string; version: number; default: ChannelPolicy | null; overrides: ChannelOverride[] };
```

| Field | Type | Usage |
| --- | --- | --- |
| `person_id` | `string` | Stable recipient Person identity ID. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `default` | `ChannelPolicy` | Recipient default channel policy; null preserves existing destination-based routing. |
| `overrides` | `ChannelOverride[]` | Ordered sender-specific delivery preferences. An exact Agent match precedes matching Agent roles, then the recipient default. |

## QueryInput



```typescript
export type QueryInput = {collection: string; search?: string; filters?: Record<string,string>; limit?: number; cursor?: string};
```

| Field | Type | Usage |
| --- | --- | --- |
| `collection` | `string` | One of the documented query collections. |
| `search` | `string` (optional) | Optional text search, at most 200 characters. |
| `filters` | `Record<string, string>` (optional) | Supported exact collection filters, not arbitrary SQL or JSON selectors. |
| `limit` | `number` (optional) | Page size: default 50, minimum 1, maximum 200. |
| `cursor` | `string` (optional) | Opaque continuation token, scoped to the same actor, workspace and query; expires after 24 hours. |

## QueryPage



```typescript
export type QueryPage<T=unknown> = {items:T[]; next_cursor?:string; order:string};
```

| Field | Type | Usage |
| --- | --- | --- |
| `items` | `T[]` | Authorized records returned by this page. |
| `next_cursor` | `string` (optional) | Opaque next-page cursor. Continue even when the current items array is empty. |
| `order` | `string` | Documented ordering for this collection. |

## CapabilityResult



```typescript
export type CapabilityResult = {observed_at:string; operations:Record<string,boolean>; request_version?:number; outcomes:string[]};
```

| Field | Type | Usage |
| --- | --- | --- |
| `observed_at` | `string` | Timestamp of this capability snapshot. |
| `operations` | `Record<string, boolean>` | Map of action names to currently allowed booleans. Actual mutation checks again. |
| `request_version` | `number` (optional) | Request version observed during capability evaluation. |
| `outcomes` | `string[]` | Currently allowed typed decision outcomes. |

## DispatchPreviewInput



```typescript
export type DispatchPreviewInput = {targets:Target[]; operation:"message"|"ask"; descriptor?:Action};
```

| Field | Type | Usage |
| --- | --- | --- |
| `targets` | `Target[]` | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `operation` | `"message" \| "ask"` | Requested operation, with values defined by that endpoint. |
| `descriptor` | `Action` (optional) | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |

## DispatchPreview



```typescript
export type DispatchPreview = {recipients:unknown[]; count:number; hidden_recipients:number; token:string; expires_at:string; sends:false};
```

| Field | Type | Usage |
| --- | --- | --- |
| `recipients` | `unknown[]` | Resolved, authorized recipient projection. |
| `count` | `number` | Number of recipients resolved by this preview. |
| `hidden_recipients` | `number` | Resolved recipients whose details the caller cannot view. |
| `token` | `string` | Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. |
| `sends` | `false` | Whether a preview itself sends anything; dispatch preview returns false. |

## PermissionRule



```typescript
export type PermissionRule = {effect?: "allow" | "deny"; action: "view" | "message" | "ask" | "decide"; target_kind: Target["kind"]; target_id: string};
```

| Field | Type | Usage |
| --- | --- | --- |
| `effect` | `"allow" \| "deny"` (optional) | Whether this contact rule allows or explicitly blocks the selected action. A matching explicit deny overrides grants. |
| `action` | `"message" \| "ask" \| "view" \| "decide"` | Optional exact bound-action descriptor for the advanced execution contract. |
| `target_kind` | `"person" \| "agent" \| "service" \| "group" \| "instance"` | Kind of identity or managed resource matched by the rule. |
| `target_id` | `string` | Stable ID or explicitly supported wildcard of the rule's target. |

## ContactPermissionsInput



```typescript
export type ContactPermissionsInput = {subject: Target; rules: PermissionRule[]; version: number};
```

| Field | Type | Usage |
| --- | --- | --- |
| `subject` | `Target` | Authorized subject projection of the access inspection. |
| `rules` | `PermissionRule[]` | Directional permission rules granted by this policy role. |
| `version` | `number` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |

## ContactPreviewInput



```typescript
export type ContactPreviewInput = {subject: Target; rules?: PermissionRule[]; version?: number; targets?: Target[]};
```

| Field | Type | Usage |
| --- | --- | --- |
| `subject` | `Target` | Authorized subject projection of the access inspection. |
| `rules` | `PermissionRule[]` (optional) | Directional permission rules granted by this policy role. |
| `version` | `number` (optional) | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `targets` | `Target[]` (optional) | Explicit targets for a private batch or shared chat. These have different audience semantics. |

## BeepgridEvent



```typescript
export type BeepgridEvent = {
  sequence: number;
  kind: string;
  actor_id: string;
  conversation_id: string;
  recipient_id: string;
  data: unknown;
  created_at: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `sequence` | `number` | Monotonically ordered canonical event sequence. Checkpoint after application processing. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `actor_id` | `string` | Identity responsible for the canonical event. |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `recipient_id` | `string` | Intended individual identity for the delivery or event projection. |
| `data` | `unknown` | Event-specific JSON data. Full events contain the canonical payload; summary mode is smaller. |
| `created_at` | `string` | Creation timestamp in RFC 3339 UTC. |

## EventOptions



```typescript
export type EventOptions = { after?: number; signal?: AbortSignal; summary?: boolean };
```

| Field | Type | Usage |
| --- | --- | --- |
| `after` | `number` (optional) | Last committed canonical event sequence. Default 0 starts from retained visible events; checkpoint only after applying each event. |
| `signal` | `AbortSignal` (optional) | Optional AbortSignal for stopping this local event stream; does not cancel durable requests. |
| `summary` | `boolean` (optional) | Plan explanation or status answer, as defined by its operation. |

## BusyMode



```typescript
export type BusyMode = "steer" | "queue";
```

## LiveInput



```typescript
export type LiveInput = {
  /** Stable across transport lease generations. Use this in host checkpoints. */
  id: string;
  conversationId: string;
  kind: string;
  delivery: Delivery;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable across transport lease generations. Use this in host checkpoints. |
| `conversationId` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `delivery` | `Delivery` | The original leased Delivery, including stable identity and canonical message or request payload. |

## StoredInput



```typescript
export type StoredInput = LiveInput & {
  state: "pending" | "submitting" | "accepted";
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable across transport lease generations. Use this in host checkpoints. |
| `conversationId` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `delivery` | `Delivery` | The original leased Delivery, including stable identity and canonical message or request payload. |
| `state` | `"pending" \| "submitting" \| "accepted"` | Lifecycle state. Read the resource-specific enum; request and execution states differ. |

## InboxStore



```typescript
export interface InboxStore {
  put(input: LiveInput): void;
  pending(limit?: number): StoredInput[];
  setState(id: string, state: StoredInput["state"]): void;
  get(id: string): StoredInput | undefined;
  close(): void;
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `put` | `(input: LiveInput) => void` | Durably store an incoming input before transport acknowledgement. Repeated stable IDs must not create duplicate work. |
| `pending` | `(limit?: number) => StoredInput[]` | Read bounded pending or uncertain inputs from the durable inbox for dispatch or reconciliation. |
| `setState` | `(id: string, state: "pending" \| "submitting" \| "accepted") => void` | Persist pending, submitting or accepted state. Uncertain submitting input requires reconciliation before replay. |
| `get` | `(id: string) => StoredInput` | Read one stored input by its stable delivery ID, or return undefined when absent. |
| `close` | `() => void` | Release the durable inbox and its local ownership resources. |

## InputBinding



```typescript
export interface InputBinding {
  readonly name: string;
  readonly supportsSteer: boolean;
  /** Return after native acceptance/checkpoint, never after the whole business job.
   * Honor input.id for deduplication. Do not elevate peer content to owner authority. */
  submit(input: LiveInput, mode: BusyMode, signal?: AbortSignal): Promise<void>;
  resume?(input: LiveInput, signal?: AbortSignal): Promise<void>;
  /** A crash/network error may leave native acceptance uncertain. No blind replay. */
  reconcile?(input: LiveInput): Promise<"accepted" | "retry" | "unknown">;
}
```

| Field | Type | Usage |
| --- | --- | --- |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `supportsSteer` | `boolean` | Whether the selected native binding supports input during active work. Queue-only bindings must not advertise steering. |
| `submit` | `(input: LiveInput, mode: BusyMode, signal?: AbortSignal) => Promise<void>` | Return after native acceptance/checkpoint, never after the whole business job. Honor input.id for deduplication. Do not elevate peer content to owner authority. |
| `resume` | `(input: LiveInput, signal?: AbortSignal) => Promise<void>` (optional) | Resume the original request waiter with its correlated result, independently of queued ordinary messages. |
| `reconcile` | `(input: LiveInput) => Promise<"unknown" \| "accepted" \| "retry">` (optional) | A crash/network error may leave native acceptance uncertain. No blind replay. |

## SessionRoute



```typescript
export type SessionRoute = (conversationId: string) => Promise<string>;
```

## RPC

Use an authenticated, initialized native client, not a URL provided by a message.

```typescript
export type RPC = (
  method: string,
  params: Record<string, unknown>,
  signal?: AbortSignal,
) => Promise<unknown>;
```

## Environment

Shared by setup UI and the published setup command. No runtime imports.

```typescript
export type Environment = {
  id: string;
  label: string;
  group: string;
  steer: boolean;
  binding: string;
  guide: string;
  note: string;
};
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `label` | `string` | Human-readable environment name shown during setup. |
| `group` | `string` | Setup catalog category for the existing harness, framework or custom host. |
| `steer` | `boolean` | Whether the environment offers a supported steering integration; the installed runtime must still satisfy the binding capabilities. |
| `binding` | `string` | Name of the runtime binding or checkpoint helper used by this environment. |
| `guide` | `string` | Environment-specific anchor in the source runtime integration guide. |
| `note` | `string` | Environment-specific setup and capability guidance. |

## Conversation



```typescript
export type Conversation = { id: string; title: string; messages: Message[] };
```

| Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `messages` | `Message[]` | Canonical message records in this response, not worker delivery envelopes. |