@sema-agent/core 7.5.0 → 7.5.1

package/dist/core/runner/prepare-question-face.d.ts

@@ -0,0 +1,119 @@
+/**
+ * design/390 §1.2 M7 — prepareTask's QUESTION-FACE phase, verbatim from the driver: the leg's ONE checkpoint-store
+ * read, the durable mandate as it binds at the question seat, the content-ask binding table (with the leak
+ * bound the routing lane checks against — the constant below), the stranded-answer disclosure and the leg-end
+ * settle, the three-way mount decision (live face / durable face / override), and the AskUserQuestion mount
+ * with its redeemed-approval, posture, fallback and synthetic-continuation arms. The interface is the
+ * dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the
+ * offload-reader mount before it and the scheduler mount after it (design/390 §1.5 S1: a stretch with no await
+ * is extracted as a sync function — an `async` wrapper would open a microtask window). Read-stability of the
+ * host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * One seat is a LIVE GETTER (design/238 D-3): the inherited-unavailable marker set is declared by the driver's
+ * gate-fold section AFTER this phase and read per call at RUN time, so it enters as `() => ReadonlySet` — a
+ * read before the driver declares it throws (temporal dead zone), which is the fail-loud an uninitialized
+ * live read owes.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import { type OnQuestion, type QuestionAnswer } from "../ask-question.js";
+import { type CheckpointStore } from "../checkpoint-store.js";
+import type { RunnerDeps, RuntimeCaps, TaskSpec } from "../types.js";
+import type { PrepareResume } from "./contracts.js";
+export declare const CONTENT_ASK_BINDING_CAP = 32;
+/** One gate-routed content-ask outcome, keyed by the call id it was produced for (see the table's own note). */
+export type ContentAskBinding = ({
+    kind: "answered";
+    answer: QuestionAnswer;
+} | {
+    kind: "failed";
+    error: unknown;
+}) & {
+    /** Digest of the exact question batch this outcome belongs to. The call id alone is not enough
+     *  to redeem a binding: it comes from the model/provider and can repeat, so an entry that
+     *  outlived its call (its call was allowed but never executed) could otherwise be handed to a
+     *  LATER call that happens to reuse the id. Matching on the batch as well means an outcome can
+     *  only ever be delivered for the question it was produced for. */
+    questionsHash: string;
+    /** The engine-minted per-delivery identity (see AskQuestionRequest.deliveryId) — carried so a
+     *  stranded-answer disclosure names DELIVERIES, not call ids: call ids can repeat, and a
+     *  disclosure keyed on them would collapse two lost answers into one. */
+    deliveryId: string;
+};
+export interface PrepareQuestionFaceInput {
+    /** borrowed-readonly — the run's frozen question seat (spec > deps), resolved once at the top of prepare;
+     *  the mount predicate and the live-face derivation both read this one value. */
+    frozenOnQuestion: OnQuestion | undefined;
+    /** borrowed-readonly — the REBOUND spec. Read: `checkpointStore` (the per-run off switch), `durableApproval`
+     *  (the durable face's opt-in), `interactiveTools` (the override), `principal` (the tool's source identity),
+     *  `interactiveQuestionFallback` (restores the continuation under a resolved posture). Never mutated. */
+    spec: Pick<TaskSpec, "checkpointStore" | "durableApproval" | "interactiveTools" | "principal" | "interactiveQuestionFallback">;
+    /** borrowed-readonly — the deployment seats: `checkpointStore` (the store the leg snapshot resolves against)
+     *  and `onError` (the stranded-answer and synthetic-continuation operator lines; swallow-guarded). */
+    deps: Pick<RunnerDeps, "checkpointStore" | "onError">;
+    /** borrowed-readonly — the principal's resolved runtime caps as of this point (`forceDurableGate` is the
+     *  mandate that outranks a live face only where a store exists to park the question). */
+    runtimeCaps: Pick<RuntimeCaps, "forceDurableGate"> | undefined;
+    /** borrowed-readonly — the resolved interaction posture (the door's value), threaded to the tool so both
+     *  no-answer arms harden under it. */
+    resolvedInteractionPosture: "interactive" | "headless" | undefined;
+    /** borrowed-readonly — the durable-resume carrier; only the redeemed content-ask call id and its questions
+     *  hash are read (the one call an operator's approval was spent on). */
+    resume: Pick<PrepareResume, "redeemedContentAskCallId" | "redeemedContentAskQuestionsHash"> | undefined;
+    /** borrowed-readonly — the acquired session id (the tool's source task id; operator-line context). */
+    sessionId: string;
+    /** borrowed-mutable — the run's shared roster (identity is the contract). Writer here: ONE push (the question
+     *  tool) when the mount predicate holds; `contentAskRoutable` reads `includes` per call against the LIVE
+     *  array (the roster is edited in place after the mount). */
+    tools: AgentTool[];
+    /** borrowed-readonly — LIVE GETTER over the inherited-unavailable marker set (declared by the driver's
+     *  gate-fold section after this phase; `has` only, per call at run time). See the module header. */
+    inheritedUnavailableAsks: () => ReadonlySet<string>;
+}
+export interface PrepareQuestionFaceResult {
+    /** borrowed-readonly — THE leg's store snapshot (`resolveCheckpointStore(spec, deps)`): the mount face, the
+     *  routability predicate, the manifest and suspendAsk all read this one value. */
+    checkpointStore: CheckpointStore | undefined;
+    /** borrowed-readonly — the run's live question face through the shared predicate (the reserved resume
+     *  placeholder is a function and is NOT a live face), or undefined. */
+    liveQuestionFace: OnQuestion | undefined;
+    /** borrowed-mutable — the one-shot answer binding table for questions the GATE routed (scope = this leg).
+     *  Writers (R-3): the routing lane (`set`, cap-checked against {@link CONTENT_ASK_BINDING_CAP} before every
+     *  insertion), the mounted face here (`delete`, one-shot redemption or a mismatched-batch drop), the settle
+     *  here (`clear`). Identity is the contract (the routing lane and the face share this exact map). */
+    contentAskBindings: Map<string, ContentAskBinding>;
+    /** owned — THE routability predicate for a content ask (per call, against the live roster and the marker set). */
+    contentAskRoutable: (toolCallId: string) => boolean;
+    /** borrowed-mutable — late answers noted before the leg settles. Writer: the routing lane's delivery-race
+     *  watcher (`push`); reader: the settle here (merged into the result disclosure by delivery id). */
+    lateStrandedAnswers: Array<{
+        deliveryId: string;
+        toolCallId: string;
+    }>;
+    /** owned — THE disclosure lane for an answer a person gave that no call could collect (swallow-guarded). */
+    discloseStrandedAnswers: (records: ReadonlyArray<{
+        deliveryId: string;
+        toolCallId: string;
+    }>, why: string) => void;
+    /** owned — the leg-end settle (`Prepared.settleContentAskBindings`): discloses surviving answers, clears the
+     *  table, returns the records the result carries. */
+    settleContentAskBindings: () => ReadonlyArray<{
+        deliveryId: string;
+        toolCallId: string;
+    }>;
+    /** owned — whether a durable delivery face exists (store wired ∧ (durableApproval ∨ forceDurableGate));
+     *  the manifest's composition-lie detector reuses this exact value. */
+    durableQuestionFace: boolean;
+    /** owned — the face the tool was mounted with: the gate-bound answer for THIS call id if one exists (one-shot),
+     *  else the live face itself; the raw frozen seat when no live face exists. */
+    mountedQuestionFace: OnQuestion | undefined;
+    /** owned — whether THIS prepare mounted the first-party question tool (the routing lane keys on it, not on
+     *  the reserved name). */
+    questionToolMounted: boolean;
+    /** borrowed-readonly — the mounted tool object itself (the exact roster member), so the routing lane can
+     *  validate a batch against the schema the executing call is re-checked against; undefined when not mounted. */
+    mountedQuestionTool: AgentTool | undefined;
+}
+/** The M7 phase body — prepareTask's question-face stretch, verbatim (see the module header). */
+export declare function prepareQuestionFace(input: PrepareQuestionFaceInput): PrepareQuestionFaceResult;

package/dist/core/runner/prepare-question-face.js

@@ -0,0 +1,83 @@
+import { createAskUserQuestionTool, isLiveQuestionFace } from "../ask-question.js";
+import { boundInputHashOf } from "../canonical-json.js";
+import { resolveCheckpointStore } from "../checkpoint-store.js";
+export const CONTENT_ASK_BINDING_CAP = 32;
+export function prepareQuestionFace(input) {
+    const { frozenOnQuestion, spec, deps, runtimeCaps, resolvedInteractionPosture, resume, sessionId, tools, inheritedUnavailableAsks } = input;
+    const onQuestion = frozenOnQuestion;
+    const liveQuestionFace = isLiveQuestionFace(onQuestion) ? onQuestion : undefined;
+    const contentAskBindings = new Map();
+    const checkpointStore = resolveCheckpointStore(spec, deps);
+    const questionParkStoreWired = checkpointStore !== undefined;
+    const questionDurableMandateBinding = runtimeCaps?.forceDurableGate === true && questionParkStoreWired;
+    const contentAskRoutable = (toolCallId) => liveQuestionFace !== undefined &&
+        mountedQuestionTool !== undefined &&
+        tools.includes(mountedQuestionTool) &&
+        !questionDurableMandateBinding &&
+        !inheritedUnavailableAsks().has(toolCallId);
+    const lateStrandedAnswers = [];
+    const discloseStrandedAnswers = (records, why) => {
+        if (records.length === 0)
+            return;
+        try {
+            deps.onError?.(new Error(`AskUserQuestion: ${records.length} question(s) were answered by a person but the call never ` +
+                `executed to collect the answer (${records.map((r) => `${r.toolCallId} [delivery ${r.deliveryId}]`).join(", ")}) — ${why}. The answer(s) were NOT ` +
+                `delivered to the model and are gone with this leg; re-ask if the decision is still needed.`), { phase: "degraded", sessionId, classification: "unconsumed-human-answer" });
+        }
+        catch {
+        }
+    };
+    const settleContentAskBindings = () => {
+        const stranded = [];
+        for (const [callId, bound] of contentAskBindings) {
+            if (bound.kind === "answered")
+                stranded.push({ deliveryId: bound.deliveryId, toolCallId: callId });
+        }
+        contentAskBindings.clear();
+        discloseStrandedAnswers(stranded, "the leg ended first (abort, batch teardown, or a loop failure)");
+        const byDelivery = new Map();
+        for (const r of [...stranded, ...lateStrandedAnswers])
+            byDelivery.set(r.deliveryId, r);
+        return [...byDelivery.values()];
+    };
+    const durableQuestionFace = questionParkStoreWired && (spec.durableApproval !== undefined || runtimeCaps?.forceDurableGate === true);
+    const mountedQuestionFace = liveQuestionFace !== undefined
+        ? async (req, signal) => {
+            const bound = contentAskBindings.get(req.toolCallId);
+            if (bound !== undefined) {
+                if (bound.questionsHash === boundInputHashOf(req.questions)) {
+                    contentAskBindings.delete(req.toolCallId);
+                    if (bound.kind === "answered")
+                        return bound.answer;
+                    throw bound.error;
+                }
+                contentAskBindings.delete(req.toolCallId);
+            }
+            return liveQuestionFace(req, signal);
+        }
+        : onQuestion;
+    const questionToolMounted = spec.interactiveTools === true || (spec.interactiveTools !== false && (onQuestion !== undefined || durableQuestionFace));
+    let mountedQuestionTool;
+    if (questionToolMounted)
+        tools.push((mountedQuestionTool =
+            createAskUserQuestionTool(mountedQuestionFace, { principal: spec.principal, sourceTaskId: sessionId }, {
+                ...(resume?.redeemedContentAskCallId !== undefined
+                    ? {
+                        redeemedApprovalCallId: resume.redeemedContentAskCallId,
+                        ...(resume.redeemedContentAskQuestionsHash !== undefined ? { redeemedApprovalQuestionsHash: resume.redeemedContentAskQuestionsHash } : {}),
+                    }
+                    : {}),
+                ...(resolvedInteractionPosture !== undefined ? { posture: resolvedInteractionPosture } : {}),
+                ...(spec.interactiveQuestionFallback === true ? { interactiveFallback: true } : {}),
+                onSyntheticContinuation: ({ questionId, reason }) => {
+                    deps.onError?.(new Error(`AskUserQuestion ${questionId}: no human answer was obtainable (` +
+                        (reason === "seam_absent"
+                            ? "no onQuestion seam is wired"
+                            : reason === "declined_unavailable"
+                                ? "the wired question channel reported nobody was reachable"
+                                : "the wired question channel failed") +
+                        `) — the model was instructed to self-answer and the run CONTINUES (warning, not a failure).`), { phase: "degraded", sessionId, classification: "no-human-autoanswered" });
+                },
+            })));
+    return { checkpointStore, liveQuestionFace, contentAskBindings, contentAskRoutable, lateStrandedAnswers, discloseStrandedAnswers, settleContentAskBindings, durableQuestionFace, mountedQuestionFace, questionToolMounted, mountedQuestionTool };
+}

package/dist/core/runner/prepare-run-refs.d.ts

@@ -0,0 +1,89 @@
+/**
+ * design/390 §1.2 M3a — prepareTask's RUN-REFS phase, verbatim from the driver: the run's own edited-files
+ * ledger, the harness ref, the per-task skill scope, the display-forwarding wrapper, the three run-local refs
+ * (review request / stop-after-turn / plan mode) with the ctx primitives that write them, the subagent-retain
+ * ledger and the worktree-isolation helper. Nothing here has behavior of its own: the phase MINTS SEATS —
+ * mutable cells and the closures bound to them — that later phases, the tool ctx and the run loop read and
+ * write. The interface is the dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the
+ * file-history phase before it and the inherited-gate fold after it (design/390 §1.5 S1: a stretch with no
+ * await is extracted as a sync function — an `async` wrapper would open a microtask window).
+ *
+ * Every cell that leaves here as `borrowed-mutable` carries its writer table on the Result member (design/238
+ * R-3): the closures minted here, the driver's harness build, the project-context phase's inherited-skill
+ * seed, the skill tool, and the run loop's two writes — nothing else writes them. Read-stability of the host
+ * handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ */
+import type { AgentHarness, ExecutionEnv } from "../../internal/harness.js";
+import type { SubagentWorktreeIsolation } from "../../agents/subagent.js";
+import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
+import type { TaskEvent, TaskSpec } from "../types.js";
+import { ActiveSkillScope } from "./active-skill-scope.js";
+import type { Prepared, RunInternals } from "./contracts.js";
+import { type EditedFilesLedger } from "./edited-files-ledger.js";
+export interface PrepareRunRefsInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `forwardSubagentEvents` (widens the forwarding filter),
+     *  `retainSubagentSessions` (the ledger opt-in and its config), `handsReadOnly` (a read-only run mints no
+     *  worktree helper). Never mutated. */
+    spec: Pick<TaskSpec, "forwardSubagentEvents" | "retainSubagentSessions" | "handsReadOnly">;
+    /** borrowed-readonly — the trusted spawn-side channel; only `onForwardEvent` (the deployment's display
+     *  sink) is read, once, to decide whether a forwarding wrapper exists at all. */
+    internals: Pick<RunInternals, "onForwardEvent"> | undefined;
+    /** borrowed-readonly — the run's resolved env; the worktree helper closes over it (lazy: no I/O until a
+     *  delegation actually mints a worktree). */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the SETTLED task root (`taskRootFinal`): the worktree helper's base repo root. */
+    taskRootFinal: string;
+}
+export interface PrepareRunRefsResult {
+    /** owned — the ledger's writer (`FileEditedHook`): handed to the hands/read-face phase as its post-write
+     *  seat; nothing else calls it. */
+    noteFileEdited: EditedFilesLedger["note"];
+    /** owned — the ledger's LIVE read face (`Prepared.editedFilesSnapshot`, read at result assembly). */
+    editedFilesSnapshot: EditedFilesLedger["snapshot"];
+    /** borrowed-mutable — the harness seat: holds the harness once built, so a tool's execute can read the model
+     *  the parent is CURRENTLY on (design/38 1B: the `ToolExecuteContext.model` snapshot a delegation tool uses
+     *  for `inherit`), and breaks the harness↔tool_search build cycle (design/36 rematerialize). Writers (R-3):
+     *  the driver, ONCE, when the harness is built (`harnessRef.current = harness`) — before any run. Readers:
+     *  `requestStopAfterTurn` here (mirrors the stop onto the harness's one-way flag), the tool ctx's model
+     *  snapshot, the rebuild seam and the delegation mounts. Identity is the contract: every closure minted
+     *  before the harness exists reads this exact cell. */
+    harnessRef: {
+        current?: AgentHarness;
+    };
+    /** borrowed-mutable — the per-task LIFO skill scope. Writers: the project-context phase (the inherited-
+     *  from-parent seed frame, `push`) and the `skill` tool minted over it (`push` on a manifest load; a frame
+     *  closes by `pop`). Readers: the tool ctx's `activeSkillScope()` snapshot and the skill-scope policy layer. */
+    skillScope: ActiveSkillScope;
+    /** owned — the FILTERED display-forwarding wrapper, or undefined when the deployment wired no sink (the
+     *  tool ctx then carries no `forwardEvent` key). */
+    forwardEvent: ((e: TaskEvent) => void) | undefined;
+    /** borrowed-mutable — the review-request cell (`Prepared.reviewRequestRef`). Writers: `requestReview` here
+     *  (the first request wins) and the run loop's turn-boundary consumer, which clears `pending` once the
+     *  `plan_review` checkpoint is minted. */
+    reviewRequestRef: Prepared["reviewRequestRef"];
+    /** owned — the ctx primitive that arms `reviewRequestRef` (design/80 D-B). */
+    requestReview: (opts?: {
+        reason?: string;
+    }) => void;
+    /** borrowed-mutable — the stop-after-turn latch (`Prepared.stopRequestedRef`). Writers: `requestStopAfterTurn`
+     *  here, and nothing else; the run loop reads it at a turn boundary. */
+    stopRequestedRef: Prepared["stopRequestedRef"];
+    /** owned — the ctx primitive: flips the latch and mirrors it onto the harness's one-way flag. */
+    requestStopAfterTurn: () => void;
+    /** borrowed-mutable — the plan-mode flag (`Prepared.planModeRef`). Writers: `enterPlanMode` here, and the run
+     *  loop's resume ladder, which re-arms it when a REJECTED `plan_review` resumes into a re-plan. Read by the
+     *  tool-call gate (the write-effect refusal). */
+    planModeRef: Prepared["planModeRef"];
+    /** owned — the ctx primitive (mounted on the ctx only under `enablePlanMode`). */
+    enterPlanMode: () => void;
+    /** ownership-ref — the parent-run subagent-retain ledger, or undefined when the spec did not opt in. Its
+     *  lifecycle protocol belongs to the Runner (disposed in the task's terminal finally, design/122 D4); a
+     *  prepare that throws has nothing to release here — the ledger is empty until a delegation retains. */
+    subagentRetain: SubagentRetainLedger | undefined;
+    /** owned — the Agent tool's worktree-isolation helper (lazy; write-capable runs only), or undefined. */
+    worktreeIsolation: SubagentWorktreeIsolation | undefined;
+}
+/** The M3a phase body — prepareTask's run-refs stretch, verbatim (see the module header). */
+export declare function prepareRunRefs(input: PrepareRunRefsInput): PrepareRunRefsResult;

package/dist/core/runner/prepare-run-refs.js

@@ -0,0 +1,39 @@
+import { createSubagentWorktreeHelper } from "../../agents/subagent.js";
+import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
+import { ActiveSkillScope } from "./active-skill-scope.js";
+import { createEditedFilesLedger } from "./edited-files-ledger.js";
+export function prepareRunRefs(input) {
+    const { spec, internals, executionEnv, taskRootFinal } = input;
+    const { note: noteFileEdited, snapshot: editedFilesSnapshot } = createEditedFilesLedger();
+    const harnessRef = {};
+    const skillScope = new ActiveSkillScope();
+    const forwardSink = internals?.onForwardEvent;
+    const forwardEvent = forwardSink
+        ? (e) => {
+            if (e.type === "task_progress")
+                forwardSink(e);
+            else if (spec.forwardSubagentEvents === true &&
+                (e.type === "text_delta" || e.type === "text_end" || e.type === "reasoning_delta" || e.type === "tool_start" || e.type === "tool_end")) {
+                forwardSink(e);
+            }
+        }
+        : undefined;
+    const reviewRequestRef = {};
+    const requestReview = (opts) => {
+        if (reviewRequestRef.pending === undefined) {
+            reviewRequestRef.pending = opts?.reason !== undefined ? { reason: opts.reason } : {};
+        }
+    };
+    const stopRequestedRef = { current: false };
+    const requestStopAfterTurn = () => {
+        stopRequestedRef.current = true;
+        harnessRef.current?.requestStopAfterTurn();
+    };
+    const planModeRef = { active: false };
+    const enterPlanMode = () => {
+        planModeRef.active = true;
+    };
+    const subagentRetain = spec.retainSubagentSessions ? new SubagentRetainLedger(spec.retainSubagentSessions) : undefined;
+    const worktreeIsolation = spec.handsReadOnly !== true ? createSubagentWorktreeHelper(executionEnv, taskRootFinal) : undefined;
+    return { noteFileEdited, editedFilesSnapshot, harnessRef, skillScope, forwardEvent, reviewRequestRef, requestReview, stopRequestedRef, requestStopAfterTurn, planModeRef, enterPlanMode, subagentRetain, worktreeIsolation };
+}

package/dist/core/runner/prepare-safety-scan.d.ts

@@ -1,4 +1,5 @@
 import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
+import type { IrreversibilityTier, ReversibilityProbes } from "./contracts.js";
 /** The namespaced-name shapes the protocol table currently owns, rendered for the two messages that have
  *  to name them (the caller-name reservation and the policy audit's unprefixed-name arm). Read from the
  *  table rather than written out: a message that hard-codes ONE protocol becomes wrong — while staying
@@ -38,14 +39,14 @@ export interface PrepareSafetyScanResult {
     /** borrowed-mutable — tools whose effect is irreversible (`always`, or `maybe` incl. by probe). */
     irreversibleTools: Set<string>;
     /** borrowed-mutable — static per-tool irreversibility tier (prepare-time resolution). */
-    irreversibilityTier: Map<string, "never" | "maybe" | "always">;
+    irreversibilityTier: IrreversibilityTier;
     /** borrowed-mutable — explicit NEGATIVE axis judgments (report-face only; `riskAxesOf` reads). */
     axisExplicitNegatives: Map<string, {
         irreversible?: false;
         egress?: false;
     }>;
     /** borrowed-mutable — declared reversibility probes by tool name. */
-    reversibilityProbes: Map<string, NonNullable<TaskSpec["tools"]>[number]["reversibilityProbe"]>;
+    reversibilityProbes: ReversibilityProbes;
     /** borrowed-readonly — the caller roster's own names, snapshotted before the first await. */
     ownToolNames: ReadonlySet<string>;
 }