@vinhnt-sdk/step-executor 0.6.5 → 0.11.0

package/README.md

@@ -11,7 +11,7 @@ pnpm add @vinhnt-sdk/step-executor
 ## Usage
 
 ```ts
-import { StepExecutor, PermissionGate, runLoop, RunStateMachine } from "@vinhnt-sdk/step-executor";
+import { StepExecutor, PermissionGate, RunStateMachine } from "@vinhnt-sdk/step-executor";
 ```
 
 ## Contents
@@ -22,7 +22,8 @@ import { StepExecutor, PermissionGate, runLoop, RunStateMachine } from "@vinhnt-
 - `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
+- `loop-policy` / `path-policy` — loop/path safety policies
+- `kernel-error` — typed step errors; failure isolation via `@vinhnt-sdk/guard` circuit breaker
 
 ## Hooks
 

package/dist/file-snapshot.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Per-step file snapshots → undo (P2-3 / G7.2).
+ *
+ * Before a mutating file tool (`write_file`/`edit_file`/`apply_patch` by
+ * default) executes, the recorder captures each target file's PRE-IMAGE:
+ * `{existed, content}` (content skipped above `maxContentBytes`). Snapshots
+ * are grouped by `runId`/`step`/`toolCallId`, kept in an in-memory bounded
+ * store (swap `fs`/store knobs via DI — no global state), and reference
+ * metadata (never file content) rides on the `tool.completed` event as
+ * `metadata.fileSnapshots`.
+ *
+ * `undo(filter)` restores newest-first: existing files get their pre-image
+ * back, files the tool created are removed, entries without a captured
+ * pre-image are reported as skipped. Opt-in via `AgentKernelConfig.fileSnapshot`
+ * (default: off — zero behavior change until enabled).
+ */
+/** Pre-image of one file captured before a mutating tool ran. */
+export interface FileSnapshot {
+    /** Target path (absolute when `workspaceRoot` is known, else as given). */
+    readonly path: string;
+    /** Whether the file existed before the tool ran. */
+    readonly existed: boolean;
+    /**
+     * Pre-image content. `undefined` when the file did not exist, was
+     * unreadable, or exceeded `maxContentBytes` (undo then reports "no
+     * pre-image" instead of corrupting the file).
+     */
+    readonly content?: string;
+    /** Pre-image size in bytes (0 when the file did not exist). */
+    readonly size: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly step: number;
+    readonly runId: string;
+    /** ISO timestamp of the capture. */
+    readonly at: string;
+    /** Set once `undo()` restored/removed this entry (never undone twice). */
+    undone: boolean;
+}
+/** Lightweight snapshot reference attached to `tool.completed` event metadata. */
+export interface FileSnapshotRef {
+    readonly path: string;
+    readonly existed: boolean;
+    /** Whether a restorable pre-image was captured (false = over-cap/unreadable). */
+    readonly hadPreImage: boolean;
+}
+/** Injectable filesystem seam (defaults to `node:fs/promises`). */
+export interface FileSnapshotFs {
+    /**
+     * Read a utf8 file. Return `content: undefined` when it exceeds `maxBytes`
+     * (still report `size`). Throw an error with `code: "ENOENT"` when missing.
+     */
+    read(path: string, maxBytes: number): Promise<{
+        content?: string;
+        size: number;
+    }>;
+    write(path: string, content: string): Promise<void>;
+    remove(path: string): Promise<void>;
+}
+/** Recorder configuration (all injectable — see defaults below). */
+export interface FileSnapshotConfig {
+    /** Tool names eligible for capture. Default: {@link DEFAULT_SNAPSHOT_TOOL_IDS}. */
+    readonly toolIds?: readonly string[];
+    /** Arg keys holding the target path (first present wins). Default: {@link DEFAULT_SNAPSHOT_PATH_ARGS}. */
+    readonly pathArgs?: readonly string[];
+    /** Skip capturing content above this many bytes (existence is still recorded). Default: 1 MiB. */
+    readonly maxContentBytes?: number;
+    /** Max retained snapshots (drop-oldest). Default: 200. */
+    readonly maxSnapshots?: number;
+    /** Resolve relative target paths against this root. */
+    readonly workspaceRoot?: string;
+    /** Filesystem seam. Default: {@link createNodeFileSnapshotFs}. */
+    readonly fs?: FileSnapshotFs;
+}
+/** Selects snapshots for `list()`/`undo()`. At least one field should match. */
+export interface FileSnapshotFilter {
+    readonly runId?: string;
+    readonly step?: number;
+    readonly path?: string;
+    readonly toolCallId?: string;
+}
+/** One successful undo action. */
+export interface FileSnapshotUndoEntry {
+    readonly path: string;
+    readonly action: "restored" | "removed";
+}
+/** One entry that could not be undone. */
+export interface FileSnapshotUndoSkipped {
+    readonly path: string;
+    readonly reason: string;
+}
+/** Result of {@link FileSnapshotRecorder.undo}. */
+export interface FileSnapshotUndoResult {
+    readonly restored: readonly FileSnapshotUndoEntry[];
+    readonly skipped: readonly FileSnapshotUndoSkipped[];
+}
+/** Input to {@link FileSnapshotRecorder.capture}. */
+export interface FileSnapshotCaptureParams {
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly toolCallId: string;
+    readonly step: number;
+    readonly runId: string;
+    /** Override the ISO timestamp source (tests). */
+    readonly now?: () => string;
+}
+/** Default mutating tool names eligible for capture. */
+export declare const DEFAULT_SNAPSHOT_TOOL_IDS: readonly ["write_file", "edit_file", "apply_patch"];
+/** Default arg keys carrying the target file path. */
+export declare const DEFAULT_SNAPSHOT_PATH_ARGS: readonly ["filePath", "path"];
+/** Default content cap: 1 MiB (larger files record existence only). */
+export declare const DEFAULT_SNAPSHOT_MAX_CONTENT_BYTES = 1048576;
+/** Default bounded store size (drop-oldest). */
+export declare const DEFAULT_SNAPSHOT_MAX_COUNT = 200;
+/** Filesystem backed by `node:fs/promises`. */
+export declare function createNodeFileSnapshotFs(): FileSnapshotFs;
+/**
+ * Extract the target file paths a mutating tool call will touch:
+ * structured `apply_patch` patches (via the G2.1 grammar — every
+ * `*** Update/Add/Delete File:` path plus `*** Move to:` targets), otherwise
+ * the first present path arg (`filePath`/`path` by default).
+ * Returns `[]` when nothing extractable (caller skips capture).
+ */
+export declare function extractSnapshotPaths(toolName: string, input: unknown, config?: Pick<FileSnapshotConfig, "pathArgs">): readonly string[];
+/**
+ * Bounded in-memory store of file pre-images with capture/undo.
+ * Not thread-safe across concurrent captures of the same path (per-tool
+ * captures are serialized by the step executor's approval flow).
+ */
+export declare class FileSnapshotRecorder {
+    private readonly toolIds;
+    private readonly pathArgs;
+    private readonly maxContentBytes;
+    private readonly maxSnapshots;
+    private readonly workspaceRoot;
+    private readonly fs;
+    private readonly snapshots;
+    constructor(config?: FileSnapshotConfig);
+    /** Total retained snapshots (bounded by `maxSnapshots`, drop-oldest). */
+    get size(): number;
+    /** Whether the given tool name is eligible for capture. */
+    accepts(toolName: string): boolean;
+    /**
+     * Capture pre-images for a mutating tool call (best-effort — never throws).
+     * Returns the lightweight refs to attach to `tool.completed` metadata.
+     */
+    capture(params: FileSnapshotCaptureParams): Promise<readonly FileSnapshotRef[]>;
+    /** List matching snapshots (copy — oldest first). */
+    list(filter?: FileSnapshotFilter): readonly FileSnapshot[];
+    /**
+     * Undo matching, NOT-yet-undone snapshots, NEWEST FIRST.
+     * Existing files → pre-image restored; tool-created files → removed;
+     * entries without a captured pre-image → skipped with a reason.
+     */
+    undo(filter?: FileSnapshotFilter): Promise<FileSnapshotUndoResult>;
+    /** Drop snapshots (all, or only a run's) — e.g. after session cleanup. */
+    clear(runId?: string): void;
+    private resolvePath;
+}
+/** Factory mirroring the SDK's create* conventions. */
+export declare function createFileSnapshotRecorder(config?: FileSnapshotConfig): FileSnapshotRecorder;
+//# sourceMappingURL=file-snapshot.d.ts.map

package/dist/file-snapshot.d.ts.map

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

package/dist/file-snapshot.js

@@ -0,0 +1,233 @@
+/**
+ * Per-step file snapshots → undo (P2-3 / G7.2).
+ *
+ * Before a mutating file tool (`write_file`/`edit_file`/`apply_patch` by
+ * default) executes, the recorder captures each target file's PRE-IMAGE:
+ * `{existed, content}` (content skipped above `maxContentBytes`). Snapshots
+ * are grouped by `runId`/`step`/`toolCallId`, kept in an in-memory bounded
+ * store (swap `fs`/store knobs via DI — no global state), and reference
+ * metadata (never file content) rides on the `tool.completed` event as
+ * `metadata.fileSnapshots`.
+ *
+ * `undo(filter)` restores newest-first: existing files get their pre-image
+ * back, files the tool created are removed, entries without a captured
+ * pre-image are reported as skipped. Opt-in via `AgentKernelConfig.fileSnapshot`
+ * (default: off — zero behavior change until enabled).
+ */
+import { readFile, writeFile, rm, stat } from "node:fs/promises";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { detectApplyPatchFormat, parseApplyPatch } from "@vinhnt-sdk/tools";
+/** Default mutating tool names eligible for capture. */
+export const DEFAULT_SNAPSHOT_TOOL_IDS = ["write_file", "edit_file", "apply_patch"];
+/** Default arg keys carrying the target file path. */
+export const DEFAULT_SNAPSHOT_PATH_ARGS = ["filePath", "path"];
+/** Default content cap: 1 MiB (larger files record existence only). */
+export const DEFAULT_SNAPSHOT_MAX_CONTENT_BYTES = 1_048_576;
+/** Default bounded store size (drop-oldest). */
+export const DEFAULT_SNAPSHOT_MAX_COUNT = 200;
+/** Filesystem backed by `node:fs/promises`. */
+export function createNodeFileSnapshotFs() {
+    return {
+        async read(path, maxBytes) {
+            const info = await stat(path);
+            if (info.size > maxBytes)
+                return { size: info.size };
+            const content = await readFile(path, "utf8");
+            return { content, size: Buffer.byteLength(content, "utf8") };
+        },
+        async write(path, content) {
+            await writeFile(path, content, "utf8");
+        },
+        async remove(path) {
+            await rm(path, { force: true });
+        },
+    };
+}
+/**
+ * Extract the target file paths a mutating tool call will touch:
+ * structured `apply_patch` patches (via the G2.1 grammar — every
+ * `*** Update/Add/Delete File:` path plus `*** Move to:` targets), otherwise
+ * the first present path arg (`filePath`/`path` by default).
+ * Returns `[]` when nothing extractable (caller skips capture).
+ */
+export function extractSnapshotPaths(toolName, input, config) {
+    const record = (typeof input === "object" && input !== null ? input : {});
+    if (toolName === "apply_patch" && typeof record.patch === "string") {
+        const patch = record.patch;
+        if (detectApplyPatchFormat(patch) === "structured") {
+            try {
+                const program = parseApplyPatch(patch, "lenient");
+                const paths = [];
+                for (const op of program.ops) {
+                    paths.push(op.path);
+                    if (op.kind === "update" && op.moveTo !== undefined)
+                        paths.push(op.moveTo);
+                }
+                return [...new Set(paths)];
+            }
+            catch {
+                // Best-effort: fall through to path-arg extraction.
+            }
+        }
+    }
+    for (const key of config?.pathArgs ?? DEFAULT_SNAPSHOT_PATH_ARGS) {
+        const value = record[key];
+        if (typeof value === "string" && value.length > 0)
+            return [value];
+    }
+    return [];
+}
+/**
+ * Bounded in-memory store of file pre-images with capture/undo.
+ * Not thread-safe across concurrent captures of the same path (per-tool
+ * captures are serialized by the step executor's approval flow).
+ */
+export class FileSnapshotRecorder {
+    toolIds;
+    pathArgs;
+    maxContentBytes;
+    maxSnapshots;
+    workspaceRoot;
+    fs;
+    snapshots = [];
+    constructor(config = {}) {
+        this.toolIds = new Set(config.toolIds ?? DEFAULT_SNAPSHOT_TOOL_IDS);
+        this.pathArgs = config.pathArgs ?? DEFAULT_SNAPSHOT_PATH_ARGS;
+        this.maxContentBytes = config.maxContentBytes ?? DEFAULT_SNAPSHOT_MAX_CONTENT_BYTES;
+        this.maxSnapshots = Math.max(1, config.maxSnapshots ?? DEFAULT_SNAPSHOT_MAX_COUNT);
+        this.workspaceRoot = config.workspaceRoot;
+        this.fs = config.fs ?? createNodeFileSnapshotFs();
+    }
+    /** Total retained snapshots (bounded by `maxSnapshots`, drop-oldest). */
+    get size() {
+        return this.snapshots.length;
+    }
+    /** Whether the given tool name is eligible for capture. */
+    accepts(toolName) {
+        return this.toolIds.has(toolName);
+    }
+    /**
+     * Capture pre-images for a mutating tool call (best-effort — never throws).
+     * Returns the lightweight refs to attach to `tool.completed` metadata.
+     */
+    async capture(params) {
+        if (!this.accepts(params.toolName))
+            return [];
+        const paths = extractSnapshotPaths(params.toolName, params.input, { pathArgs: this.pathArgs });
+        if (paths.length === 0)
+            return [];
+        const at = (params.now ?? (() => new Date().toISOString()))();
+        const refs = [];
+        for (const rawPath of paths) {
+            try {
+                const path = this.resolvePath(rawPath);
+                let existed = true;
+                let content;
+                let size = 0;
+                try {
+                    const result = await this.fs.read(path, this.maxContentBytes);
+                    content = result.content;
+                    size = result.size;
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        existed = false;
+                    }
+                    else {
+                        continue; // unreadable (permissions, directory…) — skip this path
+                    }
+                }
+                this.snapshots.push({
+                    path,
+                    existed,
+                    ...(content !== undefined ? { content } : {}),
+                    size,
+                    toolCallId: params.toolCallId,
+                    toolName: params.toolName,
+                    step: params.step,
+                    runId: params.runId,
+                    at,
+                    undone: false,
+                });
+                while (this.snapshots.length > this.maxSnapshots)
+                    this.snapshots.shift();
+                refs.push({ path, existed, hadPreImage: existed && content !== undefined });
+            }
+            catch {
+                // Path resolution failure — never break the tool call.
+            }
+        }
+        return refs;
+    }
+    /** List matching snapshots (copy — oldest first). */
+    list(filter) {
+        return this.snapshots.filter((s) => matches(s, filter));
+    }
+    /**
+     * Undo matching, NOT-yet-undone snapshots, NEWEST FIRST.
+     * Existing files → pre-image restored; tool-created files → removed;
+     * entries without a captured pre-image → skipped with a reason.
+     */
+    async undo(filter = {}) {
+        const target = this.snapshots
+            .filter((s) => !s.undone && matches(s, filter))
+            .sort((a, b) => b.at.localeCompare(a.at) || this.snapshots.indexOf(b) - this.snapshots.indexOf(a));
+        const restored = [];
+        const skipped = [];
+        for (const snapshot of target) {
+            try {
+                if (!snapshot.existed) {
+                    await this.fs.remove(snapshot.path);
+                    snapshot.undone = true;
+                    restored.push({ path: snapshot.path, action: "removed" });
+                }
+                else if (snapshot.content !== undefined) {
+                    await this.fs.write(snapshot.path, snapshot.content);
+                    snapshot.undone = true;
+                    restored.push({ path: snapshot.path, action: "restored" });
+                }
+                else {
+                    skipped.push({ path: snapshot.path, reason: "no pre-image captured (missing or over size cap)" });
+                }
+            }
+            catch (error) {
+                skipped.push({ path: snapshot.path, reason: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        return { restored, skipped };
+    }
+    /** Drop snapshots (all, or only a run's) — e.g. after session cleanup. */
+    clear(runId) {
+        if (runId === undefined) {
+            this.snapshots.length = 0;
+            return;
+        }
+        for (let i = this.snapshots.length - 1; i >= 0; i--) {
+            if (this.snapshots[i]?.runId === runId)
+                this.snapshots.splice(i, 1);
+        }
+    }
+    resolvePath(path) {
+        if (this.workspaceRoot === undefined || isAbsolute(path))
+            return path;
+        return resolvePath(this.workspaceRoot, path);
+    }
+}
+/** Factory mirroring the SDK's create* conventions. */
+export function createFileSnapshotRecorder(config) {
+    return new FileSnapshotRecorder(config);
+}
+function matches(snapshot, filter) {
+    if (filter === undefined)
+        return true;
+    if (filter.runId !== undefined && snapshot.runId !== filter.runId)
+        return false;
+    if (filter.step !== undefined && snapshot.step !== filter.step)
+        return false;
+    if (filter.path !== undefined && snapshot.path !== filter.path)
+        return false;
+    if (filter.toolCallId !== undefined && snapshot.toolCallId !== filter.toolCallId)
+        return false;
+    return true;
+}
+//# sourceMappingURL=file-snapshot.js.map

package/dist/file-snapshot.js.map

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

package/dist/index.d.ts

@@ -6,6 +6,8 @@
 export type { StepExecutorPluginHooks } from "./hooks.js";
 export { StepExecutor } from "./step-executor.js";
 export type { StepExecutorDeps, ToolExecutionPlan, HandoffSignal } from "./step-executor.js";
+export { FileSnapshotRecorder, createFileSnapshotRecorder, createNodeFileSnapshotFs, extractSnapshotPaths, DEFAULT_SNAPSHOT_TOOL_IDS, DEFAULT_SNAPSHOT_PATH_ARGS, DEFAULT_SNAPSHOT_MAX_CONTENT_BYTES, DEFAULT_SNAPSHOT_MAX_COUNT, } from "./file-snapshot.js";
+export type { FileSnapshot, FileSnapshotRef, FileSnapshotFs, FileSnapshotConfig, FileSnapshotFilter, FileSnapshotCaptureParams, FileSnapshotUndoEntry, FileSnapshotUndoSkipped, FileSnapshotUndoResult, } from "./file-snapshot.js";
 export { DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_CALLS_PER_STEP, DOOM_LOOP_THRESHOLD, toolDomain, } from "./kernel-utils.js";
 export { resolveLoopPolicy } from "./loop-policy.js";
 export type { LoopDetectionConfig, LoopDetectionAction, ResolvedLoopPolicy } from "./loop-policy.js";
@@ -19,6 +21,6 @@ export { KernelError } from "./kernel-error.js";
 export type { KernelErrorCode } from "./kernel-error.js";
 export { CircuitBreaker, CircuitBreakerOpenError } from "@vinhnt-sdk/guard";
 export type { CircuitState, CircuitBreakerOptions } from "@vinhnt-sdk/guard";
-export { RunStateMachine } from "./run-state.js";
-export type { RunState } from "./run-state.js";
+export { RunStateMachine, MAX_RETAINED_RUN_STATES } from "./run-state.js";
+export type { RunState, RunStateMachineOptions } from "./run-state.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAI7F,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,mBAAmB,EACnB,UAAU,GACX,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAIrG,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,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAIpH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIjE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAI7E,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}
+{"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,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAI7F,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,kCAAkC,EAClC,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,mBAAmB,EACnB,UAAU,GACX,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAIrG,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,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAIpH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIjE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAI7E,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -5,6 +5,8 @@
  */
 // === Step Executor ===
 export { StepExecutor } from "./step-executor.js";
+// === File snapshots → undo (G7.2 / P2-3) ===
+export { FileSnapshotRecorder, createFileSnapshotRecorder, createNodeFileSnapshotFs, extractSnapshotPaths, DEFAULT_SNAPSHOT_TOOL_IDS, DEFAULT_SNAPSHOT_PATH_ARGS, DEFAULT_SNAPSHOT_MAX_CONTENT_BYTES, DEFAULT_SNAPSHOT_MAX_COUNT, } from "./file-snapshot.js";
 // === Kernel Utils (public subset) ===
 export { DEFAULT_MAX_STEPS, DEFAULT_MAX_TOOL_CALLS_PER_STEP, DOOM_LOOP_THRESHOLD, toolDomain, } from "./kernel-utils.js";
 // === Loop Detection Policy (P1-3) ===
@@ -20,5 +22,5 @@ export { KernelError } from "./kernel-error.js";
 // === Circuit Breaker (re-exported from @vinhnt-sdk/guard) ===
 export { CircuitBreaker, CircuitBreakerOpenError } from "@vinhnt-sdk/guard";
 // === Run State ===
-export { RunStateMachine } from "./run-state.js";
+export { RunStateMachine, MAX_RETAINED_RUN_STATES } from "./run-state.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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,uCAAuC;AAEvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,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,+DAA+D;AAE/D,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAG5E,oBAAoB;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"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,8CAA8C;AAE9C,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,kCAAkC,EAClC,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAa5B,uCAAuC;AAEvC,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,mBAAmB,EACnB,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,uCAAuC;AAEvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,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,+DAA+D;AAE/D,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAG5E,oBAAoB;AAEpB,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/kernel-error.d.ts

@@ -1,10 +1,3 @@
-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" | "guardrail_denied" | "validation_error" | "missed_tool_calls";
-/** 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);
-}
+export { KernelError } from "@vinhnt-sdk/schema";
+export type { KernelErrorCode } from "@vinhnt-sdk/schema";
 //# sourceMappingURL=kernel-error.d.ts.map

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

@@ -1 +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,GACnB,kBAAkB,GAClB,kBAAkB,GAClB,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"}
+{"version":3,"file":"kernel-error.d.ts","sourceRoot":"","sources":["../src/kernel-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/kernel-error.js

@@ -1,12 +1,2 @@
-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}`;
-    }
-}
+export { KernelError } from "@vinhnt-sdk/schema";
 //# sourceMappingURL=kernel-error.js.map

package/dist/kernel-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-error.js","sourceRoot":"","sources":["../src/kernel-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAkB9C,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"}
+{"version":3,"file":"kernel-error.js","sourceRoot":"","sources":["../src/kernel-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/permission-gate.d.ts

@@ -1,7 +1,7 @@
 import type { RunId, AgentConfig } from "@vinhnt-sdk/schema";
 import type { ToolRisk, PermissionReply } from "@vinhnt-sdk/tools";
 import type { StepExecutorPluginHooks } from "./hooks.js";
-import type { ApprovalStore } from "@vinhnt-sdk/permission";
+import type { ApprovalStore, PermissionMode, PermissionClassifier, ModeEffectSource } from "@vinhnt-sdk/permission";
 import type { RunEventStore } from "@vinhnt-sdk/session";
 import type { EventBus } from "@vinhnt-sdk/event";
 /** Result of an approval check: allow, deny, or needs approval. */
@@ -17,6 +17,12 @@ export interface PermissionCheckResult {
     allowed: boolean;
     reason?: string;
     needsApproval?: boolean;
+    /**
+     * Set on needsApproval results (G5): whether the ask came from an explicit
+     * `rules` decision or the `risk` floor. The `auto` classifier only ever
+     * auto-approves risk-floor asks — explicit rule asks always prompt.
+     */
+    source?: ModeEffectSource;
 }
 /** Optional ask options for non-standard permission keys (e.g. doom_loop). */
 export interface AskForToolOptions {
@@ -27,6 +33,18 @@ export interface AskForToolOptions {
     readonly forceAsk?: boolean;
     /** Permission key reported to hooks/events. Default: `tool.<name>`. */
     readonly permissionKey?: string;
+    /**
+     * G5: risk of the tool, passed to the `auto` classifier.
+     * Missing risk makes the default classifier fail closed to the dialog.
+     */
+    readonly risk?: string | undefined;
+    /** G5: tool args handed to the `auto` classifier (semantic classification). */
+    readonly args?: Record<string, unknown> | undefined;
+    /**
+     * G5: origin of the ask (`checkTool` result source). The classifier only
+     * runs for `"risk"` asks — absent/`"rules"` asks always open the dialog.
+     */
+    readonly source?: ModeEffectSource | undefined;
 }
 /** Dependencies required by {@link PermissionGate}. */
 export interface PermissionGateDeps {
@@ -47,6 +65,16 @@ export interface PermissionGateDeps {
      * re-requesting variants after timeouts) must not run unbounded.
      */
     readonly maxApprovalAsksPerRun?: number | undefined;
+    /**
+     * G5: Claude-style approval mode (`default`/`acceptEdits`/`plan`/`bypass`/
+     * `auto` + legacy aliases). Undefined = no mode overlay (legacy behavior).
+     */
+    readonly permissionMode?: PermissionMode | undefined;
+    /**
+     * G5: classifier consulted by `auto` mode for risk-floor asks. Defaults to
+     * {@link createRiskPermissionClassifier} (pure, fail-closed).
+     */
+    readonly permissionClassifier?: PermissionClassifier | undefined;
 }
 /** Enforces 4-phase permission gating: global rules, agent perms, dynamic rules, risk defaults. */
 export declare class PermissionGate {
@@ -56,6 +84,12 @@ export declare class PermissionGate {
     private riskOverrides?;
     private topLevelRules;
     private autoApproval;
+    /** G5: Claude-style mode overlay (undefined = legacy pipeline, no overlay). */
+    private mode;
+    /** G5: injected classifier for `auto` mode; falls back to the risk classifier. */
+    private classifier;
+    /** G5: default `auto` classifier — pure, deterministic, fail-closed. */
+    private readonly fallbackClassifier;
     /** Per-approval hard timeout — separate from agent stale threshold. */
     private readonly approvalTimeoutMs;
     /** Safety valve — max approval dialogs per run. */
@@ -67,6 +101,10 @@ export declare class PermissionGate {
     constructor(deps: PermissionGateDeps);
     /** Toggle auto-approval at runtime (mirrors config.autoApprovalEnabled). */
     setAutoApprovalEnabled(enabled: boolean): void;
+    /** G5: set/replace the permission mode at runtime (undefined = no overlay). */
+    setPermissionMode(mode: PermissionMode | undefined): void;
+    /** G5: set/replace the `auto` classifier at runtime (undefined = risk default). */
+    setPermissionClassifier(classifier: PermissionClassifier | undefined): void;
     /**
      * Parse and apply config-level permission rules (OpenCode-style nested `{ tool: "allow|deny|ask" }`).
      * Bare keys are stored as `tool.<name>` so they match {@link checkTool}'s
@@ -87,10 +125,17 @@ export declare class PermissionGate {
     addDoomLoopBypass(toolName: string): void;
     /** Override risk-level defaults (read→allow, write→approval, destructive→deny). */
     setRiskOverrides(overrides?: Partial<Record<ToolRisk, ApprovalDecision>>): void;
+    /**
+     * Map a final effect to the check result, applying the G5 mode overlay
+     * first. With no mode configured the overlay passes through — behavior is
+     * byte-identical to the legacy pipeline.
+     */
+    private decide;
     /**
      * Evaluate whether a tool call is allowed.
-     * 4-phase gate: global rules → agent permissions → dynamic rules → risk defaults.
-     * Returns { allowed, reason, needsApproval }.
+     * 4-phase gate: global rules → agent permissions → dynamic rules → risk defaults,
+     * then the G5 permission-mode overlay (applied inside {@link decide}).
+     * Returns { allowed, reason, needsApproval, source }.
      */
     checkTool(name: string, risk: ToolRisk, args?: Record<string, unknown>, agent?: AgentConfig): PermissionCheckResult;
     /** Check whether combined token count stays within agent's maxTokens limit. */