@fungi.computer/shiitake-extensions 0.3.0 → 0.5.0

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;