@fungi.computer/shiitake-extensions 0.3.0 → 0.4.0

package/README.md

@@ -65,16 +65,16 @@ helper borrows the Agent. Its owner closes it when the host's lifetime ends.
 
 ## Core concepts
 
-| Extension | Ownership and behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Ask       | Up to four open decisions per Session. The model asks or withdraws; humans answer or decline. A live waiter receives the answer, while a parked question resumes through one follow-up.                                                                                                                                                                                                                                                                                                                                          |
-| Goal      | One live or paused objective per Session. The model creates, reads and completes it through `goal.*` tools, from any later turn of its Session; humans set, pause, resume or clear it. Esc, failed work, a block or three tool-less continuations pause it; a tool-less goal turn while a sub-agent command is live waits instead. Closing the app pauses it only if work stops without resuming; background work and runtime-auto-resumed turns keep it live. An achieved or cleared goal becomes one chat line in its history. |
-| Loop      | One repeated prompt per Session. It runs on a fixed cron cadence or lets its own active run request the next occurrence. Commands start, pause, resume and stop it.                                                                                                                                                                                                                                                                                                                                                              |
-| Plan      | One checklist per Session. `plan.update_plan` replaces it whole, with at most one step in progress and at most 50 steps; `steps: []` clears it. The human clears it with `/plan clear` or the footer row's Clear plan action, through the same owner. `/plan` opens the full checklist in the footer; updates keep only the current step and progress visible, and a finished or cleared plan leaves the footer while its history stays in state.                                                                                |
-| Almanac   | Agent-scope one-shot or recurring schedules. Each schedule targets a Session and tracks admission, retry and its next due time.                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Skills    | Host-supplied, read-only skill discovery. Metadata enters the prompt; `skill.load` reads a skill body or supporting file; `/skills` lists them.                                                                                                                                                                                                                                                                                                                                                                                  |
-| Home      | Agent-scope choice of an attached Computer. Each run captures its scoped file tools and current attachment choice.                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Subagents | A read-only footer view: one row per Agent this Session sent work to or created, with its live status (working, waiting on you, idle, failed, unavailable). A row opens that Agent's conversation, and `/agents` collapses the rows to one summary row and expands them again. It owns no relationship and no durable state.                                                                                                                                                                                                     |
+| Extension | Ownership and behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Ask       | Up to four open decisions per Session. The model asks or withdraws; humans answer or decline. A live waiter receives the answer, while a parked question resumes through one follow-up. On Local, an Ask raised during work another Agent sent waits on that sender first: it always parks, reads `waiting on <name>` instead of needing a person, and rides the child's reply to the sender as `waiting_on_you`. Only that sender's Session can answer it with `agents.answer`, or pass it to a person with `agents.escalate`; a person may always answer. An Ask the sender neither answers nor escalates goes to a person when the sender's turn ends, or after fifteen minutes. Hub sends every Ask to a person. |
+| Goal      | One live or paused objective per Session. The model creates, reads and completes it through `goal.*` tools, from any later turn of its Session; humans set, pause, resume or clear it. Esc, failed work, a block or three tool-less continuations pause it; a tool-less goal turn while a sub-agent command is live waits instead. Closing the app pauses it only if work stops without resuming; background work and runtime-auto-resumed turns keep it live. An achieved or cleared goal becomes one chat line in its history.                                                                                                                                                                                     |
+| Loop      | One repeated prompt per Session. It runs on a fixed cron cadence or lets its own active run request the next occurrence. Commands start, pause, resume and stop it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Plan      | One checklist per Session. `plan.update_plan` replaces it whole, with at most one step in progress and at most 50 steps; `steps: []` clears it. The human clears it with `/plan clear` or the footer row's Clear plan action, through the same owner. `/plan` opens the full checklist in the footer; updates keep only the current step and progress visible, and a finished or cleared plan leaves the footer while its history stays in state.                                                                                                                                                                                                                                                                    |
+| Almanac   | Agent-scope one-shot or recurring schedules. Each schedule targets a Session and tracks admission, retry and its next due time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Skills    | Host-supplied, read-only skill discovery. Metadata enters the prompt; `skill.load` reads a skill body or supporting file; `/skills` lists them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Home      | Agent-scope choice of an attached Computer. Each run captures its scoped file tools and current attachment choice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Subagents | A footer view: one row per Agent this Session sent work to or created, with its live status (working, waiting on an Agent, needs you, idle, failed, unavailable). A row opens that Agent's conversation, a question that needs a person can be answered from its row, and `/agents` collapses the rows to one summary row and expands them again. It owns no relationship and no durable state.                                                                                                                                                                                                                                                                                                                      |
 
 An active Goal is quiet system context on every run. Continuation instructions
 apply only to runs admitted by Goal with its continuation correlation; human
@@ -269,9 +269,14 @@ expands the footer rows, per Session and in memory).
 `source.read(sessionId, limit)` returns the Agents that Session sent work to or
 created, newest first, with a count of the rest; `source.open` is the host's
 existing Agent access. Each child's status is its owner's own Session state:
-`running` is working, any open attention (a question or a tool approval) is
-waiting on you, `done` is idle and `errored` is failed. A child whose state
-cannot be read is unavailable, never idle.
+`running` is working, `done` is idle and `errored` is failed. Attention that
+waits on a person (a question, or an approval an extension raises) is
+`needs you`; a question that waits on the Agent that sent the work is
+`waiting on <name>`, calm until it is escalated, and counted apart in the
+collapsed summary, which is amber only when a child needs a person. A
+`needs you` question carries its text and one Answer action that runs the
+question's own answer conversation. A child whose state cannot be read is
+unavailable, never idle.
 
 Rows refresh when a watcher reads the parent Session and they are at least a
 second old. While a row is working or waiting, they poll every five seconds

package/dist/goal/contract.d.ts

@@ -224,6 +224,12 @@ export declare const goalContract: {
                 readonly expectedRevision: Schema.NullOr<Schema.String>;
                 /** Idempotency key for this setting command. */
                 readonly requestId: Schema.String;
+                /**
+                 * Work already admitted in this Session that carries the objective,
+                 * such as a delegated send. The goal adopts it instead of admitting
+                 * the objective again; its settlement starts the goal turns.
+                 */
+                readonly adoptCommandId: Schema.optionalKey<Schema.String>;
             }>;
             /** Return the goal and its admission receipt. */
             readonly output: Schema.Struct<{

package/dist/goal/contract.js

@@ -154,6 +154,12 @@ export const goalContract = {
                 expectedRevision: Schema.NullOr(Schema.String),
                 /** Idempotency key for this setting command. */
                 requestId: RequestId,
+                /**
+                 * Work already admitted in this Session that carries the objective,
+                 * such as a delegated send. The goal adopts it instead of admitting
+                 * the objective again; its settlement starts the goal turns.
+                 */
+                adoptCommandId: Schema.optionalKey(RequestId),
             }),
             /** Return the goal and its admission receipt. */
             output: Schema.Struct({

package/dist/goal/host.js

@@ -14,14 +14,18 @@ import { clearConfirmation, goalMenuPrompt, replaceConfirmation, } from "./promp
 const rules = "You may start a goal yourself when none is current. Before marking complete audit every requirement against evidence; complete only after actual achievement. Block only after the same external impasse for three consecutive goal turns; a blocked goal stays paused until it is resumed. You may complete, block, clear or resume a goal that paused on its own (stalled, blocked or failed work); a goal a person paused or stopped you may only complete, and only a person clears a live goal. Human pause/resume/clear remain human controls. Use plan.update_plan for multi-step work when available.";
 /** Hashed prose and policy: every constant goal reads comes from here. */
 const config = {
-    continuation: "Continue working toward the current goal described in the goal section. Find goal.get_goal and goal.update_goal with forage.search({query:'goal'}) and forage.describe. Audit every requirement against evidence before goal.update_goal({status:'complete', reason}). If the same external blocker persists for three goal turns, report blocked with a reason. Check for progress rather than repeating yourself.",
-    moduleDescription: "Session goal tools: create_goal({objective}), get_goal({}), update_goal({status:'complete'|'blocked'|'clear'|'resume', reason}). " +
+    continuation: "Continue working toward the current goal described in the goal section. Find goal.get_goal and goal.update_goal with forage.search({query:'goal'}) and forage.describe. Audit every requirement against evidence before goal.update_goal({status:'complete', reason}). If the same external blocker persists for three goal turns, report blocked with a reason. Check for progress rather than repeating yourself. If there is nothing to do until something outside this turn happens (a child's reply, a person, the train, main), call goal.wait({reason, fallbackMinutes}) and end the turn instead of polling.",
+    moduleDescription: "Session goal tools: create_goal({objective}), get_goal({}), update_goal({status:'complete'|'blocked'|'clear'|'resume', reason}), wait({reason, fallbackMinutes}). " +
         rules,
-    createDescription: "Create a Session goal, including autonomously. Fails while a goal is active or paused; a finished goal is history.",
+    createDescription: "Create a Session goal, including autonomously. Fails while a goal is active or paused; a finished goal is history. After update_goal complete (or clear on a paused goal) in this same run, it queues the replacement, which takes over when this run settles.",
     getDescription: "Read the current goal. A requested terminal state remains provisional until successful settlement.",
     updateDescription: "Request complete only after actual achievement, or blocked only after the same external impasse for three consecutive goal turns; both also work on a paused goal, and settlement commits the request. Complete ends the goal; blocked pauses it for a person. clear abandons a paused goal with your reason. resume reactivates a paused goal now. A goal a person paused or stopped accepts only complete.",
     waitCheckMs: 60_000,
+    waitDescription: "Say the goal is waiting on something outside this turn, then end the turn. The goal stays active and admits no goal turn and no stall count until another run in this Session settles (a child's reply, a person's message, a loop tick) or fallbackMinutes (default 20, 1 to 60) pass. Use it instead of polling.",
+    waitDefaultMinutes: 20,
+    waitMaxMinutes: 60,
     waitingSummary: "Waiting on sub-agent",
+    waitingOnSummary: "Waiting",
     promptLimit: 1_024,
     stallTurns: 3,
     stallReason: "Stalled: no progress for 3 turns",
@@ -61,6 +65,17 @@ const GoalRow = Schema.Struct({
         reason: GoalReason,
     })),
     stalledTurns: Schema.Int,
+    /**
+     * The goal waits on something outside its turns. `until` is null while the
+     * requesting run is still running; its settlement fixes the fallback instant.
+     */
+    waiting: Schema.optionalKey(Schema.NullOr(Schema.Struct({
+        reason: GoalReason,
+        fallbackMs: Schema.Int,
+        until: Schema.NullOr(Schema.Int),
+    }))),
+    /** A replacement objective queued after this run's complete or clear. */
+    successor: Schema.optionalKey(Schema.NullOr(Objective)),
     /** Request that set this revision; its retry replays. */
     revisionRequestId: Schema.String,
     /** Latest work whose settlement advances this goal. */
@@ -127,6 +142,8 @@ function paused(goal, kind, detail) {
         state: "paused",
         pauseCause: { kind, detail },
         pending: null,
+        waiting: null,
+        successor: null,
     };
 }
 /**
@@ -167,6 +184,7 @@ function changeActivity(ctx, sessionId, target) {
                 state: "active",
                 pauseCause: null,
                 stalledTurns: 0,
+                waiting: null,
             }
             : paused(goal, "person", null);
         yield* commitGoal(ctx, changed);
@@ -225,26 +243,77 @@ function settle(ctx, run, subagents) {
             yield* commitGoal(ctx, paused(goal, "no-terminal", ctx.config.noTerminalReason));
             return yield* ctx.observe(run.sessionId);
         }
-        const waitingForChild = run.toolCalls === 0 &&
-            subagents?.hasLiveChildCommand(run.sessionId) === true &&
-            run.origin?.extensionId === goalContract.id;
+        const goalTurn = run.origin?.extensionId === goalContract.id;
+        // A live child command or a question or approval a person has yet to
+        // answer is a legitimate wait, whether or not this turn polled.
+        const waitingForChild = goalTurn &&
+            (subagents?.hasLiveChildCommand(run.sessionId) === true ||
+                (yield* ctx.attention.awaitsPerson(run.sessionId)));
+        const waiting = goal.waiting ?? null;
+        // The run that called goal.wait fixes the fallback instant as it settles.
+        const requested = waiting !== null &&
+            waiting.until === null &&
+            run.workId === goal.trackedWorkId;
+        // Any other run that settles while a wait is armed wakes the goal.
+        const woken = waiting !== null && waiting.until !== null;
         const tracked = {
             ...goal,
             trackedWorkId: run.workId,
-            stalledTurns: run.origin?.extensionId === goalContract.id &&
-                run.origin.correlation === goal.revision
-                ? run.toolCalls === 0
-                    ? goal.stalledTurns + 1
-                    : 0
-                : 0,
+            stalledTurns: requested
+                ? goal.stalledTurns
+                : run.origin?.extensionId === goalContract.id &&
+                    run.origin.correlation === goal.revision
+                    ? run.toolCalls === 0
+                        ? goal.stalledTurns + 1
+                        : 0
+                    : 0,
         };
         const pending = goal.trackedWorkId === run.workId ? goal.pending : null;
-        if (pending?.state === "complete")
-            yield* finishGoal(ctx, tracked, "achieved", pending.reason);
-        else if (pending?.state === "cleared")
-            yield* finishGoal(ctx, tracked, "cleared", pending.reason);
+        if (pending?.state === "complete" || pending?.state === "cleared") {
+            yield* ctx.timers.cancel(waitTimerKey(run.sessionId));
+            yield* finishGoal(ctx, tracked, pending.state === "complete" ? "achieved" : "cleared", pending.reason);
+            if (goal.successor != null) {
+                const next = {
+                    sessionId: run.sessionId,
+                    objective: goal.successor,
+                    state: "active",
+                    startedAt: yield* Clock.currentTimeMillis,
+                    pending: null,
+                    stalledTurns: 0,
+                    revision: `run:${run.workId}`,
+                    revisionRequestId: `run:${run.workId}`,
+                    trackedWorkId: run.workId,
+                    pauseCause: null,
+                    waiting: null,
+                    successor: null,
+                };
+                yield* commitGoal(ctx, yield* continueIfIdle(ctx, next, `goal-continue:${run.workId}`));
+            }
+        }
         else if (pending?.state === "blocked")
             yield* commitGoal(ctx, paused(tracked, "blocked", pending.reason));
+        else if (goal.state === "active" && requested) {
+            // goal.wait: no continuation and no stall; the next settled run or the
+            // fallback timer wakes the goal.
+            const now = yield* Clock.currentTimeMillis;
+            const until = now + waiting.fallbackMs;
+            yield* commitGoal(ctx, {
+                ...tracked,
+                waiting: { ...waiting, until },
+            });
+            yield* ctx.attention.set(run.sessionId, {
+                id: "waiting-goal",
+                kind: "goal-waiting",
+                inbox: false,
+                summary: `${ctx.config.waitingOnSummary}: ${waiting.reason}`.slice(0, 200),
+                since: now,
+            });
+            yield* ctx.timers.set(waitTimerKey(run.sessionId), until);
+        }
+        else if (goal.state === "active" && woken) {
+            yield* ctx.timers.cancel(waitTimerKey(run.sessionId));
+            yield* commitGoal(ctx, yield* continueIfIdle(ctx, { ...tracked, waiting: null }, `goal-continue:${run.workId}`));
+        }
         else if (goal.state === "active" &&
             !waitingForChild &&
             tracked.stalledTurns >= ctx.config.stallTurns)
@@ -288,7 +357,15 @@ function recheckWaiting(ctx, timer, subagents) {
         const found = yield* ctx.state.goals.get(sessionId);
         if (Option.isNone(found) || found.value.state !== "active")
             return;
-        if (subagents?.hasLiveChildCommand(sessionId) === true)
+        const armed = found.value.waiting ?? null;
+        if (armed !== null) {
+            // goal.wait's fallback: a re-armed wait ignores a stale firing.
+            if (armed.until === null || armed.until > timer.firedAt)
+                return;
+            return yield* commitGoal(ctx, yield* continueIfIdle(ctx, { ...found.value, waiting: null, stalledTurns: 0 }, `goal-wait:${found.value.trackedWorkId}`)).pipe(Effect.andThen(ctx.observe(sessionId)));
+        }
+        if (subagents?.hasLiveChildCommand(sessionId) === true ||
+            (yield* ctx.attention.awaitsPerson(sessionId)))
             return yield* ctx.timers.set(timer.key, timer.firedAt + ctx.config.waitCheckMs);
         yield* commitGoal(ctx, yield* continueIfIdle(ctx, found.value, `goal-wait:${found.value.trackedWorkId}`));
         yield* ctx.observe(sessionId);
@@ -349,8 +426,21 @@ function goalModule(ctx, sessionId, workId, initialRevision) {
                 }),
                 execute: ({ objective }) => toolCall(ctx, "create_goal", Effect.gen(function* () {
                     const decoded = yield* Schema.decodeUnknownEffect(Objective)(objective).pipe(Effect.mapError(() => conflict("Goal objective is invalid")));
-                    if (Option.isSome(yield* ctx.state.goals.get(sessionId)))
-                        return yield* Effect.fail(conflict("A Session goal is already active or paused; only a person replaces it"));
+                    const existing = yield* ctx.state.goals.get(sessionId);
+                    if (Option.isSome(existing)) {
+                        // A goal this run already finished (complete, or clear of a
+                        // paused one) hands over to the replacement at settlement.
+                        const retiring = existing.value.trackedWorkId === workId &&
+                            (existing.value.pending?.state === "complete" ||
+                                existing.value.pending?.state === "cleared");
+                        if (!retiring)
+                            return yield* Effect.fail(conflict("A Session goal is already active or paused; complete it first, or only a person replaces it"));
+                        yield* ctx.state.goals.put({
+                            ...existing.value,
+                            successor: decoded,
+                        });
+                        return { objective: decoded, state: "active" };
+                    }
                     yield* commitGoal(ctx, {
                         sessionId,
                         objective: decoded,
@@ -362,6 +452,8 @@ function goalModule(ctx, sessionId, workId, initialRevision) {
                         revisionRequestId: `run:${workId}`,
                         trackedWorkId: workId,
                         pauseCause: null,
+                        waiting: null,
+                        successor: null,
                     });
                     yield* ctx.observe(sessionId);
                     return { objective: decoded, state: "active" };
@@ -389,6 +481,50 @@ function goalModule(ctx, sessionId, workId, initialRevision) {
                             null,
                     }))),
             }),
+            wait: Mycelium.operation({
+                replay: "unsafe",
+                description: ctx.config.waitDescription,
+                input: z.strictObject({
+                    reason: z.string().min(1).max(1_000),
+                    fallbackMinutes: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(ctx.config.waitMaxMinutes)
+                        .optional(),
+                }),
+                output: z.strictObject({
+                    objective: toolObjective,
+                    state: z.literal("active"),
+                    reason: z.string(),
+                    fallbackMinutes: z.number().int(),
+                }),
+                execute: ({ reason, fallbackMinutes }) => toolCall(ctx, "wait", Effect.gen(function* () {
+                    const decoded = yield* Schema.decodeUnknownEffect(GoalReason)(reason).pipe(Effect.mapError(() => conflict("Wait reason is invalid")));
+                    const goal = yield* currentGoal;
+                    if (goal.state !== "active")
+                        return yield* Effect.fail(conflict("Only an active Session goal can wait"));
+                    if (goal.pending != null)
+                        return yield* Effect.fail(conflict("This run already requested a goal terminal"));
+                    const minutes = fallbackMinutes ?? ctx.config.waitDefaultMinutes;
+                    yield* ctx.state.goals.put({
+                        ...goal,
+                        // This run's settlement starts the wait.
+                        trackedWorkId: workId,
+                        waiting: {
+                            reason: decoded,
+                            fallbackMs: minutes * 60_000,
+                            until: null,
+                        },
+                    });
+                    return {
+                        objective: goal.objective,
+                        state: "active",
+                        reason: decoded,
+                        fallbackMinutes: minutes,
+                    };
+                })),
+            }),
             update_goal: Mycelium.operation({
                 replay: "unsafe",
                 description: ctx.config.updateDescription,
@@ -474,15 +610,22 @@ function setGoal(ctx, sessionId, input) {
         const retried = current?.revisionRequestId === input.requestId;
         if (!retried && (current?.revision ?? null) !== input.expectedRevision)
             return yield* Effect.fail(conflict("Session goal changed; read it before replacing it"));
-        const admitted = yield* ctx.send({
-            sessionId,
-            when: "now",
-            prompt: {
-                text: input.objective,
-                requestId: input.requestId,
-                delivery: "followUp",
-            },
-        });
+        // Adopted work already carries the objective; anything else admits it.
+        const admitted = input.adoptCommandId === undefined
+            ? yield* ctx.send({
+                sessionId,
+                when: "now",
+                prompt: {
+                    text: input.objective,
+                    requestId: input.requestId,
+                    delivery: "followUp",
+                },
+            })
+            : {
+                _tag: "Accepted",
+                commandId: input.adoptCommandId,
+                delivery: retried ? "replay" : "new",
+            };
         if (admitted._tag !== "Accepted")
             return yield* Effect.fail(conflict("Session goal was not admitted"));
         const accepted = {
@@ -511,10 +654,17 @@ function setGoal(ctx, sessionId, input) {
             revisionRequestId: input.requestId,
             trackedWorkId: admitted.commandId,
             pauseCause: null,
+            waiting: null,
+            successor: null,
         };
-        yield* commitGoal(ctx, row);
+        // Adopted work that already settled left the Session idle: start the
+        // first goal turn now. Otherwise its settlement does.
+        const started = input.adoptCommandId === undefined
+            ? row
+            : yield* continueIfIdle(ctx, row, `goal-adopt:${input.requestId}`);
+        yield* commitGoal(ctx, started);
         yield* ctx.observe(sessionId);
-        return { goal: committed(row), accepted };
+        return { goal: committed(started), accepted };
     });
 }
 /** The one-line state the model prompt and attention summaries carry. */

package/dist/question/answer-flow.d.ts

@@ -0,0 +1,27 @@
+import type { WhistleCatalogStepV1 } from "@fungi.computer/whistle/catalog";
+import { ExtensionCommandError } from "@fungi.computer/shiitake/extensions";
+import * as Effect from "effect/Effect";
+import { type Answers, type AnswerFlowInput, type Question } from "./contract.js";
+import type * as Schema from "effect/Schema";
+/** Drafts travel in catalog arguments; only an owner's answer commits them. */
+export type FlowInput = Schema.Schema.Type<typeof AnswerFlowInput>;
+/** What the answer conversation does next for one open Ask. */
+export type AnswerFlowOutcome = Readonly<{
+    type: "step";
+    step: WhistleCatalogStepV1;
+}> | Readonly<{
+    type: "complete";
+    askId: string;
+    requestId: string;
+    answers: Answers;
+}>;
+/**
+ * Progress one Ask's answer draft by a single human step. The owner of the
+ * Ask commits a completed set; a step only ever returns the next prompt, so
+ * the same conversation serves the Ask's own Session and a parent's footer.
+ */
+export declare function advanceAnswerFlow(row: Readonly<{
+    askId: string;
+    questions: readonly Question[];
+    closed: boolean;
+}>, input: FlowInput): Effect.Effect<AnswerFlowOutcome, ExtensionCommandError>;

package/dist/question/answer-flow.js

@@ -0,0 +1,115 @@
+import { ExtensionCommandError } from "@fungi.computer/shiitake/extensions";
+import * as Effect from "effect/Effect";
+import { ask, done, freshRequestId } from "../internal/catalog.js";
+import { titleLimit } from "../internal/headline.js";
+import {} from "./contract.js";
+/** Accept only picks the question offered, and a non-empty answer. */
+function decisionAnswer(question, answer) {
+    const offered = new Set(question.options.map((option) => option.label));
+    const written = answer.text?.trim() ?? "";
+    if (answer.selected.some((label) => !offered.has(label)) ||
+        new Set(answer.selected).size !== answer.selected.length ||
+        (question.multiple !== true && answer.selected.length > 1) ||
+        (answer.selected.length === 0 && written === ""))
+        return Effect.fail(new ExtensionCommandError({
+            reason: "invalid",
+            message: "Choose offered options or write an answer",
+        }));
+    return Effect.succeed(written === ""
+        ? { selected: answer.selected }
+        : { selected: answer.selected, text: answer.text ?? "" });
+}
+/**
+ * The Agent's own words are the title only when they fit one; a longer
+ * question gets a plain title and sits in the body, whole in the details.
+ */
+function questionHeading(question) {
+    const text = question.question.replace(/\s+/gu, " ").trim();
+    if (text.length <= titleLimit)
+        return { message: text };
+    return {
+        message: "The Agent has a question",
+        body: question.question.slice(0, 4_000),
+        bodyLabel: "Question",
+        details: [{ label: "Question", value: question.question.slice(0, 4_000) }],
+    };
+}
+function promptQuestion(nextQuestion, next, total) {
+    const base = {
+        type: "decision",
+        ...questionHeading(nextQuestion),
+        options: nextQuestion.options.map((option) => ({
+            value: option.label,
+            label: option.label,
+            description: option.description,
+        })),
+        other: {
+            label: "Other…",
+            placeholder: "Write your own answer",
+            maxLength: 4_000,
+        },
+    };
+    // Only present fields travel: the wire is JSON, which has no undefined.
+    const numbered = total > 1
+        ? {
+            ...base,
+            summary: `Question ${String(next.index + 1)} of ${String(total)}`,
+        }
+        : base;
+    return ask(nextQuestion.multiple === true ? { ...numbered, multiple: true } : numbered, { stage: "decision", ...next }, "answer");
+}
+/**
+ * Progress one Ask's answer draft by a single human step. The owner of the
+ * Ask commits a completed set; a step only ever returns the next prompt, so
+ * the same conversation serves the Ask's own Session and a parent's footer.
+ */
+export function advanceAnswerFlow(row, input) {
+    return Effect.gen(function* () {
+        const draft = "stage" in input
+            ? input
+            : {
+                stage: "start",
+                index: 0,
+                requestId: yield* freshRequestId,
+                answers: {},
+            };
+        let { index, answers } = draft;
+        const { requestId } = draft;
+        const question = row.questions[index];
+        if (question === undefined)
+            return yield* Effect.fail(new ExtensionCommandError({
+                reason: "invalid",
+                message: "Unknown question step",
+            }));
+        const answer = draft.stage === "decision"
+            ? yield* decisionAnswer(question, draft.answer)
+            : undefined;
+        if (answer !== undefined) {
+            answers = { ...answers, [question.id]: answer };
+            index += 1;
+            if (index === row.questions.length)
+                return {
+                    type: "complete",
+                    askId: row.askId,
+                    requestId,
+                    answers,
+                };
+        }
+        if (row.closed)
+            return {
+                type: "step",
+                step: done({
+                    type: "info",
+                    message: "That question is already closed.",
+                }),
+            };
+        const next = { askId: row.askId, requestId, index, answers };
+        const nextQuestion = row.questions[index];
+        if (nextQuestion === undefined)
+            throw new Error("Expected the next question");
+        return {
+            type: "step",
+            step: promptQuestion(nextQuestion, next, row.questions.length),
+        };
+    });
+}

package/dist/question/client.d.ts

@@ -1,5 +1,5 @@
 import { type ClientContributionV1 } from "@fungi.computer/shiitake/client-entry";
-/** Pending decisions use the existing footer rows and advertised answer flow. */
+/** Pending decisions take over the composer; the footer row is where a postponed one waits. */
 declare const _default: Readonly<{
     protocol: "shiitake.client/v1";
     id: import("@fungi.computer/shiitake/extensions").ExtensionId;

package/dist/question/client.js

@@ -1,6 +1,6 @@
 import { defineClientEntry, } from "@fungi.computer/shiitake/client-entry";
 import { questionContract } from "./contract.js";
-/** Pending decisions use the existing footer rows and advertised answer flow. */
+/** Pending decisions take over the composer; the footer row is where a postponed one waits. */
 export default defineClientEntry(questionContract, {
     contribute: (view) => ({
         chips: [],
@@ -8,16 +8,35 @@ export default defineClientEntry(questionContract, {
             ? []
             : view.value.asks.map((ask) => {
                 const first = ask.questions[0];
+                const title = `${first?.question ?? "Question"}${ask.questions.length > 1 ? ` (+${String(ask.questions.length - 1)} more)` : ""}`;
+                const detail = first?.options.map((option) => option.label).join(" · ") ?? "";
+                // An ask waiting on an Agent is calm: it never takes over the
+                // composer, but a person may still answer it first.
+                if (ask.waitingOn !== undefined)
+                    return {
+                        id: ask.askId,
+                        title: `waiting on ${ask.waitingOn.name} · ${title}`,
+                        detail,
+                        tone: "muted",
+                        actions: [
+                            {
+                                id: "answerFlow",
+                                label: "Answer",
+                                input: { askId: ask.askId },
+                            },
+                        ],
+                    };
                 return {
                     id: ask.askId,
-                    title: `${first?.question ?? "Question"}${ask.questions.length > 1 ? ` (+${String(ask.questions.length - 1)} more)` : ""}`,
-                    detail: first?.options.map((option) => option.label).join(" · ") ?? "",
+                    title,
+                    detail,
                     tone: "attention",
                     actions: [
                         {
                             id: "answerFlow",
                             label: "Answer",
                             input: { askId: ask.askId },
+                            awaiting: "question",
                         },
                     ],
                 };