@fungi.computer/shiitake 0.5.0 → 0.6.0

package/dist/server-visitor-stream.js

@@ -0,0 +1,115 @@
+import { SSEStreamingApi } from "hono/streaming";
+import { visitorSnapshot } from "./client-visitor.js";
+export function visitorStream(options) {
+    const { readable, writable } = new TransformStream();
+    const stream = new SSEStreamingApi(writable, readable);
+    let closing;
+    let ending = false;
+    let heartbeat;
+    const expiry = setTimeout(() => {
+        void close().catch((cause) => {
+            options.onError("channel_visitor_stream_expiry_failed", cause);
+        });
+    }, Math.max(0, options.expiresAt - options.now()));
+    const close = () => {
+        if (closing !== undefined)
+            return closing;
+        ending = true;
+        clearTimeout(expiry);
+        clearTimeout(heartbeat);
+        options.release();
+        closing = Promise.resolve().then(async () => {
+            stream.abort();
+            try {
+                await options.watch.close();
+            }
+            finally {
+                await stream.close();
+            }
+        });
+        return closing;
+    };
+    stream.onAbort(() => {
+        void close().catch((cause) => {
+            options.onError("channel_visitor_stream_close_failed", cause);
+        });
+    });
+    const admitted = async () => !ending &&
+        options.now() < options.expiresAt &&
+        (await options.canRead()) &&
+        !ending;
+    const beat = async () => {
+        if (!(await admitted())) {
+            await close();
+            return;
+        }
+        await stream.write(": heartbeat\n\n");
+        if (!ending)
+            heartbeat = setTimeout(() => {
+                void beat().catch((cause) => {
+                    options.onError("channel_visitor_stream_heartbeat_failed", cause);
+                    void close().catch((closeCause) => {
+                        options.onError("channel_visitor_stream_close_failed", closeCause);
+                    });
+                });
+            }, 30_000);
+    };
+    const publish = async (snapshot, progressOnly) => {
+        if (!(await admitted()))
+            return false;
+        const baseline = visitorSnapshot(options.filter(snapshot), options.visitorId);
+        await stream.writeSSE(progressOnly
+            ? {
+                event: "frame",
+                data: JSON.stringify({
+                    kind: "progress",
+                    progress: baseline.progress,
+                    activity: baseline.activity,
+                }),
+            }
+            : { event: "session", data: JSON.stringify(baseline) });
+        return !ending;
+    };
+    const pump = async () => {
+        try {
+            let snapshot = options.watch.snapshot;
+            if (!(await publish(snapshot, false)))
+                return;
+            heartbeat = setTimeout(() => {
+                void beat().catch((cause) => {
+                    options.onError("channel_visitor_stream_heartbeat_failed", cause);
+                    void close().catch((closeCause) => {
+                        options.onError("channel_visitor_stream_close_failed", closeCause);
+                    });
+                });
+            }, 30_000);
+            for await (const frame of options.watch.changes) {
+                if (ending)
+                    break;
+                if (frame.kind === "tool_output")
+                    continue;
+                snapshot =
+                    frame.kind === "progress"
+                        ? {
+                            ...snapshot,
+                            progress: frame.progress,
+                            activity: frame.activity,
+                        }
+                        : frame.kind === "activity"
+                            ? { ...snapshot, activity: frame.activity }
+                            : frame.kind === "reset"
+                                ? frame.baseline
+                                : await options.read();
+                if (!(await publish(snapshot, frame.kind === "progress")))
+                    break;
+            }
+        }
+        finally {
+            await close();
+        }
+    };
+    void pump().catch((cause) => {
+        options.onError("channel_visitor_stream_failed", cause);
+    });
+    return stream.responseReadable.pipeThrough(new TransformStream());
+}

package/dist/session-attention.d.ts

@@ -1,7 +1,21 @@
 import * as Schema from "effect/Schema";
+/**
+ * The Agent Session that sent the work an item belongs to. The host derives it
+ * from the accepted mail; it is the only party the item waits on until it is
+ * escalated.
+ */
+export declare const AttentionRecipientSchema: Schema.Struct<{
+    readonly agentId: Schema.NonEmptyString;
+    readonly sessionId: Schema.NonEmptyString;
+    readonly name: Schema.NonEmptyString;
+}>;
+/** Decoded Agent Session an attention item waits on. */
+export type AttentionRecipient = typeof AttentionRecipientSchema.Type;
 /**
  * An extension-owned request for human attention; expiry is owned by its timer.
  * Items marked `inbox: false` remain visible without changing the inbox state.
+ * An item with `waitingOn` waits on that Agent first and is never a person's
+ * inbox item until it is escalated past every Agent.
  */
 export declare const AttentionItemSchema: Schema.Struct<{
     readonly id: Schema.NonEmptyString;
@@ -11,6 +25,12 @@ export declare const AttentionItemSchema: Schema.Struct<{
     readonly expiresAt: Schema.optional<Schema.Int>;
     /** This item does not change the Session's inbox state; omission does. */
     readonly inbox: Schema.optional<Schema.Literal<false>>;
+    /** The Agent this item waits on; absent means a person. */
+    readonly waitingOn: Schema.optional<Schema.Struct<{
+        readonly agentId: Schema.NonEmptyString;
+        readonly sessionId: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>>;
 }>;
 /** Input to the granted attention door, scoped to the calling extension. */
 export type AttentionItem = typeof AttentionItemSchema.Type;
@@ -23,6 +43,11 @@ export declare const SessionAttentionSchema: Schema.Struct<{
     readonly since: Schema.Int;
     readonly expiresAt: Schema.optional<Schema.Int>;
     readonly inbox: Schema.optional<Schema.Literal<false>>;
+    readonly waitingOn: Schema.optional<Schema.Struct<{
+        readonly agentId: Schema.NonEmptyString;
+        readonly sessionId: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>>;
 }>;
 /** One open attention item in a Session observation. */
 export type SessionAttention = typeof SessionAttentionSchema.Type;
@@ -39,4 +64,9 @@ export declare const SessionAttentionListSchema: Schema.$Array<Schema.Struct<{
     readonly since: Schema.Int;
     readonly expiresAt: Schema.optional<Schema.Int>;
     readonly inbox: Schema.optional<Schema.Literal<false>>;
+    readonly waitingOn: Schema.optional<Schema.Struct<{
+        readonly agentId: Schema.NonEmptyString;
+        readonly sessionId: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>>;
 }>>;

package/dist/session-attention.js

@@ -1,9 +1,21 @@
 import * as Schema from "effect/Schema";
 const identity = Schema.NonEmptyString.check(Schema.isMaxLength(256));
 const instant = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/**
+ * The Agent Session that sent the work an item belongs to. The host derives it
+ * from the accepted mail; it is the only party the item waits on until it is
+ * escalated.
+ */
+export const AttentionRecipientSchema = Schema.Struct({
+    agentId: identity,
+    sessionId: identity,
+    name: identity,
+});
 /**
  * An extension-owned request for human attention; expiry is owned by its timer.
  * Items marked `inbox: false` remain visible without changing the inbox state.
+ * An item with `waitingOn` waits on that Agent first and is never a person's
+ * inbox item until it is escalated past every Agent.
  */
 export const AttentionItemSchema = Schema.Struct({
     id: identity,
@@ -13,6 +25,8 @@ export const AttentionItemSchema = Schema.Struct({
     expiresAt: Schema.optional(instant),
     /** This item does not change the Session's inbox state; omission does. */
     inbox: Schema.optional(Schema.Literal(false)),
+    /** The Agent this item waits on; absent means a person. */
+    waitingOn: Schema.optional(AttentionRecipientSchema),
 });
 /** Public identity includes the owner so two extensions can use the same id. */
 export const SessionAttentionSchema = AttentionItemSchema.mapFields((fields) => ({

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