@vinhnt-sdk/core 0.1.1 → 0.1.3

package/dist/kernel/kernel.js

@@ -1,20 +1,26 @@
+import { ValidationError, AgentNotFoundError } from "@vinhnt-sdk/schema";
+import { restoreRunFromStore, findActiveSessionIds } from "@vinhnt-sdk/session";
+import { createRedactingLogger } from "@vinhnt-sdk/security";
 import { wildcardMatch } from "@vinhnt-sdk/schema";
 import { getBehaviourProfile } from "../agent/behaviour-profiles.js";
-import { DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_CALLS_PER_STEP, DOOM_LOOP_THRESHOLD } from "./kernel-utils.js";
-import { RunStateMachine } from "./run-state.js";
-import { PermissionGate } from "./permission-gate.js";
-import { ModelCaller } from "./model-caller.js";
-import { StepExecutor } from "./step-executor.js";
-import { ToolSaga } from "./tool-saga.js";
-import { CircuitBreaker } from "./circuit-breaker.js";
-import { KernelError } from "./kernel-error.js";
+import { DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_CALLS_PER_STEP, DOOM_LOOP_THRESHOLD } from "@vinhnt-sdk/step-executor";
+/** Default thinking prompt for reasoning steps. Exported for user override. */
+export const DEFAULT_THINKING_PROMPT = "Analyze the user's request and the conversation context. Think step by step about what needs to be done. Output your reasoning.";
+import { RunStateMachine } from "@vinhnt-sdk/step-executor";
+import { PermissionGate } from "@vinhnt-sdk/step-executor";
+import { ModelCaller } from "@vinhnt-sdk/llm";
+import { StepExecutor } from "@vinhnt-sdk/step-executor";
+import { ToolSaga } from "@vinhnt-sdk/tools";
+import { createRunContext } from "@vinhnt-sdk/step-executor";
+import { CircuitBreaker } from "@vinhnt-sdk/step-executor";
+import { KernelError } from "@vinhnt-sdk/step-executor";
 import { runLoop as executeRunLoop } from "./run-loop.js";
 import { LifecycleManager } from "./lifecycle-manager.js";
-import { emitEvent as sessionEmit, addSessionMessage as sessionAddMessage, updateSessionOnComplete as sessionUpdateComplete, emitFail as sessionEmitFail, buildAgentIdentity, } from "./kernel-session.js";
+import { emitEvent as sessionEmit, addSessionMessage as sessionAddMessage, emitCompletedWithSession as sessionEmitCompleted, emitFail as sessionEmitFail, buildAgentIdentity, } from "./kernel-session.js";
 import { runAgent as runSubAgent, runAgentsParallel as runSubAgentsParallel, createSubAgentAndRegister, } from "./sub-agent-runner.js";
 import { normalizeConfig } from "./kernel-types.js";
-export { CircuitBreaker, CircuitBreakerOpenError } from "./circuit-breaker.js";
-export { KernelError } from "./kernel-error.js";
+export { CircuitBreaker, CircuitBreakerOpenError } from "@vinhnt-sdk/step-executor";
+export { KernelError } from "@vinhnt-sdk/step-executor";
 /**
  * Core agent orchestration — run loop, permission gate, tool execution, sub-agent spawning.
  * Composition root for all run-time services. Each call to `run()` creates a tracked
@@ -45,6 +51,7 @@ export class AgentKernel {
     toolProviderRegistry;
     sessionTitleGenerator;
     saga;
+    runSagas = new Map();
     stepExecutor;
     currentAgent;
     currentDepth = 0;
@@ -59,27 +66,37 @@ export class AgentKernel {
     sessionDeps;
     subAgentDeps;
     runSessionStates = new Map();
+    /** runId → sessionId for pending-input persistence (RV-21). */
+    runSessionIds = new Map();
+    /** FIFO mirror of the state-machine input queue, used to mark promotion (RV-21). */
+    runPendingEntries = new Map();
+    /** Per-session monotonic admitted-seq allocator, seeded from the store lazily (RV-21). */
+    nextAdmittedSeq = new Map();
+    /** Per-session serialized write chain so admitted seqs stay FIFO-consistent (RV-21). */
+    inputWriteChains = new Map();
+    /** Per-run execution context — keeps parallel runs' agent/depth/chain/tools isolated. */
+    runContexts = new Map();
     lifecycleManager;
     constructor(config) {
         const normalized = normalizeConfig(config);
         // Validate config values
         if (normalized.maxSteps !== undefined && normalized.maxSteps < 1) {
-            throw new Error("maxSteps must be >= 1");
+            throw new ValidationError("maxSteps must be >= 1");
         }
         if (normalized.maxTokens !== undefined && normalized.maxTokens < 1) {
-            throw new Error("maxTokens must be >= 1");
+            throw new ValidationError("maxTokens must be >= 1");
         }
         if (normalized.stepTimeout !== undefined && normalized.stepTimeout < 1000) {
-            throw new Error("stepTimeout must be >= 1000ms");
+            throw new ValidationError("stepTimeout must be >= 1000ms");
         }
         if (normalized.maxToolCallsPerStep !== undefined && normalized.maxToolCallsPerStep < 1) {
-            throw new Error("maxToolCallsPerStep must be >= 1");
+            throw new ValidationError("maxToolCallsPerStep must be >= 1");
         }
         if (normalized.doomLoopThreshold !== undefined && normalized.doomLoopThreshold < 1) {
-            throw new Error("doomLoopThreshold must be >= 1");
+            throw new ValidationError("doomLoopThreshold must be >= 1");
         }
         if (normalized.compactionThreshold !== undefined && (normalized.compactionThreshold < 0 || normalized.compactionThreshold > 1)) {
-            throw new Error("compactionThreshold must be between 0 and 1");
+            throw new ValidationError("compactionThreshold must be between 0 and 1");
         }
         this.store = normalized.store;
         this.maxSteps = normalized.maxSteps ?? DEFAULT_MAX_STEPS;
@@ -102,15 +119,36 @@ export class AgentKernel {
         this.doomLoopThreshold = normalized.doomLoopThreshold ?? DOOM_LOOP_THRESHOLD;
         this.compactionThreshold = normalized.compactionThreshold;
         this.termination = normalized.termination;
-        this.circuitBreaker = normalized.circuitBreaker ?? (normalized.circuitBreakerOptions ? new CircuitBreaker(normalized.circuitBreakerOptions) : new CircuitBreaker());
+        this.circuitBreaker = normalized.circuitBreaker ?? new CircuitBreaker({
+            ...(normalized.maxRetries !== undefined
+                ? { maxRetries: normalized.maxRetries }
+                : normalized.circuitBreakerOptions?.maxRetries !== undefined
+                    ? { maxRetries: normalized.circuitBreakerOptions.maxRetries }
+                    : {}),
+            ...(normalized.retryBackoffMs !== undefined
+                ? { backoffMs: normalized.retryBackoffMs }
+                : normalized.circuitBreakerOptions?.backoffMs !== undefined
+                    ? { backoffMs: normalized.circuitBreakerOptions.backoffMs }
+                    : {}),
+            ...(normalized.maxRetryBackoffMs !== undefined
+                ? { maxBackoffMs: normalized.maxRetryBackoffMs }
+                : normalized.circuitBreakerOptions?.maxBackoffMs !== undefined
+                    ? { maxBackoffMs: normalized.circuitBreakerOptions.maxBackoffMs }
+                    : {}),
+            ...normalized.circuitBreakerOptions,
+        });
         this.saga = new ToolSaga();
         this.stateMachine = new RunStateMachine();
         this.permissionGate = new PermissionGate({
             store: normalized.store,
-            eventBus: normalized.eventBus,
+            ...(normalized.eventBus !== undefined ? { eventBus: normalized.eventBus } : {}),
+            // Core's PluginManager structurally satisfies the step-executor hook
+            // contract (named generic fireHook — castable, matches by design).
             pluginManager: normalized.pluginManager,
             approvalStore: normalized.permissions?.approvalStore,
-            autoApprovalEnabled: normalized.permissions?.autoApprovalEnabled,
+            ...(normalized.permissions?.autoApprovalEnabled !== undefined
+                ? { autoApprovalEnabled: normalized.permissions.autoApprovalEnabled }
+                : {}),
         });
         if (normalized.permissions?.globalPermissionRules) {
             this.permissionGate.setGlobalRules(normalized.permissions.globalPermissionRules);
@@ -123,18 +161,32 @@ export class AgentKernel {
         }
         this.maxTokens = normalized.maxTokens ?? 4096;
         const maxTokens = this.maxTokens;
-        const thinkingPrompt = normalized.thinkingPrompt ?? "Analyze the user's request and the conversation context. Think step by step about what needs to be done. Output your reasoning.";
+        const thinkingPrompt = normalized.thinkingPrompt ?? DEFAULT_THINKING_PROMPT;
+        // P1-N: wire the redacting logger into the kernel so every log line that
+        // passes through it (e.g. model-caller diagnostics) is scrubbed of secrets.
+        const rawLogger = normalized.logger;
+        const redactingLogger = rawLogger
+            ? {
+                debug: createRedactingLogger(rawLogger.debug.bind(rawLogger)),
+                info: createRedactingLogger(rawLogger.info.bind(rawLogger)),
+                warn: createRedactingLogger(rawLogger.warn.bind(rawLogger)),
+                error: createRedactingLogger(rawLogger.error.bind(rawLogger)),
+            }
+            : undefined;
         this.modelCaller = new ModelCaller({
             defaultModel: normalized.model,
             modelRegistry: normalized.modelRegistry,
             maxTokens,
             thinkingBudget: this.thinkingBudget,
             thinkingPrompt,
+            // Core's PluginManager structurally satisfies the model-caller hook
+            // contract (named generic fireHook — castable, matches by design).
             pluginManager: normalized.pluginManager,
+            logger: redactingLogger,
             emitEvent: (event, persist) => this.emitEvent(event, persist),
             modelForRun: (runId) => this.stateMachine.getModelForRun(runId),
             setModelForRun: (runId, model) => this.stateMachine.setModelForRun(runId, model),
-            getAvailableTools: () => this.getAvailableTools(),
+            getAvailableTools: (runId) => this.getAvailableTools(runId),
         });
         const self = this;
         this.stepExecutor = new StepExecutor({
@@ -152,7 +204,9 @@ export class AgentKernel {
             ...(normalized.workspaceRoot !== undefined ? { workspaceRoot: normalized.workspaceRoot } : {}),
             currentAgent: this.currentAgent,
             saga: this.saga,
-            findTool: (name) => self.findTool(name),
+            agentForRun: (runId) => this.runContexts.get(runId)?.agent,
+            sagaForRun: (runId) => this.runContexts.get(runId)?.saga ?? this.saga,
+            findTool: (name, runId) => self.findTool(name, runId),
             hasTool: (name) => self.hasTool(name),
         });
         if (normalized.tools) {
@@ -160,9 +214,9 @@ export class AgentKernel {
         }
         this.sessionDeps = {
             store: this.store,
-            eventBus: this.eventBus,
-            pluginManager: this.pluginManager,
-            sessionStore: this.sessionStore,
+            ...(this.eventBus !== undefined ? { eventBus: this.eventBus } : {}),
+            ...(this.pluginManager !== undefined ? { pluginManager: this.pluginManager } : {}),
+            ...(this.sessionStore !== undefined ? { sessionStore: this.sessionStore } : {}),
             modelCaller: this.modelCaller,
             saga: this.saga,
             ...(normalized.noStore ? { noStore: true } : {}),
@@ -174,14 +228,46 @@ export class AgentKernel {
             store: this.store,
             modelCaller: this.modelCaller,
             maxSubAgentDepth: this.maxSubAgentDepth,
-            currentAgentRef: { get value() { return self.currentAgent; }, set value(v) { self.currentAgent = v; } },
-            currentDepthRef: { get value() { return self.currentDepth; }, set value(v) { self.currentDepth = v; } },
-            agentChainRef: { get value() { return self.agentChain; }, set value(v) { self.agentChain = v; } },
+            currentAgentRef: {
+                get value() { return self.activeRunContext()?.agent ?? self.currentAgent; },
+                set value(v) {
+                    const rc = self.activeRunContext();
+                    if (rc) {
+                        rc.agent = v;
+                        rc.cachedTools = null;
+                        rc.cachedToolsAgentId = undefined;
+                    }
+                    else {
+                        self.currentAgent = v;
+                    }
+                },
+            },
+            currentDepthRef: {
+                get value() { return self.activeRunContext()?.depth ?? self.currentDepth; },
+                set value(v) {
+                    const rc = self.activeRunContext();
+                    if (rc)
+                        rc.depth = v;
+                    else
+                        self.currentDepth = v;
+                },
+            },
+            agentChainRef: {
+                get value() { return self.activeRunContext()?.agentChain ?? self.agentChain; },
+                set value(v) {
+                    const rc = self.activeRunContext();
+                    if (rc)
+                        rc.agentChain = v;
+                    else
+                        self.agentChain = v;
+                },
+            },
             sessionStateRef: {
                 get value() { return self["sessionState"]; },
                 set value(v) { self["sessionState"] = v; },
             },
             runFn: (prompt, ctx, sessionId, _agentOverride) => this.run(prompt, ctx, sessionId, undefined, _agentOverride),
+            runContextFor: (runId) => this.runContexts.get(runId),
         };
         this.lifecycleManager = new LifecycleManager();
     }
@@ -223,12 +309,16 @@ export class AgentKernel {
     addSessionMessage(sid, role, content, extra) {
         return sessionAddMessage(this.sessionDeps, sid, role, content, extra);
     }
-    getAvailableTools() {
-        const agentId = this.currentAgent?.id;
-        if (this.cachedTools && this.cachedToolsAgentId === agentId) {
-            return this.cachedTools;
+    getAvailableTools(runId) {
+        const rc = runId ? this.runContexts.get(runId) : undefined;
+        const target = rc?.agent ?? this.currentAgent;
+        const agentId = target?.id;
+        const cachedTools = rc ? rc.cachedTools : this.cachedTools;
+        const cachedToolsAgentId = rc ? rc.cachedToolsAgentId : this.cachedToolsAgentId;
+        if (cachedTools && cachedToolsAgentId === agentId) {
+            return cachedTools;
         }
-        const caps = this.currentAgent?.capabilities?.tools;
+        const caps = target?.capabilities?.tools;
         // Tool source priority: toolProviderRegistry > toolRegistry > tools[]
         let pool;
         if (this.toolProviderRegistry) {
@@ -241,7 +331,7 @@ export class AgentKernel {
         // belongs to plus core tools (tools in no registered domain). Undefined
         // (legacy default) means no filtering — all tools visible. Per-domain
         // permission defaults (e.g. an MCP server set to "deny") remove the tool.
-        const domains = this.currentAgent?.domains;
+        const domains = target?.domains;
         if (domains !== undefined) {
             pool = pool.filter((t) => {
                 const domain = this.domainFor(t.id);
@@ -262,7 +352,7 @@ export class AgentKernel {
             pool = pool.filter((t) => caps.some((c) => wildcardMatch(c, t.id)));
         }
         // Apply behaviour mode profile (if not "build" mode, profile rules restrict tools)
-        const behaviourMode = this.currentAgent?.behaviourMode ?? "build";
+        const behaviourMode = target?.behaviourMode ?? "build";
         if (behaviourMode !== "build") {
             const profile = getBehaviourProfile(behaviourMode);
             pool = pool.filter((t) => {
@@ -275,15 +365,21 @@ export class AgentKernel {
             });
         }
         const result = pool.filter((t) => {
-            const perm = this.permissionGate.checkTool(t.id, t.risk, undefined, this.currentAgent);
+            const perm = this.permissionGate.checkTool(t.id, t.risk, undefined, target);
             return perm.allowed || perm.needsApproval;
         });
-        this.cachedTools = result;
-        this.cachedToolsAgentId = agentId;
+        if (rc) {
+            rc.cachedTools = result;
+            rc.cachedToolsAgentId = agentId;
+        }
+        else {
+            this.cachedTools = result;
+            this.cachedToolsAgentId = agentId;
+        }
         return result;
     }
-    findTool(name) {
-        return this.getAvailableTools().find((t) => t.id === name);
+    findTool(name, runId) {
+        return this.getAvailableTools(runId).find((t) => t.id === name);
     }
     /** Whether a tool is registered in the underlying pool (regardless of per-agent filtering). */
     hasTool(name) {
@@ -296,10 +392,10 @@ export class AgentKernel {
     /** Switch to a named agent from the registry. Syncs permissions. */
     async useAgent(agentId) {
         if (!this.agentRegistry)
-            throw new Error("No agent registry configured");
+            throw new KernelError("internal_error", "No agent registry configured");
         const agent = await this.agentRegistry.get(agentId);
         if (!agent)
-            throw new Error(`Agent '${agentId}' not found`);
+            throw new AgentNotFoundError(agentId);
         this.currentAgent = agent;
     }
     /** Directly set the active agent config (bypasses registry lookup). */
@@ -310,7 +406,7 @@ export class AgentKernel {
     /** Create and register a new sub-agent from inline params. */
     async spawnAgent(params) {
         if (!this.agentRegistry)
-            throw new Error("No agent registry configured");
+            throw new KernelError("internal_error", "No agent registry configured");
         const ref = { value: this.currentAgent };
         return createSubAgentAndRegister({ agentRegistry: this.agentRegistry, currentAgentRef: ref }, params);
     }
@@ -350,10 +446,17 @@ export class AgentKernel {
         return this.store;
     }
     /** Delegate a prompt to a named sub-agent. Returns the agent's response text. */
-    async runAgent(agentId, prompt, ctx, sessionId) {
+    async runAgent(agentId, prompt, ctx, sessionId, parentRunId, signal) {
         if (!this.agentRegistry)
-            throw new Error("No agent registry configured");
-        return runSubAgent(this.subAgentDeps, agentId, prompt, ctx, sessionId);
+            throw new KernelError("internal_error", "No agent registry configured");
+        return runSubAgent(this.subAgentDeps, agentId, prompt, ctx, sessionId, parentRunId, signal);
+    }
+    /** Build the system head (agent identity + configured system prompt) for a run. */
+    buildSystemPrompt(agent) {
+        const identity = buildAgentIdentity(agent);
+        const systemPrompt = agent?.systemPrompt;
+        const parts = [identity, systemPrompt].filter(Boolean);
+        return parts.length > 0 ? parts.join("\n\n") : undefined;
     }
     /**
      * Start a new agent run. Creates a run ID, wires abort + session, and returns
@@ -374,18 +477,20 @@ export class AgentKernel {
                 };
             }
             this.runSessionStates.set(runId, this.sessionState);
+            if (sessionId)
+                this.runSessionIds.set(runId, sessionId);
             const agent = agentOverride ?? this.currentAgent;
             if (agent) {
                 this.modelCaller.resolveAgentModel(agent, runId);
             }
-            // Build effective prompt with agent identity and system prompt
-            const identity = buildAgentIdentity(agent);
-            const systemPrompt = agent?.systemPrompt;
-            const parts = [identity, systemPrompt, prompt].filter(Boolean);
-            const effectivePrompt = parts.join("\n\n");
+            // RV-40: keep the system head separate from the user prompt so the model
+            // receives a real `system` message instead of a flattened user turn.
+            const systemPrompt = this.buildSystemPrompt(agent);
             // Per-run saga (no instance-level mutation)
             const runSaga = new ToolSaga();
-            const promise = this.runLoop(effectivePrompt, runId, ctx, abort, sessionId, userContentParts, agentOverride, runSaga).finally(() => {
+            const promise = this.runLoop(prompt, runId, ctx, abort, sessionId, userContentParts, agentOverride, runSaga, undefined, systemPrompt)
+                .then(() => undefined)
+                .finally(() => {
                 this.stateMachine.runIdStack.pop();
                 this.runSessionStates.delete(runId);
             });
@@ -400,14 +505,249 @@ export class AgentKernel {
             throw err;
         }
     }
+    /**
+     * Resume a previously persisted run from durable storage (snapshot + messages).
+     * Restores the run's session state (history, step counter, token counts) and
+     * continues the run loop from where it stopped. Emits no `run.started` event
+     * (the run has already started) and does not re-inject the original prompt.
+     *
+     * @param runId     The run to resume — must have persisted events in the store.
+     * @param prompt    The steering prompt for the resumed run (appended as the
+     *                  latest user turn).
+     * @param ctx       Request context.
+     * @param sessionId Optional session id — falls back to the persisted one.
+     */
+    async resumeRun(runId, prompt, ctx, sessionId, agentOverride) {
+        const restored = await restoreRunFromStore(this.store, this.sessionStore, runId);
+        if (!restored) {
+            return {
+                runId,
+                completed: Promise.reject(new Error(`No durable state found for run "${runId}" — nothing to resume`)),
+                abort: () => { },
+            };
+        }
+        const resolvedSessionId = restored.sessionId ?? sessionId;
+        this.stateMachine.runIdStack.push(runId);
+        try {
+            const parentRunId = this.stateMachine.runIdStack.at(-2);
+            const abort = this.stateMachine.createRun(runId, resolvedSessionId, parentRunId);
+            if (!abort) {
+                return {
+                    runId,
+                    completed: Promise.reject(new Error(`Session "${resolvedSessionId}" is busy — concurrent run rejected`)),
+                    abort: () => { },
+                };
+            }
+            this.runSessionStates.set(runId, restored.sessionState);
+            if (resolvedSessionId)
+                this.runSessionIds.set(runId, resolvedSessionId);
+            const agent = agentOverride ?? this.currentAgent;
+            if (agent) {
+                this.modelCaller.resolveAgentModel(agent, runId);
+            }
+            // RV-40: keep the system head separate from the steering prompt.
+            const systemPrompt = this.buildSystemPrompt(agent);
+            const runSaga = new ToolSaga();
+            const promise = this.runLoop(prompt, runId, ctx, abort, resolvedSessionId, undefined, agentOverride, runSaga, true, systemPrompt)
+                .then(() => undefined)
+                .finally(() => {
+                this.stateMachine.runIdStack.pop();
+                this.runSessionStates.delete(runId);
+            });
+            return {
+                runId,
+                completed: promise,
+                abort: () => { abort.abort(); },
+            };
+        }
+        catch (err) {
+            this.stateMachine.runIdStack.pop();
+            throw err;
+        }
+    }
+    /** Reconstruct session IDs with non-terminal runs from the event store (for restart recovery). */
+    async getActiveSessionIds() {
+        return findActiveSessionIds(this.store);
+    }
+    /**
+     * Start a new agent run with full lifecycle management.
+     * Returns an AgentRunHandle with cancel, status, and event streaming.
+     *
+     * @example
+     * ```typescript
+     * const handle = kernel.createRunHandle("Write a hello world program", ctx);
+     *
+     * // Wait for completion
+     * const result = await handle.completed;
+     * console.log(result.status); // "succeeded"
+     *
+     * // Or cancel
+     * handle.cancel();
+     *
+     * // Stream events
+     * for await (const event of handle.events()) {
+     *   console.log(event.type);
+     * }
+     * ```
+     */
+    createRunHandle(prompt, ctx, sessionId, userContentParts, agentOverride) {
+        const runId = crypto.randomUUID();
+        this.stateMachine.runIdStack.push(runId);
+        let cancelled = false;
+        let completed = false;
+        let result;
+        const eventHandlers = new Set();
+        const abortController = new AbortController();
+        const self = this;
+        // Create the run promise
+        const runPromise = (async () => {
+            try {
+                const parentRunId = this.stateMachine.runIdStack.at(-2);
+                const abort = this.stateMachine.createRun(runId, sessionId, parentRunId);
+                if (!abort) {
+                    throw new KernelError("session_busy", `Session "${sessionId}" is busy`);
+                }
+                // Wire the handle's cancel() into the controller the run loop listens on.
+                abortController.signal.addEventListener("abort", () => abort.abort(), { once: true });
+                // RV-7: if cancel() was called before this listener attached (sync call
+                // right after createRunHandle), the abort signal is already fired — replay
+                // it so the run converges on the single `cancelled` terminal outcome.
+                if (abortController.signal.aborted)
+                    abort.abort();
+                this.runSessionStates.set(runId, this.sessionState);
+                if (sessionId)
+                    this.runSessionIds.set(runId, sessionId);
+                const agent = agentOverride ?? this.currentAgent;
+                if (agent) {
+                    this.modelCaller.resolveAgentModel(agent, runId);
+                }
+                // RV-40: keep the system head separate from the user prompt.
+                const systemPrompt = this.buildSystemPrompt(agent);
+                // Per-run saga (no instance-level mutation)
+                const runSaga = new ToolSaga();
+                // Emit agent.started event
+                const startEvent = {
+                    type: "agent.started",
+                    timestamp: new Date().toISOString(),
+                    runId,
+                    prompt,
+                    ...(agent?.profile?.model !== undefined ? { model: agent.profile.model } : {}),
+                };
+                eventHandlers.forEach(h => h(startEvent));
+                // Run the loop — it reports its terminal status through the return value.
+                const { totalSteps, status: runStatus } = await this.runLoop(prompt, runId, ctx, abort, sessionId, userContentParts, agentOverride, runSaga, undefined, systemPrompt);
+                completed = true;
+                result = {
+                    runId,
+                    // RV-7: runLoop reports its own terminal status; the local `cancelled`
+                    // flag (handle.cancel()) agrees whenever the run was cancelled. Never
+                    // let a cancelled run be coerced into "succeeded".
+                    status: cancelled || runStatus === "cancelled"
+                        ? "cancelled"
+                        : runStatus === "failed" ? "failed" : "succeeded",
+                    totalSteps, // totalSteps from the run loop
+                };
+                // Emit agent.completed event
+                const completeEvent = {
+                    type: "agent.completed",
+                    timestamp: new Date().toISOString(),
+                    runId,
+                    status: result.status,
+                };
+                eventHandlers.forEach(h => h(completeEvent));
+                return result;
+            }
+            catch (err) {
+                completed = true;
+                result = {
+                    runId,
+                    status: "failed",
+                    error: err instanceof Error ? err.message : String(err),
+                    totalSteps: 0,
+                };
+                // Emit agent.error event
+                const errorEvent = {
+                    type: "agent.error",
+                    timestamp: new Date().toISOString(),
+                    runId,
+                    error: result.error ?? "Unknown error",
+                    ...(err instanceof KernelError ? { code: err.code } : {}),
+                };
+                eventHandlers.forEach(h => h(errorEvent));
+                throw err;
+            }
+            finally {
+                this.stateMachine.runIdStack.pop();
+                this.runSessionStates.delete(runId);
+            }
+        })();
+        return {
+            runId,
+            completed: runPromise,
+            cancel() {
+                cancelled = true;
+                abortController.abort();
+            },
+            get isCancelled() { return cancelled; },
+            get isCompleted() { return completed; },
+            get isRunning() { return !completed && !cancelled; },
+            events() {
+                return (async function* () {
+                    // Yield events as they occur
+                    const queue = [];
+                    const handler = (event) => queue.push(event);
+                    eventHandlers.add(handler);
+                    try {
+                        while (!completed) {
+                            if (queue.length > 0) {
+                                yield queue.shift();
+                            }
+                            else {
+                                await new Promise(r => setTimeout(r, 10));
+                            }
+                        }
+                        // Yield remaining events
+                        while (queue.length > 0) {
+                            yield queue.shift();
+                        }
+                    }
+                    finally {
+                        eventHandlers.delete(handler);
+                    }
+                })();
+            },
+            onEvent(handler) {
+                eventHandlers.add(handler);
+                return () => { eventHandlers.delete(handler); };
+            },
+        };
+    }
+    /**
+     * Start a new agent run and stream events as an async iterable.
+     * Returns the run ID and an async iterable of run events.
+     */
+    streamRun(prompt, ctx, sessionId, userContentParts, agentOverride) {
+        const handle = this.run(prompt, ctx, sessionId, userContentParts, agentOverride);
+        const eventBus = this.eventBus;
+        const events = eventBus ? streamRunEvents(eventBus, handle.runId, handle.completed) : (async function* () { })();
+        return {
+            runId: handle.runId,
+            events,
+        };
+    }
     getRunSession(runId) {
         return this.runSessionStates.get(runId) ?? this.sessionState;
     }
+    /** Resolve the context of the most recently started run, if one is active. */
+    activeRunContext() {
+        const runId = this.stateMachine.runIdStack.at(-1);
+        return runId ? this.runContexts.get(runId) : undefined;
+    }
     /** Run multiple sub-agents concurrently. Returns combined output. */
-    async runAgentsParallel(tasks, ctx, sessionId) {
+    async runAgentsParallel(tasks, ctx, sessionId, parentRunId, signal) {
         if (!this.agentRegistry)
-            throw new Error("No agent registry configured");
-        return runSubAgentsParallel(this.subAgentDeps, tasks, ctx, sessionId);
+            throw new KernelError("internal_error", "No agent registry configured");
+        return runSubAgentsParallel(this.subAgentDeps, tasks, ctx, sessionId, parentRunId, signal);
     }
     /** Start a run with error-safe wrapper — returns `{ ok, value }` or `{ ok: false, error }`. */
     runSafe(prompt, ctx, sessionId, userContentParts) {
@@ -424,7 +764,12 @@ export class AgentKernel {
         }
     }
     /** Get the tool saga for inspecting completed tool calls and triggering rollbacks. */
-    getSaga() {
+    getSaga(runId) {
+        if (runId) {
+            const runSaga = this.runSagas.get(runId);
+            if (runSaga)
+                return runSaga;
+        }
         return this.saga;
     }
     /** Get the circuit breaker for inspecting trip state and threshold. */
@@ -468,6 +813,13 @@ export class AgentKernel {
         if (normalized.compactionThreshold !== undefined) {
             this.compactionThreshold = normalized.compactionThreshold;
         }
+        if (normalized.maxRetries !== undefined || normalized.retryBackoffMs !== undefined || normalized.maxRetryBackoffMs !== undefined) {
+            this.circuitBreaker = new CircuitBreaker({
+                maxRetries: normalized.maxRetries ?? this.circuitBreaker.getOptions().maxRetries,
+                backoffMs: normalized.retryBackoffMs ?? this.circuitBreaker.getOptions().backoffMs,
+                maxBackoffMs: normalized.maxRetryBackoffMs ?? this.circuitBreaker.getOptions().maxBackoffMs,
+            });
+        }
         if (normalized.permissions?.globalPermissionRules) {
             this.permissionGate.setGlobalRules(normalized.permissions.globalPermissionRules);
         }
@@ -494,6 +846,96 @@ export class AgentKernel {
     /** Send a user input string to a waiting run (e.g., approval response). */
     sendInput(runId, text) {
         this.stateMachine.sendInput(runId, text);
+        this.queuePendingEntry(runId, text);
+    }
+    /** Queue an input into the runtime queue and (when a session is attached) start persisting it. */
+    queuePendingEntry(runId, text) {
+        const sessionId = this.runSessionIds.get(runId);
+        const list = this.runPendingEntries.get(runId) ?? [];
+        let persisted;
+        if (this.sessionStore && sessionId) {
+            persisted = this.persistPendingInput(sessionId, text);
+        }
+        list.push({ text, ...(persisted !== undefined ? { persisted } : {}) });
+        this.runPendingEntries.set(runId, list);
+    }
+    /** Serialize per-session writes so sequential admissions get sequential seqs (RV-21). */
+    persistPendingInput(sessionId, text) {
+        const prev = this.inputWriteChains.get(sessionId) ?? Promise.resolve();
+        const write = prev.catch(() => { }).then(async () => {
+            let next = this.nextAdmittedSeq.get(sessionId);
+            if (next === undefined) {
+                next = (await this.maxAdmittedSeq(sessionId)) + 1;
+            }
+            const admittedSeq = next;
+            this.nextAdmittedSeq.set(sessionId, admittedSeq + 1);
+            const msg = await this.sessionStore.addMessage(sessionId, "user", text, undefined, undefined, undefined, undefined, admittedSeq);
+            return { sessionId, messageId: msg.id, admittedSeq };
+        });
+        this.inputWriteChains.set(sessionId, write);
+        return write;
+    }
+    async maxAdmittedSeq(sessionId) {
+        if (typeof this.sessionStore?.listMessages !== "function")
+            return 0;
+        const messages = await this.sessionStore.listMessages(sessionId);
+        let max = 0;
+        for (const m of messages) {
+            if (typeof m.admittedSeq === "number" && m.admittedSeq > max)
+                max = m.admittedSeq;
+        }
+        return max;
+    }
+    /**
+     * Re-queue inputs admitted but not yet promoted (e.g. from a previous process
+     * that crashed mid-run) in admission order, exactly once (RV-21).
+     */
+    async hydratePendingInputs(runId, sessionId) {
+        if (!this.sessionStore || !sessionId)
+            return;
+        if (typeof this.sessionStore.listMessages !== "function")
+            return;
+        const messages = await this.sessionStore.listMessages(sessionId);
+        let max = 0;
+        // Seed the allocator from the max admittedSeq across ALL history so live
+        // inputs continue past persisted seqs even when nothing is pending.
+        for (const m of messages) {
+            if (typeof m.admittedSeq === "number" && m.admittedSeq > max)
+                max = m.admittedSeq;
+        }
+        const pending = messages
+            .filter((m) => typeof m.admittedSeq === "number" && (m.promotedSeq === undefined || m.promotedSeq < m.admittedSeq))
+            .sort((a, b) => (a.admittedSeq ?? 0) - (b.admittedSeq ?? 0));
+        const list = this.runPendingEntries.get(runId) ?? [];
+        for (const m of pending) {
+            this.stateMachine.sendInput(runId, m.content);
+            list.push({ text: m.content, persisted: Promise.resolve({ sessionId, messageId: m.id, admittedSeq: m.admittedSeq }) });
+        }
+        if (pending.length > 0 || list.length > 0) {
+            this.runPendingEntries.set(runId, list);
+        }
+        // Never regress the allocator under parallel restarts / in-flight writes.
+        this.nextAdmittedSeq.set(sessionId, Math.max(max + 1, this.nextAdmittedSeq.get(sessionId) ?? 0));
+    }
+    /** Mark the given drained inputs as promoted (best-effort, at-least-once on crash). */
+    async markInputsPromoted(runId, texts) {
+        const entries = this.runPendingEntries.get(runId);
+        if (!entries || entries.length === 0)
+            return;
+        const taken = entries.splice(0, texts.length);
+        if (this.sessionStore?.updateMessage) {
+            for (const entry of taken) {
+                if (!entry.persisted)
+                    continue;
+                try {
+                    const p = await entry.persisted;
+                    await this.sessionStore.updateMessage(p.sessionId, p.messageId, { promotedSeq: p.admittedSeq });
+                }
+                catch {
+                    // Best-effort: leave un-promoted so a later restart re-delivers at-least-once.
+                }
+            }
+        }
     }
     /** Abort all currently running sessions. */
     cancelCurrentRun() {
@@ -512,7 +954,7 @@ export class AgentKernel {
         this.cancelCurrentRun();
         return this.lifecycleManager.shutdown();
     }
-    async runLoop(prompt, runId, ctx, runAbort, sessionId, userContentParts, agentOverride, runSaga) {
+    async runLoop(prompt, runId, ctx, runAbort, sessionId, userContentParts, agentOverride, runSaga, resume, systemPrompt) {
         const runModel = this.modelCaller.getActiveModel(runId);
         const runSessionState = this.getRunSession(runId);
         const currentAgent = agentOverride ?? this.currentAgent;
@@ -524,15 +966,24 @@ export class AgentKernel {
                 judgeModel = this.modelCaller.resolveAgentModel(evaluator);
         }
         const runSagaInstance = runSaga ?? new ToolSaga();
-        const prevAgent = this.stepExecutor.getCurrentAgent();
-        this.stepExecutor.setCurrentAgent(currentAgent);
+        // Per-run context — the active agent, sub-agent depth/chain, saga and tool
+        // cache all live here so parallel runs never clobber each other's state.
+        const runContext = createRunContext(runId, currentAgent, runSagaInstance);
+        this.runContexts.set(runId, runContext);
+        // Point the run's recorder at this run's saga so that
+        // record()/registerCompensation()/rollbackStep() operate on the same instance.
+        this.runSagas.set(runId, runSagaInstance);
+        // Per-run circuit breaker — parallel runs must not share breaker state, so
+        // each run retries/trips independently. The instance breaker stays as the
+        // default config (exposed via getCircuitBreaker()) for new runs.
+        const runCircuitBreaker = new CircuitBreaker(this.circuitBreaker.getOptions());
         const orchestratorDeps = {
             modelCaller: this.modelCaller,
             permissionGate: this.permissionGate,
             stepExecutor: this.stepExecutor,
             saga: runSagaInstance,
             store: this.store,
-            circuitBreaker: this.circuitBreaker,
+            circuitBreaker: runCircuitBreaker,
             stateMachine: this.stateMachine,
             ...(this.pluginManager ? { pluginManager: this.pluginManager } : {}),
             ...(this.systemContext ? { systemContext: this.systemContext } : {}),
@@ -543,35 +994,105 @@ export class AgentKernel {
             maxTokens: this.maxTokens,
             thinkingBudget: this.thinkingBudget,
             stepTimeout: this.stepTimeout,
-            compactionThreshold: this.compactionThreshold,
+            ...(this.compactionThreshold !== undefined ? { compactionThreshold: this.compactionThreshold } : {}),
             ...(this.termination ? { termination: this.termination } : {}),
             ...(judgeModel ? { judgeModel } : {}),
             ...(currentAgent ? { currentAgent } : {}),
             addSessionMessage: (sid, role, content, extra) => this.addSessionMessage(sid, role, content, extra),
+            beforeRun: async () => {
+                const parentRunId = this.stateMachine.runIdStack.at(-2);
+                if (parentRunId)
+                    return;
+                await this.hydratePendingInputs(runId, sessionId);
+            },
+            onInputsDrained: (rid, texts) => this.markInputsPromoted(rid, texts),
         };
         try {
-            await executeRunLoop(orchestratorDeps, {
+            const result = await executeRunLoop(orchestratorDeps, {
                 prompt, runId, ctx, runAbort,
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 ...(userContentParts !== undefined ? { userContentParts } : {}),
+                ...(resume !== undefined ? { resume } : {}),
+                ...(systemPrompt !== undefined ? { systemPrompt } : {}),
                 runModel,
                 ...(runSessionState !== undefined ? { runSessionState } : {}),
                 addSessionMessage: (sid, role, content, extra) => this.addSessionMessage(sid, role, content, extra),
                 emitEvent: (event, persist) => this.emitEvent(event, persist),
                 setState: (rid, state) => this.stateMachine.setState(rid, state),
-                updateSessionOnComplete: (sid, rid, totalIn, totalOut, _steps, _status) => this.updateSessionOnComplete(sid, rid, totalIn, totalOut, _steps, _status),
-                emitFail: (rid, c, reason, steps, sid, totalIn, totalOut, dur) => this.emitFail(rid, c, reason, steps, sid, totalIn, totalOut, dur),
+                emitCompleted: (event, sid, rid, totalIn, totalOut, status) => this.emitCompleted(event, sid, rid, totalIn, totalOut, status),
+                emitFail: (rid, c, reason, steps, sid, totalIn, totalOut, dur, cancelled) => this.emitFail(rid, c, reason, steps, sid, totalIn, totalOut, dur, cancelled),
             });
+            return result;
         }
         finally {
-            this.stepExecutor.setCurrentAgent(prevAgent);
+            // Drop this run's context and saga — parallel runs each own their own.
+            this.runContexts.delete(runId);
+            this.runSagas.delete(runId);
+            this.runSessionIds.delete(runId);
+            this.runPendingEntries.delete(runId);
         }
     }
-    updateSessionOnComplete(sid, rid, totalIn, totalOut, _steps, _status) {
-        return sessionUpdateComplete(this.sessionDeps, sid, rid, totalIn, totalOut);
+    emitCompleted(event, sid, rid, totalIn, totalOut, status) {
+        return sessionEmitCompleted(this.sessionDeps, event, sid, rid, totalIn, totalOut, status);
     }
-    emitFail(rid, c, reason, steps, sid, totalIn = 0, totalOut = 0, dur) {
-        return sessionEmitFail(this.sessionDeps, rid, c, reason, steps, sid, totalIn, totalOut, dur);
+    emitFail(rid, c, reason, steps, sid, totalIn = 0, totalOut = 0, dur, cancelled = false) {
+        return sessionEmitFail(this.sessionDeps, rid, c, reason, steps, sid, totalIn, totalOut, dur, cancelled);
     }
 }
+/**
+ * Stream the events of a single run from the event bus, filtered by run ID.
+ * Subscribes eagerly so no event published before the first `next()` is missed.
+ * Terminates when the run completes (or fails).
+ */
+function streamRunEvents(eventBus, runId, completed) {
+    const queue = [];
+    let notify = null;
+    let done = false;
+    const wake = () => {
+        const r = notify;
+        notify = null;
+        if (r)
+            r();
+    };
+    const unsubscribe = eventBus.subscribeAll((event) => {
+        if (event.aggregateId !== runId)
+            return;
+        queue.push(event);
+        wake();
+    });
+    completed.then(wake, wake);
+    return {
+        [Symbol.asyncIterator]() {
+            const self = this;
+            return {
+                async next() {
+                    while (!done) {
+                        if (queue.length > 0) {
+                            return { done: false, value: queue.shift() };
+                        }
+                        const stopped = await Promise.race([
+                            new Promise((resolve) => { notify = () => resolve(false); }),
+                            completed.then(() => true, () => true),
+                        ]);
+                        if (stopped)
+                            done = true;
+                    }
+                    unsubscribe();
+                    // Drain any events that arrived after the run completed
+                    if (queue.length > 0) {
+                        return { done: false, value: queue.shift() };
+                    }
+                    return { done: true, value: undefined };
+                },
+                return() {
+                    unsubscribe();
+                    return Promise.resolve({ done: true, value: undefined });
+                },
+                [Symbol.asyncIterator]() {
+                    return self;
+                },
+            };
+        },
+    };
+}
 //# sourceMappingURL=kernel.js.map