@sema-ai/core 1.275.1

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

@@ -0,0 +1,1053 @@
+import { runAgentLoop } from "../loop/agent-loop.js";
+import { resolveAgentCoreStreamFn } from "../loop/runtime-deps.js";
+import { convertToLlm } from "./messages.js";
+import { AgentHarnessError, CompactionError, SessionError, toError, } from "./types.js";
+function createUserMessage(text, images) {
+    const content = [{ type: "text", text }];
+    if (images) {
+        content.push(...images);
+    }
+    return { role: "user", content, timestamp: Date.now() };
+}
+function createFailureMessage(model, error, aborted) {
+    return {
+        role: "assistant",
+        content: [{ type: "text", text: "" }],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        stopReason: aborted ? "aborted" : "error",
+        errorMessage: error instanceof Error ? error.message : String(error),
+        timestamp: Date.now(),
+        usage: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 0,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+    };
+}
+function cloneStreamOptions(streamOptions) {
+    return {
+        ...streamOptions,
+        headers: streamOptions?.headers ? { ...streamOptions.headers } : undefined,
+        metadata: streamOptions?.metadata ? { ...streamOptions.metadata } : undefined,
+    };
+}
+function mergeHeaders(...headers) {
+    const merged = {};
+    let hasHeaders = false;
+    for (const entry of headers) {
+        if (!entry) {
+            continue;
+        }
+        Object.assign(merged, entry);
+        hasHeaders = true;
+    }
+    return hasHeaders ? merged : undefined;
+}
+function applyStreamOptionsPatch(base, patch) {
+    const result = cloneStreamOptions(base);
+    if (!patch) {
+        return result;
+    }
+    if (Object.hasOwn(patch, "transport")) {
+        result.transport = patch.transport;
+    }
+    if (Object.hasOwn(patch, "timeoutMs")) {
+        result.timeoutMs = patch.timeoutMs;
+    }
+    if (Object.hasOwn(patch, "maxRetries")) {
+        result.maxRetries = patch.maxRetries;
+    }
+    if (Object.hasOwn(patch, "maxRetryDelayMs")) {
+        result.maxRetryDelayMs = patch.maxRetryDelayMs;
+    }
+    if (Object.hasOwn(patch, "cacheRetention")) {
+        result.cacheRetention = patch.cacheRetention;
+    }
+    if (Object.hasOwn(patch, "headers")) {
+        if (patch.headers === undefined) {
+            result.headers = undefined;
+        }
+        else {
+            const headers = { ...result.headers };
+            for (const [key, value] of Object.entries(patch.headers)) {
+                if (value === undefined) {
+                    delete headers[key];
+                }
+                else {
+                    headers[key] = value;
+                }
+            }
+            result.headers = Object.keys(headers).length > 0 ? headers : undefined;
+        }
+    }
+    if (Object.hasOwn(patch, "metadata")) {
+        if (patch.metadata === undefined) {
+            result.metadata = undefined;
+        }
+        else {
+            const metadata = { ...result.metadata };
+            for (const [key, value] of Object.entries(patch.metadata)) {
+                if (value === undefined) {
+                    delete metadata[key];
+                }
+                else {
+                    metadata[key] = value;
+                }
+            }
+            result.metadata = Object.keys(metadata).length > 0 ? metadata : undefined;
+        }
+    }
+    return result;
+}
+const SUBSCRIBER_EVENT_TYPE = "*";
+function normalizeHarnessError(error, fallbackCode) {
+    if (error instanceof AgentHarnessError) {
+        return error;
+    }
+    const cause = toError(error);
+    if (cause instanceof SessionError) {
+        return new AgentHarnessError("session", cause.message, cause);
+    }
+    if (cause instanceof CompactionError) {
+        return new AgentHarnessError("compaction", cause.message, cause);
+    }
+    return new AgentHarnessError(fallbackCode, cause.message, cause);
+}
+function normalizeHookError(error) {
+    return normalizeHarnessError(error, "hook");
+}
+export class AgentHarness {
+    env;
+    session;
+    phase = "idle";
+    /** design/74 R3-A: a one-way soft-stop flag. When set, `shouldStopAfterTurn` returns true at the next turn
+     *  boundary 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). */
+    _stopAfterTurn = false;
+    runAbortController;
+    runPromise;
+    pendingSessionWrites = [];
+    model;
+    thinkingLevel;
+    systemPrompt;
+    streamOptions;
+    getApiKeyAndHeaders;
+    runtime;
+    resources;
+    tools = new Map();
+    activeToolNames;
+    steerQueue = [];
+    steeringQueueMode;
+    maxOutputTokens;
+    maxOutputTokensPerCall;
+    callDeadlineMsPerCall; // design/130 P2b
+    loopTrace; // service [398] C2
+    resilience; // design/131
+    maxToolConcurrency;
+    streamingToolExecution;
+    followUpQueue = [];
+    followUpQueueMode;
+    nextTurnQueue = [];
+    loopRecovery;
+    /** roadmap #5 (CC Stop hook): the runner-wired stop gate — see {@link setStopGate}. */
+    stopGate;
+    handlers = new Map();
+    constructor(options) {
+        this.env = options.env;
+        this.session = options.session;
+        this.resources = options.resources ?? {};
+        this.streamOptions = cloneStreamOptions(options.streamOptions);
+        this.systemPrompt = options.systemPrompt;
+        this.getApiKeyAndHeaders = options.getApiKeyAndHeaders;
+        this.runtime = options.runtime;
+        for (const tool of options.tools ?? []) {
+            this.tools.set(tool.name, tool);
+        }
+        this.model = options.model;
+        this.thinkingLevel = options.thinkingLevel ?? "off";
+        this.activeToolNames =
+            options.activeToolNames ?? (options.tools ?? []).map((tool) => tool.name);
+        this.steeringQueueMode = options.steeringMode ?? "one-at-a-time";
+        this.maxOutputTokens = options.maxOutputTokens;
+        this.maxOutputTokensPerCall = options.maxOutputTokensPerCall;
+        this.callDeadlineMsPerCall = options.callDeadlineMsPerCall; // design/130 P2b
+        this.loopTrace = options.loopTrace; // service [398] C2
+        this.resilience = options.resilience; // design/131
+        this.maxToolConcurrency = options.maxToolConcurrency;
+        this.streamingToolExecution = options.streamingToolExecution;
+        this.followUpQueueMode = options.followUpMode ?? "one-at-a-time";
+    }
+    getHandlers(type) {
+        return this.handlers.get(type);
+    }
+    async emitOwn(event, signal) {
+        for (const listener of this.getHandlers(SUBSCRIBER_EVENT_TYPE) ?? []) {
+            try {
+                await listener(event, signal);
+            }
+            catch (error) {
+                throw normalizeHookError(error);
+            }
+        }
+    }
+    async emitAny(event, signal) {
+        for (const listener of this.getHandlers(SUBSCRIBER_EVENT_TYPE) ?? []) {
+            try {
+                await listener(event, signal);
+            }
+            catch (error) {
+                throw normalizeHookError(error);
+            }
+        }
+    }
+    /**
+     * Emit a hook event to its registered handlers and return a single result.
+     *
+     * **Last-write-wins:** handlers run in registration order; each non-`undefined` result overwrites
+     * the previous one, and the LAST non-`undefined` result is returned (`undefined` = abstain, keeps
+     * the prior winner). Handlers do NOT compose — registering two handlers that both return a result
+     * for the same event silently drops all but the last. A handler that throws aborts the whole emit
+     * (errors are not swallowed). Callers that need ordered, composable semantics for one event (e.g.
+     * the design/37 two-phase tool gate: collect arg rewrites, then adjudicate policy) must funnel that
+     * logic through a SINGLE handler rather than relying on multiple handlers + this fold.
+     */
+    async emitHook(event) {
+        const handlers = this.getHandlers(event.type);
+        if (!handlers || handlers.size === 0) {
+            return undefined;
+        }
+        let lastResult;
+        for (const handler of handlers) {
+            try {
+                const result = (await handler(event));
+                if (result !== undefined) {
+                    lastResult = result;
+                }
+            }
+            catch (error) {
+                throw normalizeHookError(error);
+            }
+        }
+        return lastResult;
+    }
+    async emitBeforeProviderRequest(model, sessionId, streamOptions) {
+        const handlers = this.getHandlers("before_provider_request");
+        let current = cloneStreamOptions(streamOptions);
+        if (!handlers || handlers.size === 0) {
+            return current;
+        }
+        for (const handler of handlers) {
+            try {
+                const result = (await handler({
+                    type: "before_provider_request",
+                    model,
+                    sessionId,
+                    streamOptions: cloneStreamOptions(current),
+                }));
+                if (result?.streamOptions) {
+                    current = applyStreamOptionsPatch(current, result.streamOptions);
+                }
+            }
+            catch (error) {
+                throw normalizeHookError(error);
+            }
+        }
+        return current;
+    }
+    async emitBeforeProviderPayload(model, payload) {
+        const handlers = this.getHandlers("before_provider_payload");
+        let current = payload;
+        if (!handlers || handlers.size === 0) {
+            return current;
+        }
+        for (const handler of handlers) {
+            try {
+                const result = (await handler({
+                    type: "before_provider_payload",
+                    model,
+                    payload: current,
+                }));
+                if (result !== undefined) {
+                    current = result.payload;
+                }
+            }
+            catch (error) {
+                throw normalizeHookError(error);
+            }
+        }
+        return current;
+    }
+    async emitQueueUpdate() {
+        await this.emitOwn({
+            type: "queue_update",
+            steer: [...this.steerQueue],
+            followUp: [...this.followUpQueue],
+            nextTurn: [...this.nextTurnQueue],
+        });
+    }
+    startRunPromise() {
+        let finish = () => { };
+        this.runPromise = new Promise((resolve) => {
+            finish = resolve;
+        });
+        return () => {
+            this.runPromise = undefined;
+            finish();
+        };
+    }
+    async createTurnState() {
+        const context = await this.session.buildContext();
+        const resources = this.getResources();
+        const sessionMetadata = await this.session.getMetadata();
+        const tools = [...this.tools.values()];
+        const activeTools = this.activeToolNames
+            .map((name) => this.tools.get(name))
+            .filter((tool) => tool !== undefined);
+        let systemPrompt = "You are a helpful assistant.";
+        if (typeof this.systemPrompt === "string") {
+            systemPrompt = this.systemPrompt;
+        }
+        else if (this.systemPrompt) {
+            systemPrompt = await this.systemPrompt({
+                env: this.env,
+                session: this.session,
+                model: this.model,
+                thinkingLevel: this.thinkingLevel,
+                activeTools,
+                resources,
+            });
+        }
+        return {
+            messages: context.messages,
+            resources,
+            streamOptions: cloneStreamOptions(this.streamOptions),
+            sessionId: sessionMetadata.id,
+            systemPrompt,
+            model: this.model,
+            thinkingLevel: this.thinkingLevel,
+            tools,
+            activeTools,
+        };
+    }
+    createContext(turnState, systemPrompt) {
+        return {
+            systemPrompt: systemPrompt ?? turnState.systemPrompt,
+            messages: turnState.messages.slice(),
+            tools: turnState.activeTools.slice(),
+        };
+    }
+    createStreamFn(getTurnState) {
+        return async (model, context, streamOptions) => {
+            const turnState = getTurnState();
+            const auth = await this.getApiKeyAndHeaders?.(model);
+            const snapshotOptions = {
+                ...turnState.streamOptions,
+                headers: mergeHeaders(turnState.streamOptions.headers, auth?.headers),
+            };
+            const requestOptions = await this.emitBeforeProviderRequest(model, turnState.sessionId, snapshotOptions);
+            return resolveAgentCoreStreamFn(this.runtime)(model, context, {
+                cacheRetention: requestOptions.cacheRetention,
+                headers: requestOptions.headers,
+                maxRetries: requestOptions.maxRetries,
+                maxRetryDelayMs: requestOptions.maxRetryDelayMs,
+                metadata: requestOptions.metadata,
+                onPayload: async (payload) => await this.emitBeforeProviderPayload(model, payload),
+                onResponse: async (response) => {
+                    const headers = { ...response.headers };
+                    await this.emitOwn({ type: "after_provider_response", status: response.status, headers }, streamOptions?.signal);
+                },
+                reasoning: streamOptions?.reasoning,
+                // design/119 #2: forward the loop-config per-request output cap (the curated snapshot below
+                // deliberately excludes provider knobs, but maxTokens is loop-owned — dropping it here was
+                // the silent break in the spec.limits.maxOutputTokens chain).
+                maxTokens: streamOptions?.maxTokens,
+                // design/130 P2b (codex BLOCKER): same class as the maxTokens line above — the curated
+                // snapshot must forward every LOOP-OWNED per-call field, or the soft call deadline silently
+                // dies at this seam on the production runner→harness→provider path.
+                callDeadlineMs: streamOptions?.callDeadlineMs,
+                // service [405]: the dynamic-cap marker rides with maxTokens (recoverable-length contract).
+                maxTokensDynamic: streamOptions?.maxTokensDynamic,
+                // [477]: the static reasoning-cut downgrade grant is loop-owned per-call state — same
+                // forwarding class as maxTokensDynamic (locked by test/stream-options-forwarding.test.ts).
+                staticReasoningCutDowngrade: streamOptions?.staticReasoningCutDowngrade,
+                // design/131: third loop-owned per-call field through this whitelist (the forwarding contract
+                // is now LOCKED by test/stream-options-forwarding.test.ts — the class that bit twice).
+                resilience: streamOptions?.resilience,
+                signal: streamOptions?.signal,
+                sessionId: turnState.sessionId,
+                timeoutMs: requestOptions.timeoutMs,
+                transport: requestOptions.transport,
+                apiKey: auth?.apiKey,
+            });
+        };
+    }
+    async drainQueuedMessages(queue, mode) {
+        const messages = mode === "all" ? queue.splice(0) : queue.splice(0, 1);
+        if (messages.length === 0) {
+            return messages;
+        }
+        try {
+            await this.emitQueueUpdate();
+            return messages;
+        }
+        catch (error) {
+            queue.unshift(...messages);
+            throw normalizeHookError(error);
+        }
+    }
+    createLoopConfig(getTurnState, setTurnState) {
+        const turnState = getTurnState();
+        // eslint-disable-next-line @typescript-eslint/no-this-alias -- the recovery getters below close over the instance
+        const self = this;
+        return {
+            model: turnState.model,
+            reasoning: turnState.thinkingLevel === "off" ? undefined : turnState.thinkingLevel,
+            // design/119 #2: per-request output cap — config extends SimpleStreamOptions, so the loop's
+            // {...config} spread carries it into every provider call as options.maxTokens.
+            ...(this.maxOutputTokens !== undefined ? { maxTokens: this.maxOutputTokens } : {}),
+            // design/130 P1: per-call dynamic cap seam — evaluated by the loop before each provider call.
+            ...(this.maxOutputTokensPerCall !== undefined ? { maxTokensPerCall: this.maxOutputTokensPerCall } : {}),
+            // design/130 P2b: per-call soft wall-clock deadline seam (brain-side stream cutoff).
+            ...(this.callDeadlineMsPerCall !== undefined ? { callDeadlineMsPerCall: this.callDeadlineMsPerCall } : {}),
+            // design/131: per-task resilience intent — rides the loop-config spread into every provider call.
+            ...(this.resilience !== undefined ? { resilience: this.resilience } : {}),
+            ...(this.maxToolConcurrency !== undefined ? { maxToolConcurrency: this.maxToolConcurrency } : {}),
+            // design/120 P2: in-stream execution reaches the loop ONLY when the host opted in AND no
+            // tool_call gate handler exists at run start (createLoopConfig runs once per prompt()). A
+            // registered tool_call handler could durably suspend (mint checkpoint + abort), which has no
+            // stable leaf mid-stream, so its presence forces the batch path for the whole run.
+            ...(this.streamingToolExecution === true && (this.getHandlers("tool_call")?.size ?? 0) === 0
+                ? { streamingToolExecution: true }
+                : {}),
+            convertToLlm,
+            // VENDORED EDIT (design/74 R3-A, VENDOR.md mod #16): wire the loop's EXISTING clean-exit callback to a
+            // one-way harness flag. The runner's `turn_boundary` subscriber sets it (via `requestStopAfterTurn`)
+            // once a resource slice limit is hit + the suspend is committed; the loop then exits cleanly at the
+            // boundary (agent_end + return) instead of via abort — no orphan-[INTERRUPTED] reconcile, clean resume.
+            shouldStopAfterTurn: () => this._stopAfterTurn,
+            transformContext: async (messages) => {
+                const result = await this.emitHook({ type: "context", messages: [...messages] });
+                return result?.messages ?? messages;
+            },
+            beforeToolCall: async ({ toolCall, args }) => {
+                const result = await this.emitHook({
+                    type: "tool_call",
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.name,
+                    input: args,
+                });
+                // Return the hook result verbatim: cherry-picking `{ block, reason }` here structurally
+                // dropped any future field (e.g. `updatedInput`, design/37) before it reached the loop, with
+                // no TS error since BeforeToolCallResult only requires block?/reason?. `ToolCallResult` is
+                // kept in sync with `BeforeToolCallResult`, so the shapes match.
+                return result;
+            },
+            afterToolCall: async ({ toolCall, args, result, isError }) => {
+                const patch = await this.emitHook({
+                    type: "tool_result",
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.name,
+                    input: args,
+                    content: result.content,
+                    details: result.details,
+                    isError,
+                });
+                return patch
+                    ? {
+                        content: patch.content,
+                        details: patch.details,
+                        isError: patch.isError,
+                        terminate: patch.terminate,
+                    }
+                    : undefined;
+            },
+            prepareNextTurn: async () => {
+                await this.flushPendingSessionWrites();
+                // VENDORED EDIT (design/64 §25 (A), within-task compaction): between-turn boundary seam. The
+                // session is fully flushed here and `createTurnState()` below rebuilds the context FROM the
+                // session, so a handler that persists a mutation (e.g. compaction via `session.appendCompaction`)
+                // is picked up by the very next request — the CC query-path autocompact position equivalent.
+                // Policy lives entirely in the subscriber (core runtask); the harness only supplies the timing.
+                // `this.model` (always set — required in AgentHarnessOptions) is what `createTurnState()` will
+                // stamp on the NEXT turn: a mid-task `setModel` (e.g. budget degrade) lands there first, so the
+                // handler's window math follows the model that actually runs the next request (council #1).
+                await this.emitHook({ type: "turn_boundary", model: this.model });
+                const nextTurnState = await this.createTurnState();
+                setTurnState(nextTurnState);
+                return {
+                    context: this.createContext(nextTurnState),
+                    model: nextTurnState.model,
+                    thinkingLevel: nextTurnState.thinkingLevel,
+                };
+            },
+            getSteeringMessages: async () => this.drainQueuedMessages(this.steerQueue, this.steeringQueueMode),
+            getFollowUpMessages: async () => {
+                const queued = await this.drainQueuedMessages(this.followUpQueue, this.followUpQueueMode);
+                if (queued.length > 0)
+                    return queued;
+                // roadmap #5 (CC Stop hook): the queue is dry and the agent would otherwise END — consult
+                // the stop gate (wired by the runner from Hooks.stop). Returned messages continue the run
+                // through the SAME pending-message path as real follow-ups; [] lets the run end normally.
+                return this.stopGate ? await this.stopGate() : queued;
+            },
+            // design/118 ④b/⑤: recovery chains. Read LIVE (not snapshotted) so setLoopRecovery() before
+            // prompt() — the runner's wiring point — always lands.
+            recovery: {
+                get truncatedOutput() {
+                    return self.loopRecovery?.truncatedOutput;
+                },
+                get malformedToolUse() {
+                    return self.loopRecovery?.malformedToolUse;
+                },
+                get thinkingOnly() {
+                    return self.loopRecovery?.thinkingOnly;
+                },
+                get degenerateOutput() {
+                    return self.loopRecovery?.degenerateOutput;
+                },
+                get walltimeCutoff() {
+                    return self.loopRecovery?.walltimeCutoff; // design/130 P2b
+                },
+                get promptTooLong() {
+                    const ptl = self.loopRecovery?.promptTooLong;
+                    if (!ptl)
+                        return undefined;
+                    return {
+                        detect: ptl.detect,
+                        maxRetries: ptl.maxRetries,
+                        withholdErrorEvents: ptl.withholdErrorEvents, // M1: relay the CC-withhold switch
+                        recover: async (_messages, attempt) => {
+                            let shrank = false;
+                            try {
+                                shrank = await ptl.recover(attempt);
+                            }
+                            catch {
+                                shrank = false; // contract belt: a throwing policy = recovery declined, never a new failure
+                            }
+                            if (!shrank)
+                                return undefined;
+                            // Rebuild the transcript FROM the session (where recover() persisted the reduction),
+                            // and adopt the rebuilt turn state so subsequent hooks see the same view.
+                            const nextTurnState = await self.createTurnState();
+                            setTurnState(nextTurnState);
+                            return self.createContext(nextTurnState).messages;
+                        },
+                    };
+                },
+            },
+        };
+    }
+    /**
+     * design/118 ④b/⑤: wire (or clear) the loop's recovery chains. The runner calls this after
+     * construction — truncated-output auto-continue and the prompt-too-long recover policy are
+     * PROFILE decisions (the harness only relays them to the loop).
+     */
+    setLoopRecovery(recovery) {
+        this.loopRecovery = recovery;
+    }
+    /**
+     * roadmap #5 (CC Stop hook): wire (or clear) the stop gate — consulted ONLY when the run would
+     * otherwise end (no tool calls, steer + followUp queues dry). Non-empty return = the run
+     * continues with those messages injected; empty = the run ends. Policy (the Hooks.stop call,
+     * consecutive-block cap, reason formatting) lives in the runner; the harness only supplies the
+     * drain-point timing.
+     */
+    setStopGate(gate) {
+        this.stopGate = gate;
+    }
+    validateToolNames(toolNames, tools = this.tools) {
+        const missing = toolNames.filter((name) => !tools.has(name));
+        if (missing.length > 0) {
+            throw new AgentHarnessError("invalid_argument", `Unknown tool(s): ${missing.join(", ")}`);
+        }
+    }
+    async flushPendingSessionWrites() {
+        // VENDOR.md mod #5 (fixed at de-vendoring, design/118 ⑤ — central guard): once THIS run's abort
+        // has fired, the session may hold an open tool_call batch whose synthetic tool_results are
+        // appended later by the caller's interrupt reconcile. Flushing caller-queued writes now (from
+        // ANY teardown path: prepareNextTurn, turn_end, agent_end, executeTurn's finally) would land
+        // them inside that open batch — an API-invalid sequence on strict providers. Hold the queue;
+        // it drains via flushQueuedSessionWrites() after the reconcile (runtask wires this) or at the
+        // next prompt() start. (Caveats, documented: ① a durable-suspend abort that never reconciles in
+        // this process holds these writes until the harness dies — the resume leg rebuilds from the
+        // checkpointed session, so a held write is lost, not corrupting; ② a same-tick turn-boundary
+        // setModel racing a hard abort CAN be held — the runtask reconcile-then-drain wiring flushes it
+        // right after the transcript is legal again, so the ordering stays correct either way.)
+        if (this.runAbortController?.signal.aborted) {
+            return;
+        }
+        while (this.pendingSessionWrites.length > 0) {
+            const write = this.pendingSessionWrites[0];
+            if (write.type === "message") {
+                await this.session.appendMessage(write.message);
+            }
+            else if (write.type === "model_change") {
+                await this.session.appendModelChange(write.provider, write.modelId);
+            }
+            else if (write.type === "thinking_level_change") {
+                await this.session.appendThinkingLevelChange(write.thinkingLevel);
+            }
+            else if (write.type === "custom") {
+                await this.session.appendCustomEntry(write.customType, write.data);
+            }
+            else if (write.type === "custom_message") {
+                await this.session.appendCustomMessageEntry(write.customType, write.content, write.display, write.details);
+            }
+            else if (write.type === "label") {
+                await this.session.appendLabel(write.targetId, write.label);
+            }
+            else if (write.type === "session_info") {
+                await this.session.appendSessionName(write.name ?? "");
+            }
+            else if (write.type === "leaf") {
+                await this.session.getStorage().setLeafId(write.targetId);
+            }
+            this.pendingSessionWrites.shift();
+        }
+    }
+    async handleAgentEvent(event, signal) {
+        if (event.type === "message_end") {
+            // VENDORED EDIT (audit A-1 layer ③, design/64 §28.3): a synthetic EMPTY failure assistant
+            // (stopReason aborted/error, no text/thinking/toolCall content — e.g. the loop-failure message
+            // for a stream that died on an aborted signal or a provider 500 with no output) is NOT model
+            // output and must not be persisted: parked between an interrupted tool batch and its reconcile
+            // tool_results it makes the session permanently invalid for strict providers. It still flows to
+            // live subscribers (emitAny below) and into the prompt() result — only the session skips it. An
+            // aborted message WITH partial content is real output and persists as before.
+            // VENDORED EDIT (message-identity Phase 1, VENDOR.md mod #23): keep the entry id `appendMessage` RETURNS
+            // (synchronous at the append — no `getLeafId` after-the-fact race) and thread it onto the emitted event via
+            // a fresh `{ ...event, entryId }` (never mutate `event`). A consumer maps this just-committed message → its
+            // persisted SessionTreeEntry id (the `message_committed` wire event). Undefined when the skip above appends
+            // nothing (empty-failure assistant) — then the event is emitted as-is and no commit event is published.
+            let entryId;
+            if (!isEmptyFailureAssistant(event.message)) {
+                entryId = await this.session.appendMessage(event.message);
+            }
+            await this.emitAny(entryId !== undefined ? { ...event, entryId } : event, signal);
+            return;
+        }
+        if (event.type === "turn_end") {
+            let eventError;
+            try {
+                await this.emitAny(event, signal);
+            }
+            catch (error) {
+                eventError = error;
+            }
+            const queued = this.pendingSessionWrites.length > 0;
+            await this.flushPendingSessionWrites(); // mod #5: no-op while this run's abort has fired
+            // Honest save_point semantics under the mod #5 hold: `hadPendingMutations` means "this save
+            // point PERSISTED queued mutations" — when the abort hold kept the queue, report false (the
+            // late drain after reconcile is not a save point).
+            const hadPendingMutations = queued && this.pendingSessionWrites.length === 0;
+            if (eventError) {
+                throw toLintErrorObject(eventError, "Non-Error thrown");
+            }
+            await this.emitOwn({ type: "save_point", hadPendingMutations });
+            return;
+        }
+        if (event.type === "agent_end") {
+            await this.flushPendingSessionWrites(); // mod #5: no-op while this run's abort has fired
+            this.phase = "idle";
+            await this.emitAny(event, signal);
+            await this.emitOwn({ type: "settled", nextTurnCount: this.nextTurnQueue.length }, signal);
+            return;
+        }
+        await this.emitAny(event, signal);
+    }
+    async emitRunFailure(model, error, aborted, signal) {
+        const failureMessage = createFailureMessage(model, error, aborted);
+        await this.handleAgentEvent({ type: "message_start", message: failureMessage }, signal);
+        await this.handleAgentEvent({ type: "message_end", message: failureMessage }, signal);
+        await this.handleAgentEvent({ type: "turn_end", message: failureMessage, toolResults: [] }, signal);
+        await this.handleAgentEvent({ type: "agent_end", messages: [failureMessage] }, signal);
+        return [failureMessage];
+    }
+    async executeTurn(turnState, text, options) {
+        let activeTurnState = turnState;
+        let messages = [createUserMessage(text, options?.images)];
+        if (this.nextTurnQueue.length > 0) {
+            const queuedMessages = this.nextTurnQueue.splice(0);
+            try {
+                await this.emitQueueUpdate();
+            }
+            catch (error) {
+                this.nextTurnQueue.unshift(...queuedMessages);
+                throw normalizeHookError(error);
+            }
+            messages = [...queuedMessages, messages[0]];
+        }
+        const beforeResult = await this.emitHook({
+            type: "before_agent_start",
+            prompt: text,
+            images: options?.images,
+            systemPrompt: turnState.systemPrompt,
+            resources: turnState.resources,
+        });
+        if (beforeResult?.messages) {
+            messages = [...messages, ...beforeResult.messages];
+        }
+        const abortController = new AbortController();
+        const getTurnState = () => activeTurnState;
+        const setTurnState = (nextTurnState) => {
+            activeTurnState = nextTurnState;
+        };
+        this.runAbortController = abortController;
+        const runResultPromise = (async () => {
+            try {
+                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, 
+                // service [398] C2: the loop's recovery trace was test-only (the 8th arg was never passed in
+                // production) — wire the host's sink so self-heal recoveries stop being invisible.
+                this.loopTrace);
+            }
+            catch (error) {
+                try {
+                    return await this.emitRunFailure(activeTurnState.model, error, abortController.signal.aborted, abortController.signal);
+                }
+                catch (failureError) {
+                    const cause = new AggregateError([toError(error), toError(failureError)], "Agent run failed and failure reporting failed");
+                    throw new AgentHarnessError("unknown", cause.message, cause);
+                }
+            }
+        })();
+        try {
+            const newMessages = await runResultPromise;
+            for (let i = newMessages.length - 1; i >= 0; i--) {
+                const message = newMessages[i];
+                if (message.role === "assistant") {
+                    // design/118 ④b: a truncated-output auto-continue splits ONE answer across several
+                    // assistant messages (…length-stop → nudge → continuation…). The prompt() result is "the
+                    // answer", so merge the trailing chain's text — otherwise the caller's result string
+                    // silently loses every segment but the last (the session/events keep the real messages).
+                    return mergeTruncatedOutputChain(newMessages, i);
+                }
+            }
+            throw new AgentHarnessError("invalid_state", "AgentHarness prompt completed without an assistant message");
+        }
+        finally {
+            try {
+                await this.flushPendingSessionWrites(); // mod #5: no-op while this run's abort has fired
+            }
+            finally {
+                this.runAbortController = undefined;
+            }
+        }
+    }
+    async prompt(text, options) {
+        if (this.phase !== "idle") {
+            throw new AgentHarnessError("busy", "AgentHarness is busy");
+        }
+        // VENDORED EDIT (design/74 council #1, VENDOR.md mod #16): the resource-suspend stop latch is ONE-SHOT
+        // per prompt. `requestStopAfterTurn()` sets it to cleanly stop THIS run's loop after the current turn;
+        // clear it at the start of every prompt so a re-prompt/reuse of the harness can't inherit a stale stop
+        // (which would silently end the next run after a single turn).
+        this._stopAfterTurn = false;
+        this.phase = "turn";
+        const finishRunPromise = this.startRunPromise();
+        try {
+            // mod #5 belt: writes held from a previous ABORTED run (whose caller never called
+            // flushQueuedSessionWrites) drain here — before createTurnState builds the new context —
+            // so they are never lost and always land AFTER any reconcile the caller did run.
+            await this.flushPendingSessionWrites();
+            const turnState = await this.createTurnState();
+            return await this.executeTurn(turnState, text, options);
+        }
+        catch (error) {
+            this.phase = "idle";
+            throw normalizeHarnessError(error, "unknown");
+        }
+        finally {
+            finishRunPromise();
+        }
+    }
+    // VENDORED EDIT (design/71 P1, 2026-06-12): skill() DELETED along with harness/skills.ts +
+    // file-loader-utils.ts (and the ignore/yaml deps they alone pulled). Upstream's explicit
+    // skill-invocation entry; zero callers here, and the system-prompt half of the feature
+    // (formatSkillsForSystemPrompt) was already dead-deleted in P0 — the model never saw skill
+    // listings in this repo. resources.skills is now a fully inert field (see TaskSpec.skills note
+    // in src/core/types.ts; the Skill TYPE stays in types.ts and is still used by core's toSkill).
+    // VENDORED EDIT (design/71 P1, 2026-06-12): promptFromTemplate() DELETED along with
+    // harness/prompt-templates.ts + prompt-template-arguments.ts. Upstream's interactive
+    // slash-command feature; resources.promptTemplates was never fed by this repo and the method had
+    // zero callers (src/ + test/). The PromptTemplate type stays in types.ts (type-level surface only).
+    async steer(text, options) {
+        if (this.phase === "idle") {
+            throw new AgentHarnessError("invalid_state", "Cannot steer while idle");
+        }
+        this.steerQueue.push(createUserMessage(text, options?.images));
+        await this.emitQueueUpdate();
+    }
+    async followUp(text, options) {
+        if (this.phase === "idle") {
+            throw new AgentHarnessError("invalid_state", "Cannot follow up while idle");
+        }
+        this.followUpQueue.push(createUserMessage(text, options?.images));
+        await this.emitQueueUpdate();
+    }
+    async nextTurn(text, options) {
+        this.nextTurnQueue.push(createUserMessage(text, options?.images));
+        await this.emitQueueUpdate();
+    }
+    async appendMessage(message) {
+        try {
+            if (this.phase === "idle") {
+                await this.session.appendMessage(message);
+            }
+            else {
+                this.pendingSessionWrites.push({ type: "message", message });
+            }
+        }
+        catch (error) {
+            throw normalizeHarnessError(error, "session");
+        }
+    }
+    // VENDORED EDIT (bug-hunt #10, 2026-06-25): the public `compact()` method was DELETED (with its 3
+    // first-party imports: compact / prepareCompaction / DEFAULT_COMPACTION_SETTINGS). It was an unreachable
+    // DIVERGENCE landmine: ZERO callers (src/ + test/ — within-task compaction goes through the first-party
+    // `maybeCompact` turn-end seam, NOT this method), `AgentHarness` is not exported from src/index.ts, AND it
+    // skipped the first-party `<analysis>`-strip + empty-summary guard that `auto-compaction.ts` applies — so if
+    // anyone HAD wired it, it would persist un-stripped scratch as the summary. Same precedent as navigateTree
+    // below (design/71 delete-the-unreachable-divergence). Deleting it also removed a vendored→first-party import.
+    // VENDORED EDIT (design/71 P0, 2026-06-12): navigateTree() DELETED along with
+    // harness/compaction/branch-summarization.ts. It was upstream's interactive branch-navigation
+    // feature (move leaf + summarize the abandoned branch); zero callers in this repo (src/ + test/),
+    // unreachable from Runner -> harness.prompt. The whole branch_summary chain (entry type, render,
+    // replay, moveTo, BranchSummaryError) was removed in the design/71 清尾 pass — zero producers ever
+    // shipped from this repo, so no stored session can contain such an entry.
+    getModel() {
+        return this.model;
+    }
+    getThinkingLevel() {
+        return this.thinkingLevel;
+    }
+    async setModel(model) {
+        try {
+            const previousModel = this.model;
+            if (this.phase === "idle") {
+                await this.session.appendModelChange(model.provider, model.id);
+            }
+            else {
+                this.pendingSessionWrites.push({
+                    type: "model_change",
+                    provider: model.provider,
+                    modelId: model.id,
+                });
+            }
+            this.model = model;
+            await this.emitOwn({ type: "model_select", model, previousModel, source: "set" });
+        }
+        catch (error) {
+            throw normalizeHarnessError(error, "session");
+        }
+    }
+    async setThinkingLevel(level) {
+        try {
+            const previousLevel = this.thinkingLevel;
+            if (this.phase === "idle") {
+                await this.session.appendThinkingLevelChange(level);
+            }
+            else {
+                this.pendingSessionWrites.push({ type: "thinking_level_change", thinkingLevel: level });
+            }
+            this.thinkingLevel = level;
+            await this.emitOwn({ type: "thinking_level_select", level, previousLevel });
+        }
+        catch (error) {
+            throw normalizeHarnessError(error, "session");
+        }
+    }
+    async setActiveTools(toolNames) {
+        try {
+            this.validateToolNames(toolNames);
+            this.activeToolNames = [...toolNames];
+        }
+        catch (error) {
+            throw normalizeHarnessError(error, "invalid_argument");
+        }
+    }
+    getSteeringMode() {
+        return this.steeringQueueMode;
+    }
+    async setSteeringMode(mode) {
+        this.steeringQueueMode = mode;
+    }
+    getFollowUpMode() {
+        return this.followUpQueueMode;
+    }
+    async setFollowUpMode(mode) {
+        this.followUpQueueMode = mode;
+    }
+    getResources() {
+        return {
+            skills: this.resources.skills?.slice(),
+            promptTemplates: this.resources.promptTemplates?.slice(),
+        };
+    }
+    async setResources(resources) {
+        const previousResources = this.getResources();
+        this.resources = {
+            skills: resources.skills?.slice(),
+            promptTemplates: resources.promptTemplates?.slice(),
+        };
+        await this.emitOwn({
+            type: "resources_update",
+            resources: this.getResources(),
+            previousResources,
+        });
+    }
+    getStreamOptions() {
+        return cloneStreamOptions(this.streamOptions);
+    }
+    async setStreamOptions(streamOptions) {
+        this.streamOptions = cloneStreamOptions(streamOptions);
+    }
+    async setTools(tools, activeToolNames) {
+        try {
+            const nextTools = new Map(tools.map((tool) => [tool.name, tool]));
+            const nextActiveToolNames = activeToolNames ? [...activeToolNames] : this.activeToolNames;
+            this.validateToolNames(nextActiveToolNames, nextTools);
+            this.tools = nextTools;
+            this.activeToolNames = [...nextActiveToolNames];
+        }
+        catch (error) {
+            throw normalizeHarnessError(error, "invalid_argument");
+        }
+    }
+    /**
+     * design/74 R3-A: request a CLEAN stop at the next turn boundary. Unlike {@link abort} (a hard
+     * AbortController cancel that — with no `suspendRef` — drives the orphan-[INTERRUPTED] session reconcile),
+     * this sets a one-way flag the loop reads via its `shouldStopAfterTurn` callback: the current turn finishes
+     * its tool calls, the loop emits `agent_end`, and returns. The runner uses it for a resource-slice suspend
+     * so the suspended session is left clean (resumable), never reconciled as interrupted. Idempotent.
+     */
+    requestStopAfterTurn() {
+        this._stopAfterTurn = true;
+    }
+    /**
+     * VENDOR.md mod #5 (fixed at de-vendoring, design/118 ⑤): drain session writes queued during an
+     * ABORTED run. The harness intentionally does NOT flush on the abort path — the caller's interrupt
+     * reconcile must append its synthetic tool_results first (closing the open tool_call batch), then
+     * call this, so queued writes always land on a legal transcript. Safe to call anytime; no-op when
+     * the queue is empty.
+     */
+    async flushQueuedSessionWrites() {
+        try {
+            await this.flushPendingSessionWrites();
+        }
+        catch (error) {
+            throw normalizeHarnessError(error, "session");
+        }
+    }
+    async abort() {
+        const clearedSteer = [...this.steerQueue];
+        const clearedFollowUp = [...this.followUpQueue];
+        this.steerQueue = [];
+        this.followUpQueue = [];
+        this.runAbortController?.abort();
+        const errors = [];
+        try {
+            await this.emitQueueUpdate();
+        }
+        catch (error) {
+            errors.push(toError(error));
+        }
+        try {
+            await this.waitForIdle();
+        }
+        catch (error) {
+            errors.push(toError(error));
+        }
+        try {
+            await this.emitOwn({ type: "abort", clearedSteer, clearedFollowUp });
+        }
+        catch (error) {
+            errors.push(toError(error));
+        }
+        if (errors.length > 0) {
+            const cause = errors.length === 1 ? errors[0] : new AggregateError(errors, "Abort completed with errors");
+            throw normalizeHarnessError(cause, "hook");
+        }
+        return { clearedSteer, clearedFollowUp };
+    }
+    async waitForIdle() {
+        await this.runPromise;
+    }
+    subscribe(listener) {
+        let handlers = this.handlers.get(SUBSCRIBER_EVENT_TYPE);
+        if (!handlers) {
+            handlers = new Set();
+            this.handlers.set(SUBSCRIBER_EVENT_TYPE, handlers);
+        }
+        handlers.add(listener);
+        return () => handlers.delete(listener);
+    }
+    on(type, handler) {
+        let handlers = this.handlers.get(type);
+        if (!handlers) {
+            handlers = new Set();
+            this.handlers.set(type, handlers);
+        }
+        handlers.add(handler);
+        return () => handlers.delete(handler);
+    }
+}
+// VENDORED EDIT (audit A-1 layer ③): a failure assistant carrying NO content — no tool calls, no
+// non-whitespace text/thinking. Only such messages are skipped from session persistence; an aborted
+// message with partial output is real transcript and persists.
+function isEmptyFailureAssistant(message) {
+    if (message.role !== "assistant")
+        return false;
+    const m = message;
+    if (m.stopReason !== "aborted" && m.stopReason !== "error")
+        return false;
+    return m.content.every((c) => c.type === "text" ? c.text.trim() === "" : c.type === "thinking" ? c.thinking.trim() === "" : false);
+}
+/**
+ * design/118 ④b: walk backward across the trailing `length`-stop chain
+ * (assistant[length] → continue-nudge custom → assistant …) and return the FINAL assistant with the
+ * chain's text concatenated in order. Non-chain shapes return the final assistant unchanged.
+ */
+function mergeTruncatedOutputChain(messages, lastAssistantIndex) {
+    const last = messages[lastAssistantIndex];
+    const parts = [];
+    let i = lastAssistantIndex;
+    while (i - 2 >= 0 &&
+        messages[i - 1].role === "custom" &&
+        messages[i - 1].customType === "loop:truncated-output-continue" &&
+        messages[i - 2].role === "assistant" &&
+        messages[i - 2].stopReason === "length") {
+        const head = messages[i - 2];
+        parts.unshift(head.content.map((c) => (c.type === "text" ? c.text : "")).join(""));
+        i -= 2;
+    }
+    if (parts.length === 0) {
+        return last;
+    }
+    const lastText = last.content.map((c) => (c.type === "text" ? c.text : "")).join("");
+    return {
+        ...last,
+        content: [
+            { type: "text", text: parts.join("") + lastText },
+            ...last.content.filter((c) => c.type !== "text"),
+        ],
+    };
+}
+function toLintErrorObject(value, fallbackMessage) {
+    if (value instanceof Error) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return new Error(value);
+    }
+    const error = new Error(fallbackMessage, { cause: value });
+    if ((typeof value === "object" && value !== null) || typeof value === "function") {
+        Object.assign(error, value);
+    }
+    return error;
+}
+//# sourceMappingURL=agent-harness.js.map