@sema-agent/core 7.11.0 → 7.11.2

package/dist/core/runner/run-brain-sinks.js

@@ -0,0 +1,61 @@
+import { runWithBrainTelemetry, runWithReasoningWireFacts, runWithStatusSink } from "../../brain/status-sink.js";
+import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
+import { emitTrace } from "../trace.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+export function runBrainSinks(input) {
+    const { queue, internals, rs, ident, parentToolCallId, observeReasoningWireFacts } = input;
+    const subagentName = parentToolCallId !== undefined && internals?.agentName !== undefined ? inlineUntrusted(internals.agentName.slice(0, 320), 80) : undefined;
+    const statusSinkNotifier = createSafeNotifier({
+        onError: (f) => console.warn(`[sema-core] ${f.site}: run-internals status sink threw (contained; further failures counted, not re-disclosed): ${f.error.message}`),
+    });
+    const statusEmit = (s) => {
+        const frame = {
+            type: "status",
+            phase: s.phase,
+            ...(s.detail !== undefined ? { detail: s.detail } : {}),
+            ...(s.retryInSec !== undefined ? { retryInSec: s.retryInSec } : {}),
+            ...(s.retryInMs !== undefined ? { retryInMs: s.retryInMs } : {}),
+            ...(s.retryAtMs !== undefined ? { retryAtMs: s.retryAtMs } : {}),
+            ...(s.elapsedMs !== undefined ? { elapsedMs: s.elapsedMs } : {}),
+            ...(s.timeoutMs !== undefined ? { timeoutMs: s.timeoutMs } : {}),
+            ...(s.attempt !== undefined ? { attempt: s.attempt } : {}),
+            ...(s.maxRetries !== undefined ? { maxRetries: s.maxRetries } : {}),
+            ...(s.errClass !== undefined ? { errClass: s.errClass } : {}),
+            ...(s.errorStatus !== undefined ? { errorStatus: s.errorStatus } : {}),
+            ...ident(),
+        };
+        Object.freeze(frame);
+        const accepted = queue.push(frame);
+        if (accepted && internals?.onStatusEvent !== undefined) {
+            statusSinkNotifier.notify(() => observeThenableRejection(internals.onStatusEvent?.(frame), statusSinkNotifier, "runtask.onStatusEvent"), "runtask.onStatusEvent");
+        }
+    };
+    const telemetryEmit = (t) => {
+        emitTrace(rs.telemetry.tracer, () => t.kind === "failover"
+            ? {
+                kind: "brain.failover",
+                version: 1,
+                taskId: rs.telemetry.taskId,
+                servedIndex: t.servedIndex,
+                total: t.total,
+                ...(t.errorCode !== undefined ? { errorCode: t.errorCode } : {}),
+                ts: Date.now(),
+            }
+            : t.kind === "breaker"
+                ? { kind: "breaker.transition", version: 1, taskId: rs.telemetry.taskId, key: t.key, phase: t.phase, failures: t.failures, ts: Date.now() }
+                : t.kind === "retry"
+                    ? {
+                        kind: "brain.retry",
+                        version: 1,
+                        taskId: rs.telemetry.taskId,
+                        attempt: t.attempt,
+                        phase: t.phase,
+                        ...(t.errClass !== undefined ? { errClass: t.errClass } : {}),
+                        ...(t.nextDelayMs !== undefined ? { nextDelayMs: t.nextDelayMs } : {}),
+                        ts: Date.now(),
+                    }
+                    : { kind: "vision.placeholder", version: 1, taskId: rs.telemetry.taskId, count: t.count, ts: Date.now() });
+    };
+    const withBrainSinks = (fn) => runWithStatusSink(statusEmit, () => runWithBrainTelemetry(telemetryEmit, () => runWithReasoningWireFacts(observeReasoningWireFacts, fn)));
+    return { subagentName, withBrainSinks };
+}

package/dist/core/runner/run-clock-and-content.d.ts

@@ -0,0 +1,52 @@
+/**
+ * design/393 S5 — the run body's CLOCK and CONTENT seats (R6), verbatim from `Runner.runLocked`: the per-slice
+ * walltime window and its MONOTONIC deadline anchored at task start, the hard-abort timer armed against that same
+ * deadline (a suspendable task gets the backstop grace), the content-event push that also forwards a sub-agent's
+ * events to the parent's display sink, the run's own committed-tail ref and the `message_committed` mint that
+ * retires a settled tool call from the started set.
+ */
+import type { PushQueue } from "../push-queue.js";
+import type { TaskEvent, TaskSpec } from "../types.js";
+import { startTimeout } from "./clock-and-limits.js";
+import type { Prepared, RunInternals, RunState } from "./contracts.js";
+export interface RunClockAndContentInput {
+    /** borrowed-readonly — the task spec: `limits.maxWalltimeMs`. */
+    spec: TaskSpec;
+    /** borrowed-readonly — the leg's prepared seat: the harness and abort controller the timer is armed against, the
+     *  resource-suspend eligibility. */
+    prepared: Prepared;
+    /** borrowed-mutable — the run's event queue: content events and `message_committed` frames. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-readonly — the trusted run-scoped channel: `onForwardEvent` (the parent's display sink). */
+    internals: RunInternals | undefined;
+    /** borrowed-mutable — the run's mutable state: `counters.walltimeSyncBackstopFired` is zeroed here; the monotonic
+     *  task-start anchor is read. */
+    rs: RunState;
+    /** borrowed-readonly — the run's event-identity mint (stamped on every committed frame). */
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    /** borrowed-readonly — the spawning tool call's id when this task runs AS A SUB-AGENT; forwarding is gated on it. */
+    parentToolCallId: string | undefined;
+    /** borrowed-mutable — the tool-mount lane's started-call set: a committed toolResult retires its id here. */
+    startedToolCallIds: Set<string>;
+}
+export interface RunClockAndContentResult {
+    /** design/164: the PER-SLICE active clock, or undefined (0 is a valid, exhausted window). */
+    effectiveTimeoutMs: number | undefined;
+    /** RB-20: the monotonic deadline every walltime enforcement decision reads, or undefined. */
+    walltimeMonotonicDeadline: number | undefined;
+    /** The hard walltime backstop: its fired flag / lateness, and the clear the teardown calls. */
+    timeout: ReturnType<typeof startTimeout>;
+    /** Push a content event to the run's queue and, for a sub-agent, to the parent's display sink. */
+    pushContent: (e: TaskEvent) => void;
+    /** #483: the id of the LAST entry this run committed — the settle-time seal's provenance anchor. */
+    ownCommittedTailRef: {
+        current: string | undefined;
+    };
+    /** The `message_committed` mint every persisted entry of this run flows through. */
+    emitCommitted: (entryId: string, role: "user" | "assistant" | "toolResult", toolCallId?: string) => void;
+}
+export declare function runClockAndContent(input: RunClockAndContentInput): RunClockAndContentResult;

package/dist/core/runner/run-clock-and-content.js

@@ -0,0 +1,26 @@
+import { startTimeout } from "./clock-and-limits.js";
+export function runClockAndContent(input) {
+    const { spec, prepared, queue, internals, rs, ident, parentToolCallId, startedToolCallIds } = input;
+    const effectiveTimeoutMs = spec.limits?.maxWalltimeMs;
+    const walltimeMonotonicDeadline = effectiveTimeoutMs !== undefined ? rs.telemetry.taskStartMonotonic + effectiveTimeoutMs : undefined;
+    rs.counters.walltimeSyncBackstopFired = false;
+    const timeout = startTimeout(prepared.harness, prepared.abortController, walltimeMonotonicDeadline !== undefined ? walltimeMonotonicDeadline - performance.now() : undefined, prepared.suspendForResource !== undefined);
+    const pushContent = (e) => {
+        queue.push(e);
+        if (parentToolCallId !== undefined && internals?.onForwardEvent) {
+            try {
+                internals.onForwardEvent(e);
+            }
+            catch {
+            }
+        }
+    };
+    const ownCommittedTailRef = { current: undefined };
+    const emitCommitted = (entryId, role, toolCallId) => {
+        ownCommittedTailRef.current = entryId;
+        if (role === "toolResult" && toolCallId !== undefined)
+            startedToolCallIds.delete(toolCallId);
+        queue.push({ type: "message_committed", entryId, role, ...(toolCallId !== undefined ? { toolCallId } : {}), ...ident() });
+    };
+    return { effectiveTimeoutMs, walltimeMonotonicDeadline, timeout, pushContent, ownCommittedTailRef, emitCommitted };
+}

package/dist/core/runner/run-compaction-machinery.d.ts

@@ -0,0 +1,35 @@
+import type { Model } from "../../internal/llm.js";
+import { type MaybeCompactOptions } from "../auto-compaction.js";
+import { type ModelPricing } from "../pricing.js";
+import type { Brain, TaskSpec } from "../types.js";
+import type { Stats } from "./assemble-result.js";
+import type { Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
+export interface RunCompactionMachineryInput {
+    /** borrowed-readonly — the task spec: the compaction settings. */
+    spec: TaskSpec;
+    /** borrowed-readonly — the leg's prepared seat: the model, the prompt overhead, the usage governance and the session id. */
+    prepared: Prepared;
+    /** borrowed-mutable — the run's mutable state: `telemetry.unpricedSpend` is set when a summarizer model is unpriced;
+     *  the budget ceiling and the telemetry are read. */
+    rs: RunState;
+    /** borrowed-mutable — the run's usage counters: every accounted summary call adds to them (compaction spend
+     *  tracked separately too). */
+    stats: Stats;
+    /** borrowed-readonly — the telemetry lane's price-table door (#462), consulted for every summarizer table adopted. */
+    noteUnevaluablePriceTable: (p: ModelPricing) => void;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`brain`, `pricing`, `onError`). */
+    runner: RunnerDepsSeat;
+}
+export interface RunCompactionMachineryResult {
+    /** The accounted compaction brain — `complete` always provided, usage recorded inline. */
+    compactionBrain: Brain;
+    /** design/64 §25 (A): whether ROUTINE turn-boundary compaction runs for this task. */
+    withinTaskCompaction: boolean;
+    /** §17.4: the consecutive-failure circuit breaker shared by every compaction lane of the run. */
+    compactionBreaker: {
+        failures: number;
+    };
+    /** design/145 门A/§3: the window-safety wiring (per call — a mid-task degrade moves the fallback target). */
+    windowSafetyOptions: (mainModel: Model) => Pick<MaybeCompactOptions, "fallbackBudget" | "onWindowSafety">;
+}
+export declare function runCompactionMachinery(input: RunCompactionMachineryInput): RunCompactionMachineryResult;

package/dist/core/runner/run-compaction-machinery.js

@@ -0,0 +1,98 @@
+import { DEFAULT_COMPACTION_SETTINGS } from "../../internal/harness.js";
+import { resolveTriggerWindow } from "../context-edit.js";
+import { sanitizeCompactionSettings } from "../auto-compaction.js";
+import { isModelPriced, modelCostToPricing } from "../pricing.js";
+import { emitTrace } from "../trace.js";
+import { runWithReasoningWireFacts, runWithStatusSink } from "../../brain/status-sink.js";
+import { cacheFamilyOf, usageCostMicroUsd } from "./usage-accounting.js";
+export function runCompactionMachinery(input) {
+    const { spec, prepared, rs, stats, noteUnevaluablePriceTable, runner } = input;
+    const recordCompactionUsage = (m, msg) => {
+        const u = msg?.usage;
+        if (!u)
+            return;
+        const fam = cacheFamilyOf(m);
+        const price = runner.deps.pricing?.[m.id] ?? modelCostToPricing(m.cost);
+        const priced = isModelPriced(m, runner.deps.pricing);
+        if (!priced)
+            rs.telemetry.unpricedSpend = true;
+        noteUnevaluablePriceTable(price);
+        const { totalInputTokens, uncachedInputTokens, costMicroUsd } = usageCostMicroUsd(fam, u, price);
+        stats.tokens += u.totalTokens || 0;
+        stats.promptTokens += uncachedInputTokens;
+        stats.totalInputTokens += totalInputTokens;
+        stats.cachedTokens += u.cacheRead || 0;
+        stats.cacheWriteTokens += u.cacheWrite || 0;
+        stats.outputTokens += u.output || 0;
+        stats.costMicroUsd += costMicroUsd;
+        stats.compactionMicroUsd = (stats.compactionMicroUsd ?? 0) + costMicroUsd;
+        emitTrace(rs.telemetry.tracer, () => ({
+            kind: "brain.call", version: 1, taskId: rs.telemetry.taskId, model: m.id, provider: m.provider,
+            promptTokens: uncachedInputTokens, totalInputTokens, completionTokens: u.output || 0,
+            cacheRead: u.cacheRead || 0, cacheWrite: u.cacheWrite || 0,
+            latencyMs: 0, ...(priced ? { costMicroUsd } : {}), ...(typeof msg?.stopReason === "string" ? { stopReason: msg.stopReason } : {}), ts: Date.now(),
+        }));
+    };
+    const compactionBrain = {
+        stream: runner.deps.brain.stream,
+        complete: async (m, c, o) => {
+            const msg = await runWithStatusSink(() => { }, async () => await runWithReasoningWireFacts(() => { }, async () => runner.deps.brain.complete
+                ? await runner.deps.brain.complete(m, c, o)
+                : await (await Promise.resolve(runner.deps.brain.stream(m, c, o))).result()));
+            recordCompactionUsage(m, msg);
+            return msg;
+        },
+    };
+    const withinTaskCompaction = (spec.compaction?.enabled ?? true) && (spec.compaction?.withinTask ?? true);
+    const compactionBreaker = { failures: 0 };
+    if (spec.compaction?.enabled ?? true) {
+        const prefixWindow = resolveTriggerWindow(prepared.model).window;
+        if (Number.isFinite(prefixWindow) && prefixWindow > 0) {
+            const prefixSettings = sanitizeCompactionSettings({ ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction }, prefixWindow);
+            const prefixCompactAt = prefixWindow - prefixSettings.reserveTokens;
+            if (prepared.promptOverheadTokens >= prefixCompactAt) {
+                runner.deps.onError?.(new Error(`compaction cannot help: the fixed request prefix (system prompt + tool schemas, ≈${prepared.promptOverheadTokens} tokens) ` +
+                    `already meets or exceeds the compaction threshold (${prefixCompactAt} of a ${prefixWindow}-token window). ` +
+                    `Compaction only shrinks conversation history, so this run will re-trigger or overflow regardless — ` +
+                    `shrink the system prompt/tool surface or use a larger-window model.`), { phase: "config", sessionId: prepared.sessionId });
+            }
+        }
+    }
+    const windowSafetyOptions = (mainModel) => ({
+        ...(rs.budget.maxCostMicroUsd !== undefined
+            ? {
+                fallbackBudget: {
+                    spentMicroUsd: () => stats.costMicroUsd,
+                    capMicroUsd: rs.budget.maxCostMicroUsd,
+                    mainInputPer1M: (runner.deps.pricing?.[mainModel.id] ?? modelCostToPricing(mainModel.cost)).inputPer1M,
+                },
+            }
+            : {}),
+        onWindowSafety: (info) => {
+            if (info.kind === "fallback") {
+                emitTrace(rs.telemetry.tracer, () => ({
+                    kind: "compaction.model_fallback",
+                    version: 1,
+                    taskId: rs.telemetry.taskId,
+                    contentTokens: info.contentTokens,
+                    headroomTokens: info.headroomTokens ?? 0,
+                    truncationRatio: info.truncationRatio,
+                    ...(info.estCostMicroUsd !== undefined ? { estCostMicroUsd: info.estCostMicroUsd } : {}),
+                    ts: Date.now(),
+                }));
+            }
+            else {
+                emitTrace(rs.telemetry.tracer, () => ({
+                    kind: "compaction.clamp_disclosure",
+                    version: 1,
+                    taskId: rs.telemetry.taskId,
+                    truncationRatio: info.truncationRatio,
+                    reason: info.reason ?? "tolerance",
+                    ...(info.estCostMicroUsd !== undefined ? { estCostMicroUsd: info.estCostMicroUsd } : {}),
+                    ts: Date.now(),
+                }));
+            }
+        },
+    });
+    return { compactionBrain, withinTaskCompaction, compactionBreaker, windowSafetyOptions };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * design/393 S5 — the run body's GIT LANE (R12), verbatim from `Runner.runLocked`: the git-status re-assert closure
+ * installed on `prepared.gitStatusRef` (compaction landing hook + owed-frame retry — an engine-minted standalone
+ * append with the receipt in hand, the announced mirror written only then), the parked mirror flush (F4), the
+ * owed-frame retry subscription registered BEFORE the boundary handler, the boundary subscription itself and the
+ * harness event subscription that dispatches to the five handler closures. The three subscriptions are taken in the
+ * order the driver took them, and the four closures come back for the driver to await and release where it did.
+ */
+import type { AgentHarnessEvent } from "../../internal/harness.js";
+import type { Model } from "../../internal/llm.js";
+import type { PushQueue } from "../push-queue.js";
+import type { TaskEvent } from "../types.js";
+import type { Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
+export interface RunGitLaneInput {
+    /** borrowed-mutable — the leg's prepared seat: `gitStatusRef.reassert` is installed here and the ref's announced /
+     *  mirror / protection slots are written by the closures; the harness is subscribed to, the session appended to. */
+    prepared: Prepared;
+    /** borrowed-mutable — the run's event queue: the re-assert pushes its `steering_injected` echo frame. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-mutable — the run's mutable state: the re-assert counts itself on `attach.attachmentsInjected`. */
+    rs: RunState;
+    /** borrowed-readonly — the run's event-identity mint (stamped on the echo frame). */
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    /** borrowed-readonly — the harness-handlers lane's message_update closure, dispatched to by identity. */
+    onMessageUpdate: (event: Extract<AgentHarnessEvent, {
+        type: "message_update";
+    }>) => void;
+    /** borrowed-readonly — the harness-handlers lane's message_end closure. */
+    onMessageEnd: (event: Extract<AgentHarnessEvent, {
+        type: "message_end";
+    }>) => void;
+    /** borrowed-readonly — the harness-handlers lane's tool_execution_start closure. */
+    onToolStart: (event: Extract<AgentHarnessEvent, {
+        type: "tool_execution_start";
+    }>) => void;
+    /** borrowed-readonly — the harness-handlers lane's tool_execution_end closure. */
+    onToolEnd: (event: Extract<AgentHarnessEvent, {
+        type: "tool_execution_end";
+    }>) => void;
+    /** borrowed-readonly — the harness-handlers lane's turn_end closure. */
+    onTurnEnd: () => void;
+    /** borrowed-readonly — the turn-boundary lane's handler, registered on `turn_boundary` AFTER the owed-frame retry
+     *  so a pending announcement is re-asserted into the session ahead of the boundary's own context work. */
+    onTurnBoundary: (event: {
+        model: Model;
+    }) => Promise<undefined>;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE inside the closures (`onError`). */
+    runner: RunnerDepsSeat;
+}
+export interface RunGitLaneResult {
+    /** The parked-mirror flush — awaited at the serialization points (the owed-frame retry here; prompt settle in the driver). */
+    flushGitMirror: () => Promise<void>;
+    /** The owed-frame retry's `turn_boundary` subscription; the driver's teardown releases it first. */
+    unsubGitRetry: () => void;
+    /** The boundary handler's `turn_boundary` subscription; released second. */
+    unsubBoundary: () => void;
+    /** The harness event subscription; released third. */
+    unsub: () => void;
+}
+export declare function runGitLane(input: RunGitLaneInput): RunGitLaneResult;

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

@@ -0,0 +1,102 @@
+import { GIT_STATUS_ECHO_PREVIEW } from "./git-status-frame.js";
+import { wrapGitFrame } from "./git-leg-delivery.js";
+export function runGitLane(input) {
+    const { prepared, queue, rs, ident, onMessageUpdate, onMessageEnd, onToolStart, onToolEnd, onTurnEnd, onTurnBoundary, runner } = input;
+    prepared.gitStatusRef.reassert = async () => {
+        const ref = prepared.gitStatusRef;
+        const frame = ref.frame;
+        if (frame === undefined)
+            return;
+        delete ref.mirrorOwed;
+        const use = ref.overBudgetShrunk && frame.shrunk !== undefined
+            ? { kind: "degraded", body: frame.shrunk.body, hash: frame.shrunk.hash }
+            : { kind: frame.kind, body: frame.body, hash: frame.hash };
+        const wrapped = wrapGitFrame(use.body, prepared.reminderMark);
+        try {
+            const entryId = await prepared.session.appendMessage({
+                role: "user",
+                content: [{ type: "text", text: wrapped }],
+                timestamp: Date.now(),
+                engineMinted: true,
+            });
+            ref.announced = { kind: use.kind, hash: use.hash, entryId };
+            ref.protectedText = wrapped;
+            if (use.kind === "full" && frame.shrunk !== undefined) {
+                ref.wrappedShrink = { find: wrapped, replace: wrapGitFrame(frame.shrunk.body, prepared.reminderMark) };
+            }
+            else {
+                delete ref.wrappedShrink;
+            }
+            queue.push({ type: "steering_injected", source: "git_status", preview: GIT_STATUS_ECHO_PREVIEW[use.kind], ...ident() });
+            rs.attach.attachmentsInjected += 1;
+            try {
+                await prepared.session.appendGitAnnouncement?.({ kind: use.kind, hash: use.hash, entryId });
+            }
+            catch (mirrorErr) {
+                try {
+                    runner.deps.onError?.(new Error(`git announcement mirror write failed (frame delivered; next leg re-announces): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`), { phase: "degraded", sessionId: prepared.sessionId });
+                }
+                catch {
+                }
+            }
+        }
+        catch (err) {
+            ref.announced = { kind: use.kind, hash: use.hash, pending: true };
+            try {
+                runner.deps.onError?.(new Error(`git status frame re-assert append failed (pending; retried at the next boundary): ${err instanceof Error ? err.message : String(err)}`), { phase: "degraded", sessionId: prepared.sessionId });
+            }
+            catch {
+            }
+        }
+    };
+    const flushGitMirror = async () => {
+        const owed = prepared.gitStatusRef.mirrorOwed;
+        if (owed === undefined)
+            return;
+        if (prepared.gitStatusRef.overBudgetShrunk && owed.kind === "full") {
+            delete prepared.gitStatusRef.mirrorOwed;
+            return;
+        }
+        delete prepared.gitStatusRef.mirrorOwed;
+        try {
+            await prepared.session.appendGitAnnouncement?.(owed);
+        }
+        catch (mirrorErr) {
+            prepared.gitStatusRef.mirrorOwed = owed;
+            try {
+                runner.deps.onError?.(new Error(`git announcement mirror write failed (frame delivered; retried at the next serialization point): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`), { phase: "degraded", sessionId: prepared.sessionId });
+            }
+            catch {
+            }
+        }
+    };
+    const unsubGitRetry = prepared.harness.on("turn_boundary", async () => {
+        await flushGitMirror();
+        if (prepared.gitStatusRef.announced?.pending === true)
+            await prepared.gitStatusRef.reassert?.();
+        return undefined;
+    });
+    const unsubBoundary = prepared.harness.on("turn_boundary", onTurnBoundary);
+    const unsub = prepared.harness.subscribe((event) => {
+        switch (event.type) {
+            case "message_update":
+                onMessageUpdate(event);
+                break;
+            case "message_end":
+                onMessageEnd(event);
+                break;
+            case "tool_execution_start":
+                onToolStart(event);
+                break;
+            case "tool_execution_end":
+                onToolEnd(event);
+                break;
+            case "turn_end":
+                onTurnEnd();
+                break;
+            default:
+                break;
+        }
+    });
+    return { flushGitMirror, unsubGitRetry, unsubBoundary, unsub };
+}

package/dist/core/runner/run-identity-wiring.d.ts

@@ -0,0 +1,96 @@
+/**
+ * design/393 S5 — the run body's IDENTITY WIRING (R1), verbatim from `Runner.runLocked`, the first thing after
+ * `prepared` exists: the notification lane's bindings (harness, session anchor, identity mint), the backstop
+ * carrier's immediate seats, the event-identity mint (`ident`) and the run's canonical task id, the wiring-manifest
+ * frame and the roster-delta subscription, the delegation-lifecycle spawn station and its owed-terminal carrier,
+ * the manual-compact mooted channel, the harness sinks for undrained engine notes / user inputs / consumed
+ * engine notes, the notify / capture-opt-out bridges, the spawner's injector hand-back, the idle-parked
+ * notification redelivery at turn open, the loop latch and the live-task handle publication, and the run's
+ * usage counters. Every push here happens before the run's first model/tool interaction, as it did.
+ */
+import { type AgentHarness } from "../../internal/harness.js";
+import type { PeerInboundChainRef } from "../../agents/peer-admission.js";
+import { type PendingSessionNotifications, type SystemInjectionPriority, type TaskNotificationPayload } from "../task-notification.js";
+import type { PushQueue } from "../push-queue.js";
+import type { TaskEvent, TaskSpec } from "../types.js";
+import type { Stats } from "./assemble-result.js";
+import type { CaptureOptOutRef, LiveHandle, ManualCompactRef, NotifyRef, Prepared, RunInternals, RunnerDepsSeat, TaskIdRef } from "./contracts.js";
+export interface RunIdentityWiringInput {
+    /** borrowed-readonly — the task spec: the task id and the memory / notification seats it names. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the run's event queue: the manifest, roster-delta, compaction_outcome and redelivered
+     *  task_notification frames. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-mutable — the leg's prepared seat: the harness sinks (`onUndrainedEngineNotes`, `engineInjectionsHeld`,
+     *  `onUndrainedUserInputs`, `onEngineNoteConsumed`) are installed, `nextTurn` is appended to; the ids, the identity
+     *  envelope, the hold refs, the memory session and the listing / roster faces are read. */
+    prepared: Prepared;
+    /** borrowed-readonly — the trusted run-scoped channel: `parentToolCallId`, `onNotifyInjectorReady`. */
+    internals: RunInternals | undefined;
+    /** borrowed-mutable — the stream layer's backstop carrier: the memory scopes, the edited-files reader and the
+     *  owed delegation terminal are published here the moment they exist. */
+    taskIdRef: TaskIdRef | undefined;
+    /** borrowed-readonly — the stream layer's readiness callback, fired ONCE with the live-task handle. */
+    onReady: (handle: LiveHandle) => void;
+    /** borrowed-mutable — the manual /compact seat: its mooted-frame channel is installed here. */
+    manualCompactRef: ManualCompactRef;
+    /** borrowed-mutable — the notify() bridge: `inject` is bound here (absent on the public path). */
+    notifyRef: NotifyRef | undefined;
+    /** borrowed-mutable — the capture opt-out bridge: `flip` is bound here when a memory session mounted. */
+    captureOptOutRef: CaptureOptOutRef | undefined;
+    /** borrowed-readonly — the notification lane's ONE injection entry (the driver's, until the lane itself moves). */
+    injectTaskNotification: (notification: TaskNotificationPayload, opts?: {
+        priority?: SystemInjectionPriority;
+    }) => Promise<"queued" | "parked" | "dropped_duplicate">;
+    /** borrowed-mutable — the turn-open dedup set (the cross-layer double-park dedup): a redelivered frame's key is registered here. */
+    deliveredAtTurnOpen: Set<string>;
+    /** borrowed-mutable — design/176: the peer inbound chain, overwritten by each consumed peer-class payload. */
+    peerInboundChainRef: PeerInboundChainRef;
+    /** borrowed-mutable — the driver's notification-lane bindings, a VIEW over its `let`s (never a copy): this lane binds
+     *  the harness, the session anchor and the identity mint the lane's closures read, and reads the anchor back in
+     *  the undrained-notes sink. */
+    notificationLane: {
+        harness: AgentHarness | undefined;
+        sessionId: string | undefined;
+        ident: () => {
+            eventId?: string;
+            parentToolCallId?: string;
+            sourceTaskId?: string;
+        };
+    };
+    /** borrowed-mutable — the driver's held agent_end account (backlog #389), a view over its `let`: the undrained-inputs
+     *  sink writes it when the run committed a durable park; the driver's tail reads it. */
+    undrainedUserAtEnd: {
+        current: {
+            steer: number;
+            followUp: number;
+        } | undefined;
+    };
+    /** borrowed-mutable — the Runner's per-session parked-notification store: drained at turn open, re-pended on failure. */
+    pendingSessionNotifications: PendingSessionNotifications;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onDelegationLifecycle`, `onNotice`). */
+    runner: RunnerDepsSeat;
+}
+export interface RunIdentityWiringResult {
+    /** The run's canonical task id (`spec.taskId ?? sessionId`) — one source, shared with `ident()`. */
+    runSourceTaskId: string;
+    /** The spawning tool call's id when this task runs AS A SUB-AGENT; undefined on a top-level run. */
+    parentToolCallId: string | undefined;
+    /** The event-identity mint: a fresh eventId per event, plus the sub-agent attribution when there is one. */
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    /** #281 件B: the delegation-lifecycle emission closure both stations share (spawn here, terminal in the driver). */
+    emitDelegationLifecycle: (event: import("../types.js").DelegationLifecycleEvent) => void;
+    /** The loop-liveness latch and the two attribution seats (ended / userInterrupted / userHalted). */
+    loopLatch: {
+        ended: boolean;
+        userInterrupted: boolean;
+        userHalted: boolean;
+    };
+    /** This leg's usage counters, zeroed here; the harness-handlers lane is their writer from the first turn on. */
+    stats: Stats;
+}
+export declare function runIdentityWiring(input: RunIdentityWiringInput): RunIdentityWiringResult;

package/dist/core/runner/run-identity-wiring.js

@@ -0,0 +1,84 @@
+import { uuidv7 } from "../../internal/harness.js";
+import { createSafeNotifier } from "../safe-notify.js";
+import { discloseDroppedPending, renderTaskNotificationXml, taskNotificationDedupKey } from "../task-notification.js";
+import { deliverDelegationLifecycle, deliverEngineNotice, undrainedUserInputNotices } from "../types.js";
+export function runIdentityWiring(input) {
+    const { spec, queue, prepared, internals, taskIdRef, onReady, manualCompactRef, notifyRef, captureOptOutRef, injectTaskNotification, deliveredAtTurnOpen, peerInboundChainRef, notificationLane, undrainedUserAtEnd, pendingSessionNotifications, runner } = input;
+    notificationLane.harness = prepared.harness;
+    notificationLane.sessionId = prepared.sessionId;
+    if (taskIdRef)
+        taskIdRef.effectiveMemoryScopes = prepared.effectiveMemoryScopes;
+    if (taskIdRef)
+        taskIdRef.editedFiles = prepared.editedFilesSnapshot;
+    const runSourceTaskId = spec.taskId ?? prepared.sessionId;
+    const parentToolCallId = internals?.parentToolCallId;
+    const ident = () => parentToolCallId !== undefined ? { eventId: uuidv7(), parentToolCallId, sourceTaskId: runSourceTaskId } : { eventId: uuidv7() };
+    notificationLane.ident = ident;
+    queue.push({ type: "wiring_manifest", manifest: prepared.wiringManifest, ...ident() });
+    prepared.toolRosterDeltas.subscribe((delta) => queue.push({ type: "tool_roster_delta", delta, ...ident() }));
+    const delegationLifecycleNotifier = createSafeNotifier({
+        onError: (f) => console.warn(`[sema-core] ${f.site}: delegation-lifecycle observer threw (contained; further failures counted, not re-disclosed): ${f.error.message}`),
+    });
+    const emitDelegationLifecycle = (event) => {
+        if (!prepared.hookIdentity.isDelegatedChild)
+            return;
+        if (runner.deps.onDelegationLifecycle === undefined)
+            return;
+        deliverDelegationLifecycle(runner.deps.onDelegationLifecycle, event, delegationLifecycleNotifier, "runtask.onDelegationLifecycle");
+    };
+    emitDelegationLifecycle({ phase: "spawn", identity: prepared.hookIdentity });
+    if (taskIdRef !== undefined && prepared.hookIdentity.isDelegatedChild && runner.deps.onDelegationLifecycle !== undefined) {
+        taskIdRef.delegationTerminalOwed = prepared.hookIdentity;
+    }
+    manualCompactRef.emitMooted = (reason) => {
+        queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason, ...ident() });
+    };
+    prepared.harness.onUndrainedEngineNotes = (payloads) => {
+        if (notificationLane.sessionId === undefined)
+            return;
+        for (const p of payloads)
+            pendingSessionNotifications.pend(notificationLane.sessionId, p);
+    };
+    prepared.harness.engineInjectionsHeld = () => prepared.batchHaltRef.current !== undefined;
+    prepared.harness.onUndrainedUserInputs = (counts) => {
+        if (prepared.pausedRef.current !== undefined) {
+            undrainedUserAtEnd.current = counts;
+            return;
+        }
+        for (const notice of undrainedUserInputNotices(counts, spec.taskId ?? prepared.sessionId, prepared.sessionId, prepared.runId)) {
+            deliverEngineNotice(runner.deps.onNotice, notice);
+        }
+    };
+    prepared.harness.onEngineNoteConsumed = (p) => {
+        const peer = p?.peer;
+        if (peer !== undefined && Array.isArray(peer.hopChain))
+            peerInboundChainRef.current = [...peer.hopChain];
+    };
+    if (notifyRef)
+        notifyRef.inject = injectTaskNotification;
+    if (captureOptOutRef && prepared.memoryEngineSession?.captureOptOut !== undefined) {
+        captureOptOutRef.flip = prepared.memoryEngineSession.captureOptOut.flip;
+    }
+    try {
+        internals?.onNotifyInjectorReady?.(injectTaskNotification);
+    }
+    catch {
+    }
+    {
+        const pendingIdle = pendingSessionNotifications.drain(prepared.sessionId);
+        if (pendingIdle !== undefined) {
+            for (const payload of discloseDroppedPending(pendingIdle)) {
+                const parkedPriority = pendingIdle.priorities?.get(payload);
+                deliveredAtTurnOpen.add(taskNotificationDedupKey(payload));
+                queue.push({ type: "task_notification", notification: payload, ...(parkedPriority !== undefined ? { priority: parkedPriority } : {}), ...ident() });
+                void prepared.harness.nextTurn(renderTaskNotificationXml(payload), { provenance: "engine-note", enginePayload: payload }).catch(() => {
+                    pendingSessionNotifications.pend(prepared.sessionId, payload, parkedPriority);
+                });
+            }
+        }
+    }
+    const loopLatch = { ended: false, userInterrupted: false, userHalted: false };
+    onReady({ harness: prepared.harness, abortController: prepared.abortController, loop: loopLatch, reminderMark: prepared.reminderMark, sessionId: prepared.sessionId, runId: prepared.runId, hookTimeoutMs: prepared.hookTimeoutMs, hookIdentity: prepared.hookIdentity });
+    const stats = { turns: 0, tokens: 0, toolCalls: 0, promptTokens: 0, totalInputTokens: 0, cachedTokens: 0, cacheWriteTokens: 0, cacheWriteTokensLong: 0, outputTokens: 0, costMicroUsd: 0 };
+    return { runSourceTaskId, parentToolCallId, ident, emitDelegationLifecycle, loopLatch, stats };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * design/393 S5 — the run body's REASONING seat (R5), verbatim from `Runner.runLocked`: the leg-entry resolution of
+ * the requested reasoning intensity against the model's real capability, the ONE publisher that writes both faces
+ * (the `reasoning.resolved` trace frame and the `TaskResult.effectiveReasoning` seat on the backstop carrier), and
+ * the wire-facts consumer that lets the leg's FIRST committed request correct the cap-blind mint (once; foreign
+ * reports are contained at their call sites, not here).
+ */
+import { type ReasoningWireFacts, type ResolvedReasoning } from "../../brain/reasoning.js";
+import type { Prepared, RunState, TaskIdRef } from "./contracts.js";
+export interface RunReasoningSeatInput {
+    /** borrowed-readonly — the leg's prepared seat: the requested thinking level and the model. */
+    prepared: Prepared;
+    /** borrowed-readonly — the run's mutable state, read for the trace frames' tracer and task id. */
+    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;
+}
+export declare function runReasoningSeat(input: RunReasoningSeatInput): RunReasoningSeatResult;