@fungi.computer/shiitake-extensions 0.2.0 → 0.4.0

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. */

package/dist/question/contract.js

@@ -1,4 +1,4 @@
-import { ExtensionId } from "@fungi.computer/shiitake/extensions";
+import { AttentionRecipientSchema, ExtensionId, } from "@fungi.computer/shiitake/extensions";
 import * as Schema from "effect/Schema";
 import { CatalogStep } from "../internal/catalog.js";
 const text = (maximum) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maximum), Schema.isPattern(/\S/u));
@@ -38,6 +38,12 @@ export const Questions = Schema.Array(Question).check(Schema.isMinLength(1), Sch
 export const OpenAsk = Schema.Struct({
     /** Durable identity of the open ask. */
     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.
+     */
+    waitingOn: Schema.optionalKey(AttentionRecipientSchema),
     /** Decisions awaiting the person's answers. */
     questions: Questions,
     /** Whether the ask is live in a turn or parked for later. */
@@ -95,6 +101,8 @@ export const HumanResult = Schema.Union([
         result: Schema.Literal("accepted"),
         /** Whether the reply resumed its turn or became a follow-up. */
         via: Schema.Literals(["in_turn", "follow_up"]),
+        /** The follow-up command carrying the reply, when it became one. */
+        commandId: Schema.optionalKey(text(256)),
     }),
     Schema.Struct({
         /** Ask had already reached a terminal state. */
@@ -107,6 +115,47 @@ export const HumanResult = Schema.Union([
         result: Schema.Literal("not_found"),
     }),
 ]);
+/** Only the Agent an Ask waits on may answer or escalate it. */
+export const SenderRefusal = Schema.Struct({
+    /** The caller is not the Agent this Ask waits on. */
+    result: Schema.Literal("refused"),
+    /** Explains why the Agent's response cannot be applied. */
+    reason: Schema.Literal("not_sender"),
+});
+/** Outcome of the Agent an Ask waits on answering it. */
+export const AgentAnswerResult = Schema.Union([HumanResult, SenderRefusal]);
+/** The Agent that answered, as the host authenticated it. */
+export const AnsweredBy = Schema.Struct({
+    /** Identifies an Agent, never a person. */
+    kind: Schema.Literal("agent"),
+    /** Stable identity of the authenticated Agent. */
+    agentId: text(256),
+});
+/** Outcome of the Agent an Ask waits on passing it on. */
+export const EscalateResult = Schema.Union([
+    Schema.Struct({
+        /** The Ask now waits on someone else. */
+        result: Schema.Literal("escalated"),
+        /** Whom it waits on now: a person. */
+        to: Schema.Literal("person"),
+    }),
+    Schema.Struct({
+        /** Ask had already reached a terminal state. */
+        result: Schema.Literal("closed"),
+        /** Terminal state that prevented the escalation. */
+        status: ClosedStatus,
+    }),
+    Schema.Struct({
+        /** No ask with this identity exists. */
+        result: Schema.Literal("not_found"),
+    }),
+    SenderRefusal,
+]);
+/** The Agent's request to pass an Ask on; the caller is host context. */
+export const EscalateInput = Schema.Struct({
+    /** Ask being passed on. */
+    askId: text(256),
+});
 const answerStep = {
     /** Ask whose answer draft is being edited. */
     askId: AnswerInput.fields.askId,
@@ -117,30 +166,14 @@ const answerStep = {
     /** Answers accumulated by preceding conversation steps. */
     answers: Answers,
 };
-/** The ordinary /answer conversation carries its draft between typed steps. */
+/** The answer conversation carries its draft between decision steps. */
 export const AnswerFlowInput = Schema.Union([
     Schema.Struct({
-        /** Multiple-choice selection step. */
-        stage: Schema.Literal("multiple"),
+        /** One decision answered in the composer. */
+        stage: Schema.Literal("decision"),
         ...answerStep,
-        /** Encoded selection supplied by the human control. */
-        selection: Schema.String.check(Schema.isMaxLength(1_000)),
-    }),
-    Schema.Struct({
-        /** Single-choice selection step. */
-        stage: Schema.Literal("selection"),
-        ...answerStep,
-        /** Encoded selection supplied by the human control. */
-        selection: Schema.String.check(Schema.isMaxLength(1_000)),
-    }),
-    Schema.Struct({
-        /** Free-text answer step. */
-        stage: Schema.Literal("text"),
-        ...answerStep,
-        /** Offered choices retained while entering free text. */
-        selected: Answers.value.fields.selected,
-        /** Free-text answer supplied by the person. */
-        text: Schema.String.check(Schema.isMaxLength(4_000)),
+        /** The person's picks and optional written answer for question `index`. */
+        answer: Answers.value,
     }),
     Schema.Struct({
         /** Ask whose answer conversation should be opened. */
@@ -172,6 +205,29 @@ export const questionContract = {
             /** Return admission or the ask's terminal state. */
             output: HumanResult,
         },
+        /** Submit the answer of the Agent this Ask waits on; never a human answer. */
+        answerAgent: {
+            /** The child Session owns the Ask; caller authority is host context. */
+            scope: "session",
+            /** Decode the answer submission without any caller-supplied actor. */
+            input: AnswerInput,
+            /** Attribute the accepted answer to its authenticated Agent. */
+            output: Schema.Struct({
+                /** Whether the answer was accepted, or why not. */
+                result: AgentAnswerResult,
+                /** The authenticated Agent that answered. */
+                answeredBy: AnsweredBy,
+            }),
+        },
+        /** Pass the Ask on from the Agent it waits on; never a human action. */
+        escalateAgent: {
+            /** The child Session owns the Ask; caller authority is host context. */
+            scope: "session",
+            /** Decode the escalation without any caller-supplied recipient. */
+            input: EscalateInput,
+            /** Where the Ask waits now, or why it did not move. */
+            output: EscalateResult,
+        },
         /** Decline an ask with an optional note. */
         decline: {
             /** The Session owns this ask. */

package/dist/question/host.d.ts

@@ -1,3 +1,7 @@
 import { type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
 /** One durable question owner over the ordinary extension doors. */
+export declare function questionExtensionFor(routesToSender: boolean): RosteredExtensionV0;
+/** Hub's shared roster sends every Ask to a person. */
 export declare const questionExtension: RosteredExtensionV0;
+/** Local's roster sends an Ask to the Agent that sent the asking work first. */
+export declare const localQuestionExtension: RosteredExtensionV0;