@vinhnt-sdk/step-executor 0.1.3

package/dist/run-context.js

@@ -0,0 +1,13 @@
+/** Create a fresh per-run context. */
+export function createRunContext(runId, agent, saga) {
+    return {
+        runId,
+        agent,
+        depth: 0,
+        agentChain: new Set(),
+        saga,
+        cachedTools: null,
+        cachedToolsAgentId: undefined,
+    };
+}
+//# sourceMappingURL=run-context.js.map

package/dist/run-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.js","sourceRoot":"","sources":["../src/run-context.ts"],"names":[],"mappings":"AAyBA,sCAAsC;AACtC,MAAM,UAAU,gBAAgB,CAC9B,KAAY,EACZ,KAA8B,EAC9B,IAAc;IAEd,OAAO;QACL,KAAK;QACL,KAAK;QACL,KAAK,EAAE,CAAC;QACR,UAAU,EAAE,IAAI,GAAG,EAAE;QACrB,IAAI;QACJ,WAAW,EAAE,IAAI;QACjB,kBAAkB,EAAE,SAAS;KAC9B,CAAC;AACJ,CAAC"}

package/dist/run-state.d.ts

@@ -0,0 +1,27 @@
+import type { RunId } from "@vinhnt-sdk/schema";
+/** Lifecycle state of a run. */
+export type RunState = "pending" | "running" | "paused" | "completed" | "failed" | "cancelled";
+/** Tracks per-run state, abort signals and input queues. */
+export declare class RunStateMachine {
+    private readonly runStates;
+    private readonly runAborts;
+    private readonly pendingInputs;
+    private readonly busySessions;
+    private readonly modelForRun;
+    private readonly stateSubscribers;
+    readonly runIdStack: RunId[];
+    getState(runId: RunId): RunState | undefined;
+    setState(runId: RunId, state: RunState): void;
+    onStateChange(listener: (runId: RunId, state: RunState) => void): () => void;
+    createRun(runId: RunId, sessionId?: string, parentRunId?: RunId): AbortController | null;
+    getAbort(runId: RunId): AbortController | undefined;
+    isAborted(runId: RunId): boolean;
+    getSignal(runId: RunId): AbortSignal;
+    cleanupRun(runId: RunId, sessionId?: string): void;
+    cancelAll(): void;
+    sendInput(runId: RunId, text: string): void;
+    drainInputs(runId: RunId): string[];
+    setModelForRun(runId: RunId, model: unknown): void;
+    getModelForRun<T>(runId: RunId): T | undefined;
+}
+//# sourceMappingURL=run-state.d.ts.map

package/dist/run-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.d.ts","sourceRoot":"","sources":["../src/run-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,gCAAgC;AAChC,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE/F,4DAA4D;AAC5D,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsD;IACvF,QAAQ,CAAC,UAAU,EAAE,KAAK,EAAE,CAAM;IAElC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS;IAI5C,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI;IAO7C,aAAa,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAK5E,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,KAAK,GAAG,eAAe,GAAG,IAAI;IAoBxF,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe,GAAG,SAAS;IAInD,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIhC,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW;IAIpC,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IASlD,SAAS,IAAI,IAAI;IAIjB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAS3C,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE;IAMnC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAIlD,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,GAAG,SAAS;CAI/C"}

package/dist/run-state.js

@@ -0,0 +1,88 @@
+/** Tracks per-run state, abort signals and input queues. */
+export class RunStateMachine {
+    runStates = new Map();
+    runAborts = new Map();
+    pendingInputs = new Map();
+    busySessions = new Set();
+    modelForRun = new Map();
+    stateSubscribers = new Set();
+    runIdStack = [];
+    getState(runId) {
+        return this.runStates.get(runId);
+    }
+    setState(runId, state) {
+        this.runStates.set(runId, state);
+        for (const sub of this.stateSubscribers) {
+            try {
+                sub(runId, state);
+            }
+            catch { }
+        }
+    }
+    onStateChange(listener) {
+        this.stateSubscribers.add(listener);
+        return () => { this.stateSubscribers.delete(listener); };
+    }
+    createRun(runId, sessionId, parentRunId) {
+        const abort = new AbortController();
+        this.runAborts.set(runId, abort);
+        this.setState(runId, "pending");
+        if (sessionId) {
+            // Parallel sub-agent runs bypass the session busy check
+            if (parentRunId && this.runAborts.has(parentRunId)) {
+                // Child run — skip busy check, child shares parent session
+            }
+            else if (this.busySessions.has(sessionId)) {
+                this.runAborts.delete(runId);
+                return null;
+            }
+            else {
+                this.busySessions.add(sessionId);
+            }
+        }
+        return abort;
+    }
+    getAbort(runId) {
+        return this.runAborts.get(runId);
+    }
+    isAborted(runId) {
+        return this.runAborts.get(runId)?.signal.aborted ?? false;
+    }
+    getSignal(runId) {
+        return this.runAborts.get(runId)?.signal ?? new AbortController().signal;
+    }
+    cleanupRun(runId, sessionId) {
+        this.runAborts.delete(runId);
+        this.pendingInputs.delete(runId);
+        this.modelForRun.delete(runId);
+        if (sessionId)
+            this.busySessions.delete(sessionId);
+        // Keep the terminal run state so post-mortem getRunState()/UI can still
+        // report how the run finished; only volatile resources are freed above.
+    }
+    cancelAll() {
+        for (const a of this.runAborts.values())
+            a.abort();
+    }
+    sendInput(runId, text) {
+        const queue = this.pendingInputs.get(runId);
+        if (queue) {
+            queue.push(text);
+        }
+        else {
+            this.pendingInputs.set(runId, [text]);
+        }
+    }
+    drainInputs(runId) {
+        const queue = this.pendingInputs.get(runId);
+        this.pendingInputs.delete(runId);
+        return queue ?? [];
+    }
+    setModelForRun(runId, model) {
+        this.modelForRun.set(runId, model);
+    }
+    getModelForRun(runId) {
+        return this.modelForRun.get(runId);
+    }
+}
+//# sourceMappingURL=run-state.js.map

package/dist/run-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.js","sourceRoot":"","sources":["../src/run-state.ts"],"names":[],"mappings":"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"}

package/dist/self-correction.d.ts

@@ -0,0 +1,29 @@
+import type { RunId, RequestContext, AgentConfig } from "@vinhnt-sdk/schema";
+import type { ChatMessage } from "@vinhnt-sdk/schema";
+import type { ToolContext } from "@vinhnt-sdk/tools";
+import type { RecentCall } from "./kernel-utils.js";
+import type { ToolExecutionPlan } from "./step-executor.js";
+import type { ModelCaller } from "@vinhnt-sdk/llm";
+import type { ModelProvider } from "@vinhnt-sdk/schema";
+import type { StepExecutorPluginHooks } from "./hooks.js";
+import type { PermissionGate } from "./permission-gate.js";
+/** Dependencies required by {@link runSelfCorrection}. */
+export interface SelfCorrectionDeps {
+    readonly store: {
+        emitEvent(event: Omit<import("@vinhnt-sdk/schema").KnownRunEvent, "sequence">, persist?: boolean): Promise<void>;
+    };
+    readonly modelCaller: ModelCaller;
+    readonly maxSelfCorrectAttempts: number;
+    readonly doomLoopThreshold: number;
+    readonly findTool: (name: string, runId?: RunId) => import("@vinhnt-sdk/tools").ToolDefinition | undefined;
+    readonly permissionGate: PermissionGate;
+    readonly pluginManager: StepExecutorPluginHooks | undefined;
+    currentAgent: AgentConfig | undefined;
+}
+/** Token accumulator for a self-correction pass. */
+export interface SelfCorrectionTokens {
+    input: number;
+    output: number;
+}
+export declare function runSelfCorrection(tc: ToolExecutionPlan, messages: ChatMessage[], recentCalls: RecentCall[], step: number, runId: RunId, ctx: RequestContext, runAbort: AbortController, toolCtx: ToolContext, errorMsg: string, runModel: ModelProvider, deps: SelfCorrectionDeps, selfCorrectTokens: SelfCorrectionTokens): Promise<void>;
+//# sourceMappingURL=self-correction.d.ts.map

package/dist/self-correction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-correction.d.ts","sourceRoot":"","sources":["../src/self-correction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE;QAAE,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,oBAAoB,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IACrI,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,OAAO,mBAAmB,EAAE,cAAc,GAAG,SAAS,CAAC;IAC3G,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAC5D,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC;CACvC;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,WAAW,EAAE,EACvB,WAAW,EAAE,UAAU,EAAE,EACzB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,kBAAkB,EACxB,iBAAiB,EAAE,oBAAoB,GACtC,OAAO,CAAC,IAAI,CAAC,CAkGf"}

package/dist/self-correction.js

@@ -0,0 +1,89 @@
+import { getTextContent } from "@vinhnt-sdk/schema";
+import { detectDoomLoop, SELF_CORRECT_PROMPT, raceWithAbort, withToolTimeout } from "./kernel-utils.js";
+import { RunAbortedError } from "@vinhnt-sdk/schema";
+export async function runSelfCorrection(tc, messages, recentCalls, step, runId, ctx, runAbort, toolCtx, errorMsg, runModel, deps, selfCorrectTokens) {
+    let corrected = false;
+    for (let attempt = 1; attempt <= deps.maxSelfCorrectAttempts; attempt++) {
+        await deps.store.emitEvent({
+            id: crypto.randomUUID(), runId, type: "tool.self_correcting",
+            occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+            data: { toolId: tc.toolId, toolName: tc.toolName, error: errorMsg, attempt },
+        });
+        try {
+            const correction = await deps.modelCaller.callModelStream([...messages, { role: "system", content: SELF_CORRECT_PROMPT }], step, runId, ctx, runAbort.signal, deps.currentAgent?.permissions?.maxTokens);
+            if (correction.content && runModel?.countTokens) {
+                selfCorrectTokens.input += [...messages, { role: "system", content: SELF_CORRECT_PROMPT }]
+                    .reduce((sum, m) => sum + runModel.countTokens(getTextContent(m.content)), 0);
+                selfCorrectTokens.output += runModel.countTokens(correction.content);
+            }
+            if (correction.toolCalls?.length) {
+                messages.push({
+                    role: "assistant", content: correction.content,
+                    toolCalls: correction.toolCalls.map((ct) => ({
+                        id: ct.id, name: ct.name, args: ct.args,
+                    })),
+                });
+                for (const ct of correction.toolCalls) {
+                    if (runAbort.signal.aborted)
+                        break;
+                    if (detectDoomLoop(recentCalls, ct.name, ct.args, deps.doomLoopThreshold)) {
+                        messages.push({ role: "tool", toolCallId: ct.id, content: `Error: Doom loop detected in self-correction for "${ct.name}"` });
+                        corrected = true;
+                        break;
+                    }
+                    const ctool = deps.findTool(ct.name, runId);
+                    if (!ctool) {
+                        messages.push({ role: "tool", toolCallId: ct.id, content: `Error: Tool "${ct.name}" not found` });
+                        continue;
+                    }
+                    const cpermResult = deps.permissionGate.checkTool(ct.name, ctool.risk, ct.args, deps.currentAgent);
+                    if (!cpermResult.allowed && !cpermResult.needsApproval) {
+                        messages.push({ role: "tool", toolCallId: ct.id, content: `Error: ${cpermResult.reason}` });
+                        continue;
+                    }
+                    if (cpermResult.needsApproval) {
+                        if (!deps.permissionGate.checkSavedApproval(ct.name, ct.args, deps.currentAgent?.id)) {
+                            const reply = await deps.permissionGate.askForTool(ct.name, ct.id, runId, "", cpermResult.reason ?? `Tool "${ct.name}" requires approval for self-correction`, deps.currentAgent?.id ?? "", ctx.traceId, deps.pluginManager, undefined, runAbort.signal);
+                            if (reply === "reject") {
+                                messages.push({ role: "tool", toolCallId: ct.id, content: `Error: Tool "${ct.name}" rejected by user` });
+                                continue;
+                            }
+                        }
+                    }
+                    try {
+                        // RV-19: cooperative timeout — signal the correction tool at the
+                        // deadline so its side effects stop, not just race-and-abandon.
+                        const cExec = ctool.timeoutMs
+                            ? withToolTimeout((signal) => ctool.execute(ct.args, { ...toolCtx, signal }), ctool.timeoutMs, runAbort.signal, `Tool "${ct.name}" timed out after ${ctool.timeoutMs}ms`)
+                            : ctool.execute(ct.args, toolCtx);
+                        const coutput = await raceWithAbort(cExec, runAbort.signal, runId);
+                        messages.push({
+                            role: "tool",
+                            content: typeof coutput === "string" ? coutput : JSON.stringify(coutput),
+                            toolCallId: ct.id,
+                        });
+                        corrected = true;
+                    }
+                    catch (cErr) {
+                        if (cErr instanceof RunAbortedError)
+                            throw cErr;
+                        messages.push({ role: "tool", toolCallId: ct.id, content: `Error: ${cErr instanceof Error ? cErr.message : String(cErr)}` });
+                    }
+                }
+            }
+            else if (correction.content) {
+                messages.push({ role: "assistant", content: correction.content });
+                corrected = true;
+            }
+        }
+        catch (err) {
+            console.warn(`[kernel] Self-correction attempt ${attempt}/${deps.maxSelfCorrectAttempts} failed:`, err instanceof Error ? err.message : String(err));
+        }
+        if (corrected)
+            break;
+    }
+    if (!corrected) {
+        console.warn(`[kernel] Self-correction exhausted after ${deps.maxSelfCorrectAttempts} attempts for tool "${tc.toolName}"`);
+    }
+}
+//# sourceMappingURL=self-correction.js.map

package/dist/self-correction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-correction.js","sourceRoot":"","sources":["../src/self-correction.ts"],"names":[],"mappings":"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"}

package/dist/step-executor.d.ts

@@ -0,0 +1,81 @@
+import type { RunId, AgentConfig, RequestContext } from "@vinhnt-sdk/schema";
+import type { ChatMessage } from "@vinhnt-sdk/schema";
+import type { ToolDefinition } from "@vinhnt-sdk/tools";
+import type { StepExecutorPluginHooks } from "./hooks.js";
+import type { PermissionGate } from "./permission-gate.js";
+import type { RecentCall } from "./kernel-utils.js";
+import type { ToolCallOutcome } from "./termination.js";
+import type { KnownRunEvent } from "@vinhnt-sdk/schema";
+import type { ModelCaller } from "@vinhnt-sdk/llm";
+import type { ModelProvider } from "@vinhnt-sdk/schema";
+import type { ToolSaga } from "@vinhnt-sdk/tools";
+/** Dependencies required by {@link StepExecutor}. */
+export interface StepExecutorDeps {
+    readonly store: {
+        emitEvent(event: Omit<KnownRunEvent, "sequence">, persist?: boolean): Promise<void>;
+    };
+    readonly addSessionMessage: (sessionId: string | undefined, role: string, content: string, extra?: Record<string, unknown>) => Promise<void>;
+    readonly pluginManager: StepExecutorPluginHooks | undefined;
+    readonly permissionGate: PermissionGate;
+    readonly modelCaller: ModelCaller;
+    readonly maxToolCallsPerStep: number;
+    readonly maxConcurrentToolCalls?: number;
+    readonly maxSelfCorrectAttempts: number;
+    readonly selfCorrectOnFailure: boolean;
+    currentAgent: AgentConfig | undefined;
+    saga: ToolSaga;
+    /** Resolve the active agent for a run — used to keep parallel runs isolated. */
+    readonly agentForRun?: (runId: RunId) => AgentConfig | undefined;
+    /** Resolve the active saga for a run — used to keep parallel runs isolated. */
+    readonly sagaForRun?: (runId: RunId) => ToolSaga;
+    readonly doomLoopThreshold: number;
+    readonly externalDirectoryAccess?: boolean;
+    readonly workspaceRoot?: string;
+    readonly findTool: (name: string, runId?: RunId) => ToolDefinition | undefined;
+    readonly hasTool: (name: string) => boolean;
+}
+/** One planned tool invocation within a step. */
+export interface ToolExecutionPlan {
+    toolId: string;
+    toolName: string;
+    args: unknown;
+}
+/**
+ * Executes tool calls within a run step — manages permissions, approval,
+ * plugin hooks, doom-loop detection, external-path checking, concurrent
+ * execution, self-correction, saga recording, and fallback strategies.
+ */
+export declare class StepExecutor {
+    private readonly deps;
+    constructor(deps: StepExecutorDeps);
+    /** Swap the saga reference for per-run saga scoping */
+    setSaga(saga: ToolSaga): void;
+    /** Swap the current agent reference for per-run agent scoping */
+    setCurrentAgent(agent: AgentConfig | undefined): void;
+    /** Get the current agent reference (used by kernel to save prev before swap) */
+    getCurrentAgent(): AgentConfig | undefined;
+    /** Resolve the agent that owns the given run, falling back to the instance default. */
+    private agentFor;
+    /** Resolve the saga that owns the given run, falling back to the instance default. */
+    private sagaFor;
+    private runConcurrent;
+    /**
+     * Execute a batch of tool calls for the current step.
+     * Handles permission gating, approval dialogs, plugin hooks, doom-loop
+     * detection, external-path checks, concurrent execution with configurable
+     * concurrency, self-correction on failure, and saga compensation recording.
+     */
+    executeToolCalls(toolCalls: ToolExecutionPlan[], messages: ChatMessage[], step: number, runId: RunId, ctx: RequestContext, runAbort: AbortController, sessionId: string | undefined, runModel: ModelProvider): Promise<{
+        toolCallCount: number;
+        recentCalls: RecentCall[];
+        selfCorrectTokens: {
+            input: number;
+            output: number;
+        };
+        toolResults: ToolCallOutcome[];
+    }>;
+    private buildToolContext;
+    private handleApproval;
+    private runSelfCorrection;
+}
+//# sourceMappingURL=step-executor.d.ts.map

package/dist/step-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-executor.d.ts","sourceRoot":"","sources":["../src/step-executor.ts"],"names":[],"mappings":"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"}