@vinhnt-sdk/core 0.1.1 → 0.1.3

package/dist/kernel/run-loop.js

@@ -1,9 +1,23 @@
-import { KernelError } from "./kernel-error.js";
-import { evaluateStopConditions } from "./termination.js";
-import { buildJudgeMessages, parseJudgeVerdict } from "./termination.js";
+import { getTextContent, COMPACTION_SUMMARY_PREFIX } from "@vinhnt-sdk/schema";
+import { KernelError } from "@vinhnt-sdk/step-executor";
+import { evaluateStopConditions, buildJudgeMessages, parseJudgeVerdict } from "@vinhnt-sdk/step-executor";
+/** Index of the head `system` message — the first one. All system instructions
+ * (identity, agent systemPrompt, context baseline/reconciled updates) must live
+ * in that single message so providers never see mid-conversation `system`
+ * messages (RV-40). */
+function headSystemIndex(messages) {
+    return messages.findIndex((m) => m.role === "system");
+}
 async function initializeSystemContext(systemContext, messages) {
     const sc = await systemContext.initialize();
     if (sc.baseline) {
+        const idx = headSystemIndex(messages);
+        if (idx >= 0) {
+            const updated = [...messages];
+            const head = updated[idx];
+            updated[idx] = { ...head, content: `${getTextContent(head.content)}\n\n${sc.baseline}` };
+            return { messages: updated, contextEpochActive: true, didChange: true };
+        }
         return { messages: [{ role: "system", content: sc.baseline }, ...messages], contextEpochActive: true, didChange: true };
     }
     return { messages, contextEpochActive: true, didChange: false };
@@ -11,13 +25,25 @@ async function initializeSystemContext(systemContext, messages) {
 async function reconcileSystemContext(systemContext, messages, step) {
     const result = await systemContext.reconcile();
     if (result.type === "updated" && result.update) {
+        // Merge the update into the head system message rather than appending a new
+        // mid-conversation `system` message that providers may reject or mis-handle.
+        const idx = headSystemIndex(messages);
+        if (idx >= 0) {
+            const updated = [...messages];
+            const head = updated[idx];
+            updated[idx] = { ...head, content: `${getTextContent(head.content)}\n\n${result.update}` };
+            return { messages: updated, contextEpochActive: true, didChange: true };
+        }
+        // No head system message (run without an agent) — keep the update rather than drop it.
         return { messages: [...messages, { role: "system", content: result.update }], contextEpochActive: true, didChange: true };
     }
     if (result.type === "replaced" && step > 0) {
-        const idx = messages.findIndex((m) => m.role === "system");
+        // Replaced: refresh the head system message content in place.
+        const idx = headSystemIndex(messages);
         const updated = [...messages];
         if (idx >= 0) {
-            updated[idx] = { role: "system", content: result.systemContext.baseline };
+            const head = updated[idx];
+            updated[idx] = { ...head, content: result.systemContext.baseline };
         }
         else {
             updated.unshift({ role: "system", content: result.systemContext.baseline });
@@ -26,12 +52,12 @@ async function reconcileSystemContext(systemContext, messages, step) {
     }
     return { messages, contextEpochActive: true, didChange: false };
 }
-async function maybeCompact(messages, runModel, deps, signal, emitEvent) {
+async function maybeCompact(messages, runModel, deps, signal, sessionId, emitEvent) {
     if (!deps.compactor)
         return { messages, didCompact: false };
     let shouldCompact = true;
     if (runModel.countTokens) {
-        const estimatedInput = messages.reduce((sum, m) => sum + runModel.countTokens(m.content), 0);
+        const estimatedInput = messages.reduce((sum, m) => sum + runModel.countTokens(getTextContent(m.content)), 0);
         const contextWindow = runModel.contextLimit ?? deps.maxTokens * 4;
         const ratio = deps.compactionThreshold ?? 0.75;
         const threshold = Math.floor(contextWindow * ratio);
@@ -49,14 +75,46 @@ async function maybeCompact(messages, runModel, deps, signal, emitEvent) {
             originalCount: compacted.summary.originalMessageCount,
             compressedCount: compacted.summary.compressedMessageCount,
         });
+        // RV-15 durable compaction: persist the summary as a durable marker so that
+        // a restart / resume rebuilds the compacted context instead of the raw
+        // transcript. Best-effort — a store failure must NOT roll back the run or
+        // the compaction (the in-memory compacted context still applies).
+        if (sessionId) {
+            const summaryText = compacted.summary.summary
+                ? `${COMPACTION_SUMMARY_PREFIX}${compacted.summary.summary}`
+                : `${COMPACTION_SUMMARY_PREFIX}Compressed ${compacted.summary.originalMessageCount} → ${compacted.summary.compressedMessageCount} messages`;
+            try {
+                await deps.addSessionMessage(sessionId, "system", summaryText);
+            }
+            catch (err) {
+                if (typeof console !== "undefined") {
+                    console.warn("[run-loop] Failed to persist compaction summary:", err instanceof Error ? err.message : String(err));
+                }
+            }
+        }
         return { messages: [...compacted.messages], didCompact: true };
     }
     return { messages, didCompact: false };
 }
-async function compactOnOverflow(messages, compactor, step, signal) {
+async function compactOnOverflow(messages, compactor, step, signal, sessionId, addSessionMessage) {
     if (step <= 0)
         throw new Error("Cannot compact on step 0 — context overflow should not occur on first step");
     const compacted = await compactor.compact(messages, signal);
+    // RV-15: overflow compaction is also durable — persist a summary marker so a
+    // restart rebuilds the compacted context. Best-effort, never rolls back.
+    if (compacted.summary.compressedMessageCount < compacted.summary.originalMessageCount && sessionId) {
+        const summaryText = compacted.summary.summary
+            ? `${COMPACTION_SUMMARY_PREFIX}${compacted.summary.summary}`
+            : `${COMPACTION_SUMMARY_PREFIX}Compressed ${compacted.summary.originalMessageCount} → ${compacted.summary.compressedMessageCount} messages`;
+        try {
+            await addSessionMessage(sessionId, "system", summaryText);
+        }
+        catch (err) {
+            if (typeof console !== "undefined") {
+                console.warn("[run-loop] Failed to persist overflow compaction summary:", err instanceof Error ? err.message : String(err));
+            }
+        }
+    }
     return [...compacted.messages];
 }
 function isContextOverflowError(msg) {
@@ -72,15 +130,10 @@ async function processStep(deps, input) {
     runAbort.signal.addEventListener("abort", onRunAbort, { once: true });
     try {
         if (runAbort.signal.aborted) {
-            return {
-                ...input, completed: true, toolCallCount: 0,
-                messages: input.messages,
-                step: input.step,
-                lastStepToolOutcomes: [],
-            };
-        }
-        if (!deps.permissionGate.checkMaxSteps(input.step, deps.currentAgent)) {
-            throw new KernelError("max_steps_exceeded", `Agent max steps exceeded (${input.step})`);
+            // RV-7: an abort landing between the loop guard and the step start must
+            // not silently report `succeeded` — surface it so the run-loop catch can
+            // converge on the single `cancelled` terminal outcome.
+            throw new DOMException("Run cancelled", "AbortError");
         }
         if (!deps.permissionGate.checkMaxTokens(input.totalInputTokens, input.totalOutputTokens, deps.currentAgent)) {
             throw new KernelError("max_tokens_exceeded", `Agent max tokens exceeded (${input.totalInputTokens + input.totalOutputTokens})`);
@@ -89,14 +142,26 @@ async function processStep(deps, input) {
         if (deps.thinkingBudget > 0) {
             await deps.modelCaller.doThinkingStep(messages, input.step, runId, ctx, stepTimeoutController.signal);
         }
-        if (runModel.countTokens) {
-            input.totalInputTokens += messages.reduce((sum, m) => sum + runModel.countTokens(m.content), 0);
-        }
         let response;
         try {
-            response = await deps.circuitBreaker.call(() => deps.modelCaller.callModelStream(messages, input.step, runId, ctx, stepTimeoutController.signal, deps.currentAgent?.permissions?.maxTokens, input.disableTools));
+            response = await deps.circuitBreaker.call(() => deps.modelCaller.callModelStream(messages, input.step, runId, ctx, stepTimeoutController.signal, deps.currentAgent?.permissions?.maxTokens, input.disableTools), stepTimeoutController.signal);
         }
         catch (err) {
+            if (stepTimeoutController.signal.aborted && !runAbort.signal.aborted) {
+                // Step-level timeout: the step fails but the run continues to the next step.
+                return {
+                    messages,
+                    step: input.step,
+                    runId,
+                    totalInputTokens: input.totalInputTokens,
+                    totalOutputTokens: input.totalOutputTokens,
+                    finalOutput: input.finalOutput,
+                    completed: false,
+                    toolCallCount: 0,
+                    lastStepToolOutcomes: [],
+                    stepFailed: { reason: "timeout", error: `Model call timed out after ${deps.stepTimeout}ms` },
+                };
+            }
             const circuitErr = err;
             if (circuitErr?.constructor?.name === "CircuitBreakerOpenError") {
                 throw new KernelError("model_unavailable", err.message, err);
@@ -104,15 +169,28 @@ async function processStep(deps, input) {
             const errMsg = err instanceof Error ? err.message : String(err);
             if (isContextOverflowError(errMsg) && deps.compactor && input.step > 0) {
                 const compactor = deps.compactor;
-                messages = await compactOnOverflow(messages, compactor, input.step, stepTimeoutController.signal);
+                messages = await compactOnOverflow(messages, compactor, input.step, stepTimeoutController.signal, sessionId, deps.addSessionMessage);
                 runSessionState?.resetMessages(messages);
-                response = await deps.circuitBreaker.call(() => deps.modelCaller.callModelStream(messages, input.step, runId, ctx, stepTimeoutController.signal, deps.currentAgent?.permissions?.maxTokens));
+                response = await deps.circuitBreaker.call(() => deps.modelCaller.callModelStream(messages, input.step, runId, ctx, stepTimeoutController.signal, deps.currentAgent?.permissions?.maxTokens), stepTimeoutController.signal);
             }
             else {
                 throw err;
             }
         }
-        if (runModel.countTokens) {
+        // RV-42: single authoritative token accounting — prefer the provider's usage
+        // (now surfaced on ModelResponse), fall back to local countTokens.
+        const usageIn = response.usage?.promptTokens;
+        const usageOut = response.usage?.completionTokens;
+        if (usageIn !== undefined && usageIn > 0) {
+            input.totalInputTokens += usageIn;
+        }
+        else if (runModel.countTokens) {
+            input.totalInputTokens += messages.reduce((sum, m) => sum + runModel.countTokens(getTextContent(m.content)), 0);
+        }
+        if (usageOut !== undefined && usageOut > 0) {
+            input.totalOutputTokens += usageOut;
+        }
+        else if (runModel.countTokens) {
             input.totalOutputTokens += runModel.countTokens(response.content);
         }
         const toolCalls = response.toolCalls ?? [];
@@ -149,6 +227,27 @@ async function processStep(deps, input) {
             };
         }
         const { toolCallCount, selfCorrectTokens, toolResults } = await deps.stepExecutor.executeToolCalls(toolCalls.map((tc) => ({ toolId: tc.id, toolName: tc.name, args: tc.args })), messages, input.step, runId, ctx, stepTimeoutController, sessionId, runModel);
+        if (stepTimeoutController.signal.aborted && !runAbort.signal.aborted) {
+            // Step timed out during tool execution — surface an error for any tool call
+            // that never got a response so the conversation stays coherent for the model.
+            for (const tc of toolCalls) {
+                if (!messages.some((m) => m.role === "tool" && m.toolCallId === tc.id)) {
+                    messages.push({ role: "tool", toolCallId: tc.id, content: `Error: Step timed out after ${deps.stepTimeout}ms` });
+                }
+            }
+            return {
+                messages,
+                step: input.step,
+                runId,
+                totalInputTokens: input.totalInputTokens,
+                totalOutputTokens: input.totalOutputTokens,
+                finalOutput: input.finalOutput,
+                completed: false,
+                toolCallCount,
+                lastStepToolOutcomes: toolResults,
+                stepFailed: { reason: "timeout", error: `Tool execution timed out after ${deps.stepTimeout}ms` },
+            };
+        }
         // Accumulate self-correction tokens into run totals
         input.totalInputTokens += selfCorrectTokens.input;
         input.totalOutputTokens += selfCorrectTokens.output;
@@ -156,19 +255,23 @@ async function processStep(deps, input) {
             runSessionState.step = input.step + 1;
             runSessionState.toolCallCount += toolCallCount;
         }
-        // Snapshot run state
-        deps.store.saveSnapshot(runId, {
-            step: input.step + 1,
-            model: runModel.model,
-            totalInputTokens: input.totalInputTokens,
-            totalOutputTokens: input.totalOutputTokens,
-            finalOutput: input.finalOutput,
-            sessionId,
-        }).catch((err) => {
+        // Snapshot run state — awaited so a write failure is observed before the
+        // step is reported complete, preventing silent state loss (RV-33).
+        try {
+            await deps.store.saveSnapshot(runId, {
+                step: input.step + 1,
+                model: runModel.model,
+                totalInputTokens: input.totalInputTokens,
+                totalOutputTokens: input.totalOutputTokens,
+                finalOutput: input.finalOutput,
+                sessionId,
+            });
+        }
+        catch (err) {
             if (typeof console !== "undefined") {
                 console.warn("[run-loop] Failed to save snapshot:", err instanceof Error ? err.message : String(err));
             }
-        });
+        }
         return {
             messages,
             step: input.step,
@@ -190,7 +293,7 @@ async function processStep(deps, input) {
 // Run loop
 // ---------------------------------------------------------------------------
 export async function runLoop(deps, input) {
-    const { prompt, runId, ctx, runAbort, sessionId, userContentParts, runModel, runSessionState, addSessionMessage, emitEvent, setState, updateSessionOnComplete, emitFail } = input;
+    const { prompt, runId, ctx, runAbort, sessionId, userContentParts, runModel, runSessionState, addSessionMessage, emitEvent, setState, emitCompleted, emitFail } = input;
     const startTime = Date.now();
     let totalInputTokens = 0;
     let totalOutputTokens = 0;
@@ -198,53 +301,123 @@ export async function runLoop(deps, input) {
     let step = 0;
     let finalOutput = "";
     let contextEpochActive = false;
-    const effectiveMaxSteps = deps.termination?.maxSteps ?? deps.maxSteps;
+    // Real system head (identity + agent systemPrompt) sent as a proper `system`
+    // message at the head of the conversation instead of being flattened into the
+    // user turn (RV-40).
+    const systemHead = input.systemPrompt
+        ? [{ role: "system", content: input.systemPrompt }]
+        : [];
+    // Single max-steps authority: resolve the run's step budget from every
+    // applicable source (config default, termination policy, agent permission)
+    // once, then enforce it in exactly one place — the loop bound below.
+    const runMaxSteps = Math.min(deps.termination?.maxSteps ?? Number.POSITIVE_INFINITY, deps.currentAgent?.permissions?.maxSteps ?? Number.POSITIVE_INFINITY, deps.maxSteps);
     const emitEvt = (type, data) => emitEvent({
         id: crypto.randomUUID(), runId, type,
         occurredAt: new Date().toISOString(), traceId: ctx.traceId,
         data,
     });
+    const saveFinalSnapshot = async (status) => {
+        try {
+            await deps.store.saveSnapshot(runId, {
+                step: step + 1,
+                model: runModel.model,
+                totalInputTokens,
+                totalOutputTokens,
+                finalOutput,
+                sessionId,
+                status,
+            });
+        }
+        catch (err) {
+            if (typeof console !== "undefined") {
+                console.warn("[run-loop] Failed to save final snapshot:", err instanceof Error ? err.message : String(err));
+            }
+        }
+    };
+    // RV-7: exactly ONE terminal cancelled outcome regardless of abort timing.
+    // Every cancellation path funnels through this single block (loop guard,
+    // step-start abort, in-flight AbortError, and terminal-emission guards), so a
+    // run cancelled at any moment reports `cancelled` exactly once — never a
+    // silent `succeeded` or a confusing `failed`.
+    const cancelRun = async (steps) => {
+        await emitFail(runId, ctx, "Run cancelled", steps, sessionId, totalInputTokens, totalOutputTokens, Date.now() - startTime, true);
+        await deps.saga.rollbackAll();
+        setState(runId, "cancelled");
+        if (runSessionState)
+            runSessionState.isRunning = false;
+        await saveFinalSnapshot("cancelled");
+        return { totalSteps: steps, status: "cancelled" };
+    };
     try {
         setState(runId, "running");
+        // Re-queue any persisted-but-un-promoted inputs before the first step drains (RV-21).
+        if (deps.beforeRun) {
+            await deps.beforeRun(runId);
+        }
         const startedModel = runModel.model;
         const startedAgentName = deps.currentAgent?.profile.name;
         const startedAgentId = deps.currentAgent?.id;
         // Skip run.started event when resuming from durable storage
         if (!input.resume) {
+            // Audit + session record keep the full effective prompt (system head +
+            // user prompt); the messages sent to the model split them into a real
+            // `system` head + `user` turn (RV-40).
+            const effectivePrompt = [input.systemPrompt, prompt].filter(Boolean).join("\n\n");
             await emitEvt("run.started", {
-                prompt,
+                prompt: effectivePrompt,
                 ...(startedModel ? { model: startedModel } : {}),
                 ...(startedAgentName ? { agentName: startedAgentName } : {}),
                 ...(startedAgentId ? { agentId: startedAgentId } : {}),
             });
             await deps.pluginManager?.fireHook("onRunStarted", { runId, prompt });
             const currentModel = runModel.model;
-            await addSessionMessage(sessionId, "user", prompt, { ...(currentModel ? { model: currentModel } : {}) });
+            await addSessionMessage(sessionId, "user", effectivePrompt, { ...(currentModel ? { model: currentModel } : {}) });
             messages = [
+                ...systemHead,
                 userContentParts?.length
-                    ? { role: "user", content: prompt, contentParts: userContentParts }
+                    ? { role: "user", content: userContentParts }
                     : { role: "user", content: prompt },
             ];
         }
-        // When resuming, messages already contain the full conversation history
-        if (input.resume && runSessionState && runSessionState.messages.length > 0) {
-            messages = [...runSessionState.messages];
+        // On resume, rebuild from persisted history (never double-append it) and keep
+        // the current steering prompt as the latest user turn. On a continuation run
+        // the conversation history must come BEFORE the fresh prompt so the
+        // transcript stays chronologically ordered (the prompt was seeded above).
+        if (input.resume) {
+            if (runSessionState && runSessionState.messages.length > 0) {
+                messages = [...runSessionState.messages];
+            }
+            if (prompt)
+                messages.push({ role: "user", content: prompt });
+            // Persisted history predates the RV-40 system head — re-inject it so a
+            // resumed run still sends a real `system` message to the model.
+            if (systemHead.length > 0 && !messages.some((m) => m.role === "system")) {
+                messages = [...systemHead, ...messages];
+            }
         }
-        if (runSessionState && runSessionState.messages.length > 0) {
-            messages.push(...runSessionState.messages);
+        else if (runSessionState && runSessionState.messages.length > 0) {
+            messages = [
+                ...systemHead,
+                ...runSessionState.messages,
+                userContentParts?.length
+                    ? { role: "user", content: userContentParts }
+                    : { role: "user", content: prompt },
+            ];
         }
-        step = runSessionState?.step ?? 0;
-        for (step = 0; step < effectiveMaxSteps; step++) {
+        // Continue from the restored step counter so max-steps accounting and any
+        // step-relative logic stay continuous across a resume.
+        const startedStep = runSessionState?.step ?? 0;
+        for (step = startedStep; step < runMaxSteps; step++) {
             if (runAbort.signal.aborted) {
-                await emitFail(runId, ctx, "Run cancelled", step, sessionId, totalInputTokens, totalOutputTokens);
-                await deps.saga.rollbackAll();
-                setState(runId, "cancelled");
-                return;
+                return cancelRun(step);
             }
             const drainedInputs = deps.stateMachine.drainInputs(runId);
             for (const text of drainedInputs) {
                 messages.push({ role: "user", content: text });
             }
+            if (drainedInputs.length > 0 && deps.onInputsDrained) {
+                await deps.onInputsDrained(runId, drainedInputs);
+            }
             if (deps.systemContext) {
                 if (!contextEpochActive) {
                     const result = await initializeSystemContext(deps.systemContext, messages);
@@ -262,7 +435,7 @@ export async function runLoop(deps, input) {
             const compactResult = await maybeCompact(messages, {
                 ...(runModel.countTokens ? { countTokens: runModel.countTokens } : {}),
                 ...(runModel.contextLimit !== undefined ? { contextLimit: runModel.contextLimit } : {}),
-            }, deps, runAbort.signal, (type, data) => emitEvt(type, data));
+            }, deps, runAbort.signal, sessionId, (type, data) => emitEvt(type, data));
             if (compactResult.didCompact) {
                 messages = compactResult.messages;
                 runSessionState?.resetMessages(compactResult.messages);
@@ -270,13 +443,13 @@ export async function runLoop(deps, input) {
                     contextEpochActive = false;
                 }
             }
-            if (step >= effectiveMaxSteps - 1) {
+            if (step >= runMaxSteps - 1) {
                 messages.push({
                     role: "system",
-                    content: `[You have reached the maximum number of steps (${effectiveMaxSteps}). This is your final opportunity to respond. Do NOT call any tools. Provide a comprehensive summary and any final output.]`,
+                    content: `[You have reached the maximum number of steps (${runMaxSteps}). This is your final opportunity to respond. Do NOT call any tools. Provide a comprehensive summary and any final output.]`,
                 });
             }
-            const onLastStep = step >= effectiveMaxSteps - 1;
+            const onLastStep = step >= runMaxSteps - 1;
             const stepResult = await processStep(deps, {
                 messages, step, runId, ctx, runAbort,
                 ...(sessionId !== undefined ? { sessionId } : {}),
@@ -289,8 +462,14 @@ export async function runLoop(deps, input) {
             totalInputTokens = stepResult.totalInputTokens;
             totalOutputTokens = stepResult.totalOutputTokens;
             finalOutput = stepResult.finalOutput;
-            await emitEvt("step.completed", { step, toolCallCount: stepResult.toolCallCount });
-            await deps.pluginManager?.fireHook("onStepCompleted", { step, toolCallCount: stepResult.toolCallCount });
+            if (stepResult.stepFailed) {
+                await emitEvt("step.failed", { step, reason: stepResult.stepFailed.reason, ...(stepResult.stepFailed.error ? { error: stepResult.stepFailed.error } : {}) });
+                await deps.pluginManager?.fireHook("onStepFailed", { step, reason: stepResult.stepFailed.reason, ...(stepResult.stepFailed.error ? { error: stepResult.stepFailed.error } : {}) });
+            }
+            else {
+                await emitEvt("step.completed", { step, toolCallCount: stepResult.toolCallCount });
+                await deps.pluginManager?.fireHook("onStepCompleted", { step, toolCallCount: stepResult.toolCallCount });
+            }
             if (stepResult.completed) {
                 finalOutput = stepResult.finalOutput;
                 break;
@@ -305,11 +484,13 @@ export async function runLoop(deps, input) {
                         (budget.output !== undefined && totalOutputTokens > budget.output) ||
                         (budget.total !== undefined && total > budget.total);
                     if (over) {
+                        if (runAbort.signal.aborted)
+                            return cancelRun(step + 1);
                         const reason = `Token budget exceeded (${total} tokens)`;
                         await emitFail(runId, ctx, reason, step, sessionId, totalInputTokens, totalOutputTokens);
                         await deps.saga.rollbackAll();
                         setState(runId, "failed");
-                        return;
+                        return { totalSteps: step + 1, status: "failed" };
                     }
                 }
                 const stopCtx = {
@@ -349,13 +530,19 @@ export async function runLoop(deps, input) {
                     }
                 }
                 if (stopReason) {
-                    await emitEvt("run.completed", {
-                        status: "succeeded", output: finalOutput, totalSteps: step + 1,
-                        durationMs: Date.now() - startTime,
-                        stopCondition: stopReason,
-                        ...(totalInputTokens > 0 ? { inputTokens: totalInputTokens } : {}),
-                        ...(totalOutputTokens > 0 ? { outputTokens: totalOutputTokens } : {}),
-                    });
+                    if (runAbort.signal.aborted)
+                        return cancelRun(step + 1);
+                    await emitCompleted({
+                        id: crypto.randomUUID(), runId, type: "run.completed",
+                        occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+                        data: {
+                            status: "succeeded", output: finalOutput, totalSteps: step + 1,
+                            durationMs: Date.now() - startTime,
+                            stopCondition: stopReason,
+                            ...(totalInputTokens > 0 ? { inputTokens: totalInputTokens } : {}),
+                            ...(totalOutputTokens > 0 ? { outputTokens: totalOutputTokens } : {}),
+                        },
+                    }, sessionId, runId, totalInputTokens, totalOutputTokens, "succeeded");
                     await deps.pluginManager?.fireHook("onRunCompleted", { status: "succeeded", output: finalOutput, stopCondition: stopReason });
                     setState(runId, "completed");
                     if (runSessionState) {
@@ -363,20 +550,26 @@ export async function runLoop(deps, input) {
                         runSessionState.step = step + 1;
                         runSessionState.isRunning = false;
                     }
-                    await updateSessionOnComplete(sessionId, runId, totalInputTokens, totalOutputTokens, step + 1, "succeeded");
-                    return;
+                    await saveFinalSnapshot("succeeded");
+                    return { totalSteps: step + 1, status: "succeeded" };
                 }
             }
         }
         const durationMs = Date.now() - startTime;
-        if (step >= effectiveMaxSteps) {
+        if (step >= runMaxSteps) {
+            if (runAbort.signal.aborted)
+                return cancelRun(step + 1);
             if (finalOutput) {
-                await emitEvt("run.completed", {
-                    status: "succeeded", output: finalOutput, totalSteps: step + 1,
-                    durationMs,
-                    ...(totalInputTokens > 0 ? { inputTokens: totalInputTokens } : {}),
-                    ...(totalOutputTokens > 0 ? { outputTokens: totalOutputTokens } : {}),
-                });
+                await emitCompleted({
+                    id: crypto.randomUUID(), runId, type: "run.completed",
+                    occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+                    data: {
+                        status: "succeeded", output: finalOutput, totalSteps: step + 1,
+                        durationMs,
+                        ...(totalInputTokens > 0 ? { inputTokens: totalInputTokens } : {}),
+                        ...(totalOutputTokens > 0 ? { outputTokens: totalOutputTokens } : {}),
+                    },
+                }, sessionId, runId, totalInputTokens, totalOutputTokens, "succeeded");
                 await deps.pluginManager?.fireHook("onRunCompleted", { status: "succeeded", output: finalOutput });
                 if (deps.sessionStore && deps.sessionTitleGenerator && sessionId) {
                     const session = await deps.sessionStore.getSession(sessionId).catch(() => null);
@@ -391,24 +584,30 @@ export async function runLoop(deps, input) {
                         }
                     }
                 }
-                if (sessionId) {
-                    await updateSessionOnComplete(sessionId, runId, totalInputTokens, totalOutputTokens, step + 1, "succeeded");
-                }
                 setState(runId, "completed");
-                return;
+                await saveFinalSnapshot("succeeded");
+                return { totalSteps: step + 1, status: "succeeded" };
             }
-            await emitFail(runId, ctx, `Exceeded max steps (${effectiveMaxSteps})`, step, sessionId, totalInputTokens, totalOutputTokens, durationMs);
+            if (runAbort.signal.aborted)
+                return cancelRun(step + 1);
+            await emitFail(runId, ctx, `Exceeded max steps (${runMaxSteps})`, step, sessionId, totalInputTokens, totalOutputTokens, durationMs);
             await deps.saga.rollbackAll();
             setState(runId, "failed");
-            return;
+            return { totalSteps: step, status: "failed" };
         }
         else {
-            await emitEvt("run.completed", {
-                status: "succeeded", output: finalOutput, totalSteps: step + 1,
-                durationMs,
-                ...(totalInputTokens > 0 ? { inputTokens: totalInputTokens } : {}),
-                ...(totalOutputTokens > 0 ? { outputTokens: totalOutputTokens } : {}),
-            });
+            if (runAbort.signal.aborted)
+                return cancelRun(step + 1);
+            await emitCompleted({
+                id: crypto.randomUUID(), runId, type: "run.completed",
+                occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+                data: {
+                    status: "succeeded", output: finalOutput, totalSteps: step + 1,
+                    durationMs,
+                    ...(totalInputTokens > 0 ? { inputTokens: totalInputTokens } : {}),
+                    ...(totalOutputTokens > 0 ? { outputTokens: totalOutputTokens } : {}),
+                },
+            }, sessionId, runId, totalInputTokens, totalOutputTokens, "succeeded");
             await deps.pluginManager?.fireHook("onRunCompleted", { status: "succeeded", output: finalOutput });
             if (deps.sessionStore && deps.sessionTitleGenerator && sessionId) {
                 const session = await deps.sessionStore.getSession(sessionId).catch(() => null);
@@ -430,16 +629,25 @@ export async function runLoop(deps, input) {
             runSessionState.step = step + 1;
             runSessionState.isRunning = false;
         }
-        await updateSessionOnComplete(sessionId, runId, totalInputTokens, totalOutputTokens, step + 1, "succeeded");
+        await saveFinalSnapshot("succeeded");
+        return { totalSteps: step + 1, status: "succeeded" };
     }
     catch (err) {
+        // A cancellation that surfaced as an abort (e.g. the model call rejecting
+        // with AbortError, or the step-start guard) must converge on the single
+        // `cancelled` terminal outcome — never a confusing `failed`.
+        if (runAbort.signal.aborted) {
+            return cancelRun(step + 1);
+        }
         const errorMsg = err instanceof Error ? err.message : String(err);
         const failDurationMs = Date.now() - startTime;
-        // emitFail already emits run.completed(failed) and calls saga.rollbackAll()
+        // emitFail already emits run.completed(failed); roll back the per-run saga explicitly.
+        await deps.saga.rollbackAll();
         await emitFail(runId, ctx, errorMsg, step, sessionId, totalInputTokens, totalOutputTokens, failDurationMs);
         setState(runId, "failed");
         if (runSessionState)
             runSessionState.isRunning = false;
+        return { totalSteps: step + 1, status: "failed" };
     }
     finally {
         deps.saga.clear();