@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/ask-question.d.ts

@@ -1,25 +1,106 @@
 import type { AgentTool } from "../internal/harness-types.js";
 import type { ToolPolicy } from "./tool-policy.js";
+/** The reserved tool name for AskUserQuestion — shared so the durable-resume path (runtask) can recognize it
+ *  as a content-ask whose SHOWN questions must not be rewritten by an operator `updatedInput` (design/80 D-F).
+ *
+ *  RESERVED means the whole engine keys content-ask semantics on this name: a policy `ask` on it is NEVER
+ *  routed to a synchronous PERMISSION approver — on the main gate, the degraded fall-through, and the
+ *  inherited ancestor wrappers alike (a permission frame's allow/deny cannot carry an ANSWER; CC parity:
+ *  AskUserQuestion never raises a permission card). What it DOES reach, in this order, is the run's own
+ *  content-ask channel: a LIVE question face answers it in-stream (the gate routes the question, not a
+ *  verdict), and only with no live face — or with the durable gate forced — does it park durably or answer
+ *  the typed refusal. Permission-GATING this tool stays unsupported by design; content-ROUTING it is the
+ *  supported path. A caller-supplied tool reusing this name inherits the same routing; don't. */
 export declare const ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion";
+/**
+ * AskUserQuestion (design/64 §5). A model-callable tool that lets the agent ask the USER a structured
+ * multiple-choice question (which approach? which of these?) — distinct from the design/37 permission `ask`
+ * ("may I run this tool?"). The model only EMITS the call; the harness routes it to the caller via the
+ * {@link OnQuestion} seam (deployment supplies a real human / UI / HITL). **LLM has zero IO** — it cannot
+ * collect answers itself. Headless (no `onQuestion`) returns a typed "no human available" so the model
+ * proceeds with a default instead of hanging. **design/80 D-F (answer fence):** the answer no longer assumes a
+ * trusted control plane — in the Supervisor topology it arrives over the wire (an operator `/decide`), an
+ * injection vector. So a `selected` value is echoed as a chosen option ONLY if it is one of the offered option
+ * labels (`selected ⊆ options` — the model's own text), and the operator's free-text (`note`, plus any off-list
+ * input) is wrapped in an untrusted-DATA fence so it can never be read as instructions. Abort while waiting is
+ * handled by the §9 interrupt path (the pending call is closed). Mounting ([884], CC non-interactive `isEnabled`
+ * parity): only when a delivery face exists — a live `onQuestion`, or a durable park consumer (`checkpointStore`
+ * + `durableApproval`/`forceDurableGate`), or an explicit `TaskSpec.interactiveTools: true` — see that knob.
+ */
 export interface AskQuestionOption {
+    /** The choice text the user picks. */
     label: string;
+    /** What this option means / its trade-off. */
     description: string;
+    /** design/116 W3 (CC parity): optional preview content (mockup / code snippet / comparison) shown while this
+     *  option is focused. The engine only TRANSPORTS it — it rides the {@link AskQuestionRequest} to `onQuestion`
+     *  untouched; rendering (markdown box, side-by-side, …) is the shell/HITL surface's job. */
     preview?: string;
 }
 export interface AskQuestion {
+    /** The full question. */
     question: string;
+    /** A short header/label (≤ ~12 chars) for UIs. */
     header: string;
+    /** 2-4 mutually-exclusive choices (unless multiSelect). */
     options: AskQuestionOption[];
+    /** Allow selecting more than one option. */
     multiSelect?: boolean;
 }
 export interface AskQuestionRequest {
     toolCallId: string;
+    /** 1-4 questions. */
     questions: AskQuestion[];
+    /** Runner-filled source identity (parallel to {@link import("./tool-policy.js").AskRequest}.principal,
+     *  design S1d §1): the issuing task's end-user principal (design/62), for per-user attribution by an
+     *  AGGREGATING onQuestion. Worker/tool cannot set it. Undefined ⇒ none (a non-aggregating onQuestion
+     *  ignores it — additive, no-op). `readonly`: Runner-populated metadata. Populated on every path that
+     *  actually CALLS a question face: the in-tool synchronous call, and the gate's pre-execution content-ask
+     *  routing. A durable suspend invokes no face at all, so it carries none. */
     readonly principal?: string;
+    /** Runner-filled source-task identity (= issuing task's session id), for per-worker attribution by an
+     *  aggregating onQuestion. **worker-unforgeable for Runner-created delegated subagents/team members**
+     *  (those child specs do not pass TaskSpec.sessionId — the Runner mints the id); a top-level caller CAN
+     *  still set `TaskSpec.sessionId`, so this is NOT a globally unforgeable run id (design S1d §1.3).
+     *  `readonly` + same "only where a face is really called" caveat as `principal`. */
     readonly sourceTaskId?: string;
+    /**
+     * The canonical hash of the tool-call arguments this question was built from, as computed by the
+     * engine's one `boundInputHashOf` (the same digest the durable park binds its checkpoint to, so the
+     * two lanes are reconcilable against each other). Present only when the engine routed the question
+     * — a directly-mounted tool calling its own face carries none.
+     *
+     * The split to keep straight, because the two words are easy to swap:
+     *  - `(sourceTaskId, toolCallId, boundInputHash)` is the RECONCILIATION key — "is this the same
+     *    question, on the same call, in the same run?". It is what lets an in-stream delivery be matched
+     *    against a parked one, and what an audit trail joins on. It is NOT an identity: all three
+     *    components repeat for two sequential deliveries of an identical question.
+     *  - {@link deliveryId} is the IDENTITY — "which delivery attempt is this?" — and is the only one of
+     *    the two a registry may key open requests on.
+     * Keying a registry on the reconciliation key closes the second delivery on the first one's ticket.
+     */
     readonly boundInputHash?: string;
+    /**
+     * The IDENTITY of this delivery attempt: engine-minted, unique per delivery, never derived from
+     * anything a model or a caller supplies. This is the key for the single-winner obligation in
+     * {@link OnQuestion} — a registry keys open requests on it (scoped by tenant), so a deadline expiry
+     * and a UI submission for the SAME delivery resolve to exactly one winner, and a late answer is
+     * refused instead of applied to a question nobody is waiting on any more.
+     *
+     * Why not the tuple you might reach for first: `toolCallId` comes from the model/provider and is not
+     * guaranteed unique within a session, `sourceTaskId` can be caller-supplied, and the argument hash
+     * is identical for two identical questions. Their combination therefore repeats for two sequential
+     * deliveries of the same question — under which a registry would close the second on the first's
+     * ticket, or hand the second the first's late answer. That tuple remains the RECONCILIATION key
+     * (see {@link boundInputHash}); this field is the identity. One names the question, the other names
+     * the attempt, and only the attempt is unique.
+     *
+     * Present on EVERY delivery the engine makes, by either route (the tool's own call and the gate's
+     * pre-execution routing). Optional on the type only because a deployment may mount the tool itself.
+     */
     readonly deliveryId?: string;
 }
+/** One question's answer: the selected option label(s) + an optional free-text note. */
 export interface QuestionAnswerItem {
     header: string;
     selected: string[];
@@ -28,11 +109,35 @@ export interface QuestionAnswerItem {
 export interface QuestionAnswer {
     answers: QuestionAnswerItem[];
 }
+/**
+ * The "nobody could be reached for this one" arm of {@link OnQuestionOutcome}. Its contract is narrow and
+ * load-bearing: return it ONLY when the deployment made ZERO interaction on this question — no card was
+ * shown, no partial selection was collected, nothing was submitted. That is what lets the engine re-route
+ * the same question (park it durably for a later human, or answer the honest "it was NOT shown" refusal)
+ * without any risk of the same question being decided twice.
+ *
+ * A face that DID show the question and then failed (disconnect, deadline after render, adapter error)
+ * must THROW instead — the two are deliberately different values with different engine handling, and
+ * folding a failure into this arm is what would put one question in front of two deciders.
+ */
 export interface QuestionUnavailable {
     readonly kind: "unavailable";
 }
+/**
+ * The three-valued outcome of a content-ask delivery (one value per thing that can actually happen):
+ *  · a {@link QuestionAnswer} — the human answered (including "selected nothing", which IS an answer);
+ *  · {@link QuestionUnavailable} — nobody was reachable and nothing was shown (see its contract);
+ *  · a THROW — delivery was attempted and failed. Never collapse a throw into `unavailable`.
+ */
 export type OnQuestionOutcome = QuestionAnswer | QuestionUnavailable;
-export type QuestionOutcomeReading = {
+/** How an {@link OnQuestionOutcome} reads. `"contradictory"` covers a value claiming BOTH arms at
+ *  once (the `unavailable` discriminant alongside an `answers` array — structural typing permits it, and
+ *  the outcome is deployment-supplied and may cross a wire), a value claiming NEITHER arm (a failed
+ *  decode must not read as "the user selected nothing"), and a value that cannot be read at all. */
+export type QuestionOutcomeReading = 
+/** The answer, already narrowed AND captured as an inert, density-validated clone — a caller
+ *  neither re-reads the caller's value to get at it nor needs a `structuredClone` of its own. */
+{
     readonly shape: "answered";
     readonly answer: QuestionAnswer;
 } | {
@@ -40,17 +145,78 @@ export type QuestionOutcomeReading = {
 } | {
     readonly shape: "contradictory";
 };
+/**
+ * THE reader for a question outcome, and the only place its fields are touched. Total by construction:
+ * every way the value can misbehave — a throwing getter, both arms at once — lands on
+ * `"contradictory"`, which the callers refuse rather than resolve. That refusal is the point: reading a
+ * contradictory value as unavailable would discard an answer somebody may have given AND re-route the
+ * question to a second decider, while reading it as answered would deliver an answer the face may have
+ * meant to withhold. Neither guess is safe, so neither is made.
+ */
 export declare function classifyQuestionOutcome(outcome: OnQuestionOutcome): QuestionOutcomeReading;
 export declare function canonicalizeCapturedPlainData(node: unknown, seen?: WeakSet<object>): boolean;
+/**
+ * Narrow an {@link OnQuestionOutcome} to its no-interaction arm — the ONLY value that licenses
+ * re-routing a question to a later decider, so it is read strictly (the discriminant must be present
+ * and the value must not also carry answers).
+ *
+ * For a FORWARDING wrapper relaying this seam. The engine's own decision points do not use it: they
+ * call {@link classifyQuestionOutcome} ONCE and switch on the result, because the value is
+ * deployment-supplied and its fields may be getters — classifying twice lets an outcome read as
+ * answered on one call and unavailable on the next, which is precisely how one question would reach
+ * two deciders. A wrapper that needs more than "is this the unavailable arm" should classify once too.
+ */
 export declare function isQuestionUnavailable(outcome: OnQuestionOutcome): outcome is QuestionUnavailable;
+/**
+ * The content-ask seam (design/64 §5.2): the deployment routes an AskUserQuestion to a real human/UI and
+ * returns their selection. Parallel to (and independent of) {@link import("./tool-policy.js").OnAsk} — a
+ * permission ask is allow/deny, a content ask is a choice. `signal` fires on task abort: race your wait so
+ * an unanswered question is released at the deadline (it does not hang the worker).
+ *
+ * **Single-winner obligation (the deployment's half).** A face that races a deadline against a real UI
+ * owns the atomicity: before returning {@link QuestionUnavailable} it must CLOSE the open request, so a
+ * submission arriving one tick later is refused rather than applied. A signal race alone is not enough —
+ * two independent resolutions of one question is the shape this seam exists to prevent. Key the registry
+ * on {@link AskQuestionRequest.deliveryId} (scoped by tenant) — NOT on the call id or the argument hash,
+ * neither of which is unique per delivery. The engine consumes exactly one outcome per call id
+ * and never asks the same call twice, so honoring this contract makes the whole path single-winner; core
+ * does NOT serialize question delivery ACROSS runs (a shared UI seat is the deployment's closure), only
+ * within a run — the tool executes sequentially, so one run never has two questions in flight.
+ */
 export type OnQuestion = (req: AskQuestionRequest, signal?: AbortSignal) => Promise<OnQuestionOutcome>;
+/**
+ * design/173 §8.1/§8.2 — why a synthetic self-answer instruction (the NO_HUMAN text) was returned:
+ * `"seam_absent"` = no `onQuestion` face was wired at all; `"callback_failed"` = a face WAS wired
+ * and threw (shell disconnect / timeout — the more common field case, and the more deceptive one:
+ * the deployment believes it has this limb); `"declined_unavailable"` = a face was wired, it was
+ * called, and it affirmed that nobody was reachable for this question (nothing was shown). The three
+ * must never collapse — "not installed", "installed but broken" and "installed, working, and nobody
+ * home" are three different operator actions.
+ */
 export type SyntheticContinuationReason = "seam_absent" | "callback_failed" | "declined_unavailable";
+/** design/173 §8.1 — who produced the answer the model continues on. The engine never fabricates an
+ *  answer: the synthetic arm returns a self-answer INSTRUCTION, hence the honest name. */
 export type AskAnswerContinuationSource = "human_response" | "synthetic_self_answer_instruction";
+/**
+ * design/173 §8.1 — the AskUserQuestion tool card (`details.type: "ask-question"`, registered in
+ * `CC_DETAIL_TYPES` — the card set is a two-way contract: mint and registration travel in the SAME
+ * change). The in-band structured marker is the AUTHORITATIVE provenance signal (disclosure frames
+ * can drop or reorder; a consumer must never match the NO_HUMAN prose). Two shapes:
+ *  - the CONTINUATION card — every answered exit, human or synthetic (`runContinues: true` is the
+ *    warning-not-error semantic: the run proceeds by design, a headless deployment must not be
+ *    marked failed over it);
+ *  - the INTERACTIVE-FAILURE card — the run refuses the silent synthetic continuation and reports a
+ *    coded tool failure instead (`isError: true`). Two codes, kept apart for the same reason the
+ *    reasons above are: `"question.human_channel_failed"` = the wired channel threw;
+ *    `"question.human_unavailable"` = the channel worked and said nobody was reachable.
+ */
 export type AskQuestionCardDetails = {
     type: "ask-question";
+    /** The question's id (= the tool call id — the same key the park/HITL faces use). */
     questionId: string;
     continuationSource: AskAnswerContinuationSource;
     runContinues: true;
+    /** Present iff `continuationSource` is synthetic. */
     reason?: SyntheticContinuationReason;
 } | {
     type: "ask-question";
@@ -58,23 +224,127 @@ export type AskQuestionCardDetails = {
     code: "question.human_channel_failed" | "question.human_unavailable";
     reason: "callback_failed" | "declined_unavailable";
 };
+/**
+ * The ONE mint point for the continuation card. Every exit that continues the run on
+ * an answer — human or synthetic, in the tool or on the engine's routing lane — builds its card here, so
+ * a new delivery point cannot quietly reopen the silent-degrade hole by shipping without a card.
+ */
 export declare function askQuestionContinuationCard(questionId: string, continuationSource: AskAnswerContinuationSource, reason?: SyntheticContinuationReason): AskQuestionCardDetails;
+/**
+ * The ONE shape validator for a question batch, shared by the tool body and by the engine's routing lane
+ * (which validates BEFORE it puts anything in front of a person — a malformed batch must be refused to
+ * the model, not rendered). Returns the model-facing error text, or `undefined` when the batch is well
+ * formed. Total: it never throws on hostile field shapes.
+ */
 export declare function validateAskQuestions(questions: unknown): string | undefined;
+/** design/173 件3 — engine-side options for the mounted tool (prepare wires them; a deployment
+ *  mounting the tool directly may too). All optional: absent = pre-173 behavior. */
 export interface AskUserQuestionToolOptions {
+    /** The run's RESOLVED interaction posture — see {@link import("./types.js").TaskSpec.interactionPosture}
+     *  for the three-leg resolution (spec > the spawning run's resolved posture > deps); prepare passes
+     *  that one resolved value, the same one the posture door reads.
+     *  Under `"interactive"` BOTH no-answer arms of a wired channel are coded tool FAILURES instead of a
+     *  silent synthetic continuation — a channel that THROWS returns `question.human_channel_failed`, one
+     *  that reports nobody reachable returns `question.human_unavailable` — because an interactive
+     *  deployment must face both. `"headless"`/absent keep the existing degrade. */
     posture?: "interactive" | "headless";
+    /** The EXPLICIT knob (default off) letting posture `"interactive"` continue with the synthetic
+     *  self-answer instruction after all, on BOTH hardened arms (channel threw / nobody reachable);
+     *  disclosure still minted. */
     interactiveFallback?: boolean;
+    /** Engine sink for the synthetic-continuation disclosure (the onError parallel leg — phase
+     *  `"degraded"`, classification `"no-human-autoanswered"`). Deduped **per ask-call** (the dedup key
+     *  is the tool-call id; one call may carry 1–4 questions and still discloses ONCE — "per question"
+     *  would misread against that array), not per run: a second ask-call in the same run still
+     *  discloses. The suppression set lives for ONE prepare (one leg): a continuation leg re-discloses
+     *  the same call id — deliberate, or the second leg's host would be blind; a host aggregating
+     *  across legs dedups on (sessionId, toolCallId) itself. Swallow-guarded — an observer bug never
+     *  faults the ask. */
     onSyntheticContinuation?: (info: {
         questionId: string;
         reason: SyntheticContinuationReason;
     }) => void;
+    /**
+     * The call id of the ONE pending question this leg is redeeming an operator's approval for. An
+     * approval was spent to get that question executed, so an `unavailable` outcome on THAT call must not
+     * be absorbed into the synthetic self-answer: the operator has to learn their decision bought a
+     * question nobody answered, and it becomes the coded failure `question.human_unavailable` instead.
+     * Scoped to the id rather than to the leg — a NEW question raised later on the same leg had no
+     * approval spent on it and keeps the ordinary continuation. (A THROW keeps its own posture-driven
+     * handling on every call; that arm is unchanged.)
+     */
     redeemedApprovalCallId?: string;
+    /** Digest of the question batch that approval was granted for, paired with
+     *  {@link redeemedApprovalCallId}. Call ids are provider-supplied and can repeat, so the id alone
+     *  would let a LATER question inherit the claim that an operator approved it. */
     redeemedApprovalQuestionsHash?: string;
 }
+/**
+ * Durable ask (design/64 TC-5.4 — ABOVE CC, the disconnected-human case): instead of the headless
+ * "proceed with your best judgment" default, an AskUserQuestion **suspends the task durably** and the
+ * answer resumes it — built ENTIRELY from existing primitives, no new gate kind.
+ *
+ * **The park is the fallback, not the mandate.** An adjudicated question parks durably UNLESS this run
+ * has a live question face (see {@link isLiveQuestionFace}), in which case the engine routes the question
+ * to that face and the answer arrives in-stream — same turn, no checkpoint, no rebuild. The park is what
+ * happens when nobody is there: no live face, the face affirming nobody is reachable, or a control-plane
+ * `forceDurableGate` that mandates the durable breakpoint regardless. A deployment that wired a live face
+ * AND wants every question parked anyway states that with `forceDurableGate` (or by not wiring the face).
+ *
+ *  1. Run the task with `durableApproval` + a durable `CheckpointStore` (+ durable session/offload
+ *     stores) and `combinePolicies(createDurableQuestionPolicy(), yourPolicy)`. The policy adjudicates
+ *     the AskUserQuestion call `ask`; in durable mode that suspends BEFORE the tool executes —
+ *     `onQuestion` is never called on the suspend side, so mount the tool with
+ *     {@link QUESTION_AWAITS_RESUME} when no live human is connected.
+ *  2. The HITL surface reads the questions from `checkpoint.pendingAction.args.questions` and collects
+ *     the human's {@link QuestionAnswer} out-of-band (hours/days later, any replica).
+ *  3. `runner.resume(token, { gate: "policy_ask", decision: "allow", boundCallId:
+ *     checkpoint.pendingAction.toolCallId }, { ...taskConfig, onQuestion: async () => answer })` — the resume
+ *     re-mounts the tool with the answer closure; the pending call executes against it and the model
+ *     continues with "The user answered: …". `boundCallId` (design/80 D-1) must name the pending call the
+ *     human answered, or the resume is rejected (`checkpoint.invalid_outcome`).
+ *
+ * A deployment that wants the CC-style threshold form ("wait N minutes for a live human, then go
+ * durable") implements it inside its own policy: return `allow` while a human is connected (the live
+ * `onQuestion` answers synchronously) and `ask` when none is — the sync-vs-durable choice is exactly
+ * one policy decision.
+ */
 export declare function createDurableQuestionPolicy(): ToolPolicy;
+/**
+ * Placeholder {@link OnQuestion} that mounts the AskUserQuestion tool on a worker with NO live human
+ * (the durable-ask suspend side, TC-5.4). It must never actually run — the durable-question policy
+ * suspends the call before execution — so reaching it means the wiring is missing the policy/store;
+ * it throws a configuration error rather than silently telling the model "no human is available".
+ */
 export declare const QUESTION_AWAITS_RESUME: OnQuestion;
+/**
+ * Brand a face that can answer exactly ONE pre-bound call and nothing else — the engine builds one
+ * when a resume carries an operator's answer for the checkpointed question. It is a real face for that
+ * one call id and a dead end for every other question, which is why it must not be mistaken for a run's
+ * live question channel: routing a NEW question to it would turn "ask a human" into a guaranteed
+ * failure on a leg where the honest outcome is to park the new question for its own decision.
+ * Returns the same function, so it can wrap the construction site inline.
+ */
 export declare function markBoundOnlyQuestionFace<F extends OnQuestion>(face: F): F;
+/**
+ * THE named predicate for "this run has a question face that can actually answer a question put to it",
+ * shared by every reader (the gate's routing decision, the tool mount, the wiring manifest's
+ * `question.wired`, and the resume guard). One derivation, because the ways of getting it wrong point in
+ * different directions and all of them are silent:
+ *  · a non-function seat value (a JS caller passing junk) is not a face at all;
+ *  · {@link QUESTION_AWAITS_RESUME} IS a function, and IS the documented standard assembly of the durable
+ *    topology — but its whole contract is that it must never run. Counting it as live would route real
+ *    questions into a configuration error instead of the park the deployment built;
+ *  · a {@link markBoundOnlyQuestionFace} face answers one already-decided call and refuses the rest.
+ * Callers resolve the seat first (`spec.onQuestion ?? deps.onQuestion`) and pass the resolved value.
+ */
 export declare function isLiveQuestionFace(face: unknown): face is OnQuestion;
-export declare function createAskUserQuestionTool(onQuestion?: OnQuestion, source?: {
+/** Build the AskUserQuestion tool. When `onQuestion` is undefined the tool still mounts but returns the
+ *  headless default (so a run started without a human in the loop never hangs). */
+export declare function createAskUserQuestionTool(onQuestion?: OnQuestion, 
+/** design S1d §1.2: Runner-filled source identity, merged into the {@link AskQuestionRequest} so an
+ *  aggregating onQuestion can attribute per worker/user. Omitted ⇒ fields stay undefined (no-op). */
+source?: {
     principal?: string;
     sourceTaskId?: string;
 }, opts?: AskUserQuestionToolOptions): AgentTool;