@fungi.computer/shiitake-extensions 0.3.0 → 0.5.0

package/dist/subagents/contract.d.ts

@@ -2,11 +2,12 @@ import * as Schema from "effect/Schema";
 /** The most Agents one conversation's footer lists; the rest are counted. */
 export declare const maximumSubagents = 16;
 /**
- * What the human sees for one ordinary created Agent. `waiting` is any open attention on
- * its conversation (a question or a tool approval); `unavailable` means its
- * status could not be read, and is never shown as idle.
+ * What the human sees for one ordinary created Agent. `waiting_on_agent` is an
+ * open question that waits on the Agent that sent the work, calm until it is
+ * escalated; `needs_you` is attention that waits on a person; `unavailable`
+ * means its status could not be read, and is never shown as idle.
  */
-export declare const SubagentState: Schema.Literals<readonly ["working", "waiting", "idle", "failed", "unavailable"]>;
+export declare const SubagentState: Schema.Literals<readonly ["working", "waiting_on_agent", "needs_you", "idle", "failed", "unavailable"]>;
 /** Display state of one created Agent's conversation. */
 export type SubagentState = typeof SubagentState.Type;
 /** A footer row for an ordinary Agent created by this Agent, never merely sent work. */
@@ -18,9 +19,27 @@ export declare const Subagent: Schema.Struct<{
     /** Its latest conversation; null when it has none. */
     readonly sessionId: Schema.NullOr<Schema.String>;
     /** Observed conversation state, including unreadable status. */
-    readonly state: Schema.Literals<readonly ["working", "waiting", "idle", "failed", "unavailable"]>;
-    /** The child's own summary of what waits on the human, when waiting. */
+    readonly state: Schema.Literals<readonly ["working", "waiting_on_agent", "needs_you", "idle", "failed", "unavailable"]>;
+    /** The child's own summary of what it waits on, when waiting. */
     readonly attention: Schema.optionalKey<Schema.String>;
+    /** Display name of the Agent a `waiting_on_agent` child waits on. */
+    readonly waitingOn: Schema.optionalKey<Schema.String>;
+    /** The question a waiting child asks, so a person can answer from here. */
+    readonly ask: Schema.optionalKey<Schema.Struct<{
+        /** Durable identity of the child's open Ask. */
+        readonly askId: Schema.String;
+        /** The decisions the child asks, so they can be answered from here. */
+        readonly questions: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly header: Schema.String;
+            readonly question: Schema.String;
+            readonly options: Schema.$Array<Schema.Struct<{
+                readonly label: Schema.String;
+                readonly description: Schema.String;
+            }>>;
+            readonly multiple: Schema.optionalKey<Schema.Boolean>;
+        }>>;
+    }>>;
 }>;
 /** Decoded footer row for a created Agent. */
 export type Subagent = typeof Subagent.Type;
@@ -39,9 +58,27 @@ export declare const SubagentsProjection: Schema.Struct<{
         /** Its latest conversation; null when it has none. */
         readonly sessionId: Schema.NullOr<Schema.String>;
         /** Observed conversation state, including unreadable status. */
-        readonly state: Schema.Literals<readonly ["working", "waiting", "idle", "failed", "unavailable"]>;
-        /** The child's own summary of what waits on the human, when waiting. */
+        readonly state: Schema.Literals<readonly ["working", "waiting_on_agent", "needs_you", "idle", "failed", "unavailable"]>;
+        /** The child's own summary of what it waits on, when waiting. */
         readonly attention: Schema.optionalKey<Schema.String>;
+        /** Display name of the Agent a `waiting_on_agent` child waits on. */
+        readonly waitingOn: Schema.optionalKey<Schema.String>;
+        /** The question a waiting child asks, so a person can answer from here. */
+        readonly ask: Schema.optionalKey<Schema.Struct<{
+            /** Durable identity of the child's open Ask. */
+            readonly askId: Schema.String;
+            /** The decisions the child asks, so they can be answered from here. */
+            readonly questions: Schema.$Array<Schema.Struct<{
+                readonly id: Schema.String;
+                readonly header: Schema.String;
+                readonly question: Schema.String;
+                readonly options: Schema.$Array<Schema.Struct<{
+                    readonly label: Schema.String;
+                    readonly description: Schema.String;
+                }>>;
+                readonly multiple: Schema.optionalKey<Schema.Boolean>;
+            }>>;
+        }>>;
     }>>;
     /** Additional created Agents not included in the visible rows. */
     readonly more: Schema.Int;
@@ -50,6 +87,33 @@ export declare const SubagentsProjection: Schema.Struct<{
 }>;
 /** Decoded list and expansion state projected into the footer. */
 export type SubagentsProjection = typeof SubagentsProjection.Type;
+/**
+ * The question flow's own steps, each naming the child whose Ask they answer.
+ * The footer owns the conversation; the child's question owner commits it.
+ */
+export declare const AnswerChildInput: Schema.Union<Schema.Struct<{
+    readonly agentId: Schema.String;
+    readonly sessionId: Schema.String;
+    readonly answer: Schema.Struct<{
+        readonly selected: Schema.$Array<Schema.String>;
+        readonly text: Schema.optionalKey<Schema.String>;
+    }>;
+    readonly askId: Schema.String;
+    readonly requestId: Schema.String;
+    readonly index: Schema.Number;
+    readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly selected: Schema.$Array<Schema.String>;
+        readonly text: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly stage: Schema.Literal<"decision">;
+} | {
+    readonly agentId: Schema.String;
+    readonly sessionId: Schema.String;
+    readonly askId: Schema.String;
+} | {
+    readonly agentId: Schema.String;
+    readonly sessionId: Schema.String;
+}>[]>;
 /** Created-Agent footer control and its visible projection. */
 export declare const subagentsContract: {
     /** Stable extension identity. */
@@ -65,6 +129,37 @@ export declare const subagentsContract: {
             /** Return the server-owned human control step. */
             output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
         };
+        /** Answer a question an escalated sub-agent asks, from this conversation. */
+        answerChild: {
+            /** The Session owns its footer. */
+            scope: "session";
+            /** The next step of the child's answer conversation. */
+            input: Schema.Union<Schema.Struct<{
+                readonly agentId: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly answer: Schema.Struct<{
+                    readonly selected: Schema.$Array<Schema.String>;
+                    readonly text: Schema.optionalKey<Schema.String>;
+                }>;
+                readonly askId: Schema.String;
+                readonly requestId: Schema.String;
+                readonly index: Schema.Number;
+                readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+                    readonly selected: Schema.$Array<Schema.String>;
+                    readonly text: Schema.optionalKey<Schema.String>;
+                }>>;
+                readonly stage: Schema.Literal<"decision">;
+            } | {
+                readonly agentId: Schema.String;
+                readonly sessionId: Schema.String;
+                readonly askId: Schema.String;
+            } | {
+                readonly agentId: Schema.String;
+                readonly sessionId: Schema.String;
+            }>[]>;
+            /** Return the next human conversation step. */
+            output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
+        };
     };
     /** Footer rows and expansion state. */
     readonly projection: {
@@ -79,9 +174,27 @@ export declare const subagentsContract: {
                 /** Its latest conversation; null when it has none. */
                 readonly sessionId: Schema.NullOr<Schema.String>;
                 /** Observed conversation state, including unreadable status. */
-                readonly state: Schema.Literals<readonly ["working", "waiting", "idle", "failed", "unavailable"]>;
-                /** The child's own summary of what waits on the human, when waiting. */
+                readonly state: Schema.Literals<readonly ["working", "waiting_on_agent", "needs_you", "idle", "failed", "unavailable"]>;
+                /** The child's own summary of what it waits on, when waiting. */
                 readonly attention: Schema.optionalKey<Schema.String>;
+                /** Display name of the Agent a `waiting_on_agent` child waits on. */
+                readonly waitingOn: Schema.optionalKey<Schema.String>;
+                /** The question a waiting child asks, so a person can answer from here. */
+                readonly ask: Schema.optionalKey<Schema.Struct<{
+                    /** Durable identity of the child's open Ask. */
+                    readonly askId: Schema.String;
+                    /** The decisions the child asks, so they can be answered from here. */
+                    readonly questions: Schema.$Array<Schema.Struct<{
+                        readonly id: Schema.String;
+                        readonly header: Schema.String;
+                        readonly question: Schema.String;
+                        readonly options: Schema.$Array<Schema.Struct<{
+                            readonly label: Schema.String;
+                            readonly description: Schema.String;
+                        }>>;
+                        readonly multiple: Schema.optionalKey<Schema.Boolean>;
+                    }>>;
+                }>>;
             }>>;
             /** Additional created Agents not included in the visible rows. */
             readonly more: Schema.Int;

package/dist/subagents/contract.js

@@ -1,17 +1,20 @@
 import { ExtensionId, } from "@fungi.computer/shiitake/extensions";
 import * as Schema from "effect/Schema";
 import { CatalogStep } from "../internal/catalog.js";
+import { AnswerFlowInput, Questions } from "../question/contract.js";
 const identity = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
 /** The most Agents one conversation's footer lists; the rest are counted. */
 export const maximumSubagents = 16;
 /**
- * What the human sees for one ordinary created Agent. `waiting` is any open attention on
- * its conversation (a question or a tool approval); `unavailable` means its
- * status could not be read, and is never shown as idle.
+ * What the human sees for one ordinary created Agent. `waiting_on_agent` is an
+ * open question that waits on the Agent that sent the work, calm until it is
+ * escalated; `needs_you` is attention that waits on a person; `unavailable`
+ * means its status could not be read, and is never shown as idle.
  */
 export const SubagentState = Schema.Literals([
     "working",
-    "waiting",
+    "waiting_on_agent",
+    "needs_you",
     "idle",
     "failed",
     "unavailable",
@@ -26,8 +29,17 @@ export const Subagent = Schema.Struct({
     sessionId: Schema.NullOr(identity),
     /** Observed conversation state, including unreadable status. */
     state: SubagentState,
-    /** The child's own summary of what waits on the human, when waiting. */
+    /** The child's own summary of what it waits on, when waiting. */
     attention: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(200))),
+    /** Display name of the Agent a `waiting_on_agent` child waits on. */
+    waitingOn: Schema.optionalKey(identity),
+    /** The question a waiting child asks, so a person can answer from here. */
+    ask: Schema.optionalKey(Schema.Struct({
+        /** Durable identity of the child's open Ask. */
+        askId: identity,
+        /** The decisions the child asks, so they can be answered from here. */
+        questions: Questions,
+    })),
 });
 /**
  * This Agent's created Agents and how many are not listed.
@@ -42,6 +54,18 @@ export const SubagentsProjection = Schema.Struct({
     /** Whether individual rows are expanded instead of summarized. */
     expanded: Schema.Boolean,
 });
+/** One child, as an answer step names it beside the draft it advances. */
+const child = {
+    /** Identity of the child Agent whose Ask is being answered. */
+    agentId: identity,
+    /** The child's conversation that holds the Ask. */
+    sessionId: identity,
+};
+/**
+ * The question flow's own steps, each naming the child whose Ask they answer.
+ * The footer owns the conversation; the child's question owner commits it.
+ */
+export const AnswerChildInput = Schema.Union(AnswerFlowInput.members.map((member) => Schema.Struct({ ...member.fields, ...child })));
 /** The human `/agents` command: a bare call expands or collapses the footer rows. */
 const commands = {
     /** Toggle the created-Agent footer between expanded and summarized views. */
@@ -53,6 +77,15 @@ const commands = {
         /** Return the server-owned human control step. */
         output: CatalogStep,
     },
+    /** Answer a question an escalated sub-agent asks, from this conversation. */
+    answerChild: {
+        /** The Session owns its footer. */
+        scope: "session",
+        /** The next step of the child's answer conversation. */
+        input: AnswerChildInput,
+        /** Return the next human conversation step. */
+        output: CatalogStep,
+    },
 };
 /** Created-Agent footer control and its visible projection. */
 export const subagentsContract = {

package/dist/subagents/host.d.ts

@@ -14,7 +14,7 @@ export type SubagentAgent = Readonly<{
     /** Read the child's owner-ordered conversation summaries. */
     listSessions: ShiitakeAgent["listSessions"];
     /** Open the read-only view of a selected child conversation. */
-    session: (sessionId: string) => Pick<ShiitakeSession, "read" | "readSettlement">;
+    session: (sessionId: string) => Pick<ShiitakeSession, "read" | "readSettlement" | "extension">;
 }>;
 /**
  * The host's read-only facts. `read` returns ordinary created Agents,
@@ -44,10 +44,8 @@ export type SubagentSource = Readonly<{
 export type SubagentTiming = Readonly<{
     /** A watcher's read refreshes rows at least this old. */
     refreshMs: number;
-    /** While a row is working or waiting, rows refresh this often. */
+    /** While a live view watches a working or waiting row, refresh this often. */
     pollMs: number;
-    /** Polling stops once no watcher has read the Session this long. */
-    interestMs: number;
 }>;
 /** Host admission for the read-only created-Agent footer and human toggle. */
 export declare const subagentsGrant: ExtensionGrantV0;

package/dist/subagents/host.js

@@ -1,14 +1,16 @@
 import { defineExtension, } from "@fungi.computer/shiitake/extensions";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 import { catalog, done } from "../internal/catalog.js";
+import { advanceAnswerFlow } from "../question/answer-flow.js";
+import { AskProjection, questionContract } from "../question/contract.js";
 import { maximumSubagents, subagentsContract, } from "./contract.js";
 const defaultTiming = Object.freeze({
     refreshMs: 1_000,
     pollMs: 5_000,
-    interestMs: 30_000,
 });
-/** Sessions whose rows are held at once; the least recently read go first. */
+/** Sessions held at once; evict unwatched rows first, then least recently read. */
 const cachedSessions = 64;
 /** Owner pages scanned for one child's row: 400 conversations. */
 const statusPages = 2;
@@ -19,7 +21,7 @@ export const subagentsGrant = {
 };
 const settledState = {
     running: "working",
-    needs_you: "waiting",
+    needs_you: "needs_you",
     done: "idle",
     errored: "failed",
 };
@@ -56,15 +58,44 @@ async function status(source, record, signal) {
             if (row === undefined || row.state === "unavailable")
                 return { ...base, state: "unavailable" };
             const selected = { ...base, sessionId: row.sessionId };
-            if (row.state !== "needs_you")
+            if (row.state === "running" || row.state === "errored")
                 return { ...selected, state: settledState[row.state] };
+            // An item waiting on an Agent is calm and leaves the inbox state alone,
+            // so a finished child is read for it too. Escalated items wait on a person.
             const snapshot = await opened.agent
                 .session(row.sessionId)
                 .read({ limit: 1 });
-            const attention = snapshot.attention[0]?.summary;
-            return attention === undefined
-                ? { ...selected, state: "waiting" }
-                : { ...selected, state: "waiting", attention };
+            const slot = snapshot.extensions[questionContract.id];
+            const asked = slot?.status === "running"
+                ? Schema.decodeUnknownOption(AskProjection)(slot.value)
+                : Option.none();
+            const openAsks = Option.isSome(asked) ? asked.value.asks : [];
+            const routed = snapshot.attention.find((item) => item.waitingOn);
+            if (routed?.waitingOn !== undefined) {
+                const waiting = {
+                    ...selected,
+                    state: "waiting_on_agent",
+                    attention: routed.summary,
+                    waitingOn: routed.waitingOn.name,
+                };
+                // A person may always answer first; the calm row offers it too.
+                const routedAsk = openAsks.find((open) => open.askId === routed.id);
+                return routedAsk === undefined
+                    ? waiting
+                    : {
+                        ...waiting,
+                        ask: { askId: routedAsk.askId, questions: routedAsk.questions },
+                    };
+            }
+            const attention = snapshot.attention.find((item) => item.inbox !== false)?.summary;
+            if (row.state === "done")
+                return { ...selected, state: "idle" };
+            const ask = openAsks.find((open) => open.waitingOn === undefined);
+            const needing = { ...selected, state: "needs_you" };
+            const summary = attention === undefined ? needing : { ...needing, attention };
+            return ask === undefined
+                ? summary
+                : { ...summary, ask: { askId: ask.askId, questions: ask.questions } };
         }
         finally {
             await opened.release();
@@ -76,19 +107,34 @@ async function status(source, record, signal) {
         return { ...base, state: "unavailable" };
     }
 }
-const live = (value) => value?.agents.some((agent) => agent.state === "working" || agent.state === "waiting") === true;
+const live = (value) => value?.agents.some((agent) => agent.state === "working" ||
+    agent.state === "waiting_on_agent" ||
+    agent.state === "needs_you") === true;
 /**
  * One activation's in-memory rows. A watcher's projection read refreshes
- * stale rows outside the snapshot transaction; a changed or still-live result
- * publishes one observation, whose re-read keeps interest alive.
+ * stale rows outside the snapshot transaction. Only changed rows publish;
+ * only an actual live-view registration keeps polling alive.
  */
-function createRoster(source, timing, publish) {
+function createRoster(source, timing, publish, isObserved) {
     const entries = new Map();
     const lifetime = new AbortController();
     function forget(sessionId) {
         clearTimeout(entries.get(sessionId)?.timer);
         entries.delete(sessionId);
     }
+    function schedule(sessionId, entry) {
+        if (!lifetime.signal.aborted &&
+            entries.get(sessionId) === entry &&
+            entry.timer === undefined &&
+            !entry.refreshing &&
+            live(entry.value) &&
+            isObserved(sessionId))
+            entry.timer = setTimeout(() => {
+                entry.timer = undefined;
+                if (isObserved(sessionId))
+                    void refresh(sessionId, entry);
+            }, timing.pollMs);
+    }
     async function refresh(sessionId, entry) {
         entry.refreshing = true;
         clearTimeout(entry.timer);
@@ -103,7 +149,7 @@ function createRoster(source, timing, publish) {
             };
             const changed = JSON.stringify(value) !== JSON.stringify(entry.value);
             entry.value = value;
-            if (!lifetime.signal.aborted && (changed || live(value)))
+            if (!lifetime.signal.aborted && changed)
                 await publish(sessionId);
         }
         catch (cause) {
@@ -113,13 +159,7 @@ function createRoster(source, timing, publish) {
             entry.refreshedAt = Date.now();
             entry.refreshing = false;
         }
-        if (!lifetime.signal.aborted &&
-            entries.get(sessionId) === entry &&
-            live(entry.value) &&
-            Date.now() - entry.readAt < timing.interestMs)
-            entry.timer = setTimeout(() => {
-                void refresh(sessionId, entry);
-            }, timing.pollMs);
+        schedule(sessionId, entry);
     }
     return {
         /** Flip whether the footer lists the rows; undefined while there is nothing to list. */
@@ -144,7 +184,8 @@ function createRoster(source, timing, publish) {
                 };
                 entries.set(sessionId, entry);
                 if (entries.size > cachedSessions) {
-                    const oldest = [...entries].sort(([, left], [, right]) => left.readAt - right.readAt)[0];
+                    const oldest = [...entries].sort(([leftId, left], [rightId, right]) => Number(isObserved(leftId)) - Number(isObserved(rightId)) ||
+                        left.readAt - right.readAt)[0];
                     if (oldest !== undefined)
                         forget(oldest[0]);
                 }
@@ -152,10 +193,46 @@ function createRoster(source, timing, publish) {
             entry.readAt = now;
             if (!entry.refreshing && now - entry.refreshedAt >= timing.refreshMs)
                 void refresh(sessionId, entry);
+            else
+                schedule(sessionId, entry);
             return entry.value === undefined
                 ? undefined
                 : { ...entry.value, expanded: entry.expanded };
         },
+        /** The last read of one child of this conversation, if it is listed. */
+        child(sessionId, agentId, childSessionId) {
+            return entries
+                .get(sessionId)
+                ?.value?.agents.find((agent) => agent.agentId === agentId && agent.sessionId === childSessionId);
+        },
+        /**
+         * Hand a person's completed answer to the child's own question owner. The
+         * command that asked returns first, so the answer is sent outside it; a
+         * failure is logged and the row stays, so the person can answer again.
+         */
+        submit(sessionId, target) {
+            void (async () => {
+                const opened = await source.open(target.agentId, lifetime.signal);
+                try {
+                    await opened.agent
+                        .session(target.sessionId)
+                        .extension(questionContract.id)
+                        .call("answer", {
+                        askId: target.askId,
+                        requestId: target.requestId,
+                        answers: target.answers,
+                    });
+                }
+                finally {
+                    await opened.release();
+                }
+                const entry = entries.get(sessionId);
+                if (entry !== undefined && !entry.refreshing)
+                    await refresh(sessionId, entry);
+            })().catch((cause) => {
+                Effect.runFork(Effect.logError("subagents.answer", cause));
+            });
+        },
         close() {
             lifetime.abort();
             for (const sessionId of entries.keys())
@@ -177,7 +254,7 @@ export function subagentsExtension(options) {
         .define({
         hooks: {
             start: (ctx) => Effect.acquireRelease(Effect.sync(() => {
-                const roster = createRoster(options.source, options.timing ?? defaultTiming, (sessionId) => Effect.runPromise(ctx.transact(ctx.observe(sessionId)).pipe(Effect.ignore)));
+                const roster = createRoster(options.source, options.timing ?? defaultTiming, (sessionId) => Effect.runPromise(ctx.transact(ctx.observe(sessionId)).pipe(Effect.ignore)), ctx.isObserved);
                 rosters.set(ctx, roster);
                 return roster;
             }), (roster) => Effect.sync(() => {
@@ -197,6 +274,13 @@ export function subagentsExtension(options) {
                     slash: { aliases: ["agents"], order: 6 },
                 },
             },
+            {
+                // Reached only from a sub-agent row's Answer action.
+                id: "answerChild",
+                title: "Answer a sub-agent",
+                category: "Conversation",
+                description: "Answer a question a sub-agent has escalated to you",
+            },
         ]),
         projection: {
             schema: subagentsContract.projection.schema,
@@ -216,6 +300,52 @@ export function subagentsExtension(options) {
                     // The changed rows already show the result; don't echo the toggle.
                     return { type: "done" };
                 }),
+                answerChild: ({ sessionId, input }) => Effect.gen(function* () {
+                    const roster = rosters.get(ctx);
+                    const row = roster?.child(sessionId, input.agentId, input.sessionId);
+                    if (roster === undefined || row?.ask === undefined)
+                        return done({
+                            type: "info",
+                            message: "That question is no longer waiting.",
+                        });
+                    const outcome = yield* advanceAnswerFlow({ ...row.ask, closed: false }, input);
+                    if (outcome.type === "complete") {
+                        roster.submit(sessionId, {
+                            agentId: input.agentId,
+                            sessionId: input.sessionId,
+                            askId: outcome.askId,
+                            requestId: outcome.requestId,
+                            answers: outcome.answers,
+                        });
+                        return done({
+                            type: "success",
+                            // The child's owner commits it; an answer that loses the race changes nothing.
+                            message: `Sending your answer to ${row.name}.`,
+                        });
+                    }
+                    const step = outcome.step;
+                    // Each prompt continues here, naming the child it is for, and
+                    // says whose question it is: the composer shows only the prompt.
+                    return step.type === "prompt"
+                        ? {
+                            ...step,
+                            prompt: {
+                                ...step.prompt,
+                                summary: step.prompt.summary === undefined
+                                    ? `${row.name} asks`
+                                    : `${row.name} asks · ${step.prompt.summary}`,
+                            },
+                            next: {
+                                ...step.next,
+                                arguments: {
+                                    ...step.next.arguments,
+                                    agentId: input.agentId,
+                                    sessionId: input.sessionId,
+                                },
+                            },
+                        }
+                        : step;
+                }),
             }),
         },
     });

package/docs/api/README.md

@@ -28,6 +28,7 @@
 | [question/host](question/host.md)                           | -           |
 | [roster](roster.md)                                         | -           |
 | [roster/conversation-agents](roster/conversation-agents.md) | -           |
+| [schedules](schedules.md)                                   | -           |
 | [skills/host](skills/host.md)                               | -           |
 | [skills/source](skills/source.md)                           | -           |
 | [subagents/client](subagents/client.md)                     | -           |

package/docs/api/goal/contract.md

@@ -244,7 +244,7 @@ Session-owned goal controls and their visible projection.
 | `commands.clear.output`                       | `Struct`\<\{ \}\>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | -                  | A successful clear has no result fields.              |
 | `commands.set`                                | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                  | Set an objective against the revision the person saw. |
 | `commands.set.scope`                          | `"session"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"session"`        | The Session owns this goal.                           |
-| `commands.set.input`                          | `Struct`\<\{ `objective`: `String`; `expectedRevision`: `NullOr`\<`String`\>; `requestId`: `String`; \}\>                                                                                                                                                                                                                                                                                                                                                                                                                               | -                  | Decode the new objective and replacement fence.       |
+| `commands.set.input`                          | `Struct`\<\{ `objective`: `String`; `expectedRevision`: `NullOr`\<`String`\>; `requestId`: `String`; `adoptCommandId`: `optionalKey`\<`String`\>; \}\>                                                                                                                                                                                                                                                                                                                                                                                  | -                  | Decode the new objective and replacement fence.       |
 | `commands.set.output`                         | `Struct`\<\{ `goal`: `Struct`\<\{ `revision`: `String`; `objective`: `String`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`\]\>; `startedAt`: `Int`; `pauseCause`: `NullOr`\<`Struct`\<\{ `kind`: `Literals`\<...\>; `detail`: `NullOr`\<...\>; \}\>\>; \}\>; `accepted`: `Struct`\<\{ `status`: `Literal`\<`"accepted"`\>; `commandId`: `String`; \}\>; \}\>                                                                                                                                                                 | -                  | Return the goal and its admission receipt.            |
 | <a id="property-projection"></a> `projection` | `object`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                  | Current and ended goals visible to clients.           |
 | `projection.schema`                           | `Struct`\<\{ `goal`: `NullOr`\<`Struct`\<\{ `revision`: `String`; `objective`: `String`; `state`: `Literals`\<readonly \[`"active"`, `"paused"`\]\>; `startedAt`: `Int`; `pauseCause`: `NullOr`\<`Struct`\<\{ `kind`: `Literals`\<...\>; `detail`: `NullOr`\<...\>; \}\>\>; \}\>\>; `ended`: `$Array`\<`Struct`\<\{ `sequence`: `Int`; `objective`: `String`; `outcome`: `Literals`\<readonly \[`"achieved"`, `"cleared"`\]\>; `reason`: `NullOr`\<`String`\>; `endedAt`: `Int`; `afterSequence`: `Int`; \}\>\>; `omitted`: `Int`; \}\> | `GoalProjection`   | Decoder for the goal projection.                      |

package/docs/api/goal/host.md

@@ -26,4 +26,25 @@ The commands this extension advertises to every client.
 const goalExtension: RosteredExtensionV0;
 ```
 
-Botanical's Session goal, driven only by settled runs.
+Ordinary roster when no created-Agent directory is available.
+
+## Functions
+
+### goalExtensionFor()
+
+```ts
+function goalExtensionFor(subagents?): RosteredExtensionV0;
+```
+
+Botanical's Session goal; hosts with created-Agent facts include them in
+progress.
+
+#### Parameters
+
+| Parameter    | Type                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subagents?` | `Readonly`\<\{ `hasLiveChildCommand`: (`sessionId`) => `boolean`; `read`: (`sessionId`, `limit`) => `Promise`\<`Readonly`\<\{ `agents`: readonly `Readonly`\<\{ `agentId`: `string`; `name`: `string`; `sessionId`: ... \| ...; \}\>[]; `more`: `number`; \}\>\>; `open`: (`agentId`, `signal`) => `Promise`\<`Readonly`\<\{ `agent`: [`SubagentAgent`](../subagents/host.md#subagentagent); `release`: () => `Promise`\<`void`\>; \}\>\>; \}\> |
+
+#### Returns
+
+`RosteredExtensionV0`