@sema-agent/core 7.11.1 → 7.12.0

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,77 @@
+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, NotificationLaneBindings, 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 R0 lane's). */
+    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 notification lane's bindings seat (its own `let`s behind getters / setters, 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: NotificationLaneBindings;
+    /** 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;
+    /** backlog #389 — the held agent_end account, a READ FACE over this lane's own `let` (the undrained-inputs sink writes it
+     *  when the run committed a durable park); the terminal-adoption lane settles it minus what the park carried. */
+    undrainedUserAtEnd: {
+        readonly current: {
+            steer: number;
+            followUp: number;
+        } | undefined;
+    };
+}
+export declare function runIdentityWiring(input: RunIdentityWiringInput): RunIdentityWiringResult;

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

@@ -0,0 +1,85 @@
+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, 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;
+    let undrainedUserAtEnd;
+    prepared.harness.onUndrainedUserInputs = (counts) => {
+        if (prepared.pausedRef.current !== undefined) {
+            undrainedUserAtEnd = 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, undrainedUserAtEnd: { get current() { return undrainedUserAtEnd; } } };
+}

package/dist/core/runner/run-leg.d.ts

@@ -0,0 +1,106 @@
+/**
+ * design/393 S6 — the run body's LEG (R13), verbatim from `Runner.runLocked`: the one `harness.prompt` of the leg and
+ * everything that decides whether it is issued. Two legs behind one try / catch / finally: the RESUME leg (the walltime
+ * and governance-window entrance claims, the gated decision's application, the exhaustion arms, the continuation prompt's
+ * assembly — orphaned background tasks, the git frame, the parked steer queue and the wake message each under its own trust
+ * framing and redelivery screen — and the prompt itself) and the OBJECTIVE leg (the UserPromptSubmit screen, the git
+ * frame's primary delivery, the first-frame listings, the pre-call budget / token / entry-governance gates, the image
+ * conversion, the objective's human-input frame and the prompt itself). The tail captures the abort facts; the catch
+ * re-throws the resume-equivalent env failures after a bounded teardown and adopts everything else as the leg's throw;
+ * the finally releases the timer, the diagnostics, the signal, the content-ask bindings, flips the notification lane
+ * and releases the four subscriptions in their order.
+ *
+ * Async (twenty first-level awaits, the same awaits at the same positions). It ends by entering the terminal adoption
+ * (`next`) in its LAST continuation — the adoption's first read sits on the tick the finally ran on, as it did in the
+ * one-function body — and returns what it returns. The two legs stay ONE function on purpose: splitting them into two
+ * async functions (the design's "internal split") costs a microtask on the leg → tail edge, and the tail's first reads
+ * there — `abortController.signal.aborted`, `loopLatch.userInterrupted` — are host-mutable attribution facts a late read
+ * would mis-sign (the adversarial r2 HIGH-1 finding recorded on them); the forwarded-frame depth ratchet measured the
+ * extra hop (58 → 59) when the split was tried.
+ */
+import type { AssistantMessage } from "../../internal/llm.js";
+import { type ActorAssertion } from "../checkpoint-store.js";
+import type { PushQueue } from "../push-queue.js";
+import { type TaskEvent, type TaskSpec } from "../types.js";
+import { type WriteFamily } from "./turn-attachments.js";
+import type { NotificationLaneBindings, Prepared, ResumeRun, RunnerDepsSeat, RunState } from "./contracts.js";
+export interface RunLegInput<R> {
+    /** borrowed-readonly — the task spec: the objective, the images, the hooks slot, the principal, the task id. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the run's event queue: the human-input frames, the git echo frames, the listing echo frames. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-mutable — the leg's prepared seat: the harness is prompted, the blocked / git / listing refs written, the abort controller aborted and the signal released in the finally. */
+    prepared: Prepared;
+    /** borrowed-readonly — the resume plan when this leg resumes a checkpoint: chooses the resume leg; its delivery bits are written. */
+    resume: ResumeRun | undefined;
+    /** borrowed-mutable — the run's mutable state: the limit flags and the platform terminal are written by the entrance gates. */
+    rs: RunState;
+    /** borrowed-readonly — the API-boundary attribution snapshot of the objective's actor (the objective leg's speaker envelope). */
+    entryActor: ActorAssertion | undefined;
+    /** borrowed-readonly — the effective walltime window (undefined = unbounded): `<= 0` refuses the first turn. */
+    effectiveTimeoutMs: number | undefined;
+    /** borrowed-mutable — the hard walltime timer: claimed (`fired`) and cleared by the exhausted arms and the finally. */
+    timeout: {
+        fired: boolean;
+        clear: () => void;
+    };
+    /** borrowed-readonly — the content push (the resumed batch's frames ride it with the leg's identity). */
+    pushContent: (e: TaskEvent) => void;
+    /** borrowed-readonly — the run's event-identity mint. */
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    /** borrowed-readonly — the `message_committed` mint (the resumed batch's re-applied tool results). */
+    emitCommitted: (entryId: string, role: "user" | "assistant" | "toolResult", toolCallId?: string) => void;
+    /** borrowed-readonly — the write-family resolver (the resume-executed gated write's attachment anchor). */
+    writeFamilyOf: (name: string) => WriteFamily | undefined;
+    /** borrowed-mutable — the observed tool-start ids: the resume-executed gated call registers itself here. */
+    startedToolCallIds: Set<string>;
+    /** borrowed-readonly — the harness-handlers lane's workspace-move announcer (the approved `cd`'s frame). */
+    announceWorkspaceMove: () => void;
+    /** borrowed-readonly — the brain-sinks composition the leg's prompt runs under. */
+    withBrainSinks: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** borrowed-readonly — the git lane's parked-mirror flush, settled after the prompt (single-turn legs reach no boundary). */
+    flushGitMirror: () => Promise<void>;
+    /** borrowed-mutable — the loop-liveness latch: `ended` flips when the prompt settles (or a no-prompt / throw arm is taken); `userInterrupted` is snapshotted. */
+    loopLatch: {
+        ended: boolean;
+        readonly userInterrupted: boolean;
+    };
+    /** borrowed-mutable — the notification lane's bindings seat: `live` flips false in the finally (every later notification parks). */
+    notificationLane: NotificationLaneBindings;
+    /** borrowed-readonly — the notification lane's subscription release, called in the finally right after the flip. */
+    unsubscribeTaskNotifications: () => void;
+    /** borrowed-readonly — the git lane's owed-frame retry release, called in the finally first of the three. */
+    unsubGitRetry: () => void;
+    /** borrowed-readonly — the git lane's boundary-handler release, called second. */
+    unsubBoundary: () => void;
+    /** borrowed-readonly — the git lane's harness-event release, called third. */
+    unsub: () => void;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError`, `hooks`, `onNotice`, `allowImageUrl`); the one home of
+     *  why it is a seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the Runner's application of the resumed decision (its private method, as a delegate). */
+    applyResumeDecision: (prepared: Prepared, resume: ResumeRun, emit: (e: TaskEvent) => void, emitCommitted: (entryId: string, role: "user" | "assistant" | "toolResult", toolCallId?: string) => void, onResolvedToolSuccess?: (toolName: string, details: unknown) => void, onExecuteStart?: (toolCallId: string) => void) => Promise<void>;
+    /** borrowed-readonly — the terminal adoption, entered in this lane's last continuation with the leg's facts. */
+    next: (leg: RunLegResult) => Promise<R>;
+}
+/** The leg's facts — what the terminal adoption and the settle read. */
+export interface RunLegResult {
+    /** The final assistant message; undefined on every no-prompt arm (blocked, refused, exhausted). */
+    final: AssistantMessage | undefined;
+    /** What the leg threw (undefined on a clean end); the terminal adoption may lift a typed cause over it. */
+    threw: unknown;
+    /** The live-abort flag, captured before the finally's unconditional release-abort. */
+    abortedLive: boolean;
+    /** The snapshot of `loopLatch.userInterrupted`, taken with `abortedLive`. */
+    userInterruptedLive: boolean;
+    /** design/174: the answered-but-never-collected deliveries the finally settled. */
+    strandedHumanAnswers: ReadonlyArray<{
+        deliveryId: string;
+        toolCallId: string;
+    }>;
+}
+export declare function runLeg<R>(input: RunLegInput<R>): Promise<R>;