@vinhnt-sdk/step-executor 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Thanh Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @vinhnt-sdk/step-executor
+
+Step execution kernel for VNT Agent — tool lifecycle, per-tool timeouts, permission gating, doom-loop detection, self-correction and run state machine.
+
+## Install
+
+```bash
+pnpm add @vinhnt-sdk/step-executor
+```
+
+## Usage
+
+```ts
+import { StepExecutor, PermissionGate, runLoop, RunStateMachine } from "@vinhnt-sdk/step-executor";
+```
+
+## Contents
+
+- `StepExecutor` — per-step tool execution: invoke → permission re-check → run with timeout → result processing, with pluggable hooks/logging
+- `PermissionGate` — permission evaluation against saved patterns, rules and risk defaults (consumes `@vinhnt-sdk/permission`)
+- `tool-context-builder` / `approval-handler` / `tool-error-router` / `self-correction` / `tool-result-processor` — step lifecycle helpers
+- `termination` — stop-condition evaluation and judge-based loop termination
+- `kernel-utils` — doom-loop detection, arg hashing, timeouts, tool domains, defaults
+- `run-state` / `run-context` — per-run state machine and context
+- `circuit-breaker` / `kernel-error` — failure isolation and typed errors
+
+## Hooks
+
+The package exposes a minimal structural `StepExecutorPluginHooks` interface. Hosts (e.g. core's `PluginManager`) only need to implement `fireHook` for the tool-lifecycle / permission hook names.

package/dist/approval-handler.d.ts

@@ -0,0 +1,18 @@
+import type { RunId, RequestContext } from "@vinhnt-sdk/schema";
+import type { ChatMessage } from "@vinhnt-sdk/schema";
+import type { ToolContext } from "@vinhnt-sdk/tools";
+import type { StepExecutorPluginHooks } from "./hooks.js";
+import type { PermissionGate, PermissionCheckResult } from "./permission-gate.js";
+import type { ToolExecutionPlan } from "./step-executor.js";
+import type { AgentConfig } from "@vinhnt-sdk/schema";
+/** Dependencies required by {@link handleApproval}. */
+export interface ApprovalHandlerDeps {
+    readonly store: {
+        emitEvent(event: Omit<import("@vinhnt-sdk/schema").KnownRunEvent, "sequence">, persist?: boolean): Promise<void>;
+    };
+    readonly permissionGate: PermissionGate;
+    readonly pluginManager: StepExecutorPluginHooks | undefined;
+    currentAgent: AgentConfig | undefined;
+}
+export declare function handleApproval(permResult: PermissionCheckResult, tc: ToolExecutionPlan, toolCtx: ToolContext, runId: RunId, ctx: RequestContext, _sessionId: string | undefined, messages: ChatMessage[], deps: ApprovalHandlerDeps, selfApproving?: boolean): Promise<boolean>;
+//# sourceMappingURL=approval-handler.d.ts.map

package/dist/approval-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-handler.d.ts","sourceRoot":"","sources":["../src/approval-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,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,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAC5D,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC;CACvC;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,qBAAqB,EACjC,EAAE,EAAE,iBAAiB,EACrB,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,WAAW,EAAE,EACvB,IAAI,EAAE,mBAAmB,EACzB,aAAa,CAAC,EAAE,OAAO,GACtB,OAAO,CAAC,OAAO,CAAC,CAsClB"}

package/dist/approval-handler.js

@@ -0,0 +1,39 @@
+import { toolDomain } from "./kernel-utils.js";
+export async function handleApproval(permResult, tc, toolCtx, runId, ctx, _sessionId, messages, deps, selfApproving) {
+    // Allowed or needs-approval → proceed. A hard deny (!allowed, no approval
+    // needed) must surface as a rejection — a caller who skips this check would
+    // otherwise hand a denied tool straight through to execution.
+    if (permResult.allowed)
+        return true;
+    if (!permResult.needsApproval) {
+        messages.push({ role: "tool", toolCallId: tc.toolId, content: `Error: Tool "${tc.toolName}" denied by permission rules` });
+        return false;
+    }
+    // Single approval path: self-approving tools ask via their own `ctx.ask`
+    // (which persists savePatterns on "always"). Defer the gate-level ask.
+    if (selfApproving)
+        return true;
+    const savedOk = deps.permissionGate.checkSavedApproval(tc.toolName, tc.args, deps.currentAgent?.id);
+    if (savedOk)
+        return true;
+    const reply = await toolCtx.ask({
+        permission: `tool.${tc.toolName}`,
+        resource: tc.toolName,
+        reason: permResult.reason,
+    });
+    if (reply === "reject") {
+        deps.permissionGate.saveRejection(tc.toolName, tc.args, deps.currentAgent?.id);
+        await deps.store.emitEvent({
+            id: crypto.randomUUID(), runId, type: "tool.failed",
+            occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+            data: { toolId: tc.toolId, toolName: tc.toolName, domain: toolDomain(tc.toolName), decision: "deny", error: `Tool "${tc.toolName}" rejected by user` },
+        });
+        messages.push({ role: "tool", toolCallId: tc.toolId, content: `Error: Tool "${tc.toolName}" rejected by user` });
+        return false;
+    }
+    if (reply === "always") {
+        deps.permissionGate.saveApproval(tc.toolName, tc.args, deps.currentAgent?.id);
+    }
+    return true;
+}
+//# sourceMappingURL=approval-handler.js.map

package/dist/approval-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-handler.js","sourceRoot":"","sources":["../src/approval-handler.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAU/C,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAAiC,EACjC,EAAqB,EACrB,OAAoB,EACpB,KAAY,EACZ,GAAmB,EACnB,UAA8B,EAC9B,QAAuB,EACvB,IAAyB,EACzB,aAAuB;IAEvB,0EAA0E;IAC1E,4EAA4E;IAC5E,8DAA8D;IAC9D,IAAI,UAAU,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;QAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,QAAQ,8BAA8B,EAAE,CAAC,CAAC;QAC3H,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yEAAyE;IACzE,uEAAuE;IACvE,IAAI,aAAa;QAAE,OAAO,IAAI,CAAC;IAE/B,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAA+B,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC/H,IAAI,OAAO;QAAE,OAAO,IAAI,CAAC;IAEzB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC9B,UAAU,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE;QACjC,QAAQ,EAAE,EAAE,CAAC,QAAQ;QACrB,MAAM,EAAE,UAAU,CAAC,MAAO;KAC3B,CAAC,CAAC;IAEH,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAA+B,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC1G,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;YACzB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa;YACnD,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO;YAC1D,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,QAAQ,oBAAoB,EAAE;SACvJ,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,QAAQ,oBAAoB,EAAE,CAAC,CAAC;QACjH,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAA+B,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,48 @@
+/** Current circuit breaker state. */
+export type CircuitState = "closed" | "open" | "half_open";
+/** Tuning for {@link CircuitBreaker}: failure/success thresholds and retry policy. */
+export interface CircuitBreakerOptions {
+    failureThreshold?: number;
+    successThreshold?: number;
+    resetTimeoutMs?: number;
+    isFailure?: (err: unknown) => boolean;
+    /** Maximum number of retries for transient failures. Default: 3 */
+    maxRetries?: number;
+    /** Base delay for exponential backoff in ms. Default: 1000 */
+    backoffMs?: number;
+    /** Maximum delay for backoff in ms. Default: 30000 */
+    maxBackoffMs?: number;
+}
+/** Circuit breaker with failure thresholds, retry/backoff and half-open probing. */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private halfOpenSuccesses;
+    private readonly options;
+    constructor(options?: CircuitBreakerOptions);
+    getState(): CircuitState;
+    /**
+     * Execute a function with circuit breaker and retry logic.
+     * Retries on transient failures with exponential backoff.
+     *
+     * @param fn - The async function to execute
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns The result of the function
+     * @throws CircuitBreakerOpenError if circuit is open
+     * @throws The original error if all retries fail
+     */
+    call<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    private sleepAbortable;
+    private onSuccess;
+    private onFailure;
+    reset(): void;
+    /** Get the current configuration options. */
+    getOptions(): Readonly<Required<CircuitBreakerOptions>>;
+}
+/** Thrown when a call is rejected because the breaker is open. */
+export declare class CircuitBreakerOpenError extends Error {
+    readonly remainingMs: number;
+    constructor(resetTimeoutMs: number);
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAEA,qCAAqC;AACrC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAyBD,oFAAoF;AACpF,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;gBAE9C,OAAO,CAAC,EAAE,qBAAqB;IAO3C,QAAQ,IAAI,YAAY;IAQxB;;;;;;;;;OASG;IACG,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;YA0DvD,cAAc;IAsB5B,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,SAAS;IAcjB,KAAK,IAAI,IAAI;IAOb,6CAA6C;IAC7C,UAAU,IAAI,QAAQ,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC;CAGxD;AAED,kEAAkE;AAClE,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,cAAc,EAAE,MAAM;CAKnC"}

package/dist/circuit-breaker.js

@@ -0,0 +1,171 @@
+import { VntError } from "@vinhnt-sdk/schema";
+const DEFAULT_OPTIONS = {
+    failureThreshold: 5,
+    successThreshold: 2,
+    resetTimeoutMs: 30_000,
+    maxRetries: 3,
+    backoffMs: 1000,
+    maxBackoffMs: 30_000,
+    isFailure: (err) => {
+        if (err instanceof DOMException && err.name === "AbortError")
+            return false;
+        if (err instanceof Error && err.name === "AbortError")
+            return false;
+        // Structured SDK errors carry an explicit retryable flag — upstream auth
+        // (401/403) and validation failures are marked non-retryable and must never
+        // count toward the breaker or be retried, even if their message text does
+        // not match the substring heuristics below.
+        if (err instanceof VntError && err.retryable === false)
+            return false;
+        const msg = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
+        if (msg.includes("auth") || msg.includes("unauthorized") || msg.includes("invalid api key"))
+            return false;
+        if (msg.includes("context") && msg.includes("token"))
+            return false;
+        if (msg.includes("not found") || msg.includes("not_found"))
+            return false;
+        return true;
+    },
+};
+/** Circuit breaker with failure thresholds, retry/backoff and half-open probing. */
+export class CircuitBreaker {
+    state = "closed";
+    failureCount = 0;
+    lastFailureTime = 0;
+    halfOpenSuccesses = 0;
+    options;
+    constructor(options) {
+        this.options = {
+            ...DEFAULT_OPTIONS,
+            ...Object.fromEntries(Object.entries(options ?? {}).filter(([, v]) => v !== undefined)),
+        };
+    }
+    getState() {
+        if (this.state === "open" && Date.now() - this.lastFailureTime >= this.options.resetTimeoutMs) {
+            this.state = "half_open";
+            this.halfOpenSuccesses = 0;
+        }
+        return this.state;
+    }
+    /**
+     * Execute a function with circuit breaker and retry logic.
+     * Retries on transient failures with exponential backoff.
+     *
+     * @param fn - The async function to execute
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns The result of the function
+     * @throws CircuitBreakerOpenError if circuit is open
+     * @throws The original error if all retries fail
+     */
+    async call(fn, signal) {
+        const state = this.getState();
+        if (state === "open") {
+            throw new CircuitBreakerOpenError(this.options.resetTimeoutMs);
+        }
+        let lastError;
+        let attempt = 0;
+        while (attempt <= this.options.maxRetries) {
+            if (signal?.aborted) {
+                throw new DOMException("Aborted", "AbortError");
+            }
+            try {
+                const result = await fn();
+                this.onSuccess();
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                // Cancellation is never a failure — rethrow without counting it so an
+                // aborted run cannot trip the breaker or get retried.
+                if (signal?.aborted || (err instanceof DOMException && err.name === "AbortError") || (err instanceof Error && err.name === "AbortError")) {
+                    throw signal?.aborted ? new DOMException("Aborted", "AbortError") : err;
+                }
+                // Check if error is retryable
+                if (!this.options.isFailure(err)) {
+                    throw err;
+                }
+                this.onFailure(err);
+                // Don't retry if we've hit the circuit breaker
+                if (this.getState() === "open") {
+                    throw new CircuitBreakerOpenError(this.options.resetTimeoutMs);
+                }
+                // Don't retry on last attempt
+                if (attempt >= this.options.maxRetries) {
+                    throw err;
+                }
+                // Calculate delay with exponential backoff
+                const delay = Math.min(this.options.backoffMs * Math.pow(2, attempt), this.options.maxBackoffMs);
+                await this.sleepAbortable(delay, signal);
+                attempt++;
+            }
+        }
+        throw lastError;
+    }
+    async sleepAbortable(ms, signal) {
+        if (!signal) {
+            await new Promise((resolve) => setTimeout(resolve, ms));
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                signal.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(new DOMException("Aborted", "AbortError"));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            if (signal.aborted) {
+                clearTimeout(timer);
+                reject(new DOMException("Aborted", "AbortError"));
+            }
+        });
+    }
+    onSuccess() {
+        if (this.state === "half_open") {
+            this.halfOpenSuccesses++;
+            if (this.halfOpenSuccesses >= this.options.successThreshold) {
+                this.state = "closed";
+                this.failureCount = 0;
+                this.halfOpenSuccesses = 0;
+            }
+        }
+        else if (this.state === "closed") {
+            this.failureCount = 0;
+        }
+    }
+    onFailure(err) {
+        if (!this.options.isFailure(err))
+            return;
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        if (this.failureCount >= this.options.failureThreshold) {
+            this.state = "open";
+        }
+        else if (this.state === "half_open") {
+            this.state = "open";
+            this.halfOpenSuccesses = 0;
+        }
+    }
+    reset() {
+        this.state = "closed";
+        this.failureCount = 0;
+        this.lastFailureTime = 0;
+        this.halfOpenSuccesses = 0;
+    }
+    /** Get the current configuration options. */
+    getOptions() {
+        return this.options;
+    }
+}
+/** Thrown when a call is rejected because the breaker is open. */
+export class CircuitBreakerOpenError extends Error {
+    remainingMs;
+    constructor(resetTimeoutMs) {
+        super(`Circuit breaker is open — too many consecutive failures. Will retry in ${resetTimeoutMs}ms`);
+        this.name = "CircuitBreakerOpenError";
+        this.remainingMs = resetTimeoutMs;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal structural plugin-hook surface used by the step executor.
+ *
+ * Hosts (e.g. core's `PluginManager`) only need to implement `fireHook` for
+ * the tool-lifecycle / permission hook names; no direct dependency on the
+ * full plugin contract.
+ */
+export interface StepExecutorPluginHooks {
+    fireHook(name: "onToolInvoked" | "onBeforeToolExecution" | "onAfterToolExecution" | "onToolCompleted" | "onToolFailed" | "onShellEnv" | "onPermissionAsk", data: Record<string, unknown>): Promise<{
+        modified: Record<string, unknown>;
+    } | null | void> | {
+        modified: Record<string, unknown>;
+    } | null | void;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CACN,IAAI,EACA,eAAe,GACf,uBAAuB,GACvB,sBAAsB,GACtB,iBAAiB,GACjB,cAAc,GACd,YAAY,GACZ,iBAAiB,EACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAE3B,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,GAAG,IAAI,CAAC,GAC5D;QAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GACrC,IAAI,GACJ,IAAI,CAAC;CACV"}

package/dist/hooks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module @vinhnt-sdk/step-executor
+ * Step execution kernel: tool lifecycle, per-tool timeouts, permission gating,
+ * doom-loop detection, self-correction and run state machine.
+ */
+export type { StepExecutorPluginHooks } from "./hooks.js";
+export { StepExecutor } from "./step-executor.js";
+export type { StepExecutorDeps, ToolExecutionPlan } from "./step-executor.js";
+export { DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_CALLS_PER_STEP, DOOM_LOOP_THRESHOLD, toolDomain, } from "./kernel-utils.js";
+export { evaluateStopConditions, buildJudgeMessages, parseJudgeVerdict, toToolCallOutcome } from "./termination.js";
+export type { ToolCallOutcome, StepVerificationContext, StopCondition, TerminationPolicy } from "./termination.js";
+export { PermissionGate } from "./permission-gate.js";
+export type { ApprovalDecision, DynamicRule, PermissionCheckResult } from "./permission-gate.js";
+export { createRunContext } from "./run-context.js";
+export type { RunContext } from "./run-context.js";
+export { KernelError } from "./kernel-error.js";
+export type { KernelErrorCode } from "./kernel-error.js";
+export { CircuitBreaker, CircuitBreakerOpenError } from "./circuit-breaker.js";
+export type { CircuitState, CircuitBreakerOptions } from "./circuit-breaker.js";
+export { RunStateMachine } from "./run-state.js";
+export type { RunState } from "./run-state.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAI1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI9E,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,mBAAmB,EACnB,UAAU,GACX,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACpH,YAAY,EAAE,eAAe,EAAE,uBAAuB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAInH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIhF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @module @vinhnt-sdk/step-executor
+ * Step execution kernel: tool lifecycle, per-tool timeouts, permission gating,
+ * doom-loop detection, self-correction and run state machine.
+ */
+// === Step Executor ===
+export { StepExecutor } from "./step-executor.js";
+// === Kernel Utils (public subset) ===
+export { DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_CALLS_PER_STEP, DOOM_LOOP_THRESHOLD, toolDomain, } from "./kernel-utils.js";
+// === Termination ===
+export { evaluateStopConditions, buildJudgeMessages, parseJudgeVerdict, toToolCallOutcome } from "./termination.js";
+// === Permission Gate ===
+export { PermissionGate } from "./permission-gate.js";
+// === Run Context ===
+export { createRunContext } from "./run-context.js";
+// === Kernel Error ===
+export { KernelError } from "./kernel-error.js";
+// === Circuit Breaker ===
+export { CircuitBreaker, CircuitBreakerOpenError } from "./circuit-breaker.js";
+// === Run State ===
+export { RunStateMachine } from "./run-state.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,wBAAwB;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,uCAAuC;AAEvC,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,mBAAmB,EACnB,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,sBAAsB;AAEtB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGpH,0BAA0B;AAE1B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,sBAAsB;AAEtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,uBAAuB;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,0BAA0B;AAE1B,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/E,oBAAoB;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/kernel-error.d.ts

@@ -0,0 +1,10 @@
+import { VntError } from "@vinhnt-sdk/schema";
+/** Kernel-level failure codes for {@link KernelError}. */
+export type KernelErrorCode = "session_busy" | "cancelled" | "max_steps_exceeded" | "max_tokens_exceeded" | "tool_failed" | "model_failed" | "session_store_failed" | "internal_error" | "timeout" | "model_unavailable";
+/** Kernel-level failure with a typed {@link KernelErrorCode}. */
+export declare class KernelError extends VntError {
+    readonly code: string;
+    readonly retryable = false;
+    constructor(kernelCode: KernelErrorCode, message: string, cause?: unknown);
+}
+//# sourceMappingURL=kernel-error.d.ts.map

package/dist/kernel-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-error.d.ts","sourceRoot":"","sources":["../src/kernel-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,WAAW,GACX,oBAAoB,GACpB,qBAAqB,GACrB,aAAa,GACb,cAAc,GACd,sBAAsB,GACtB,gBAAgB,GAChB,SAAS,GACT,mBAAmB,CAAC;AAExB,iEAAiE;AACjE,qBAAa,WAAY,SAAQ,QAAQ;IACvC,SAAyB,IAAI,EAAE,MAAM,CAAC;IACtC,SAAyB,SAAS,SAAS;gBAE/B,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK1E"}

package/dist/kernel-error.js

@@ -0,0 +1,12 @@
+import { VntError } from "@vinhnt-sdk/schema";
+/** Kernel-level failure with a typed {@link KernelErrorCode}. */
+export class KernelError extends VntError {
+    code;
+    retryable = false;
+    constructor(kernelCode, message, cause) {
+        super(message, { cause });
+        this.code = kernelCode;
+        this.name = `KernelError.${kernelCode}`;
+    }
+}
+//# sourceMappingURL=kernel-error.js.map

package/dist/kernel-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-error.js","sourceRoot":"","sources":["../src/kernel-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAe9C,iEAAiE;AACjE,MAAM,OAAO,WAAY,SAAQ,QAAQ;IACd,IAAI,CAAS;IACb,SAAS,GAAG,KAAK,CAAC;IAE3C,YAAY,UAA2B,EAAE,OAAe,EAAE,KAAe;QACvE,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,eAAe,UAAU,EAAE,CAAC;IAC1C,CAAC;CACF"}

package/dist/kernel-utils.d.ts

@@ -0,0 +1,49 @@
+import type { RunId } from "@vinhnt-sdk/schema";
+/** Race a promise against an abort signal — rejects with RunAbortedError if aborted. @internal */
+export declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal, runId: RunId): Promise<T>;
+/**
+ * Run a tool execution with a cooperative timeout (RV-19). The caller's
+ * `run` receives a local `AbortSignal` that fires when EITHER the parent
+ * (run) signal aborts OR the tool exceeds `timeoutMs`. Well-behaved tools
+ * that watch their context signal stop their side effects at the deadline
+ * instead of continuing past it (a plain `Promise.race` abandons the tool
+ * promise and its effects keep running). The returned promise still
+ * hard-rejects at `timeoutMs`, so a non-cooperative tool can never hang the
+ * caller longer than the deadline. Parent aborts are NOT synthesised here —
+ * the caller's `raceWithAbort` rejects with `RunAbortedError`.
+ * @internal
+ */
+export declare function withToolTimeout<T>(run: (signal: AbortSignal) => Promise<T>, timeoutMs: number, parent: AbortSignal, timeoutMessage: string): Promise<T>;
+/** Default cap on steps per run. */
+export declare const DEFAULT_MAX_STEPS = 25;
+/** Default cap on tool calls per step. */
+export declare const DEFAULT_MAX_TOOL_CALLS_PER_STEP = 20;
+/** Consecutive identical calls that trigger doom-loop detection. */
+export declare const DOOM_LOOP_THRESHOLD = 3;
+/** System prompt guiding the model to correct a failed tool call. @internal */
+export declare const SELF_CORRECT_PROMPT = "A tool call just failed. Analyze the error and try a corrected approach.\n\nGuidelines:\n- If the error is about arguments, fix the arguments and retry.\n- If the tool is unavailable, suggest an alternative tool.\n- If the problem is permanent (e.g., invalid request), explain to the user.\n- Do NOT repeat the same failing call.";
+/** A recorded tool invocation used for doom-loop detection. @internal */
+export interface RecentCall {
+    id: string;
+    args: unknown;
+    /** Canonical hash of `args` — precomputed once for O(1) doom-loop comparison */
+    argsKey?: string;
+}
+/**
+ * Stable, order-independent hash of an arbitrary tool-arguments value.
+ * Object key order is normalized so `{a:1,b:2}` and `{b:2,a:1}` hash the same,
+ * and the hash is computed once per call (vs. repeated JSON.stringify in a
+ * doom-loop scan). Collisions are possible but astronomically unlikely for the
+ * small arg payloads agents produce.
+ * @internal
+ */
+export declare function hashArgs(value: unknown): string;
+/** Detect whether the same tool+args repeated the last `threshold` calls. @internal */
+export declare function detectDoomLoop(recentCalls: RecentCall[], name: string, args: unknown, threshold?: number): boolean;
+/**
+ * Derive the owning domain from a namespaced tool id:
+ * `mcp__<server>__<tool>` → "mcp:<server>", `coding.read_file` → "coding",
+ * bare ids → "core".
+ */
+export declare function toolDomain(toolName: string): string;
+//# sourceMappingURL=kernel-utils.d.ts.map

package/dist/kernel-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-utils.d.ts","sourceRoot":"","sources":["../src/kernel-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAanG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,EACnB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,CAAC,CAAC,CA4BZ;AAED,oCAAoC;AACpC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,0CAA0C;AAC1C,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,8UAMO,CAAC;AAExC,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC;IACd,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE/C;AAoBD,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,SAAsB,GAAG,OAAO,CAK/H;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOnD"}