omk-agent-core 0.98.0 → 0.98.2

package/dist/harness/agent-harness.js

@@ -1,138 +1,33 @@
-import { streamSimple } from "omk-ai";
-import { runAgentLoop } from "../agent-loop.js";
-import { collectEntriesForBranchSummary, generateBranchSummary } from "./compaction/branch-summarization.js";
-import { compact, DEFAULT_COMPACTION_SETTINGS, prepareCompaction } from "./compaction/compaction.js";
-import { convertToLlm } from "./messages.js";
+import { isContextOverflow, streamSimple, } from "omk-ai";
+import { runAgentLoop, runAgentLoopContinue } from "../agent-loop.js";
+import { collectEntriesForBranchSummary } from "./compaction/branch-summarization.js";
+import { compact, DEFAULT_COMPACTION_SETTINGS, estimateContextTokens, prepareCompaction, shouldCompact, } from "./compaction/compaction.js";
+import { HarnessSessionFacade } from "./harness-session.js";
+import { convertToLlm, createFailureMessage, createUserMessage } from "./messages.js";
+import { findDuplicateNames } from "./name-validation.js";
+import { OperationLifecycleController, } from "./operation-lifecycle-controller.js";
+import { PROMPT_FAMILY_KINDS, } from "./operation-lifecycle-types.js";
+import { classifyAssistantOutcome, classifyAttemptFailure, classifyAttemptOutcome, classifyNavigateTreeOutcome, combineBoundaryErrors, normalizeHarnessError, resolveOperationFailure, resolveOperationOutcome, } from "./operation-outcome.js";
 import { formatPromptTemplateInvocation } from "./prompt-templates.js";
+import { uuidv7 } from "./session/uuid.js";
+import { SessionWriteCoordinator } from "./session-write-coordinator.js";
 import { formatSkillInvocation } from "./skills.js";
-import { AgentHarnessError, BranchSummaryError, 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 findDuplicateNames(names) {
-    const seen = new Set();
-    const duplicates = new Set();
-    for (const name of names) {
-        if (seen.has(name))
-            duplicates.add(name);
-        seen.add(name);
-    }
-    return [...duplicates];
-}
-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);
-    if (cause instanceof BranchSummaryError)
-        return new AgentHarnessError("branch_summary", cause.message, cause);
-    return new AgentHarnessError(fallbackCode, cause.message, cause);
-}
-function normalizeHookError(error) {
-    return normalizeHarnessError(error, "hook");
-}
+import { applyStreamOptionsPatch, cloneStreamOptions, mergeHeaders } from "./stream-options.js";
+import { SubscriberFanout } from "./subscriber-fanout.js";
+import { createSummarizationRetry } from "./summarization-retry.js";
+import { resolveNavigationTarget, runBranchSummary } from "./tree-navigation.js";
+import { AgentHarnessError, toError } from "./types.js";
 export class AgentHarness {
     env;
     session;
-    phase = "idle";
-    runAbortController;
-    runPromise;
-    pendingSessionWrites = [];
+    sessionFacade;
+    lifecycle;
+    sessionWrites;
     model;
     thinkingLevel;
     systemPrompt;
     streamOptions;
+    compactionSettings;
     getApiKeyAndHeaders;
     resources;
     tools = new Map();
@@ -143,11 +38,19 @@ export class AgentHarness {
     followUpQueueMode;
     nextTurnQueue = [];
     handlers = new Map();
+    subscribers = new SubscriberFanout();
     constructor(options) {
         this.env = options.env;
         this.session = options.session;
+        this.sessionWrites = new SessionWriteCoordinator(this.session);
+        this.lifecycle = new OperationLifecycleController({
+            createOperationId: () => uuidv7(),
+            now: () => Date.now(),
+        });
+        this.sessionFacade = new HarnessSessionFacade(this.session, () => this.currentPhase(), this.sessionWrites);
         this.resources = options.resources ?? {};
         this.streamOptions = cloneStreamOptions(options.streamOptions);
+        this.compactionSettings = { ...DEFAULT_COMPACTION_SETTINGS, ...options.compaction };
         this.systemPrompt = options.systemPrompt;
         this.getApiKeyAndHeaders = options.getApiKeyAndHeaders;
         this.validateUniqueNames((options.tools ?? []).map((tool) => tool.name), "Duplicate tool name(s)");
@@ -164,31 +67,19 @@ export class AgentHarness {
         this.steeringQueueMode = options.steeringMode ?? "one-at-a-time";
         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);
-            }
-        }
+        await this.emitAny(event, signal);
     }
+    /** Subscriber fan-out; the self-wait barrier lives in `SubscriberFanout`. */
     async emitAny(event, signal) {
-        for (const listener of this.getHandlers(SUBSCRIBER_EVENT_TYPE) ?? []) {
-            try {
-                await listener(event, signal);
-            }
-            catch (error) {
-                throw normalizeHookError(error);
-            }
-        }
+        await this.subscribers.emit(event, this.lifecycle.getCurrentOperation()?.operationId, signal);
+    }
+    /** Fail closed when an awaited listener tries to wait on its own operation. */
+    rejectCurrentOperationSelfWait(api) {
+        this.subscribers.assertNotSelfWait(api, this.lifecycle.getCurrentOperation()?.operationId);
     }
     async emitHook(event) {
-        const handlers = this.getHandlers(event.type);
+        const handlers = this.handlers.get(event.type);
         if (!handlers || handlers.size === 0)
             return undefined;
         let lastResult;
@@ -200,13 +91,13 @@ export class AgentHarness {
                 }
             }
             catch (error) {
-                throw normalizeHookError(error);
+                throw normalizeHarnessError(error, "hook");
             }
         }
         return lastResult;
     }
     async emitBeforeProviderRequest(model, sessionId, streamOptions) {
-        const handlers = this.getHandlers("before_provider_request");
+        const handlers = this.handlers.get("before_provider_request");
         let current = cloneStreamOptions(streamOptions);
         if (!handlers || handlers.size === 0)
             return current;
@@ -223,13 +114,13 @@ export class AgentHarness {
                 }
             }
             catch (error) {
-                throw normalizeHookError(error);
+                throw normalizeHarnessError(error, "hook");
             }
         }
         return current;
     }
     async emitBeforeProviderPayload(model, payload) {
-        const handlers = this.getHandlers("before_provider_payload");
+        const handlers = this.handlers.get("before_provider_payload");
         let current = payload;
         if (!handlers || handlers.size === 0)
             return current;
@@ -241,7 +132,7 @@ export class AgentHarness {
                 }
             }
             catch (error) {
-                throw normalizeHookError(error);
+                throw normalizeHarnessError(error, "hook");
             }
         }
         return current;
@@ -254,23 +145,88 @@ export class AgentHarness {
             nextTurn: [...this.nextTurnQueue],
         });
     }
-    startRunPromise() {
-        let finish = () => { };
-        const runPromise = new Promise((resolve) => {
-            finish = resolve;
+    /**
+     * Facade write-gate vocabulary mapped from lifecycle state. `settling` maps
+     * to "idle": the queue is drained by the settlement finalizer first, and
+     * listener writes persist after it through the coordinator tail.
+     */
+    currentPhase() {
+        const snapshot = this.lifecycle.getSnapshot();
+        if (snapshot.tag !== "active")
+            return "idle";
+        switch (snapshot.operation.kind) {
+            case "manual_compaction":
+                return "compaction";
+            case "tree_navigation":
+                return "branch_summary";
+            default:
+                return "turn";
+        }
+    }
+    /** Config writes persist immediately outside an active operation and queue during one. */
+    async persistConfigChange(write) {
+        if (this.lifecycle.getSnapshot().tag !== "active") {
+            await this.sessionWrites.persistAfterPending(write);
+        }
+        else {
+            this.sessionWrites.enqueue(write);
+        }
+    }
+    /**
+     * Single wrapper for every public operation: begin a lease, run the body,
+     * then settle exactly once. The final flush and the `settled` event happen
+     * inside the settling barrier; a finalizer failure never reports success.
+     */
+    async runOperation(kind, fallbackCode, body, classifyResult) {
+        const lease = this.lifecycle.begin(kind);
+        let result;
+        let bodyError;
+        // Everything after a successful begin() runs inside one capture region. A
+        // throwing `operation_started` listener must not escape before settle(),
+        // or the lifecycle would stay active and wedge the harness at "busy".
+        try {
+            await this.emitOwn({ type: "operation_started", operation: lease.operation });
+            result = await body(lease);
+        }
+        catch (error) {
+            bodyError = error;
+        }
+        // The final flush precedes classification: a persistence failure after a
+        // provider success must never record or report a completed operation.
+        let flushError;
+        try {
+            await this.sessionWrites.flush();
+        }
+        catch (error) {
+            flushError = error;
+        }
+        const outcome = resolveOperationOutcome({
+            signalAborted: lease.signal.aborted,
+            result,
+            bodyError,
+            flushError,
+            classifyResult,
+            fallbackCode,
         });
-        this.runPromise = runPromise;
-        return {
-            runPromise,
-            finishRunPromise: () => {
-                // A settled/agent_end listener may have started a new run while this
-                // one was still unwinding; only clear state still owned by this run.
-                if (this.runPromise === runPromise) {
-                    this.runPromise = undefined;
-                }
-                finish();
-            },
-        };
+        let settleError;
+        try {
+            await this.lifecycle.settle(lease, outcome, async () => {
+                await this.emitOwn({
+                    type: "settled",
+                    nextTurnCount: this.nextTurnQueue.length,
+                    operationId: lease.operation.operationId,
+                    outcome,
+                    attemptCount: this.lifecycle.getAttemptSummaries(lease).length,
+                }, lease.signal);
+            });
+        }
+        catch (error) {
+            settleError = error;
+        }
+        const failure = resolveOperationFailure({ bodyError, flushError, settleError, fallbackCode });
+        if (failure !== undefined)
+            throw failure;
+        return result;
     }
     async createTurnState() {
         const context = await this.session.buildContext();
@@ -316,13 +272,14 @@ export class AgentHarness {
     createStreamFn(getTurnState) {
         return async (model, context, streamOptions) => {
             const turnState = getTurnState();
+            const requestContext = await this.maybeAutoCompact(model, context, streamOptions?.signal);
             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 streamSimple(model, context, {
+            return streamSimple(model, requestContext, {
                 cacheRetention: requestOptions.cacheRetention,
                 headers: requestOptions.headers,
                 maxRetries: requestOptions.maxRetries,
@@ -352,10 +309,10 @@ export class AgentHarness {
         }
         catch (error) {
             queue.unshift(...messages);
-            throw normalizeHookError(error);
+            throw normalizeHarnessError(error, "hook");
         }
     }
-    createLoopConfig(getTurnState, setTurnState) {
+    createLoopConfig(getTurnState, setTurnState, lease) {
         const turnState = getTurnState();
         return {
             model: turnState.model,
@@ -389,7 +346,13 @@ export class AgentHarness {
                     : undefined;
             },
             prepareNextTurn: async () => {
-                await this.flushPendingSessionWrites();
+                await this.sessionWrites.flush();
+                if (lease) {
+                    const snapshot = this.lifecycle.getSnapshot();
+                    if (snapshot.tag === "active" && snapshot.stage === "save_point") {
+                        this.lifecycle.setStage(lease, "attempt_running");
+                    }
+                }
                 const nextTurnState = await this.createTurnState();
                 setTurnState(nextTurnState);
                 return {
@@ -413,40 +376,7 @@ export class AgentHarness {
         if (missing.length > 0)
             throw new AgentHarnessError("invalid_argument", `Unknown tool(s): ${missing.join(", ")}`);
     }
-    async flushPendingSessionWrites() {
-        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 === "active_tools_change") {
-                await this.session.appendActiveToolsChange(write.activeToolNames);
-            }
-            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) {
+    async handleAgentEvent(event, signal, lease) {
         if (event.type === "message_end") {
             await this.session.appendMessage(event.message);
             await this.emitAny(event, signal);
@@ -460,39 +390,48 @@ export class AgentHarness {
             catch (error) {
                 eventError = error;
             }
-            const hadPendingMutations = this.pendingSessionWrites.length > 0;
-            await this.flushPendingSessionWrites();
-            if (eventError)
-                throw eventError;
+            // The flush runs even after a failing listener so accepted writes are
+            // not stranded; a failing flush must then report next to that listener
+            // error, not in place of it.
+            const hadPendingMutations = this.sessionWrites.hasPending();
+            let flushError;
+            try {
+                await this.sessionWrites.flush();
+            }
+            catch (error) {
+                flushError = error;
+            }
+            if (lease) {
+                const snapshot = this.lifecycle.getSnapshot();
+                if (snapshot.tag === "active" && snapshot.stage === "attempt_running") {
+                    this.lifecycle.setStage(lease, "save_point");
+                }
+            }
+            const failure = combineBoundaryErrors([eventError, flushError], "turn_end listener failed and the save-point flush failed", "hook");
+            if (failure !== undefined)
+                throw failure;
             await this.emitOwn({ type: "save_point", hadPendingMutations });
             return;
         }
         if (event.type === "agent_end") {
-            // Finish this run's cleanup before flipping to "idle": listeners observing
-            // agent_end/settled may start the next prompt() immediately, and that run
-            // must not inherit state still owned by the run that just completed.
-            await this.flushPendingSessionWrites();
-            if (this.runAbortController && this.runAbortController.signal === signal) {
-                this.runAbortController = undefined;
-            }
-            this.phase = "idle";
+            // agent_end is an attempt event: flush its accepted writes, but lifecycle
+            // settlement and the settled event belong to OperationLease.settle().
+            await this.sessionWrites.flush();
             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, completedMessages) {
+    async emitRunFailure(model, error, aborted, signal, completedMessages, lease) {
         const failureMessage = createFailureMessage(model, error, aborted);
         const messages = [...completedMessages, failureMessage];
-        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 }, signal);
+        await this.handleAgentEvent({ type: "message_start", message: failureMessage }, signal, lease);
+        await this.handleAgentEvent({ type: "message_end", message: failureMessage }, signal, lease);
+        await this.handleAgentEvent({ type: "turn_end", message: failureMessage, toolResults: [] }, signal, lease);
+        await this.handleAgentEvent({ type: "agent_end", messages }, signal, lease);
         return messages;
     }
-    async executeTurn(turnState, text, options) {
-        let activeTurnState = turnState;
+    async executeTurn(lease, turnState, text, options) {
         let messages = [createUserMessage(text, options?.images)];
         if (this.nextTurnQueue.length > 0) {
             const queuedMessages = this.nextTurnQueue.splice(0);
@@ -501,7 +440,7 @@ export class AgentHarness {
             }
             catch (error) {
                 this.nextTurnQueue.unshift(...queuedMessages);
-                throw normalizeHookError(error);
+                throw normalizeHarnessError(error, "hook");
             }
             messages = [...queuedMessages, messages[0]];
         }
@@ -514,125 +453,173 @@ export class AgentHarness {
         });
         if (beforeResult?.messages)
             messages = [...messages, ...beforeResult.messages];
-        const abortController = new AbortController();
-        const getTurnState = () => activeTurnState;
-        const setTurnState = (nextTurnState) => {
-            activeTurnState = nextTurnState;
-        };
-        this.runAbortController = abortController;
-        const completedMessages = [];
-        const runResultPromise = (async () => {
+        const result = await this.executeAgentRun(lease, "initial", turnState, this.createContext(turnState, beforeResult?.systemPrompt), messages);
+        return await this.recoverContextOverflow(lease, result);
+    }
+    /**
+     * Sole attempt boundary: begin, announce, run, classify, close, announce, flush.
+     *
+     * Once `beginAttempt()` succeeds the attempt is closed exactly once on every
+     * path, so `count(attempt_started) == count(attempt_finished)` holds even when
+     * the `attempt_started` observer throws. `attempt_finished` is emitted only
+     * after the attempt is already closed, so a throwing observer can fail the
+     * operation but can never reopen committed attempt state. The closing flush
+     * is not a `finally`: a `finally` that awaits a throwing flush would replace
+     * the body error, hiding the provider or listener failure from the audit trail.
+     */
+    async runAttempt(lease, reason, body, classify) {
+        const attemptLease = this.lifecycle.beginAttempt(lease, reason);
+        let result;
+        let bodyError;
+        try {
+            await this.emitOwn({ type: "attempt_started", attempt: attemptLease.attempt }, lease.signal);
+            result = await body(attemptLease);
+        }
+        catch (error) {
+            bodyError = error;
+        }
+        const outcome = bodyError === undefined ? classify(result) : classifyAttemptFailure(bodyError);
+        this.lifecycle.finishAttempt(lease, attemptLease, outcome);
+        let observerError;
+        try {
+            await this.emitOwn({ type: "attempt_finished", summary: this.lifecycle.getAttemptSummary(lease, attemptLease) }, lease.signal);
+        }
+        catch (error) {
+            observerError = error;
+        }
+        let flushError;
+        try {
+            await this.sessionWrites.flush();
+        }
+        catch (error) {
+            flushError = error;
+        }
+        const failure = combineBoundaryErrors([bodyError, observerError, flushError], "Attempt failed and its attempt_finished reporting or closing flush failed", "unknown");
+        if (failure !== undefined)
+            throw failure;
+        return result;
+    }
+    async executeAgentRun(lease, reason, turnState, context, initialMessages) {
+        let activeTurnState = turnState;
+        return await this.runAttempt(lease, reason, async (attemptLease) => {
+            const signal = attemptLease.signal;
+            const getTurnState = () => activeTurnState;
+            const setTurnState = (nextTurnState) => {
+                activeTurnState = nextTurnState;
+            };
+            const completedMessages = [];
+            const emit = async (event) => {
+                if (event.type === "message_end")
+                    completedMessages.push(event.message);
+                await this.handleAgentEvent(event, signal, lease);
+            };
+            let newMessages;
             try {
-                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState), async (event) => {
-                    if (event.type === "message_end")
-                        completedMessages.push(event.message);
-                    await this.handleAgentEvent(event, abortController.signal);
-                }, abortController.signal, this.createStreamFn(getTurnState));
+                const loopConfig = this.createLoopConfig(getTurnState, setTurnState, lease);
+                const streamFn = this.createStreamFn(getTurnState);
+                newMessages = initialMessages
+                    ? await runAgentLoop(initialMessages, context, loopConfig, emit, signal, streamFn)
+                    : await runAgentLoopContinue(context, loopConfig, emit, signal, streamFn);
             }
             catch (error) {
                 try {
-                    return await this.emitRunFailure(activeTurnState.model, error, abortController.signal.aborted, abortController.signal, completedMessages);
+                    newMessages = await this.emitRunFailure(activeTurnState.model, error, signal.aborted, signal, completedMessages, lease);
                 }
                 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") {
+                if (message.role === "assistant")
                     return message;
-                }
             }
             throw new AgentHarnessError("invalid_state", "AgentHarness prompt completed without an assistant message");
-        }
-        finally {
-            try {
-                await this.flushPendingSessionWrites();
-            }
-            finally {
-                // Ownership check: a re-entrant run started from a settled/agent_end
-                // listener may have installed its own controller already.
-                if (this.runAbortController === abortController) {
-                    this.runAbortController = undefined;
-                }
-            }
-        }
-    }
-    async prompt(text, options) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "AgentHarness is busy");
-        this.phase = "turn";
-        const { runPromise, finishRunPromise } = this.startRunPromise();
+        }, (message) => classifyAttemptOutcome(message, activeTurnState.model.contextWindow));
+    }
+    /**
+     * One-shot overflow recovery inside the originating operation. The lease is
+     * proof that this operation still owns the harness, so no run-ownership or
+     * phase re-check is needed; a strict lifecycle makes a newer operation
+     * starting mid-recovery impossible.
+     */
+    async recoverContextOverflow(lease, message) {
+        if (!this.compactionSettings.enabled || !isContextOverflow(message, this.model.contextWindow)) {
+            return message;
+        }
+        if (!this.getApiKeyAndHeaders)
+            return message;
+        const leafId = await this.session.getLeafId();
+        if (!leafId)
+            return message;
+        const leaf = await this.session.getEntry(leafId);
+        if (leaf?.type !== "message" ||
+            leaf.message.role !== "assistant" ||
+            leaf.message.timestamp !== message.timestamp ||
+            !isContextOverflow(leaf.message, this.model.contextWindow)) {
+            return message;
+        }
+        await this.session.moveTo(leaf.parentId);
+        this.lifecycle.setStage(lease, "recovering_overflow");
         try {
+            const compacted = await this.runCompaction({ automatic: true, signal: lease.signal });
+            if (!compacted) {
+                await this.session.moveTo(leafId);
+                return message;
+            }
             const turnState = await this.createTurnState();
-            return await this.executeTurn(turnState, text, options);
+            return await this.executeAgentRun(lease, "context_overflow_recovery", turnState, this.createContext(turnState));
         }
         catch (error) {
-            // Only reset the phase if this call still owns the run; a listener may
-            // have started the next run while this one was unwinding.
-            if (this.runPromise === runPromise)
-                this.phase = "idle";
-            throw normalizeHarnessError(error, "unknown");
-        }
-        finally {
-            finishRunPromise();
+            await this.session.moveTo(leafId);
+            throw error;
         }
     }
+    async prompt(text, options) {
+        return this.runOperation("prompt", "unknown", async (lease) => {
+            const turnState = await this.createTurnState();
+            return await this.executeTurn(lease, turnState, text, options);
+        }, classifyAssistantOutcome);
+    }
     async skill(name, additionalInstructions) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "AgentHarness is busy");
-        this.phase = "turn";
-        const { runPromise, finishRunPromise } = this.startRunPromise();
-        try {
+        return this.runOperation("skill", "unknown", async (lease) => {
             const turnState = await this.createTurnState();
             const skill = (turnState.resources.skills ?? []).find((candidate) => candidate.name === name);
             if (!skill)
                 throw new AgentHarnessError("invalid_argument", `Unknown skill: ${name}`);
-            return await this.executeTurn(turnState, formatSkillInvocation(skill, additionalInstructions));
-        }
-        catch (error) {
-            if (this.runPromise === runPromise)
-                this.phase = "idle";
-            throw normalizeHarnessError(error, "unknown");
-        }
-        finally {
-            finishRunPromise();
-        }
+            return await this.executeTurn(lease, turnState, formatSkillInvocation(skill, additionalInstructions));
+        }, classifyAssistantOutcome);
     }
     async promptFromTemplate(name, args = []) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "AgentHarness is busy");
-        this.phase = "turn";
-        const { runPromise, finishRunPromise } = this.startRunPromise();
-        try {
+        return this.runOperation("prompt_template", "unknown", async (lease) => {
             const turnState = await this.createTurnState();
             const template = (turnState.resources.promptTemplates ?? []).find((candidate) => candidate.name === name);
             if (!template)
                 throw new AgentHarnessError("invalid_argument", `Unknown prompt template: ${name}`);
-            return await this.executeTurn(turnState, formatPromptTemplateInvocation(template, args));
-        }
-        catch (error) {
-            if (this.runPromise === runPromise)
-                this.phase = "idle";
-            throw normalizeHarnessError(error, "unknown");
-        }
-        finally {
-            finishRunPromise();
+            return await this.executeTurn(lease, turnState, formatPromptTemplateInvocation(template, args));
+        }, classifyAssistantOutcome);
+    }
+    /**
+     * Steering and follow-up input is consumed only by a running agent attempt.
+     * A structural operation (`compact`, `navigateTree`) runs none, so accepting
+     * input there would silently inject it into an unrelated later prompt.
+     */
+    expectQueueConsumer(action) {
+        const snapshot = this.lifecycle.getSnapshot();
+        if (snapshot.tag !== "active")
+            throw new AgentHarnessError("invalid_state", `Cannot ${action} while idle`);
+        if (!PROMPT_FAMILY_KINDS.includes(snapshot.operation.kind)) {
+            throw new AgentHarnessError("invalid_state", `Cannot ${action} during ${snapshot.operation.kind}: no agent attempt can consume it`);
         }
     }
     async steer(text, options) {
-        if (this.phase === "idle")
-            throw new AgentHarnessError("invalid_state", "Cannot steer while idle");
+        this.expectQueueConsumer("steer");
         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.expectQueueConsumer("follow up");
         this.followUpQueue.push(createUserMessage(text, options?.images));
         await this.emitQueueUpdate();
     }
@@ -640,73 +627,89 @@ export class AgentHarness {
         this.nextTurnQueue.push(createUserMessage(text, options?.images));
         await this.emitQueueUpdate();
     }
+    getSession() {
+        return this.sessionFacade;
+    }
     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");
+        await this.sessionFacade.appendMessage(message);
+    }
+    async runCompaction(options) {
+        const model = this.model;
+        const auth = await this.getApiKeyAndHeaders?.(model);
+        if (!auth) {
+            if (options.automatic)
+                return undefined;
+            throw new AgentHarnessError("auth", "No auth available for compaction");
+        }
+        const branchEntries = await this.session.getBranch();
+        const preparationResult = prepareCompaction(branchEntries, this.compactionSettings);
+        if (!preparationResult.ok)
+            throw preparationResult.error;
+        const preparation = preparationResult.value;
+        if (!preparation) {
+            if (options.automatic)
+                return undefined;
+            throw new AgentHarnessError("compaction", "Nothing to compact");
+        }
+        const signal = options.signal ?? new AbortController().signal;
+        const hookResult = await this.emitHook({
+            type: "session_before_compact",
+            preparation,
+            branchEntries,
+            customInstructions: options.customInstructions,
+            signal,
+        });
+        if (hookResult?.cancel) {
+            if (options.automatic)
+                return undefined;
+            throw new AgentHarnessError("compaction", "Compaction cancelled");
+        }
+        const provided = hookResult?.compaction;
+        const compactResult = provided
+            ? { ok: true, value: provided }
+            : await compact(preparation, model, auth.apiKey, auth.headers, options.customInstructions, signal, this.thinkingLevel, createSummarizationRetry("compaction", this.streamOptions.summarizationRetry, (event) => this.emitOwn(event)));
+        if (!compactResult.ok)
+            throw compactResult.error;
+        const result = compactResult.value;
+        options.beforeCommit?.();
+        const entryId = await this.session.appendCompaction(result.summary, result.firstKeptEntryId, result.tokensBefore, result.details, provided !== undefined);
+        const entry = await this.session.getEntry(entryId);
+        if (entry?.type === "compaction") {
+            await this.emitOwn({ type: "session_compact", compactionEntry: entry, fromHook: provided !== undefined });
         }
+        return result;
+    }
+    async maybeAutoCompact(model, context, signal) {
+        const projected = estimateContextTokens(context.messages).tokens;
+        if (!shouldCompact(projected, model.contextWindow ?? 0, this.compactionSettings))
+            return context;
+        const result = await this.runCompaction({ automatic: true, signal });
+        if (!result)
+            return context;
+        const persisted = await this.session.buildContext();
+        return { ...context, messages: convertToLlm(persisted.messages) };
     }
     async compact(customInstructions) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "compact() requires idle harness");
-        this.phase = "compaction";
-        try {
-            const model = this.model;
-            if (!model)
-                throw new AgentHarnessError("invalid_state", "No model set for compaction");
-            const auth = await this.getApiKeyAndHeaders?.(model);
-            if (!auth)
-                throw new AgentHarnessError("auth", "No auth available for compaction");
-            const branchEntries = await this.session.getBranch();
-            const preparationResult = prepareCompaction(branchEntries, DEFAULT_COMPACTION_SETTINGS);
-            if (!preparationResult.ok)
-                throw preparationResult.error;
-            const preparation = preparationResult.value;
-            if (!preparation)
-                throw new AgentHarnessError("compaction", "Nothing to compact");
-            const hookResult = await this.emitHook({
-                type: "session_before_compact",
-                preparation,
-                branchEntries,
+        return this.runOperation("manual_compaction", "compaction", async (lease) => {
+            this.lifecycle.setStage(lease, "structural_running");
+            const result = await this.runCompaction({
+                automatic: false,
                 customInstructions,
-                signal: new AbortController().signal,
+                beforeCommit: () => {
+                    this.lifecycle.setStage(lease, "committing");
+                },
             });
-            if (hookResult?.cancel)
-                throw new AgentHarnessError("compaction", "Compaction cancelled");
-            const provided = hookResult?.compaction;
-            const compactResult = provided
-                ? { ok: true, value: provided }
-                : await compact(preparation, model, auth.apiKey, auth.headers, customInstructions, undefined, this.thinkingLevel);
-            if (!compactResult.ok)
-                throw compactResult.error;
-            const result = compactResult.value;
-            const entryId = await this.session.appendCompaction(result.summary, result.firstKeptEntryId, result.tokensBefore, result.details, provided !== undefined);
-            const entry = await this.session.getEntry(entryId);
-            if (entry?.type === "compaction") {
-                await this.emitOwn({ type: "session_compact", compactionEntry: entry, fromHook: provided !== undefined });
-            }
+            if (!result)
+                throw new AgentHarnessError("compaction", "Nothing to compact");
             return result;
-        }
-        catch (error) {
-            throw normalizeHarnessError(error, "compaction");
-        }
-        finally {
-            this.phase = "idle";
-        }
+        });
     }
     async navigateTree(targetId, options) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "navigateTree() requires idle harness");
-        this.phase = "branch_summary";
-        try {
+        return this.runOperation("tree_navigation", "branch_summary", async (lease) => {
+            this.lifecycle.setStage(lease, "structural_running");
             const oldLeafId = await this.session.getLeafId();
+            // No-op navigation mutates nothing, so it completes without ever
+            // entering the `committing` stage.
             if (oldLeafId === targetId)
                 return { cancelled: false };
             const targetEntry = await this.session.getEntry(targetId);
@@ -737,51 +740,24 @@ export class AgentHarness {
                 const auth = await this.getApiKeyAndHeaders?.(model);
                 if (!auth)
                     throw new AgentHarnessError("auth", "No auth available for branch summary");
-                const branchSummary = await generateBranchSummary(entries, {
+                const branchSummary = await runBranchSummary({
+                    entries,
                     model,
                     apiKey: auth.apiKey,
                     headers: auth.headers,
-                    signal: new AbortController().signal,
                     customInstructions: hookResult?.customInstructions ?? options?.customInstructions,
                     replaceInstructions: hookResult?.replaceInstructions ?? options?.replaceInstructions,
+                    summarizationRetry: this.streamOptions.summarizationRetry,
+                    emit: (event) => this.emitOwn(event),
                 });
-                if (!branchSummary.ok) {
-                    if (branchSummary.error.code === "aborted")
-                        return { cancelled: true };
-                    throw new AgentHarnessError("branch_summary", branchSummary.error.message, branchSummary.error);
-                }
-                summaryText = branchSummary.value.summary;
-                summaryDetails = {
-                    readFiles: branchSummary.value.readFiles,
-                    modifiedFiles: branchSummary.value.modifiedFiles,
-                };
-            }
-            let editorText;
-            let newLeafId;
-            if (targetEntry.type === "message" && targetEntry.message.role === "user") {
-                newLeafId = targetEntry.parentId;
-                const content = targetEntry.message.content;
-                editorText =
-                    typeof content === "string"
-                        ? content
-                        : content
-                            .filter((c) => c.type === "text")
-                            .map((c) => c.text)
-                            .join("");
-            }
-            else if (targetEntry.type === "custom_message") {
-                newLeafId = targetEntry.parentId;
-                editorText =
-                    typeof targetEntry.content === "string"
-                        ? targetEntry.content
-                        : targetEntry.content
-                            .filter((c) => c.type === "text")
-                            .map((c) => c.text)
-                            .join("");
-            }
-            else {
-                newLeafId = targetId;
-            }
+                if (branchSummary.cancelled)
+                    return { cancelled: true };
+                summaryText = branchSummary.summary;
+                summaryDetails = branchSummary.details;
+            }
+            const { newLeafId, editorText } = resolveNavigationTarget(targetEntry, targetId);
+            // Single declared commit point of a tree navigation.
+            this.lifecycle.setStage(lease, "committing");
             const summaryId = await this.session.moveTo(newLeafId, summaryText
                 ? { summary: summaryText, details: summaryDetails, fromHook: hookResult?.summary !== undefined }
                 : undefined);
@@ -798,13 +774,7 @@ export class AgentHarness {
                 fromHook: hookResult?.summary !== undefined,
             });
             return { cancelled: false, editorText, summaryEntry };
-        }
-        catch (error) {
-            throw normalizeHarnessError(error, "branch_summary");
-        }
-        finally {
-            this.phase = "idle";
-        }
+        }, classifyNavigateTreeOutcome);
     }
     getModel() {
         return this.model;
@@ -812,12 +782,9 @@ export class AgentHarness {
     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 });
-            }
+            const nextProvider = model.provider;
+            const nextModelId = model.id;
+            await this.persistConfigChange({ type: "model_change", provider: nextProvider, modelId: nextModelId });
             this.model = model;
             await this.emitOwn({ type: "model_update", model, previousModel, source: "set" });
         }
@@ -831,12 +798,7 @@ export class AgentHarness {
     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 });
-            }
+            await this.persistConfigChange({ type: "thinking_level_change", thinkingLevel: level });
             this.thinkingLevel = level;
             await this.emitOwn({ type: "thinking_level_update", level, previousLevel });
         }
@@ -855,12 +817,7 @@ export class AgentHarness {
             this.validateToolNames(nextActiveToolNames, nextTools);
             const previousToolNames = [...this.tools.keys()];
             const previousActiveToolNames = [...this.activeToolNames];
-            if (this.phase === "idle") {
-                await this.session.appendActiveToolsChange(nextActiveToolNames);
-            }
-            else {
-                this.pendingSessionWrites.push({ type: "active_tools_change", activeToolNames: [...nextActiveToolNames] });
-            }
+            await this.persistConfigChange({ type: "active_tools_change", activeToolNames: [...nextActiveToolNames] });
             this.tools = nextTools;
             this.activeToolNames = [...nextActiveToolNames];
             await this.emitOwn({
@@ -881,16 +838,12 @@ export class AgentHarness {
     }
     async setActiveTools(toolNames) {
         try {
-            this.validateToolNames(toolNames);
+            const nextActiveToolNames = [...toolNames];
+            this.validateToolNames(nextActiveToolNames);
             const previousToolNames = [...this.tools.keys()];
             const previousActiveToolNames = [...this.activeToolNames];
-            if (this.phase === "idle") {
-                await this.session.appendActiveToolsChange(toolNames);
-            }
-            else {
-                this.pendingSessionWrites.push({ type: "active_tools_change", activeToolNames: [...toolNames] });
-            }
-            this.activeToolNames = [...toolNames];
+            await this.persistConfigChange({ type: "active_tools_change", activeToolNames: [...nextActiveToolNames] });
+            this.activeToolNames = [...nextActiveToolNames];
             await this.emitOwn({
                 type: "tools_update",
                 toolNames: [...this.tools.keys()],
@@ -937,11 +890,21 @@ export class AgentHarness {
         this.streamOptions = cloneStreamOptions(streamOptions);
     }
     async abort() {
-        const clearedSteer = [...this.steerQueue];
-        const clearedFollowUp = [...this.followUpQueue];
-        this.steerQueue = [];
-        this.followUpQueue = [];
-        this.runAbortController?.abort();
+        // Aborting awaits the captured operation's settlement, so a listener of that
+        // same operation must never reach the wait below.
+        this.rejectCurrentOperationSelfWait("abort()");
+        const snapshot = this.lifecycle.getSnapshot();
+        if (snapshot.tag === "active" && snapshot.operation.kind === "manual_compaction") {
+            throw new AgentHarnessError("invalid_state", "Cannot abort during compaction");
+        }
+        if (snapshot.tag === "active" && snapshot.operation.kind === "tree_navigation") {
+            throw new AgentHarnessError("invalid_state", "Cannot abort during branch_summary");
+        }
+        // Capture the current operation before delivering any signal: an operation
+        // started later by a settlement listener is never this call's target.
+        const capture = this.lifecycle.requestAbort();
+        const clearedSteer = this.steerQueue.splice(0);
+        const clearedFollowUp = this.followUpQueue.splice(0);
         const errors = [];
         try {
             await this.emitQueueUpdate();
@@ -950,7 +913,8 @@ export class AgentHarness {
             errors.push(toError(error));
         }
         try {
-            await this.waitForIdle();
+            if (capture.target)
+                await capture.target.settled;
         }
         catch (error) {
             errors.push(toError(error));
@@ -968,20 +932,12 @@ export class AgentHarness {
         return { clearedSteer, clearedFollowUp };
     }
     async waitForIdle() {
-        // Runs can chain: a settled listener may start the next prompt() before the
-        // previous run's promise resolves, so keep waiting until no run is active.
-        while (this.runPromise) {
-            await this.runPromise;
-        }
+        this.rejectCurrentOperationSelfWait("waitForIdle()");
+        // Delegates to the lifecycle: resolves once no operation is active or settling.
+        await this.lifecycle.waitForIdle();
     }
     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);
+        return this.subscribers.subscribe(listener);
     }
     on(type, handler) {
         let handlers = this.handlers.get(type);