@fungi.computer/shiitake-extensions 0.3.0 → 0.5.0

package/dist/loop/host.js

@@ -281,6 +281,13 @@ function fire(ctx, sessionId, dueAt, now) {
                 delivery: "followUp",
             },
         }));
+        // The Agent owner will pause this loop after flipping its archive flag.
+        // If this timer wins that short interval, keep the loop resumable instead
+        // of treating an intentional archive refusal as a permanent failed run.
+        if (Result.isFailure(admitted) && admitted.failure.reason === "archived") {
+            yield* arm(ctx, { ...loop, lastError: admitted.failure.message }, now + 30_000);
+            return yield* ctx.observe(sessionId);
+        }
         if (Result.isFailure(admitted) || admitted.success._tag === "NotReady") {
             yield* commitLoop(ctx, {
                 ...loop,
@@ -493,6 +500,14 @@ function stopLoop(ctx, sessionId, reason) {
         return projected(stopped);
     });
 }
+/** Match and mutate within the same extension command transaction. */
+function controlIdentifiedLoop(ctx, target, action) {
+    return requireLoop(ctx, target.sessionId).pipe(Effect.flatMap((loop) => loop.loopId !== target.loopId
+        ? Effect.fail(conflict("Session loop has been replaced"))
+        : action === "pause"
+            ? pauseLoop(ctx, target.sessionId)
+            : stopLoop(ctx, target.sessionId)));
+}
 function cronForInterval(value, unit) {
     if (unit === "m" || unit === "min")
         return value > 59 ? undefined : `0 */${String(value)} * * * *`;
@@ -662,6 +677,14 @@ export const loopExtension = defineExtension({
     commands: {
         specs: loopContract.commands,
         handlers: (ctx) => ({
+            pauseLoop: ({ input }) => controlIdentifiedLoop(ctx, input, "pause"),
+            stopLoop: ({ input }) => controlIdentifiedLoop(ctx, input, "stop"),
+            list: ({ input }) => ctx.state.loops
+                .page({ after: input.after, limit: input.limit ?? 64 })
+                .pipe(Effect.map((rows) => rows.map((row) => ({
+                ...projected(row),
+                sessionId: row.sessionId,
+            })))),
             startSelfPaced: ({ sessionId, input }) => start(ctx, sessionId, input, null),
             startFixedInterval: ({ sessionId, input }) => start(ctx, sessionId, input, {
                 expression: input.expression,

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",
                         },
                     ],
                 };

package/dist/question/contract.d.ts

@@ -41,6 +41,16 @@ export type Question = Schema.Schema.Type<typeof Question>;
 export declare const OpenAsk: Schema.Struct<{
     /** Durable identity of the open ask. */
     readonly askId: Schema.String;
+    /**
+     * The Agent this ask waits on first, derived by the host from whom the
+     * asking run's work came from. Absent means a person. An ask waiting on an
+     * Agent is calm: the Agent answers it or escalates it to a person.
+     */
+    readonly waitingOn: Schema.optionalKey<Schema.Struct<{
+        readonly agentId: Schema.NonEmptyString;
+        readonly sessionId: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>>;
     /** Decisions awaiting the person's answers. */
     readonly questions: Schema.$Array<Schema.Struct<{
         /** Identity used to associate this question with its answer. */
@@ -74,6 +84,16 @@ export declare const AskProjection: Schema.Struct<{
     readonly asks: Schema.$Array<Schema.Struct<{
         /** Durable identity of the open ask. */
         readonly askId: Schema.String;
+        /**
+         * The Agent this ask waits on first, derived by the host from whom the
+         * asking run's work came from. Absent means a person. An ask waiting on an
+         * Agent is calm: the Agent answers it or escalates it to a person.
+         */
+        readonly waitingOn: Schema.optionalKey<Schema.Struct<{
+            readonly agentId: Schema.NonEmptyString;
+            readonly sessionId: Schema.NonEmptyString;
+            readonly name: Schema.NonEmptyString;
+        }>>;
         /** Decisions awaiting the person's answers. */
         readonly questions: Schema.$Array<Schema.Struct<{
             /** Identity used to associate this question with its answer. */
@@ -146,6 +166,8 @@ export declare const HumanResult: Schema.Union<readonly [Schema.Struct<{
     readonly result: Schema.Literal<"accepted">;
     /** Whether the reply resumed its turn or became a follow-up. */
     readonly via: Schema.Literals<readonly ["in_turn", "follow_up"]>;
+    /** The follow-up command carrying the reply, when it became one. */
+    readonly commandId: Schema.optionalKey<Schema.String>;
 }>, Schema.Struct<{
     /** Ask had already reached a terminal state. */
     readonly result: Schema.Literal<"closed">;
@@ -157,40 +179,80 @@ export declare const HumanResult: Schema.Union<readonly [Schema.Struct<{
 }>]>;
 /** Decoded outcome of a human answer or decline. */
 export type HumanResult = Schema.Schema.Type<typeof HumanResult>;
-/** The ordinary /answer conversation carries its draft between typed steps. */
-export declare const AnswerFlowInput: Schema.Union<readonly [Schema.Struct<{
-    /** Encoded selection supplied by the human control. */
-    readonly selection: Schema.String;
-    readonly askId: Schema.String;
-    readonly requestId: Schema.String;
-    readonly index: Schema.Number;
-    readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
-        /** Labels of the offered choices selected by the person. */
-        readonly selected: Schema.$Array<Schema.String>;
-        /** Optional free-text answer supplied by the person. */
-        readonly text: Schema.optionalKey<Schema.String>;
-    }>>;
-    /** Multiple-choice selection step. */
-    readonly stage: Schema.Literal<"multiple">;
+/** Only the Agent an Ask waits on may answer or escalate it. */
+export declare const SenderRefusal: Schema.Struct<{
+    /** The caller is not the Agent this Ask waits on. */
+    readonly result: Schema.Literal<"refused">;
+    /** Explains why the Agent's response cannot be applied. */
+    readonly reason: Schema.Literal<"not_sender">;
+}>;
+/** Outcome of the Agent an Ask waits on answering it. */
+export declare const AgentAnswerResult: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+    /** Reply was accepted. */
+    readonly result: Schema.Literal<"accepted">;
+    /** Whether the reply resumed its turn or became a follow-up. */
+    readonly via: Schema.Literals<readonly ["in_turn", "follow_up"]>;
+    /** The follow-up command carrying the reply, when it became one. */
+    readonly commandId: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+    /** Ask had already reached a terminal state. */
+    readonly result: Schema.Literal<"closed">;
+    /** Terminal state that prevented another answer. */
+    readonly status: Schema.Literals<readonly ["answered", "declined", "withdrawn", "expired", "cancelled", "undeliverable"]>;
 }>, Schema.Struct<{
-    /** Encoded selection supplied by the human control. */
-    readonly selection: Schema.String;
+    /** No ask with this identity exists. */
+    readonly result: Schema.Literal<"not_found">;
+}>]>, Schema.Struct<{
+    /** The caller is not the Agent this Ask waits on. */
+    readonly result: Schema.Literal<"refused">;
+    /** Explains why the Agent's response cannot be applied. */
+    readonly reason: Schema.Literal<"not_sender">;
+}>]>;
+/** Decoded result of an authenticated Agent answer. */
+export type AgentAnswerResult = Schema.Schema.Type<typeof AgentAnswerResult>;
+/** The Agent that answered, as the host authenticated it. */
+export declare const AnsweredBy: Schema.Struct<{
+    /** Identifies an Agent, never a person. */
+    readonly kind: Schema.Literal<"agent">;
+    /** Stable identity of the authenticated Agent. */
+    readonly agentId: Schema.String;
+}>;
+/** Outcome of the Agent an Ask waits on passing it on. */
+export declare const EscalateResult: Schema.Union<readonly [Schema.Struct<{
+    /** The Ask now waits on someone else. */
+    readonly result: Schema.Literal<"escalated">;
+    /** Whom it waits on now: a person. */
+    readonly to: Schema.Literal<"person">;
+}>, Schema.Struct<{
+    /** Ask had already reached a terminal state. */
+    readonly result: Schema.Literal<"closed">;
+    /** Terminal state that prevented the escalation. */
+    readonly status: Schema.Literals<readonly ["answered", "declined", "withdrawn", "expired", "cancelled", "undeliverable"]>;
+}>, Schema.Struct<{
+    /** No ask with this identity exists. */
+    readonly result: Schema.Literal<"not_found">;
+}>, Schema.Struct<{
+    /** The caller is not the Agent this Ask waits on. */
+    readonly result: Schema.Literal<"refused">;
+    /** Explains why the Agent's response cannot be applied. */
+    readonly reason: Schema.Literal<"not_sender">;
+}>]>;
+/** Decoded result of passing an Ask on. */
+export type EscalateResult = Schema.Schema.Type<typeof EscalateResult>;
+/** The Agent's request to pass an Ask on; the caller is host context. */
+export declare const EscalateInput: Schema.Struct<{
+    /** Ask being passed on. */
     readonly askId: Schema.String;
-    readonly requestId: Schema.String;
-    readonly index: Schema.Number;
-    readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+}>;
+/** The answer conversation carries its draft between decision steps. */
+export declare const AnswerFlowInput: Schema.Union<readonly [Schema.Struct<{
+    /** The person's picks and optional written answer for question `index`. */
+    readonly answer: Schema.Struct<{
         /** Labels of the offered choices selected by the person. */
         readonly selected: Schema.$Array<Schema.String>;
         /** Optional free-text answer supplied by the person. */
         readonly text: Schema.optionalKey<Schema.String>;
-    }>>;
-    /** Single-choice selection step. */
-    readonly stage: Schema.Literal<"selection">;
-}>, Schema.Struct<{
-    /** Offered choices retained while entering free text. */
-    readonly selected: Schema.$Array<Schema.String>;
-    /** Free-text answer supplied by the person. */
-    readonly text: Schema.String;
+    }>;
     readonly askId: Schema.String;
     readonly requestId: Schema.String;
     readonly index: Schema.Number;
@@ -200,8 +262,8 @@ export declare const AnswerFlowInput: Schema.Union<readonly [Schema.Struct<{
         /** Optional free-text answer supplied by the person. */
         readonly text: Schema.optionalKey<Schema.String>;
     }>>;
-    /** Free-text answer step. */
-    readonly stage: Schema.Literal<"text">;
+    /** One decision answered in the composer. */
+    readonly stage: Schema.Literal<"decision">;
 }>, Schema.Struct<{
     /** Ask whose answer conversation should be opened. */
     readonly askId: Schema.String;
@@ -218,38 +280,13 @@ export declare const questionContract: {
             readonly scope: "session";
             /** Decode the current answer-draft step. */
             readonly input: Schema.Union<readonly [Schema.Struct<{
-                /** Encoded selection supplied by the human control. */
-                readonly selection: Schema.String;
-                readonly askId: Schema.String;
-                readonly requestId: Schema.String;
-                readonly index: Schema.Number;
-                readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+                /** The person's picks and optional written answer for question `index`. */
+                readonly answer: Schema.Struct<{
                     /** Labels of the offered choices selected by the person. */
                     readonly selected: Schema.$Array<Schema.String>;
                     /** Optional free-text answer supplied by the person. */
                     readonly text: Schema.optionalKey<Schema.String>;
-                }>>;
-                /** Multiple-choice selection step. */
-                readonly stage: Schema.Literal<"multiple">;
-            }>, Schema.Struct<{
-                /** Encoded selection supplied by the human control. */
-                readonly selection: Schema.String;
-                readonly askId: Schema.String;
-                readonly requestId: Schema.String;
-                readonly index: Schema.Number;
-                readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
-                    /** Labels of the offered choices selected by the person. */
-                    readonly selected: Schema.$Array<Schema.String>;
-                    /** Optional free-text answer supplied by the person. */
-                    readonly text: Schema.optionalKey<Schema.String>;
-                }>>;
-                /** Single-choice selection step. */
-                readonly stage: Schema.Literal<"selection">;
-            }>, Schema.Struct<{
-                /** Offered choices retained while entering free text. */
-                readonly selected: Schema.$Array<Schema.String>;
-                /** Free-text answer supplied by the person. */
-                readonly text: Schema.String;
+                }>;
                 readonly askId: Schema.String;
                 readonly requestId: Schema.String;
                 readonly index: Schema.Number;
@@ -259,8 +296,8 @@ export declare const questionContract: {
                     /** Optional free-text answer supplied by the person. */
                     readonly text: Schema.optionalKey<Schema.String>;
                 }>>;
-                /** Free-text answer step. */
-                readonly stage: Schema.Literal<"text">;
+                /** One decision answered in the composer. */
+                readonly stage: Schema.Literal<"decision">;
             }>, Schema.Struct<{
                 /** Ask whose answer conversation should be opened. */
                 readonly askId: Schema.String;
@@ -292,6 +329,8 @@ export declare const questionContract: {
                 readonly result: Schema.Literal<"accepted">;
                 /** Whether the reply resumed its turn or became a follow-up. */
                 readonly via: Schema.Literals<readonly ["in_turn", "follow_up"]>;
+                /** The follow-up command carrying the reply, when it became one. */
+                readonly commandId: Schema.optionalKey<Schema.String>;
             }>, Schema.Struct<{
                 /** Ask had already reached a terminal state. */
                 readonly result: Schema.Literal<"closed">;
@@ -302,6 +341,87 @@ export declare const questionContract: {
                 readonly result: Schema.Literal<"not_found">;
             }>]>;
         };
+        /** Submit the answer of the Agent this Ask waits on; never a human answer. */
+        readonly answerAgent: {
+            /** The child Session owns the Ask; caller authority is host context. */
+            readonly scope: "session";
+            /** Decode the answer submission without any caller-supplied actor. */
+            readonly input: Schema.Struct<{
+                /** Ask being answered. */
+                readonly askId: Schema.String;
+                /** Stable identity shared by this command and its retries. */
+                readonly requestId: Schema.String;
+                /** Answers to the ask's question set. */
+                readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+                    /** Labels of the offered choices selected by the person. */
+                    readonly selected: Schema.$Array<Schema.String>;
+                    /** Optional free-text answer supplied by the person. */
+                    readonly text: Schema.optionalKey<Schema.String>;
+                }>>;
+            }>;
+            /** Attribute the accepted answer to its authenticated Agent. */
+            readonly output: Schema.Struct<{
+                /** Whether the answer was accepted, or why not. */
+                readonly result: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+                    /** Reply was accepted. */
+                    readonly result: Schema.Literal<"accepted">;
+                    /** Whether the reply resumed its turn or became a follow-up. */
+                    readonly via: Schema.Literals<readonly ["in_turn", "follow_up"]>;
+                    /** The follow-up command carrying the reply, when it became one. */
+                    readonly commandId: Schema.optionalKey<Schema.String>;
+                }>, Schema.Struct<{
+                    /** Ask had already reached a terminal state. */
+                    readonly result: Schema.Literal<"closed">;
+                    /** Terminal state that prevented another answer. */
+                    readonly status: Schema.Literals<readonly ["answered", "declined", "withdrawn", "expired", "cancelled", "undeliverable"]>;
+                }>, Schema.Struct<{
+                    /** No ask with this identity exists. */
+                    readonly result: Schema.Literal<"not_found">;
+                }>]>, Schema.Struct<{
+                    /** The caller is not the Agent this Ask waits on. */
+                    readonly result: Schema.Literal<"refused">;
+                    /** Explains why the Agent's response cannot be applied. */
+                    readonly reason: Schema.Literal<"not_sender">;
+                }>]>;
+                /** The authenticated Agent that answered. */
+                readonly answeredBy: Schema.Struct<{
+                    /** Identifies an Agent, never a person. */
+                    readonly kind: Schema.Literal<"agent">;
+                    /** Stable identity of the authenticated Agent. */
+                    readonly agentId: Schema.String;
+                }>;
+            }>;
+        };
+        /** Pass the Ask on from the Agent it waits on; never a human action. */
+        readonly escalateAgent: {
+            /** The child Session owns the Ask; caller authority is host context. */
+            readonly scope: "session";
+            /** Decode the escalation without any caller-supplied recipient. */
+            readonly input: Schema.Struct<{
+                /** Ask being passed on. */
+                readonly askId: Schema.String;
+            }>;
+            /** Where the Ask waits now, or why it did not move. */
+            readonly output: Schema.Union<readonly [Schema.Struct<{
+                /** The Ask now waits on someone else. */
+                readonly result: Schema.Literal<"escalated">;
+                /** Whom it waits on now: a person. */
+                readonly to: Schema.Literal<"person">;
+            }>, Schema.Struct<{
+                /** Ask had already reached a terminal state. */
+                readonly result: Schema.Literal<"closed">;
+                /** Terminal state that prevented the escalation. */
+                readonly status: Schema.Literals<readonly ["answered", "declined", "withdrawn", "expired", "cancelled", "undeliverable"]>;
+            }>, Schema.Struct<{
+                /** No ask with this identity exists. */
+                readonly result: Schema.Literal<"not_found">;
+            }>, Schema.Struct<{
+                /** The caller is not the Agent this Ask waits on. */
+                readonly result: Schema.Literal<"refused">;
+                /** Explains why the Agent's response cannot be applied. */
+                readonly reason: Schema.Literal<"not_sender">;
+            }>]>;
+        };
         /** Decline an ask with an optional note. */
         readonly decline: {
             /** The Session owns this ask. */
@@ -321,6 +441,8 @@ export declare const questionContract: {
                 readonly result: Schema.Literal<"accepted">;
                 /** Whether the reply resumed its turn or became a follow-up. */
                 readonly via: Schema.Literals<readonly ["in_turn", "follow_up"]>;
+                /** The follow-up command carrying the reply, when it became one. */
+                readonly commandId: Schema.optionalKey<Schema.String>;
             }>, Schema.Struct<{
                 /** Ask had already reached a terminal state. */
                 readonly result: Schema.Literal<"closed">;
@@ -343,6 +465,16 @@ export declare const questionContract: {
                 readonly asks: Schema.$Array<Schema.Struct<{
                     /** Durable identity of the open ask. */
                     readonly askId: Schema.String;
+                    /**
+                     * The Agent this ask waits on first, derived by the host from whom the
+                     * asking run's work came from. Absent means a person. An ask waiting on an
+                     * Agent is calm: the Agent answers it or escalates it to a person.
+                     */
+                    readonly waitingOn: Schema.optionalKey<Schema.Struct<{
+                        readonly agentId: Schema.NonEmptyString;
+                        readonly sessionId: Schema.NonEmptyString;
+                        readonly name: Schema.NonEmptyString;
+                    }>>;
                     /** Decisions awaiting the person's answers. */
                     readonly questions: Schema.$Array<Schema.Struct<{
                         /** Identity used to associate this question with its answer. */
@@ -379,6 +511,16 @@ export declare const questionContract: {
             readonly asks: Schema.$Array<Schema.Struct<{
                 /** Durable identity of the open ask. */
                 readonly askId: Schema.String;
+                /**
+                 * The Agent this ask waits on first, derived by the host from whom the
+                 * asking run's work came from. Absent means a person. An ask waiting on an
+                 * Agent is calm: the Agent answers it or escalates it to a person.
+                 */
+                readonly waitingOn: Schema.optionalKey<Schema.Struct<{
+                    readonly agentId: Schema.NonEmptyString;
+                    readonly sessionId: Schema.NonEmptyString;
+                    readonly name: Schema.NonEmptyString;
+                }>>;
                 /** Decisions awaiting the person's answers. */
                 readonly questions: Schema.$Array<Schema.Struct<{
                     /** Identity used to associate this question with its answer. */