@fungi.computer/shiitake 0.4.0 → 0.6.0

package/docs/api/agent-control.md

@@ -75,8 +75,9 @@ readonly reason:
 ### AgentCreateRefused
 
 A host's refusal of an Agent creating an Agent: the creator asked to give the
-created Agent more than it holds, or the host cannot tell which Agent is
-creating. It reaches the caller as an `agents.create` failure.
+created Agent more than it holds, the host cannot tell which Agent is creating,
+or the request id belongs to another creating Agent or Session. It reaches the
+caller as an `agents.create` failure.
 
 #### Extends
 
@@ -92,10 +93,10 @@ new AgentCreateRefused(reason, message): AgentCreateRefused;
 
 ###### Parameters
 
-| Parameter | Type                                  |
-| --------- | ------------------------------------- |
-| `reason`  | `"exceeds_creator"` \| `"no_creator"` |
-| `message` | `string`                              |
+| Parameter | Type                                                          |
+| --------- | ------------------------------------------------------------- |
+| `reason`  | `"exceeds_creator"` \| `"no_creator"` \| `"request_conflict"` |
+| `message` | `string`                                                      |
 
 ###### Returns
 
@@ -124,11 +125,62 @@ Error.name;
 ##### reason
 
 ```ts
-readonly reason: "exceeds_creator" | "no_creator";
+readonly reason: "exceeds_creator" | "no_creator" | "request_conflict";
 ```
 
 ## Type Aliases
 
+### AgentControlAnswerInput
+
+```ts
+type AgentControlAnswerInput = Readonly<{
+  agentId: string;
+  sessionId: string;
+  askId: string;
+  requestId: string;
+  answers: MyceliumJsonValue;
+}>;
+```
+
+Sender-authenticated submission for one child Session's routed Ask.
+
+---
+
+### AgentControlEscalateInput
+
+```ts
+type AgentControlEscalateInput = Readonly<{
+  agentId: string;
+  sessionId: string;
+  itemId: string;
+  note?: string;
+}>;
+```
+
+Sender-authenticated escalation of one item a child Session left waiting.
+
+---
+
+### AgentControlAnswerOutput
+
+```ts
+type AgentControlAnswerOutput = z.infer<typeof answerOutput>;
+```
+
+Typed outcome of a sender's answer to a child Ask.
+
+---
+
+### AgentControlEscalateOutput
+
+```ts
+type AgentControlEscalateOutput = z.infer<typeof escalateOutput>;
+```
+
+Typed outcome of a sender's escalation of a child's item.
+
+---
+
 ### ArchiveRefusalReason
 
 ```ts
@@ -173,10 +225,16 @@ One host-offered model usable as an Agent's create or setModel choice.
 ```ts
 type AgentDelegationInput = Readonly<{
   agentId: string;
-  sessionId: string;
   text: string;
   requestId: string;
-  delivery: "steer" | "followUp";
+}> &
+  | Readonly<{
+  sessionId: string;
+  delivery: "steer";
+}>
+  | Readonly<{
+  sessionId?: string;
+  delivery: "followUp";
 }>;
 ```
 
@@ -226,6 +284,16 @@ type AgentControlDirectory = Readonly<{
     invocation?,
   ) => Promise<Accepted | Held>;
   recall?: (input, sourceSessionId, signal) => Promise<CancelResult>;
+  answer?: (
+    input,
+    senderSessionId,
+    signal,
+  ) => Promise<AgentControlAnswerOutput>;
+  escalate?: (
+    input,
+    senderSessionId,
+    signal,
+  ) => Promise<AgentControlEscalateOutput>;
   create?: (input, signal) => Promise<AgentControlAgent>;
   setModel?: (input, signal) => Promise<void>;
   archive?: (input, signal) => Promise<void>;
@@ -248,6 +316,126 @@ Host-owned discovery and per-operation access to ordinary Agents.
 
 ## Variables
 
+### answerOutput
+
+```ts
+const answerOutput: ZodDiscriminatedUnion<
+  [
+    ZodObject<
+      {
+        status: ZodLiteral<"answered">;
+        via: ZodEnum<{
+          in_turn: "in_turn";
+          follow_up: "follow_up";
+        }>;
+        commandId: ZodExactOptional<ZodString>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        status: ZodLiteral<"not_found">;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        status: ZodLiteral<"closed">;
+        reason: ZodEnum<{
+          cancelled: "cancelled";
+          undeliverable: "undeliverable";
+          answered: "answered";
+          declined: "declined";
+          withdrawn: "withdrawn";
+          expired: "expired";
+        }>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        status: ZodLiteral<"refused">;
+        reason: ZodEnum<{
+          not_sender: "not_sender";
+          no_provenance: "no_provenance";
+        }>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        status: ZodLiteral<"unavailable">;
+        reason: ZodLiteral<"unsupported">;
+      },
+      $strict
+    >,
+  ],
+  "status"
+>;
+```
+
+Typed outcome of a sender's answer to a child Ask.
+
+---
+
+### escalateOutput
+
+```ts
+const escalateOutput: ZodDiscriminatedUnion<
+  [
+    ZodObject<
+      {
+        status: ZodLiteral<"escalated">;
+        to: ZodLiteral<"person">;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        status: ZodLiteral<"not_found">;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        status: ZodLiteral<"closed">;
+        reason: ZodEnum<{
+          cancelled: "cancelled";
+          undeliverable: "undeliverable";
+          answered: "answered";
+          declined: "declined";
+          withdrawn: "withdrawn";
+          expired: "expired";
+        }>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        status: ZodLiteral<"refused">;
+        reason: ZodEnum<{
+          not_sender: "not_sender";
+          no_provenance: "no_provenance";
+        }>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        status: ZodLiteral<"unavailable">;
+        reason: ZodLiteral<"unsupported">;
+      },
+      $strict
+    >,
+  ],
+  "status"
+>;
+```
+
+Typed outcome of a sender's escalation of a child's item.
+
+---
+
 ### archiveRefusalReasons
 
 ```ts
@@ -279,10 +467,16 @@ function waitForAgentSettlement(
 ): Promise<
   Readonly<{
     acceptedSender: string | null;
+    delegator: string | null;
     terminal: SessionTerminal;
     content: string;
     usage: readonly Pick<AssistantMessage, "model" | "provider" | "usage">[];
     toolCalls: number;
+    waitingOnYou: readonly Readonly<{
+      itemId: string;
+      kind: string;
+      summary: string;
+    }>[];
   }>
 >;
 ```
@@ -301,10 +495,12 @@ Await one exact durable terminal without opening a transcript observation.
 
 #### Returns
 
-`Promise`\<`Readonly`\<\{ `acceptedSender`: `string` \| `null`; `terminal`:
-[`SessionTerminal`](client.md#sessionterminal); `content`: `string`; `usage`:
-readonly `Pick`\<`AssistantMessage`, `"model"` \| `"provider"` \| `"usage"`\>[];
-`toolCalls`: `number`; \}\>\>
+`Promise`\<`Readonly`\<\{ `acceptedSender`: `string` \| `null`; `delegator`:
+`string` \| `null`; `terminal`: [`SessionTerminal`](client.md#sessionterminal);
+`content`: `string`; `usage`: readonly `Pick`\<`AssistantMessage`, `"model"` \|
+`"provider"` \| `"usage"`\>[]; `toolCalls`: `number`; `waitingOnYou`: readonly
+`Readonly`\<\{ `itemId`: `string`; `kind`: `string`; `summary`: `string`;
+\}\>[]; \}\>\>
 
 ---
 

package/docs/api/client-entry.md

@@ -172,6 +172,7 @@ const clientTimelineCellSchemaV1: Struct<{
         id: String;
         label: String;
         input: optional<$Record<..., ...>>;
+        awaiting: optionalKey<Literal<...>>;
      }>>>;
   }>>;
 }>;
@@ -222,6 +223,7 @@ const clientContributionSchemaV1: Struct<{
         id: String;
         label: String;
         input: optional<$Record<..., ...>>;
+        awaiting: optionalKey<Literal<...>>;
      }>>>;
      inspection: optionalKey<Struct<{
         commandId: String;
@@ -261,6 +263,7 @@ const clientContributionSchemaV1: Struct<{
         id: String;
         label: String;
         input: optional<$Record<String, Codec<Json, Json, never, never>>>;
+        awaiting: optionalKey<Literal<"question">>;
      }>;
   }>>;
 }>;

package/docs/api/client.md

@@ -10,12 +10,57 @@
 
 ## Type Aliases
 
+### ParticipantPolicy
+
+```ts
+type ParticipantPolicy = Readonly<{
+  turnIsCurrent: (sessionId, commandId) => boolean;
+  deliverAgentReply: (sessionId, commandId, reply) => boolean;
+}>;
+```
+
+The host decides which Agent work may be delivered to this participant.
+
+---
+
+### VisitorView
+
+```ts
+type VisitorView = Readonly<{
+  status: "idle" | "working";
+  lines: readonly Readonly<{
+    id: string;
+    from: "visitor" | "agent" | "operator";
+    text: string;
+  }>[];
+  progress: string | null;
+}>;
+```
+
+What a visitor may see of their own conversation Session.
+
+---
+
+### VisitorPendingPrompt
+
+```ts
+type VisitorPendingPrompt = Pick<
+  SessionPendingPrompt,
+  "commandId" | "requestId" | "text" | "delivery" | "images"
+>;
+```
+
+Public pending facts exclude the host's private metadata and admission origin.
+
+---
+
 ### Accepted
 
 ```ts
 type Accepted = Readonly<{
   status: "accepted";
   commandId: string;
+  sessionId?: string;
 }>;
 ```
 
@@ -115,6 +160,7 @@ type SessionCommandHandler = {
     Readonly<{
       status: "accepted";
       commandId: string;
+      sessionId?: string;
     }>
   >;
   (input): Promise<CancelResult>;
@@ -142,6 +188,7 @@ Execute one retained type-discriminated Session command.
 (input): Promise<Readonly<{
   status: "accepted";
   commandId: string;
+  sessionId?: string;
 }>>;
 ```
 
@@ -155,7 +202,8 @@ Accept a prompt or a compaction request as queued Session work.
 
 ##### Returns
 
-`Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>\>
+`Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`;
+`sessionId?`: `string`; \}\>\>
 
 #### Call Signature
 
@@ -978,6 +1026,93 @@ A delegated send is accepted by its owner or held in durable mail custody.
 
 ## Functions
 
+### participantSnapshot()
+
+```ts
+function participantSnapshot(snapshot, owner): SessionSnapshot;
+```
+
+Filter participant delivery only; the holder's stored Session is unchanged.
+
+#### Parameters
+
+| Parameter  | Type                                      |
+| ---------- | ----------------------------------------- |
+| `snapshot` | [`SessionSnapshot`](#sessionsnapshot)     |
+| `owner`    | [`ParticipantPolicy`](#participantpolicy) |
+
+#### Returns
+
+[`SessionSnapshot`](#sessionsnapshot)
+
+---
+
+### visitorPendingPrompt()
+
+```ts
+function visitorPendingPrompt(prompt, visitorId): VisitorPendingPrompt;
+```
+
+Project one owner-selected prompt without exposing host identity or correlation
+metadata.
+
+#### Parameters
+
+| Parameter   | Type                                            |
+| ----------- | ----------------------------------------------- |
+| `prompt`    | [`SessionPendingPrompt`](#sessionpendingprompt) |
+| `visitorId` | `string`                                        |
+
+#### Returns
+
+[`VisitorPendingPrompt`](#visitorpendingprompt)
+
+---
+
+### visitorSnapshot()
+
+```ts
+function visitorSnapshot(snapshot, visitorId): SessionSnapshot;
+```
+
+Visitor-scoped Session facts use the visitor's public address, never the
+internal Session ID.
+
+#### Parameters
+
+| Parameter   | Type                                  |
+| ----------- | ------------------------------------- |
+| `snapshot`  | [`SessionSnapshot`](#sessionsnapshot) |
+| `visitorId` | `string`                              |
+
+#### Returns
+
+[`SessionSnapshot`](#sessionsnapshot)
+
+---
+
+### visitorView()
+
+```ts
+function visitorView(snapshot, visitorId): VisitorView;
+```
+
+Project only this visitor's host-attributed prompts, their replies, and explicit
+operator replies.
+
+#### Parameters
+
+| Parameter   | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `snapshot`  | \| `Readonly`\<\{ `sessionId`: `string`; `cursor`: `string` \| `null`; `hasMore`: `boolean`; `oldestCursor?`: `string` \| `null`; `messages`: readonly `Readonly`\<\{ `requestId?`: `string`; `meta?`: [`Json`](extensions.md#json); `data?`: [`Json`](extensions.md#json); `origin?`: `Readonly`\<\{ `extensionId`: `string`; `correlation`: `string` \| `null`; \}\>; `id`: `string`; `sequence`: `number`; `commandId`: `string` \| `null`; `value`: [`ModelMessage`](#modelmessage); \}\>[]; `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`](#sessioncompactiontrigger) \| `null`; \}\>[]; `compactionNotices?`: readonly `Readonly`\<\{ `id`: `string`; `sequence`: `number`; `at`: `number`; `trigger`: [`SessionCompactionTrigger`](#sessioncompactiontrigger); `result`: `"failed"` \| `"nothing_to_compact"` \| `"stale"` \| `"insufficient"`; `diagnostic`: `string` \| `null`; \}\>[]; `sandboxFailures?`: readonly `object`[]; `pending`: [`SessionPendingPrompts`](#sessionpendingprompts); `activity`: [`SessionActivity`](#sessionactivity); `progress`: \| `Readonly`\<\{ `messageId`: `string`; `revision`: `number`; `text`: `string`; `thinking`: `string`; `textTruncated`: `boolean`; `thinkingTruncated`: `boolean`; \}\> \| `null`; `toolOutput`: readonly `Readonly`\<\{ `toolCallId`: `string`; `revision`: `number`; `tail`: `string`; `droppedBytes`: `number`; `totalBytes`: `number`; \}\>[]; `extensions`: [`SessionExtensionSlots`](#sessionextensionslots); `attention`: readonly `object`[]; `context?`: `Readonly`\<\{ `tokens`: `number`; `window`: `number` \| `null`; \}\>; \}\> \| `null` |
+| `visitorId` | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+#### Returns
+
+[`VisitorView`](#visitorview)
+
+---
+
 ### parseDelegationReceipt()
 
 ```ts

package/docs/api/cloudflare.md

@@ -428,7 +428,13 @@ type CloudflareShiitake = ShiitakeOwnerAgent &
       sessionId,
       commandId,
     ) => Promise<CommandSettlement | undefined>;
-    acceptMail: (mail, meta?, reply?) => Promise<Accepted>;
+    acceptMail: (
+      mail,
+      meta?,
+      reply?,
+      stageAcceptedNotice?,
+      sessionGrantDelivery?,
+    ) => Promise<Accepted>;
     alarm: () => Promise<void>;
     activeSessions: () => Promise<readonly string[]>;
     abortActive: () => Promise<void>;