@sema-agent/core 7.17.7 → 7.19.0

package/dist/core/wiring-manifest.d.ts

@@ -22,6 +22,7 @@
  */
 import type { RunnerDeps, TaskSpec } from "./types.js";
 import { type StoreDurability } from "./checkpoint-store.js";
+import type { WiringManifestHookEntry } from "./hook-seats.js";
 import type { McpDelivered, McpFailureKind } from "./mcp-failure.js";
 export type { StoreDurability };
 /** The manifest-face projection of {@link StoreDurability}: `"declared_durable"` (the name says it —
@@ -110,11 +111,27 @@ export interface WiringManifestMcpEntry {
     error?: string;
     toolCount: number;
 }
+/** Which LSP lanes this leg armed. The two lanes are INDEPENDENT and the word is their product: `tool` = the
+ *  code-intelligence tool mounted and nothing more; `diagnostics` = the push lane armed (a registry-feeding
+ *  manager, write-capable hands, no opt-out) while the tool is NOT on the roster; `tool_and_diagnostics` =
+ *  both. A leg whose `LSP` tool was excluded can still be pushing diagnostics. */
+export declare const LSP_LANES: readonly ["tool", "diagnostics", "tool_and_diagnostics"];
+export type LspLane = (typeof LSP_LANES)[number];
+/** The contract id the LSP tool mounts under (`createLspTool`) — the roster's structural discriminator, which
+ *  a disclosure keys on instead of re-spelling the wire name. */
+export declare const LSP_CONTRACT_ID = "core.lsp@1";
+/** The manifest's LSP seam from its two INDEPENDENT facts (see {@link WiringManifest.lsp}): the lane word is
+ *  their product, and is absent only when neither lane is live. */
+export declare function deriveLspSeam(mounted: boolean, diagnosticsLive: boolean): {
+    mounted: boolean;
+    lane?: LspLane;
+};
 /**
  * design/173 §2.2/§8.4 — the wiring manifest. Consumers MUST ignore unknown fields
  * (`schemaVersion` bumps only on a semantic break of an EXISTING field). The TaskEvent face is the
  * host/operator plane — the manifest never enters model context.
  */
+export type { WiringManifestHookEntry };
 export interface WiringManifest {
     schemaVersion: 1;
     /** Present on EFFECTIVE (per-leg) manifests only; the static half has no leg. */
@@ -280,6 +297,28 @@ export interface WiringManifest {
      * `tool_roster_delta` event, never as a re-emitted manifest.
      */
     tools?: import("./tool-roster.js").ToolRoster;
+    /**
+     * EFFECTIVE half only: the hook seats this leg wired, one entry per family, in {@link import("./hook-seats.js").HOOK_FAMILIES} order. PRESENT IFF at least one
+     * seat is wired — a deployment that wires none reports nothing here and its manifest (and {@link configFingerprint}) is byte-for-byte what it was; an empty
+     * array is never emitted, so absence reads as "this leg wired no hook RECORD of its own" — NOT as "no hook runs": a delegated child with no local record can
+     * still be screened (and refused) by an ancestor's `preToolUse` through the gate's constraint fold, which this face deliberately does not call a hook of
+     * this leg. Every entry is deployment code the engine awaits on the critical path, fail-closed on the two decision seats. EXCLUDED from
+     * {@link configFingerprint}: the record is a per-task seat, so one assembly's legs legitimately differ on it.
+     */
+    hooks?: readonly WiringManifestHookEntry[];
+    /**
+     * EFFECTIVE half only: the LSP code-intelligence seam. PRESENT IFF a manager seat resolved
+     * (`spec.lspManager ?? deps.lspManager`); a deployment that wires none reports nothing (byte-for-byte
+     * unchanged, fingerprint included). `mounted` is the ROSTER fact, not the seat fact — a wired manager
+     * whose `LSP` tool was excluded reports `false` — and `lane` is INDEPENDENT of it: the diagnostics push
+     * lane arms on the manager, the hands and the opt-out, never on the mount, so
+     * `{mounted:false, lane:"diagnostics"}` is a real and reachable state. `lane` is absent only when
+     * neither lane is live.
+     */
+    lsp?: {
+        mounted: boolean;
+        lane?: LspLane;
+    };
     /** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
      *  JSON of this manifest's own resolved facts; every field here is an enum/boolean/count, no
      *  secrets) so an operator can correlate legs that ran under the same resolved assembly. */
@@ -351,6 +390,13 @@ export interface WiringFacts {
     mcp?: readonly WiringManifestMcpEntry[];
     /** Effective half only — the leg's minted tool roster (see {@link WiringManifest.tools}). */
     tools?: import("./tool-roster.js").ToolRoster;
+    /** Effective half only — the wired hook seats ({@link WiringManifest.hooks}); an empty array and an absent value derive the same thing (no section). */
+    hooks?: readonly WiringManifestHookEntry[];
+    /** Effective half only — the LSP seam ({@link WiringManifest.lsp}); absent ⇒ no manager wired. */
+    lsp?: {
+        mounted: boolean;
+        lane?: LspLane;
+    };
 }
 /** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
  *  single-source shapes, no parallel hand-copied interface). */

package/dist/core/wiring-manifest.js

@@ -4,6 +4,12 @@ import { resolveCheckpointStore } from "./checkpoint-store.js";
 import { isLiveQuestionFace } from "./ask-question.js";
 import { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export const AUTO_MODE_ARM_REASONS = ["armed", "no_intent", "no_face", "denied", "resolver_fault"];
+export const LSP_LANES = ["tool", "diagnostics", "tool_and_diagnostics"];
+export const LSP_CONTRACT_ID = "core.lsp@1";
+export function deriveLspSeam(mounted, diagnosticsLive) {
+    const lane = mounted ? (diagnosticsLive ? "tool_and_diagnostics" : "tool") : diagnosticsLive ? "diagnostics" : undefined;
+    return { mounted, ...(lane !== undefined ? { lane } : {}) };
+}
 export function resolveDeclaredDurability(store, storeName) {
     const declared = store?.durability;
     if (declared === undefined)
@@ -133,9 +139,11 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.autoMode !== undefined ? { autoMode: readAutoModeFact(facts.autoMode) } : {}),
         ...(facts.half === "effective" && facts.mcp !== undefined ? { mcp: facts.mcp.map((e) => ({ ...e })) } : {}),
         ...(facts.half === "effective" && facts.tools !== undefined ? { tools: facts.tools } : {}),
+        ...(facts.half === "effective" && facts.hooks !== undefined && facts.hooks.length > 0 ? { hooks: facts.hooks.map((h) => ({ ...h })) } : {}),
+        ...(facts.half === "effective" && facts.lsp !== undefined ? { lsp: { ...facts.lsp } } : {}),
     };
     if (facts.half === "effective") {
-        const { leg: _leg, mcp: _mcp, tools: _tools, ...assembly } = manifest;
+        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, ...assembly } = manifest;
         const { provenance: _askSeat, ...askForHash } = assembly.ask;
         const { provenance: _questionSeat, ...questionForHash } = assembly.question;
         manifest.configFingerprint = createHash("sha256")

package/dist/core/write-protect.d.ts

@@ -51,8 +51,13 @@ export interface WriteProtectionMatcher {
     /** The resolved rows this judge was compiled from (canonical names — the disclosure face). */
     readonly rows: readonly WriteProtectedRow[];
     /** Judge ONE path spelling. Returns the first matching row (basename rows first, then segment,
-     *  then segment-run — deterministic), or null. */
-    matchPath(path: string): WriteProtectedHit | null;
+     *  then segment-run — deterministic), or null.
+     *
+     *  `cwd` = the call's LIVE tracked working directory, read at judgment time off the ONE ref the fs
+     *  hand tools resolve with — the law every path guard here follows: judge the file the tool will write.
+     *  Absent ⇒ judged exactly as given — the historical reading, and the honest answer for a host
+     *  that tracks no cwd. */
+    matchPath(path: string, cwd?: string): WriteProtectedHit | null;
 }
 /**
  * Compile the write-protection judge for a deployment configuration. Returns `undefined` when the
@@ -82,4 +87,4 @@ export declare function compileWriteProtection(entries?: readonly WriteProtected
  */
 export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[], opts?: {
     dataRoot?: string;
-}): ((toolName: string, args: unknown, face?: ToolCallLike["face"]) => WriteProtectedHit | null) | undefined;
+}): ((toolName: string, args: unknown, face?: ToolCallLike["face"], cwd?: string) => WriteProtectedHit | null) | undefined;

package/dist/core/write-protect.js

@@ -1,4 +1,4 @@
-import { isWinFormPath, writeTargetPath, isUncPath } from "../tools/fs/safety.js";
+import { isWinFormPath, writeTargetPath, isUncPath, isAbsoluteForFamily, joinForFamily, pathFamilyOf } from "../tools/fs/safety.js";
 import { isProtectedWrite } from "./tool-registry.js";
 import { dataRootSpellings } from "./sensitive-path-policy.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
@@ -182,8 +182,11 @@ export function compileWriteProtection(entries, opts) {
     }
     return {
         rows,
-        matchPath(path) {
-            const judged = relativeUnderDataRoot(path, rootViews) ?? path;
+        matchPath(path, cwd) {
+            const base = typeof cwd === "string" && cwd.length > 0 ? cwd : undefined;
+            const family = pathFamilyOf({ cwd: base });
+            const spelled = base !== undefined && family !== undefined && !isAbsoluteForFamily(family, path) ? joinForFamily(family, base, path) : path;
+            const judged = relativeUnderDataRoot(spelled, rootViews) ?? spelled;
             const judge = (raw) => {
                 if (raw.length === 0)
                     return null;
@@ -213,13 +216,13 @@ export function createWriteProtectionCheck(entries, opts) {
     const matcher = compileWriteProtection(entries, opts);
     if (matcher === undefined)
         return undefined;
-    return (toolName, args, face) => {
+    return (toolName, args, face, cwd) => {
         const call = { toolName, args, ...(face !== undefined ? { face } : {}) };
         if (!isProtectedWrite(call))
             return null;
         const path = writeTargetPath(call);
         if (typeof path !== "string" || path.length === 0)
             return null;
-        return matcher.matchPath(path);
+        return matcher.matchPath(path, cwd);
     };
 }

package/dist/engine/execution-env/node-execution-env.js

@@ -359,7 +359,7 @@ export class NodeExecutionEnv {
             const stderrTail = new RollingTailBuffer();
             let settled = false;
             let timedOut = false;
-            let abortKillInFlight = false;
+            let terminationInFlight = false;
             let callbackError;
             let child;
             const timeoutRef = {};
@@ -391,7 +391,7 @@ export class NodeExecutionEnv {
                 return { stdout: markTruncated(so.text, so.droppedBytes), stderr: markTruncated(se.text, se.droppedBytes) };
             };
             const onAbort = () => {
-                abortKillInFlight = true;
+                terminationInFlight = true;
                 if (child?.pid) {
                     const abortTarget = child;
                     killProcessTree(child.pid, { stillRunning: () => abortTarget.exitCode === null && abortTarget.signalCode === null });
@@ -480,10 +480,11 @@ export class NodeExecutionEnv {
                 timeoutMs === undefined
                     ? undefined
                     : setTimeout(() => {
-                        if (options?.autoBackgroundOnTimeout && !abortKillInFlight && adoptOnTimeoutRef.current) {
+                        if (options?.autoBackgroundOnTimeout && !terminationInFlight && adoptOnTimeoutRef.current) {
                             adoptOnTimeoutRef.current();
                             return;
                         }
+                        terminationInFlight = true;
                         timedOut = true;
                         if (child?.pid) {
                             const timeoutTarget = child;
@@ -598,9 +599,11 @@ export class NodeExecutionEnv {
                 spoolPumpRef.current.unref?.();
             }
             const onDetach = (cause) => {
-                if (settled || !child)
+                if (settled || terminationInFlight || !child)
                     return false;
                 pumpSpoolRef.current?.();
+                if (settled || terminationInFlight)
+                    return false;
                 const shellId = this.adoptRunningChild(child, stdoutTail.result(), stderrTail.result(), execSpoolRef.current !== undefined ? { spool: execSpoolRef.current, cursors: { out: spoolCursor.out, err: spoolCursor.err } } : undefined);
                 if (shellId === undefined)
                     return false;
@@ -616,6 +619,9 @@ export class NodeExecutionEnv {
             adoptOnTimeoutRef.current = () => {
                 if (onDetach("timeout"))
                     return;
+                if (terminationInFlight)
+                    return;
+                terminationInFlight = true;
                 timedOut = true;
                 if (child?.pid) {
                     const adoptFallbackTarget = child;

package/dist/engine/harness/agent-harness.d.ts

@@ -1,4 +1,5 @@
 import type { ActorAssertion, AssistantMessage, ImageContent, Model, UserMessage } from "../llm/index.js";
+import type { HaltRemainingDirective } from "../loop/types.js";
 import type { AgentMessage, AgentTool, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
 import { type EngineSegment } from "../../core/untrusted-text.js";
 import type { AbortResult, AgentHarnessEvent, AgentHarnessEventResultMap, AgentHarnessOptions, AgentHarnessOwnEvent, AgentHarnessResources, AgentHarnessStreamOptions, ExecutionEnv, PromptTemplate, Skill } from "./types.js";
@@ -24,6 +25,16 @@ export interface HaltConsumption {
         readonly sources: ReadonlyArray<StopRequestSource>;
     };
 }
+/** `prompt()` option: settle the transcript's trailing UNANSWERED tool batch through the loop's own batch pipeline
+ *  BEFORE the prompt is delivered (a resumed run whose suspended batch still holds unanswered calls). `halt` settles
+ *  every unanswered call as not-executed instead (the batch-halt form). No unanswered tail ⇒ a no-op. */
+export interface TrailingToolBatchOptions {
+    readonly halt?: HaltRemainingDirective;
+}
+/** `prompt()` option: called when the prompt and next-turn queue's messages enter the loop transcript, before
+ *  their frames are emitted and committed. Not called when a trailing-batch settlement ends the run first — the
+ *  caller then still owns whatever the prompt was carrying. */
+export type PromptDeliveredCallback = () => void;
 export interface UserMessageProvenance {
     /** Exact char length of the engine-prepended prefix on `text` (first-frame reminders etc.).
      *  Sugar for the single segment `[0, chars)` — when `engineSegments` is also supplied, segments win. */
@@ -124,6 +135,14 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     readonly env: ExecutionEnv;
     private session;
     private phase;
+    /** Can an engine injection land at a turn boundary RIGHT NOW? A producer choosing a destination
+     *  BEFORE it commits (the session notification route) needs this as a fact, not as a rejected
+     *  promise afterwards. Three conjuncts, each a condition a later stage enforces: a turn must EXIST
+     *  (`steer`/`followUp` throw while idle); the run must not be UNWINDING; it must not be STOPPING
+     *  (`halt()` / `requestStopAfterTurn()` latch a source and the loop exits at the next boundary) —
+     *  the phase reads `"turn"` through all of that. Nothing awaits between this read and the injection
+     *  it gates, so a `true` cannot go stale under its caller. */
+    get acceptsInjections(): boolean;
     /** design/74 R3-A: the one-way clean-stop latch — SET iff this set is non-empty. When set, the boundary consults
      *  answer true so the loop exits CLEANLY (emit `agent_end` + return) WITHOUT an abort/interrupt — the path a
      *  resource-slice suspend needs (an abort would trip the orphan-[INTERRUPTED] reconcile = corrupt resume). It is
@@ -136,6 +155,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  per turn, so identity carries the generation); the loop's cut-consumption report is accepted for THIS seat only. */
     private lastPublishedSeat?;
     private readonly seatCutSources;
+    private trailingBatchEndedOn?;
     private turnCutConsumed?;
     /** backlog #389 — one-way latch set by {@link abort}. Read by `drainQueuedMessages`: no boundary may
      *  hand a queued frame to the model once the run is unwinding, and — crucially — none may SPLICE one
@@ -208,6 +228,26 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  clearing, so they are LEFT STANDING (the durable-park migration reads them AFTER abort()
      *  returns) and the abort-side pass is the belt for an exit that never reached agent_end. */
     private sweepUndrainedEngineNotes;
+    /**
+       * How much of a PERSON's input is currently accepted-but-unserved, per lane — the one predicate behind
+       * both readers below, so "a person's input is waiting" cannot come to mean two things. Engine-AUTHORED
+       * frames are excluded, and the IN-FLIGHT slot counts (a frame spliced out of a queue and never injected
+       * is as pending as one that never left it).
+     */
+    private pendingUserInputsByLane;
+    /**
+     * Is a PERSON's input waiting for this run's NEXT TURN BOUNDARY? The live read face over
+     * {@link pendingUserInputsByLane}, for the producer that must decide whether to YIELD that boundary
+     * sooner — the shell's auto-backgrounding leg.
+     *
+       * THE STEER LANE ONLY: the follow-up lane's contract is delivery at the run's natural
+       * would-otherwise-stop seat, which backgrounding a command cannot bring forward.
+       * `announceUndrainedUserInputs` still reads both lanes.
+     *
+       * Synchronous and side-effect-free by contract, the same posture as {@link pendingInjectionCount}:
+       * nothing is awaited between the read and the action it gates. An UNWINDING run answers `false`.
+     */
+    hasPendingUserInput(): boolean;
     /** backlog #259 — what remains in the steer/follow-up queues AFTER the engine-note sweep is USER
      *  input that was accepted ("queued") and will never be consumed: the run reached agent_end first.
      *  User inputs have no redelivery semantics (unlike engine notes — a steer aimed at a finished run
@@ -320,6 +360,8 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  zero-assistant ending still throws (see the executeTurn tail). */
     prompt(text: string, options?: {
         images?: ImageContent[];
+        settleUnansweredToolCalls?: TrailingToolBatchOptions;
+        onDelivered?: PromptDeliveredCallback;
     } & UserMessageProvenance): Promise<AssistantMessage | undefined>;
     /** R2-③: an empty/whitespace-only injection with no images carries ZERO information — it
      *  must not mint a user frame (strict endpoints reject empty user content, and an empty follow-up would

package/dist/engine/harness/agent-harness.js

@@ -187,6 +187,9 @@ export class AgentHarness {
     env;
     session;
     phase = "idle";
+    get acceptsInjections() {
+        return this.phase !== "idle" && !this.aborting && !this.stopRequested;
+    }
     stopRequestSources = new Set();
     get stopRequested() {
         return this.stopRequestSources.size > 0;
@@ -194,6 +197,7 @@ export class AgentHarness {
     boundaryStopConsumed;
     lastPublishedSeat;
     seatCutSources = new WeakMap();
+    trailingBatchEndedOn;
     turnCutConsumed;
     aborting = false;
     drainedPendingInjection = [];
@@ -229,12 +233,20 @@ export class AgentHarness {
             }
         }
     }
-    announceUndrainedUserInputs() {
+    pendingUserInputsByLane() {
         const inFlight = (lane) => this.drainedPendingInjection.filter((m) => !engineAuthoredInjections.has(m) && drainedFromLane.get(m) === lane).length;
-        const counts = {
+        return {
             steer: this.steerQueue.filter((m) => !engineAuthoredInjections.has(m)).length + inFlight("steer"),
             followUp: this.followUpQueue.filter((m) => !engineAuthoredInjections.has(m)).length + inFlight("followUp"),
         };
+    }
+    hasPendingUserInput() {
+        if (this.aborting)
+            return false;
+        return this.pendingUserInputsByLane().steer > 0;
+    }
+    announceUndrainedUserInputs() {
+        const counts = this.pendingUserInputsByLane();
         if ((counts.steer > 0 || counts.followUp > 0) && this.onUndrainedUserInputs) {
             try {
                 this.onUndrainedUserInputs(counts);
@@ -826,29 +838,7 @@ export class AgentHarness {
     }
     async executeTurn(turnState, text, options) {
         let activeTurnState = turnState;
-        let messages = [createUserMessage(text, options?.images, options)];
-        if (this.nextTurnQueue.length > 0) {
-            const queuedMessages = this.nextTurnQueue.splice(0);
-            try {
-                await this.emitQueueUpdate();
-            }
-            catch (error) {
-                this.nextTurnQueue.unshift(...queuedMessages);
-                throw normalizeHookError(error);
-            }
-            for (const m of queuedMessages) {
-                const payload = engineNotePayloads.get(m);
-                if (payload !== undefined) {
-                    try {
-                        this.onEngineNoteConsumed?.(payload);
-                    }
-                    catch {
-                    }
-                }
-                engineNotePayloads.delete(m);
-            }
-            messages = [...queuedMessages, messages[0]];
-        }
+        const userMessage = createUserMessage(text, options?.images, options);
         const beforeResult = await this.emitHook({
             type: "before_agent_start",
             prompt: text,
@@ -856,9 +846,35 @@ export class AgentHarness {
             systemPrompt: turnState.systemPrompt,
             resources: turnState.resources,
         });
-        if (beforeResult?.messages) {
-            messages = [...messages, ...beforeResult.messages];
-        }
+        const takePrompts = async () => {
+            let messages = [userMessage];
+            if (this.nextTurnQueue.length > 0) {
+                const queuedMessages = this.nextTurnQueue.splice(0);
+                try {
+                    await this.emitQueueUpdate();
+                }
+                catch (error) {
+                    this.nextTurnQueue.unshift(...queuedMessages);
+                    throw normalizeHookError(error);
+                }
+                for (const m of queuedMessages) {
+                    const payload = engineNotePayloads.get(m);
+                    if (payload !== undefined) {
+                        try {
+                            this.onEngineNoteConsumed?.(payload);
+                        }
+                        catch {
+                        }
+                    }
+                    engineNotePayloads.delete(m);
+                }
+                messages = [...queuedMessages, messages[0]];
+            }
+            if (beforeResult?.messages) {
+                messages = [...messages, ...beforeResult.messages];
+            }
+            return messages;
+        };
         const abortController = new AbortController();
         const getTurnState = () => activeTurnState;
         const setTurnState = (nextTurnState) => {
@@ -867,7 +883,20 @@ export class AgentHarness {
         this.runAbortController = abortController;
         const runResultPromise = (async () => {
             try {
-                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace);
+                return await runAgentLoop(takePrompts, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace, {
+                    ...(options?.settleUnansweredToolCalls !== undefined
+                        ? {
+                            settle: {
+                                ...(options.settleUnansweredToolCalls.halt !== undefined ? { halt: options.settleUnansweredToolCalls.halt } : {}),
+                                report: (outcome) => {
+                                    if (outcome.aborted)
+                                        this.trailingBatchEndedOn = outcome.assistantMessage;
+                                },
+                            },
+                        }
+                        : {}),
+                    ...(options?.onDelivered !== undefined ? { onPromptsDelivered: options.onDelivered } : {}),
+                });
             }
             catch (error) {
                 try {
@@ -889,6 +918,8 @@ export class AgentHarness {
             }
             if (this.stopRequested)
                 return undefined;
+            if (this.trailingBatchEndedOn !== undefined)
+                return this.trailingBatchEndedOn;
             throw new AgentHarnessError("invalid_state", "AgentHarness prompt completed without an assistant message");
         }
         finally {
@@ -904,6 +935,7 @@ export class AgentHarness {
         if (this.phase !== "idle") {
             throw new AgentHarnessError("busy", "AgentHarness is busy");
         }
+        this.trailingBatchEndedOn = undefined;
         this.stopRequestSources.clear();
         this.boundaryStopConsumed = undefined;
         this.turnCutConsumed = undefined;

package/dist/engine/loop/agent-loop.d.ts

@@ -1,5 +1,29 @@
+/**
+ * First-party agent loop (design/118 ④a — de-vendoring 4/6).
+ *
+ * Rewritten from the vendored openclaw distillation with the loop's control flow made EXPLICIT as a
+ * state machine (the CC query.ts State/transition shape, sema deps injected): every "go around again"
+ * is a named {@link LoopContinue} and every exit is a named {@link LoopTerminal}, so tests can assert
+ * WHICH path ran (test/loop-transitions.test.ts) instead of inferring it from event order. ④a is
+ * behavior-1:1 with the vendored loop — no new recovery chains; those land in ④b as new Continue
+ * reasons on this skeleton.
+ *
+ * Load-bearing invariants carried over verbatim (the VENDORED EDIT provenance comments are kept at
+ * their sites as history):
+ * - A-1 layer ② abort-before-stream guard (a mid-batch abort must never reach the next provider
+ *   request) — {@link runSingleTurn} entry guard, Terminal `aborted_before_stream`.
+ * - Durable double-execution gate (a deferred parallel tool closure must never run its side effect
+ *   after a mid-batch suspend/abort) — {@link executePreparedToolCall} entry guard.
+ * - D4 post-hook posture (afterToolCall throw must not rewrite a committed side effect into a flat
+ *   failure) — {@link finalizeExecutedToolCall}.
+ * - The TWO queue drain points (1.204 priority wiring基石): steer drains at every turn end
+ *   (Continue `steer_injected` / mid-work boundary), followUp drains only when the agent would
+ *   otherwise stop (Continue `follow_up_injected`). Never merge these into one queue.
+ * - text_delta.partial reconstruction (upstream cherry-pick 6fcc945702).
+ */
+import type { AssistantMessage, ToolResultMessage } from "../llm/index.js";
 import { type AgentCoreStreamRuntimeDeps } from "./runtime-deps.js";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, HaltRemainingDirective, StreamFn } from "./types.js";
 /** Callback used by synchronous loop runners to publish agent lifecycle events. */
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 /** Named reasons the loop goes around again. Assertable in tests via the trace sink. */
@@ -88,8 +112,48 @@ export type LoopStep = {
  * `next_turn`), then `next_turn`. Don't read the trace as a complete enumeration of concurrent causes.
  */
 export type LoopTraceSink = (step: LoopStep) => void;
-/** Run a prompt-started loop and emit events through a caller-owned sink. */
-export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn, runtime?: AgentCoreStreamRuntimeDeps, trace?: LoopTraceSink): Promise<AgentMessage[]>;
+/**
+ * A request to settle the transcript's trailing UNANSWERED tool batch before the prompts are delivered
+ * (a resumed run whose suspended batch still holds calls no tool result answers). The batch is settled
+ * as ONE turn of the loop: the live batch pipeline under a turn-scoped interrupt seat, the interrupted-
+ * turn settlement when that seat is cut, then the ordinary turn boundary (`prepareNextTurn` + the stop
+ * consult). `halt` settles every call as not-executed instead (the batch-halt form). `report` receives
+ * the outcome once; `aborted` means the run ENDED before the prompts were delivered (the run signal
+ * fired, or the boundary / the interrupt settlement stopped the run).
+ */
+export interface TrailingToolBatchSettlement {
+    halt?: HaltRemainingDirective;
+    report: (outcome: {
+        assistantMessage: AssistantMessage;
+        settled: number;
+        aborted: boolean;
+    }) => void;
+}
+/** The caller-facing seams of a prompt run beyond the prompts themselves: an optional trailing-batch
+ *  settlement, and the moment the prompts enter the loop transcript, before their frames are emitted
+ *  — delivery accounts precede the carrying messages' commits. */
+export interface RunAgentLoopSeams {
+    settle?: TrailingToolBatchSettlement;
+    onPromptsDelivered?: () => void;
+}
+/** The last assistant message of `messages` when at least one of its tool calls has no tool result after it. */
+export declare function findUnansweredToolBatch(messages: readonly AgentMessage[]): AssistantMessage | undefined;
+/**
+ * Settle the unanswered tool calls of `assistantMessage` (the batch tail a suspended run left open):
+ * ONE pipeline with the live turn — the same partition, concurrency cap, preflight gate (a call may
+ * suspend again), execution and source-ordered result commit — or, under `halt`, the same not-executed
+ * settlement a batch-halt directive applies to never-started siblings. Every unanswered call gets a
+ * tool result unless the signal fires mid-batch (the dangling remainder is the suspended batch's own shape).
+ */
+export declare function settleUnansweredToolCalls(context: AgentContext, assistantMessage: AssistantMessage, config: AgentLoopConfig, signal: AbortSignal | undefined, emit: AgentEventSink, halt?: HaltRemainingDirective): Promise<ExecutedToolCallBatch>;
+/** Run a prompt-started loop and emit events through a caller-owned sink. `prompts` may be a thunk: it is
+ *  taken only when the prompts are about to be delivered, so a caller whose prompt assembly CONSUMES queued
+ *  input (a harness draining its next-turn queue) loses nothing when a trailing-batch settlement ends the run first. */
+export declare function runAgentLoop(prompts: AgentMessage[] | (() => Promise<AgentMessage[]>), context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn, runtime?: AgentCoreStreamRuntimeDeps, trace?: LoopTraceSink, seams?: RunAgentLoopSeams): Promise<AgentMessage[]>;
+type ExecutedToolCallBatch = {
+    messages: ToolResultMessage[];
+    terminate: boolean;
+};
 /**
  * How many tool names an unknown-tool miss spells out. A miss is a NAME problem: seeing a couple of dozen
  * real names is what lets a model spot the one it meant, while a full listing grows with the deployment
@@ -110,3 +174,4 @@ export declare const TOOL_VALIDATION_REFUSED_CODE = "tool.validation_refused";
  *  reported on the fault seat): a validator is a precondition read, not a network call, so a single
  *  bound serves every tool; a deployment validator that needs longer is a validator doing too much. */
 export declare const TOOL_INPUT_VALIDATION_TIMEOUT_MS = 10000;
+export {};