@sema-agent/core 7.11.2 → 7.12.0

package/dist/core/runner/run-notification-lane.d.ts

@@ -0,0 +1,55 @@
+import { type PeerInboundChainRef } from "../../agents/peer-admission.js";
+import type { PushQueue } from "../push-queue.js";
+import type { SessionStore } from "../session.js";
+import { type PendingSessionNotifications, type SystemInjectionPriority, type TaskNotificationPayload } from "../task-notification.js";
+import type { RunnerDeps, TaskEvent, TaskSpec } from "../types.js";
+import type { SessionReadFileStates } from "./prepare-hands-readface.js";
+import type { NotificationLaneBindings, Prepared, PrepareResume, ResumeRun, RunInternals, RunnerDepsSeat, RunnerSelfSeat, TaskIdRef } from "./contracts.js";
+export interface RunNotificationLaneInput<R> {
+    /** borrowed-readonly — the task spec: prepare's input, and the principal the peer scope is minted from. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the run's event queue: the routed `task_notification` frames are pushed here. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-readonly — the resume plan when this leg resumes a checkpoint (prepare's resume seed is derived from it). */
+    resume: ResumeRun | undefined;
+    /** borrowed-readonly — the trusted run-scoped channel: the detach hub, the uplink, the root / parent anchors, the peer refs, the upstream notification observer. */
+    internals: RunInternals | undefined;
+    /** borrowed-mutable — the stream layer's backstop carrier, handed to prepare so a prepare THROW still names its run. */
+    taskIdRef: TaskIdRef | undefined;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError` in the park closure — after the run, on a swapped
+     *  catalog it is still the CURRENT sink; `models` and prepare's `deps` at the natural-snapshot pin); the one home of why it
+     *  is a seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the TRUSTED Runner self-reference prepare mounts the `run_workflow` tool over (never a TaskSpec field). */
+    self: RunnerSelfSeat;
+    /** borrowed-readonly — the session store prepare acquires / creates the leg's session through. */
+    sessions: SessionStore;
+    /** borrowed-mutable — the Runner's own per-session read-state seat, ALWAYS this Runner's (a caller-supplied one is overridden). */
+    sessionReadStates: SessionReadFileStates;
+    /** borrowed-mutable — the Runner's per-session parked-notification store: the torn-down lane and the escalation pend here. */
+    pendingSessionNotifications: PendingSessionNotifications;
+    /** borrowed-readonly — the orchestrator's entry (a lane may not name the orchestrator; the driver hands it in). */
+    prepareTask: (spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume: PrepareResume | undefined, internals: RunInternals, runnerSelf: RunnerSelfSeat, taskIdRef: TaskIdRef | undefined) => Promise<Prepared>;
+    /** borrowed-readonly — the lanes after this one, entered in this lane's last continuation with what it prepared and bound. */
+    next: (lane: RunNotificationLaneResult) => Promise<R>;
+}
+/** What the lane prepared and bound — the seats every lane after it reads. */
+export interface RunNotificationLaneResult {
+    /** The leg's prepared seat. */
+    prepared: Prepared;
+    /** The ONE injection entry every notification producer rides (the identity lane binds the notify() bridge to it). */
+    injectTaskNotification: (notification: TaskNotificationPayload, opts?: {
+        priority?: SystemInjectionPriority;
+    }) => Promise<"queued" | "parked" | "dropped_duplicate">;
+    /** The turn-open dedup set (the cross-layer double-park dedup): the identity lane registers a redelivered frame's key here. */
+    deliveredAtTurnOpen: Set<string>;
+    /** design/176: the peer inbound chain ref this run carries (the spawn chain's, or a fresh one). */
+    peerInboundChainRef: PeerInboundChainRef;
+    /** The model catalog pinned BEFORE prepare (the natural-snapshot closure for swapDeps): the budget seats resolve against it. */
+    modelCatalog: RunnerDeps["models"];
+    /** The lane's bindings as one seat over its own variables — see {@link NotificationLaneBindings}. */
+    notificationLane: NotificationLaneBindings;
+    /** The queue subscription's release; the leg lane's finally calls it right after flipping `live`. */
+    unsubscribeTaskNotifications: () => void;
+}
+export declare function runNotificationLane<R>(input: RunNotificationLaneInput<R>): Promise<R>;

package/dist/core/runner/run-notification-lane.js

@@ -0,0 +1,128 @@
+import { createPeerInboundChainRef, createPeerSelfRef } from "../../agents/peer-admission.js";
+import { boundInputHashOf } from "../canonical-json.js";
+import { isDelegatedAgentTerminal, isTerminalTaskNotification, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
+import { ToolDetachHub } from "../tool-detach.js";
+import { pendingContentAskCallId } from "./decide-continuation.js";
+export async function runNotificationLane(input) {
+    const { spec, queue, resume, internals, taskIdRef, runner, self, sessions, sessionReadStates, pendingSessionNotifications, prepareTask, next } = input;
+    const prepareResume = resume
+        ? {
+            leafId: resume.cp.leafId,
+            suspendedBatch: new Set(resume.cp.pendingAction.kind === "tool_approval" ? resume.cp.pendingAction.batchToolCallIds : []),
+            seed: resume.cp.state,
+            priorSuspendCount: resume.cp.suspendCount,
+            priorLedger: resume.cp.resourceLedger,
+            priorHumanReview: resume.cp.humanReview,
+            workspaceHandle: resume.cp.state.workspaceHandle,
+            executesApprovedAction: resume.cp.pendingAction.kind === "tool_approval" &&
+                resume.outcome.gate !== "wake" &&
+                resume.outcome.decision === "allow",
+            ...(resume.outcome.gate !== "wake" && resume.outcome.decision === "allow" && pendingContentAskCallId(resume.cp) !== undefined
+                ? {
+                    redeemedContentAskCallId: pendingContentAskCallId(resume.cp),
+                    redeemedContentAskQuestionsHash: boundInputHashOf(resume.cp.pendingAction.args?.questions),
+                }
+                : {}),
+        }
+        : undefined;
+    const taskNotificationQueue = new SystemInjectionQueue();
+    const detachHub = internals?.detachHub ?? new ToolDetachHub();
+    let notificationHarness;
+    let notificationIdent = () => ({});
+    let notificationLaneLive = true;
+    let notificationSessionId;
+    let descendantAnchorDisclosed = false;
+    const parkTaskNotification = (payload, priority) => {
+        if (notificationSessionId !== undefined)
+            pendingSessionNotifications.pend(notificationSessionId, payload, priority);
+        if (!isDelegatedAgentTerminal(payload))
+            return;
+        const uplink = internals?.parentNotify;
+        if (uplink !== undefined) {
+            try {
+                uplink(payload, { priority });
+            }
+            catch (e) {
+                runner.deps.onError?.(e, { phase: "degraded", sessionId: notificationSessionId ?? "", classification: "descendant-terminal-uplink" });
+            }
+            return;
+        }
+        const rootAnchor = internals?.rootSessionId;
+        if (rootAnchor !== undefined && rootAnchor !== notificationSessionId) {
+            pendingSessionNotifications.pend(rootAnchor, payload, priority);
+            return;
+        }
+        if (internals?.parentSessionId !== undefined && !descendantAnchorDisclosed) {
+            descendantAnchorDisclosed = true;
+            runner.deps.onError?.(new Error(`background-agent terminal ${payload.task_id} parked on this run's own session — the delegation tree's root session is not reachable from this run (no uplink, no root anchor)`), { phase: "degraded", sessionId: notificationSessionId ?? "", classification: "descendant-terminal-unrouted" });
+        }
+    };
+    const unsubscribeTaskNotifications = taskNotificationQueue.subscribe((item) => {
+        queue.push({ type: "task_notification", notification: item.payload, priority: item.priority, ...notificationIdent() });
+        if (notificationHarness && prepared.batchHaltRef.current === undefined) {
+            const xml = renderTaskNotificationXml(item.payload);
+            const noteOptions = {
+                provenance: "engine-note",
+                enginePayload: item.payload,
+                ...(item.payload.task_type !== "external" && isTerminalTaskNotification(item.payload) ? { capPreferred: true } : {}),
+            };
+            const deliver = item.priority === "later"
+                ? notificationHarness.followUp(xml, noteOptions)
+                : notificationHarness.steer(xml, { ...noteOptions, ...(item.priority === "now" ? { immediate: true } : {}) });
+            void deliver.then(() => item.onDisposition?.("queued"), () => {
+                parkTaskNotification(item.payload, item.priority);
+                item.onDisposition?.("parked");
+            });
+        }
+        else {
+            parkTaskNotification(item.payload, item.priority);
+            item.onDisposition?.("parked");
+        }
+    });
+    const upstreamTaskNotification = internals?.onTaskNotification;
+    const deliveredAtTurnOpen = new Set();
+    const injectTaskNotification = (notification, opts) => {
+        if (deliveredAtTurnOpen.has(taskNotificationDedupKey(notification)))
+            return Promise.resolve("dropped_duplicate");
+        if (!notificationLaneLive) {
+            parkTaskNotification(notification, opts?.priority ?? "later");
+            return Promise.resolve("parked");
+        }
+        return new Promise((resolve) => {
+            const accepted = taskNotificationQueue.enqueue({
+                kind: "task_notification",
+                priority: opts?.priority ?? "later",
+                dedupKey: taskNotificationDedupKey(notification),
+                payload: notification,
+                onDisposition: resolve,
+            });
+            if (!accepted)
+                resolve("queued");
+        });
+    };
+    const peerSelfRef = internals?.peerSelfRef ?? createPeerSelfRef(internals?.registryScope ?? spec.principal ?? "default");
+    const peerInboundChainRef = internals?.peerInboundChainRef ?? createPeerInboundChainRef();
+    const modelCatalog = runner.deps.models;
+    const prepared = await prepareTask(spec, runner.deps, sessions, prepareResume, {
+        ...(internals ?? {}),
+        peerSelfRef,
+        peerInboundChainRef,
+        detachHub,
+        sessionReadStates,
+        onTaskNotification: (notification, opts) => {
+            try {
+                upstreamTaskNotification?.(notification, opts);
+            }
+            catch {
+            }
+            injectTaskNotification(notification, opts);
+        },
+    }, self, taskIdRef);
+    const notificationLane = {
+        get harness() { return notificationHarness; }, set harness(h) { notificationHarness = h; },
+        get sessionId() { return notificationSessionId; }, set sessionId(s) { notificationSessionId = s; },
+        get ident() { return notificationIdent; }, set ident(f) { notificationIdent = f; },
+        get live() { return notificationLaneLive; }, set live(v) { notificationLaneLive = v; },
+    };
+    return await next({ prepared, injectTaskNotification, deliveredAtTurnOpen, peerInboundChainRef, modelCatalog, notificationLane, unsubscribeTaskNotifications });
+}

package/dist/core/runner/run-reasoning-seat.d.ts

@@ -14,14 +14,14 @@ export interface RunReasoningSeatInput {
     rs: RunState;
     /** borrowed-mutable — the stream layer's backstop carrier: `effectiveReasoning` is published here at every mint. */
     taskIdRef: TaskIdRef | undefined;
-    /** borrowed-mutable — the driver's resolution cell (the `let` the result assembly reads): the leg-entry mint and
-     *  the first-committed-request correction are written here, and the dedupe reads it back. */
-    reasoningResolution: {
-        current: ResolvedReasoning | undefined;
-    };
 }
 export interface RunReasoningSeatResult {
     /** The CONSUMPTION half of {@link ReasoningWireFacts} — installed as the third brain ALS sink. */
     observeReasoningWireFacts: (facts: ReasoningWireFacts) => void;
+    /** #327 — the leg's resolution as a READ FACE over this lane's own `let` (the leg-entry mint, then at most one
+     *  first-committed-request correction): the settle lane's result assembly reads it for `effectiveReasoning`. */
+    reasoningResolution: {
+        readonly current: ResolvedReasoning | undefined;
+    };
 }
 export declare function runReasoningSeat(input: RunReasoningSeatInput): RunReasoningSeatResult;

package/dist/core/runner/run-reasoning-seat.js

@@ -1,10 +1,10 @@
 import { resolveReasoning } from "../../brain/reasoning.js";
 import { emitTrace } from "../trace.js";
 export function runReasoningSeat(input) {
-    const { prepared, rs, taskIdRef, reasoningResolution } = input;
-    reasoningResolution.current = prepared.thinking && prepared.thinking !== "off" ? resolveReasoning(prepared.thinking, prepared.model) : undefined;
+    const { prepared, rs, taskIdRef } = input;
+    let reasoningResolution = prepared.thinking && prepared.thinking !== "off" ? resolveReasoning(prepared.thinking, prepared.model) : undefined;
     const publishReasoningResolution = (r) => {
-        reasoningResolution.current = r;
+        reasoningResolution = r;
         if (taskIdRef)
             taskIdRef.effectiveReasoning = r;
         emitTrace(rs.telemetry.tracer, () => ({
@@ -22,8 +22,8 @@ export function runReasoningSeat(input) {
             ts: Date.now(),
         }));
     };
-    if (reasoningResolution.current !== undefined)
-        publishReasoningResolution(reasoningResolution.current);
+    if (reasoningResolution !== undefined)
+        publishReasoningResolution(reasoningResolution);
     let reasoningFactsConsumed = false;
     const observeReasoningWireFacts = (facts) => {
         if (reasoningFactsConsumed)
@@ -32,7 +32,7 @@ export function runReasoningSeat(input) {
         if (prepared.thinking === undefined || prepared.thinking === "off")
             return;
         const next = resolveReasoning(prepared.thinking, prepared.model, facts);
-        const current = reasoningResolution.current;
+        const current = reasoningResolution;
         if (current !== undefined &&
             current.effective === next.effective &&
             current.graded === next.graded &&
@@ -44,5 +44,5 @@ export function runReasoningSeat(input) {
         }
         publishReasoningResolution(next);
     };
-    return { observeReasoningWireFacts };
+    return { observeReasoningWireFacts, reasoningResolution: { get current() { return reasoningResolution; } } };
 }

package/dist/core/runner/run-settle-and-teardown.d.ts

@@ -0,0 +1,109 @@
+/**
+ * design/393 S6 — the run body's SETTLE AND TEARDOWN (R15), verbatim from `Runner.runLocked`: the end-of-task
+ * compaction's frames and detector reset, the nested-stats fold, the prefix-cache observability and its loud
+ * mismatch / low-hit disclosures, the cross-slice cumulative spend fold, the human-review and mechanism counters,
+ * the result assembly (`assembleResult` — the one place the leg's facts become a TaskResult), the resume leg's
+ * unstarted-action reopen compensation, the read-state seal and the settle-time workspace-state write, the
+ * StopFailure observer, the delegation-lifecycle terminal, the reap-stash for a committed pause, the resumed-terminal
+ * unpin, the memory harvest, the `task.end` trace, `setResult`, the sub-agent's terminal tick, the mooted manual
+ * compaction, the forwarded-frame drain and the queue's `done` + close, the file-history boundary settle and the
+ * prompt-suggestion kickoff — then, in its finally, the four teardown legs in the order they were: the shell-lane
+ * children settle, the background-shell sweep, the registry clears / the background-agent abort / the retained
+ * child sessions, and the owned env's teardown.
+ *
+ * Async (eleven first-level awaits, all of them the same awaits at the same positions). The `queue.push("done")` and
+ * the teardown legs' order are contract (the forwarded-frame drain lands before `done`; the env is torn down after
+ * every reader of it); nothing here reorders them. Products: the result is PUBLISHED through `setResult` and the
+ * effects are installed on the borrowed seats — nothing comes back to the driver (the same empty Result the seat
+ * lanes whose products are all installations carry).
+ */
+import type { AssistantMessage } from "../../internal/llm.js";
+import type { ResolvedReasoning } from "../../brain/reasoning.js";
+import type { PushQueue } from "../push-queue.js";
+import type { SessionStore } from "../session.js";
+import type { CompactOutcome, DelegationLifecycleEvent, TaskEvent, TaskResult, TaskSpec } from "../types.js";
+import { type Stats } from "./assemble-result.js";
+import type { EndOfTaskCompaction, ManualCompactRef, Prepared, ResumeRun, RunInternals, RunnerDepsSeat, RunState, SuspendReap, TaskIdRef } from "./contracts.js";
+export interface RunSettleAndTeardownInput {
+    /** borrowed-readonly — the task spec: the hooks slot, the suggestion opt-in, the retain / forward flags, the task id and principal. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the run's event queue: the compaction / human-input / task_progress / done frames, then CLOSED here. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-mutable — the leg's prepared seat: the settle-time seal and workspace write, the refs the result assembly reads, the env the teardown reaps. */
+    prepared: Prepared;
+    /** borrowed-readonly — the resume plan when this leg resumed a checkpoint (the reopen compensation and the unpin read it). */
+    resume: ResumeRun | undefined;
+    /** borrowed-readonly — the trusted run-scoped channel: the delegation task type, cycle seq, parent task id and the display-sink forward. */
+    internals: RunInternals | undefined;
+    /** borrowed-readonly — the run's mutable state, read for the telemetry / degrade / limits / counters the result and the frames report. */
+    rs: RunState;
+    /** borrowed-mutable — this leg's usage counters: the nested / cumulative folds, the cache-hit rate, the mechanism counters are written here. */
+    stats: Stats;
+    /** borrowed-readonly — the run's event-identity mint. */
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    /** borrowed-readonly — the spawning tool call's id when this task runs AS A SUB-AGENT (gates the terminal tick). */
+    parentToolCallId: string | undefined;
+    /** borrowed-readonly — the sub-agent display name for the terminal tick. */
+    subagentName: string | undefined;
+    /** borrowed-readonly — the loop-liveness latch: `userHalted` signs the result's halt seat. */
+    loopLatch: {
+        readonly userHalted: boolean;
+    };
+    /** borrowed-readonly — the hard walltime timer: `fired` and `latenessMs` ride the result and the `task.end` frame. */
+    timeout: {
+        readonly fired: boolean;
+        readonly latenessMs?: number;
+    };
+    /** borrowed-readonly — the run's own committed tail (the read-state seal). */
+    ownCommittedTailRef: {
+        readonly current: string | undefined;
+    };
+    /** borrowed-readonly — the delegation-lifecycle emission closure (the terminal station is here). */
+    emitDelegationLifecycle: (event: DelegationLifecycleEvent) => void;
+    /** borrowed-mutable — the stream layer's backstop carrier: the owed delegation terminal is cleared here. */
+    taskIdRef: TaskIdRef | undefined;
+    /** borrowed-mutable — the manual /compact seat: the parked waiters are mooted and the channel closed before `done`. */
+    manualCompactRef: ManualCompactRef;
+    /** borrowed-readonly — the boundary lane's drain of the manual-compact waiters (with the outcome every waiter receives). */
+    drainManualCompact: (outcome: CompactOutcome) => void;
+    /** borrowed-readonly — the leg lane's final assistant message (undefined on every no-prompt arm). */
+    final: AssistantMessage | undefined;
+    /** borrowed-readonly — the adopted terminal cause (the leg's throw, or what the terminal-adoption lane lifted over it). */
+    threw: unknown;
+    /** borrowed-readonly — the live-abort flag captured before the leg's release-abort. */
+    abortedLive: boolean;
+    /** borrowed-readonly — design/174: the answered-but-never-collected deliveries the leg's finally settled. */
+    strandedHumanAnswers: ReadonlyArray<{
+        deliveryId: string;
+        toolCallId: string;
+    }>;
+    /** borrowed-readonly — the reasoning seat's resolution, as the read face on its Result (the result's `effectiveReasoning`). */
+    reasoningResolution: {
+        readonly current: ResolvedReasoning | undefined;
+    };
+    /** borrowed-readonly — the end-of-task compaction's outcome (the terminal-adoption lane's `finish` call). */
+    comp: EndOfTaskCompaction;
+    /** borrowed-readonly — the stream's result setter: the assembled TaskResult is published through it exactly once. */
+    setResult: (r: TaskResult) => void;
+    /** borrowed-readonly — the stream's suggestions seat: the fire-and-forget suggestion pass's promise is handed to it. */
+    onSuggestions: (p: Promise<string[]>) => void;
+    /** borrowed-readonly — the stream's reap-stash for a committed pause (what `destroy()` reaps when the run SUSPENDED). */
+    onSuspend: (reap: SuspendReap) => void;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError`, `hooks`, `checkpointStore`, `executionEnv`, `onNotice`);
+     *  the one home of why it is a seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the session store: the resumed-terminal leg unpins the checkpoint's session through it. */
+    sessions: SessionStore;
+    /** borrowed-readonly — the Runner's post-completion prompt-suggestion pass (its private method, as a delegate). */
+    suggestNextPrompts: (spec: TaskSpec, prepared: Prepared, result: TaskResult) => Promise<string[]>;
+    /** borrowed-readonly — the Runner's owned-env teardown (its private method, as a delegate; its gate mirrors the reap-stash's). */
+    teardownOwnedEnv: (prepared: Prepared) => Promise<void>;
+}
+/** Nothing comes back: the result is published through `setResult`, the queue is closed, the teardown legs ran. */
+export interface RunSettleAndTeardownResult {
+}
+export declare function runSettleAndTeardown(input: RunSettleAndTeardownInput): Promise<RunSettleAndTeardownResult>;