@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/docs/api/fleet.md

@@ -0,0 +1,734 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / fleet
+
+# fleet
+
+## Classes
+
+### AgentGrantError
+
+Refusal of supplied authority; no host policy lookup is performed.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AgentGrantError(reason): AgentGrantError;
+```
+
+###### Parameters
+
+| Parameter | Type                                                                                  |
+| --------- | ------------------------------------------------------------------------------------- |
+| `reason`  | `"agent"` \| `"action"` \| `"expired"` \| `"delegation_loop"` \| `"delegation_depth"` |
+
+###### Returns
+
+[`AgentGrantError`](#agentgranterror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### reason
+
+```ts
+readonly reason: "agent" | "action" | "expired" | "delegation_loop" | "delegation_depth";
+```
+
+---
+
+### DirectoryError
+
+Directory input, replay or storage refusal.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new DirectoryError(status, code): DirectoryError;
+```
+
+###### Parameters
+
+| Parameter | Type                                                                                                                              |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `status`  | `400` \| `403` \| `404` \| `409` \| `503`                                                                                         |
+| `code`    | \| `"not_found"` \| `"invalid_input"` \| `"name_taken"` \| `"request_conflict"` \| `"computer_team_conflict"` \| `"partial_init"` |
+
+###### Returns
+
+[`DirectoryError`](#directoryerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### status
+
+```ts
+readonly status: 400 | 403 | 404 | 409 | 503;
+```
+
+##### code
+
+```ts
+readonly code:
+  | "not_found"
+  | "invalid_input"
+  | "name_taken"
+  | "request_conflict"
+  | "computer_team_conflict"
+  | "partial_init";
+```
+
+## Type Aliases
+
+### AgentAction
+
+```ts
+type AgentAction = z.infer<typeof agentActionSchema>;
+```
+
+One host-admitted fleet operation.
+
+---
+
+### AgentGrant
+
+```ts
+type AgentGrant = z.infer<typeof agentGrantSchema>;
+```
+
+A trusted host's bounded, addressed authority for fleet operations.
+
+---
+
+### AgentLifecycleFact
+
+```ts
+type AgentLifecycleFact = Readonly<{
+  kind: "created" | "deleted";
+  agentId: string;
+  provenance: AgentGrant["provenance"];
+}>;
+```
+
+A committed directory transition, returned in the host's transaction.
+
+---
+
+### AgentId
+
+```ts
+type AgentId = CairnId<"agent", "agent">;
+```
+
+An ordinary Agent directory identity.
+
+---
+
+### AgentCreation
+
+```ts
+type AgentCreation = z.infer<typeof agentCreationSchema>;
+```
+
+One idempotent directory reservation.
+
+---
+
+### AgentRename
+
+```ts
+type AgentRename = z.infer<typeof agentRenameSchema>;
+```
+
+Input to [createAgentDirectory](#createagentdirectory)'s `rename`.
+
+---
+
+### DirectoryAgent
+
+```ts
+type DirectoryAgent = Readonly<{
+  agentId: AgentId;
+  name: string;
+  createdAt: number;
+  updatedAt: number;
+}>;
+```
+
+One durable Agent directory record.
+
+---
+
+### AgentDelegationTask
+
+```ts
+type AgentDelegationTask = z.infer<typeof agentDelegationTaskSchema>;
+```
+
+A caller reuses this task unchanged while polling Pending.
+
+---
+
+### AgentDelegationOutcome
+
+```ts
+type AgentDelegationOutcome = Readonly<{
+  kind: "settled";
+  agentId: string;
+  sessionId: string;
+}> &
+  CommandSettlement;
+```
+
+Exact settled Session facts, including Pi usage and tool-call records.
+
+---
+
+### FleetDelegationOptions
+
+```ts
+type FleetDelegationOptions = Readonly<{
+  storage: WatchdogSqliteOwner;
+  deliver: (mail) => Promise<Accepted>;
+  readSettlement: (
+    agentId,
+    sessionId,
+    commandId,
+  ) => Promise<CommandSettlement | undefined>;
+  open: (agentId) => Promise<
+    Readonly<{
+      agent: ShiitakeAgent;
+      release: () => Promise<void>;
+    }>
+  >;
+}>;
+```
+
+Ordinary runtime and mail transports; these ports do not decide host policy.
+
+---
+
+### AuthenticatedDelegationReply
+
+```ts
+type AuthenticatedDelegationReply = Readonly<{
+  ancestors: readonly string[];
+  maxDepth: number;
+  reply: VerifiedAgentReply;
+}>;
+```
+
+The delegation meta the host attaches to an authenticated reply: the caller's
+own path plus the verified reply, whose `agentId` is the reply's author.
+
+---
+
+### DelegationSendMeta
+
+```ts
+type DelegationSendMeta = object;
+```
+
+The host metadata a delegated send carries, as JSON.
+
+#### Properties
+
+##### author
+
+```ts
+author: FungiAuthor;
+```
+
+##### delegation?
+
+```ts
+optional delegation?: object;
+```
+
+###### ancestors
+
+```ts
+ancestors: string[];
+```
+
+###### maxDepth
+
+```ts
+maxDepth: number;
+```
+
+---
+
+### DelegationReplyMeta
+
+```ts
+type DelegationReplyMeta = Readonly<{
+  author: FungiAuthor;
+  delegation: Readonly<{
+    ancestors: readonly string[];
+    maxDepth: number;
+    reply: VerifiedAgentReply;
+  }>;
+}>;
+```
+
+The host metadata on one authenticated reply line, as JSON.
+
+---
+
+### FleetRecipient
+
+```ts
+type FleetRecipient = Readonly<{
+  agentId: string;
+  sessionId: string;
+  sentAt: number;
+}>;
+```
+
+One Agent a Session sent work to: its latest addressed conversation.
+
+---
+
+### FleetRecipients
+
+```ts
+type FleetRecipients = Readonly<{
+  recipients: readonly FleetRecipient[];
+  more: number;
+}>;
+```
+
+A bounded page of recipients and how many more exist past it.
+
+---
+
+### FleetAgentAccess
+
+```ts
+type FleetAgentAccess = (
+  agentId,
+  meta?,
+) => Promise<
+  Readonly<{
+    agent: ShiitakeAgent;
+    release: () => Promise<void>;
+  }>
+>;
+```
+
+Acquire ordinary Session access; an in-process host applies meta with withMeta.
+
+#### Parameters
+
+| Parameter | Type                         |
+| --------- | ---------------------------- |
+| `agentId` | `string`                     |
+| `meta?`   | [`Json`](extensions.md#json) |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `agent`: [`ShiitakeAgent`](client.md#shiitakeagent);
+`release`: () => `Promise`\<`void`\>; \}\>\>
+
+---
+
+### FleetMessage
+
+```ts
+type FleetMessage = Readonly<{
+  requestId: string;
+  text: string;
+  delivery?: "steer" | "followUp";
+}>;
+```
+
+One idempotent prompt, using the Session owner's existing delivery grammar.
+
+## Variables
+
+### agentActionSchema
+
+```ts
+const agentActionSchema: ZodEnum<{
+  send: "send";
+  read: "read";
+  create: "create";
+  manage: "manage";
+  delegate: "delegate";
+}>;
+```
+
+Operations explicitly admitted by the host.
+
+---
+
+### agentProvenanceSchema
+
+```ts
+const agentProvenanceSchema: ZodObject<
+  {
+    actor: ZodString;
+    workflowRunId: ZodOptional<ZodString>;
+    toolCallInputDigest: ZodOptional<ZodString>;
+    session: ZodOptional<
+      ZodObject<
+        {
+          agentId: ZodString;
+          sessionId: ZodString;
+        },
+        $strict
+      >
+    >;
+  },
+  $strict
+>;
+```
+
+Attribution supplied by the admitting host, without Team semantics.
+
+---
+
+### agentGrantSchema
+
+```ts
+const agentGrantSchema: ZodObject<
+  {
+    agents: ZodUnion<readonly [ZodLiteral<"all">, ZodArray<ZodString>]>;
+    actions: ZodArray<
+      ZodEnum<{
+        send: "send";
+        read: "read";
+        create: "create";
+        manage: "manage";
+        delegate: "delegate";
+      }>
+    >;
+    expiresAt: ZodNumber;
+    provenance: ZodObject<
+      {
+        actor: ZodString;
+        workflowRunId: ZodOptional<ZodString>;
+        toolCallInputDigest: ZodOptional<ZodString>;
+        session: ZodOptional<
+          ZodObject<
+            {
+              agentId: ZodString;
+              sessionId: ZodString;
+            },
+            $strict
+          >
+        >;
+      },
+      $strict
+    >;
+    meta: ZodOptional<ZodJSONSchema>;
+    maxDepth: ZodOptional<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+Fleet authority is supplied, never looked up in host policy.
+
+---
+
+### agentIds
+
+```ts
+const agentIds: Readonly<{
+  agent: IdCodec<"agent", "agent", 1>;
+}>;
+```
+
+Stable Agent identities, retained across host compositions.
+
+---
+
+### agentCreationSchema
+
+```ts
+const agentCreationSchema: ZodObject<
+  {
+    name: ZodString;
+    requestId: ZodString;
+    configuration: ZodString;
+  },
+  $strict
+>;
+```
+
+Stable replay input; configuration is an opaque host creation choice.
+
+---
+
+### agentRenameSchema
+
+```ts
+const agentRenameSchema: ZodObject<
+  {
+    name: ZodString;
+  },
+  $strict
+>;
+```
+
+Owner-only rename input: an Agent's new display name.
+
+---
+
+### agentDelegationTaskSchema
+
+```ts
+const agentDelegationTaskSchema: ZodObject<
+  {
+    requestId: ZodString;
+    agentId: ZodString;
+    sessionId: ZodOptional<ZodString>;
+    text: ZodString;
+  },
+  $strict
+>;
+```
+
+Replay identity and work, with the parent supplied exclusively by the grant.
+
+---
+
+### commandSettlementSchema
+
+```ts
+const commandSettlementSchema: Schema.Codec<CommandSettlement>;
+```
+
+Exact host facts encoded over internal transports, without transcript content.
+
+## Functions
+
+### assertAgentGrant()
+
+```ts
+function assertAgentGrant(grant, action, agentId?): void;
+```
+
+Check every operation against its explicit authority.
+
+#### Parameters
+
+| Parameter                               | Type                                                                                                                                                                                                                                                                                                                                                            | Description                                                                |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `grant`                                 | \{ `agents`: `string`[] \| `"all"`; `actions`: (`"send"` \| `"read"` \| `"create"` \| `"manage"` \| `"delegate"`)[]; `expiresAt`: `number`; `provenance`: \{ `actor`: `string`; `workflowRunId?`: `string`; `toolCallInputDigest?`: `string`; `session?`: \{ `agentId`: `string`; `sessionId`: `string`; \}; \}; `meta?`: `JSONType`; `maxDepth?`: `number`; \} | -                                                                          |
+| `grant.agents`                          | `string`[] \| `"all"`                                                                                                                                                                                                                                                                                                                                           | -                                                                          |
+| `grant.actions`                         | (`"send"` \| `"read"` \| `"create"` \| `"manage"` \| `"delegate"`)[]                                                                                                                                                                                                                                                                                            | -                                                                          |
+| `grant.expiresAt?`                      | `number`                                                                                                                                                                                                                                                                                                                                                        | -                                                                          |
+| `grant.provenance?`                     | \{ `actor`: `string`; `workflowRunId?`: `string`; `toolCallInputDigest?`: `string`; `session?`: \{ `agentId`: `string`; `sessionId`: `string`; \}; \}                                                                                                                                                                                                           | -                                                                          |
+| `grant.provenance.actor?`               | `string`                                                                                                                                                                                                                                                                                                                                                        | -                                                                          |
+| `grant.provenance.workflowRunId?`       | `string`                                                                                                                                                                                                                                                                                                                                                        | -                                                                          |
+| `grant.provenance.toolCallInputDigest?` | `string`                                                                                                                                                                                                                                                                                                                                                        | Host fingerprint of the enclosing model program, frozen with replay input. |
+| `grant.provenance.session?`             | \{ `agentId`: `string`; `sessionId`: `string`; \}                                                                                                                                                                                                                                                                                                               | -                                                                          |
+| `grant.provenance.session.agentId?`     | `string`                                                                                                                                                                                                                                                                                                                                                        | -                                                                          |
+| `grant.provenance.session.sessionId?`   | `string`                                                                                                                                                                                                                                                                                                                                                        | -                                                                          |
+| `grant.meta?`                           | `JSONType`                                                                                                                                                                                                                                                                                                                                                      | -                                                                          |
+| `grant.maxDepth?`                       | `number`                                                                                                                                                                                                                                                                                                                                                        | Delegation abuse bound; inherited paths may only narrow it.                |
+| `action?`                               | `"send"` \| `"read"` \| `"create"` \| `"manage"` \| `"delegate"`                                                                                                                                                                                                                                                                                                | -                                                                          |
+| `agentId?`                              | `string`                                                                                                                                                                                                                                                                                                                                                        | -                                                                          |
+
+#### Returns
+
+`void`
+
+---
+
+### createAgentDirectory()
+
+```ts
+function createAgentDirectory(sql): object;
+```
+
+Agent identities, replay receipts and erasure roster. Mutations belong inside
+the caller's storage transaction, so lifecycle facts and host projections commit
+together. Physical table names retain the existing Hub store layout.
+
+#### Parameters
+
+| Parameter | Type                                                                                |
+| --------- | ----------------------------------------------------------------------------------- |
+| `sql`     | `Readonly`\<\{ `exec`: (`statement`, ...`bindings`) => `WatchdogSqliteCursor`; \}\> |
+
+#### Returns
+
+| Name                      | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Default value                 | Description                                                                                                                            |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `readCreation()`          | (`grant`, `raw`) => \| `Readonly`\<\{ `agentId`: [`AgentId`](#agentid); `name`: `string`; `createdAt`: `number`; `updatedAt`: `number`; \}\> \| `null`                                                                                                                                                                                                                                                                                                                                                                                                                            | -                             | Resolve a matching creation receipt before host admission of a new reservation.                                                        |
+| `create()`                | (`grant`, `raw`) => \| \{ `agent`: `Readonly`\<\{ `agentId`: [`AgentId`](#agentid); `name`: `string`; `createdAt`: `number`; `updatedAt`: `number`; \}\>; `fact`: `null`; \} \| \{ `agent`: `Readonly`\<\{ `agentId`: [`AgentId`](#agentid); `name`: `string`; `createdAt`: `number`; `updatedAt`: `number`; \}\>; `fact`: \{ `kind`: `"created"`; `agentId`: `CairnId`\<`"agent"`, `"agent"`, `1`\>; `provenance`: \{ `actor`: `string`; `workflowRunId?`: `string`; `toolCallInputDigest?`: `string`; `session?`: \{ `agentId`: `string`; `sessionId`: `string`; \}; \}; \}; \} | -                             | Reserve an Agent once and return its committed lifecycle fact.                                                                         |
+| `read()`                  | (`grant`, `agentId`) => \| `Readonly`\<\{ `agentId`: [`AgentId`](#agentid); `name`: `string`; `createdAt`: `number`; `updatedAt`: `number`; \}\> \| `null`                                                                                                                                                                                                                                                                                                                                                                                                                        | -                             | Read one admitted Agent identity.                                                                                                      |
+| `list()`                  | (`grant`) => readonly `Readonly`\<\{ `agentId`: [`AgentId`](#agentid); `name`: `string`; `createdAt`: `number`; `updatedAt`: `number`; \}\>[]                                                                                                                                                                                                                                                                                                                                                                                                                                     | -                             | List only identities covered by the supplied grant.                                                                                    |
+| `remove()`                | (`grant`, `agentId`) => \| `Readonly`\<\{ `kind`: `"deleted"` \| `"created"`; `agentId`: `string`; `provenance`: \{ `actor`: `string`; `workflowRunId?`: `string`; `toolCallInputDigest?`: `string`; `session?`: \{ `agentId`: `string`; `sessionId`: `string`; \}; \}; \}\> \| `null`                                                                                                                                                                                                                                                                                            | -                             | Remove an identity while retaining its erasure address.                                                                                |
+| `rename()`                | (`grant`, `agentId`, `raw`) => [`DirectoryAgent`](#directoryagent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                             | Rename an existing Agent; refuses a name already held by another one. Owner-only rename; refuses a name already held by another Agent. |
+| `readCreator()`           | (`grant`, `agentId`) => `string` \| `null`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                             | Read the host actor recorded at creation. The user who created an Agent; that user's own credentials follow it.                        |
+| `listErasureIds()`        | () => readonly `string`[]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `store.listErasureIds`        | Enumerate retained addresses for host erasure.                                                                                         |
+| `erasureRosterComplete()` | () => `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `store.erasureRosterComplete` | Whether the retained erasure roster covers this store.                                                                                 |
+
+---
+
+### delegationProvenance()
+
+```ts
+function delegationProvenance(
+  session,
+  toolCallCode?,
+): Promise<{
+  actor: string;
+  workflowRunId?: string;
+  toolCallInputDigest?: string;
+  session?: {
+    agentId: string;
+    sessionId: string;
+  };
+}>;
+```
+
+Provenance for one delegated send from the invoking Agent's Session. The model
+program's digest is frozen with the replay input, so a retried tool call that
+changed its code conflicts instead of replaying.
+
+#### Parameters
+
+| Parameter       | Type                                                            |
+| --------------- | --------------------------------------------------------------- |
+| `session`       | `Readonly`\<\{ `agentId`: `string`; `sessionId`: `string`; \}\> |
+| `toolCallCode?` | `string`                                                        |
+
+#### Returns
+
+`Promise`\<\{ `actor`: `string`; `workflowRunId?`: `string`;
+`toolCallInputDigest?`: `string`; `session?`: \{ `agentId`: `string`;
+`sessionId`: `string`; \}; \}\>
+
+---
+
+### delegationSendMeta()
+
+```ts
+function delegationSendMeta(sender, invocationMeta?): DelegationSendMeta;
+```
+
+The host metadata one delegated send carries: the sending Agent as author and
+only the path inherited from the invoking line. A reply's verified facts stay on
+that reply's own line and never travel onward.
+
+#### Parameters
+
+| Parameter         | Type                                    |
+| ----------------- | --------------------------------------- |
+| `sender`          | \{ `id`: `string`; `name`: `string`; \} |
+| `sender.id`       | `string`                                |
+| `sender.name?`    | `string`                                |
+| `invocationMeta?` | [`Json`](extensions.md#json)            |
+
+#### Returns
+
+[`DelegationSendMeta`](#delegationsendmeta)
+
+---
+
+### delegationReplyMeta()
+
+```ts
+function delegationReplyMeta(delegation, replierName): DelegationReplyMeta;
+```
+
+The host metadata for one authenticated reply line: the replying Agent is its
+author, and the verified reply rides beside the caller's own path.
+
+#### Parameters
+
+| Parameter     | Type                                                            |
+| ------------- | --------------------------------------------------------------- |
+| `delegation`  | [`AuthenticatedDelegationReply`](#authenticateddelegationreply) |
+| `replierName` | `string`                                                        |
+
+#### Returns
+
+[`DelegationReplyMeta`](#delegationreplymeta)
+
+---
+
+### createFleetDelegation()
+
+```ts
+function createFleetDelegation(options): object;
+```
+
+Hosted BirdDog submission and Pending observation. The durable row freezes
+correspondence before transport; an ambiguous delivery reuses that exact mail.
+Shiitake owns work deduplication, execution and settlement; Post owns replies.
+
+#### Parameters
+
+| Parameter | Type                                                |
+| --------- | --------------------------------------------------- |
+| `options` | [`FleetDelegationOptions`](#fleetdelegationoptions) |
+
+#### Returns
+
+| Name                  | Type                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `authenticateReply()` | (`mail`) => \| `Readonly`\<\{ `ancestors`: readonly `string`[]; `maxDepth`: `number`; `reply`: \{ `commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`: `string`; `agentId`: `string`; `sessionId`: `string`; \}; \}\> \| `undefined` | Authenticate a reply against its frozen mail and restore the caller's path. Authenticate one arriving reply against the frozen mail this owner sent. It must be BirdDog's single reply key for that mail, mirror its sender and recipient exactly, carry BirdDog's settlement facts and, once the send's receipt is recorded, name that receipt's `commandId`. The result restores the caller's own delegation path and the verified reply; it never reads the reply's text or any settlement metadata. |
+| `recipients()`        | (`parent`, `limit`) => [`FleetRecipients`](#fleetrecipients)                                                                                                                                                                                                                                                             | One grouped read of the Agents a parent Session sent work to. The distinct Agents one parent Session sent work to, newest send first, with how many more exist past `limit`. Read-only over the frozen mail.                                                                                                                                                                                                                                                                                            |
+| `start()`             | (`grant`, `raw`) => `Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>\>                                                                                                                                                                                                                      | Submit once and return the existing Shiitake admission receipt.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `delegate()`          | (`grant`, `task`) => `Promise`\< \| `Readonly`\<\{ `kind`: `"pending"`; `retryAfterMs`: `number`; \}\> \| [`AgentDelegationOutcome`](#agentdelegationoutcome)\>                                                                                                                                                          | Submit or poll the exact turn, yielding Agar Pending until settled.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+
+---
+
+### createFleetSessions()
+
+```ts
+function createFleetSessions(open): object;
+```
+
+Addressed Session operations over the existing Shiitake client. Each operation
+checks a fresh supplied grant and releases its transport without stopping work.
+
+#### Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| `open`    | [`FleetAgentAccess`](#fleetagentaccess) |
+
+#### Returns
+
+| Name       | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Description                                                              |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `list()`   | (`grant`, `agentId`, `after?`) => `Promise`\<`Readonly`\<\{ `sessions`: readonly [`SessionSummaryRow`](client.md#sessionsummaryrow)[]; `next`: `string` \| `undefined`; \}\>\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Enumerate existing Sessions through the owner's bounded cursor.          |
+| `read()`   | (`grant`, `agentId`, `sessionId`) => `Promise`\<`Readonly`\<\{ `sessionId`: `string`; `cursor`: `string` \| `null`; `hasMore`: `boolean`; `oldestCursor?`: `string` \| `null`; `messages`: readonly `Readonly`\<\{ `meta?`: [`Json`](extensions.md#json); `origin?`: `Readonly`\<\{ `extensionId`: ...; `correlation`: ...; \}\>; `id`: `string`; `sequence`: `number`; `commandId`: `string` \| `null`; `value`: `Message`; \}\>[]; `terminals`: readonly `Readonly`\<\{ `commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"`; `sequence`: `number`; `diagnostic`: `string` \| `null`; `meta?`: [`Json`](extensions.md#json); \}\>[]; `compactions?`: readonly `Readonly`\<\{ `id`: `string`; `sequence`: `number`; `at`: `number`; `tokensBefore`: `number`; `tokensAfter`: `number` \| `null`; `trigger`: [`SessionCompactionTrigger`](client.md#sessioncompactiontrigger) \| `null`; \}\>[]; `compactionNotices?`: readonly `Readonly`\<\{ `id`: `string`; `sequence`: `number`; `at`: `number`; `trigger`: [`SessionCompactionTrigger`](client.md#sessioncompactiontrigger); `result`: `"failed"` \| `"nothing_to_compact"`; `diagnostic`: `string` \| `null`; \}\>[]; `sandboxFailures?`: readonly `object`[]; `pending`: [`SessionPendingPrompts`](client.md#sessionpendingprompts); `activity`: [`SessionActivity`](client.md#sessionactivity); `progress`: \| `Readonly`\<\{ `messageId`: `string`; `revision`: `number`; `text`: `string`; `thinking`: `string`; `textTruncated`: `boolean`; `thinkingTruncated`: `boolean`; \}\> \| `null`; `extensions`: [`SessionExtensionSlots`](client.md#sessionextensionslots); `attention`: readonly `object`[]; `context?`: `Readonly`\<\{ `tokens`: `number`; `window`: `number` \| `null`; \}\>; \}\>\> | Open the exact saved conversation without creating work.                 |
+| `create()` | (`grant`, `agentId`, `requestId`) => `Promise`\<`string`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Create a Session once under the caller's replay identity.                |
+| `remove()` | (`grant`, `agentId`, `sessionId`) => `Promise`\<`boolean`\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Remove a Session through its runtime owner.                              |
+| `send()`   | (`grant`, `agentId`, `sessionId`, `message`) => `Promise`\<\{ `status`: `"accepted"`; `commandId`: `string`; `sessionId`: `string`; \}\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Send once; an omitted Session is created under the same replay identity. |