@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/run/ArtifactTracker.js

@@ -0,0 +1,132 @@
+/**
+ * ArtifactTracker — records meaningful artifact refs during run execution.
+ *
+ * Listens to StreamEvents and identifies:
+ *   - Files written or edited (Write / Edit tool results)
+ *   - Files created by Bash commands (mkdir, touch, cp, git commit, etc.)
+ *   - Structured outputs (e.g., generated configs, test results)
+ *
+ * Design constraint (§14):
+ *   - Only record artifacts valuable for recovery, display, evaluation, or audit
+ *   - Do NOT record every Read or every tool output
+ *   - Judgment: file writes are artifacts, reads are not
+ */
+import { nanoid } from "nanoid";
+export class ArtifactTracker {
+    config;
+    pendingCalls = new Map();
+    recordedPaths = new Set();
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Feed a StreamEvent to the tracker.
+     */
+    async onStreamEvent(event) {
+        switch (event.type) {
+            case "tool_use_start":
+                this.pendingCalls.set(event.toolCall.id, {
+                    toolName: event.toolCall.toolName,
+                    args: event.toolCall.args,
+                });
+                break;
+            case "tool_result": {
+                const call = this.pendingCalls.get(event.result.id);
+                if (!call)
+                    break;
+                this.pendingCalls.delete(event.result.id);
+                // Only track successful results
+                if (event.result.isError || event.result.error)
+                    break;
+                await this.processToolResult(call, event.result.result);
+                break;
+            }
+        }
+    }
+    /** Get all recorded artifact paths. */
+    getRecordedPaths() {
+        return [...this.recordedPaths];
+    }
+    // ─── Internal ──────────────────────────────────────────────────
+    async processToolResult(call, resultText) {
+        switch (call.toolName) {
+            case "Write":
+                await this.recordFileArtifact(call.args.file_path, "output", "file");
+                break;
+            case "Edit":
+                await this.recordFileArtifact(call.args.file_path, "output", "file");
+                break;
+            case "Bash":
+                await this.extractBashArtifacts(call.args.command, resultText);
+                break;
+            case "NotebookEdit":
+                if (call.args.notebook_path) {
+                    await this.recordFileArtifact(call.args.notebook_path, "output", "document");
+                }
+                break;
+        }
+    }
+    async recordFileArtifact(filePath, role, kind) {
+        if (!filePath)
+            return;
+        // Reject path traversal attempts
+        if (filePath.includes(".."))
+            return;
+        // Deduplicate — only record each path once per run
+        if (this.recordedPaths.has(filePath))
+            return;
+        this.recordedPaths.add(filePath);
+        const ref = {
+            artifactRefId: nanoid(12),
+            runId: this.config.runId,
+            kind,
+            title: extractFileName(filePath),
+            locator: filePath,
+            role,
+            version: null,
+            metadata: {},
+        };
+        await this.config.store.appendArtifactRef(ref);
+    }
+    /**
+     * Extract artifact refs from Bash commands.
+     * Only track commands that clearly produce files.
+     */
+    async extractBashArtifacts(command, _resultText) {
+        if (!command)
+            return;
+        const trimmed = command.trim();
+        // git commit — the commit itself is an artifact
+        if (/^git\s+commit\b/.test(trimmed)) {
+            const ref = {
+                artifactRefId: nanoid(12),
+                runId: this.config.runId,
+                kind: "resource",
+                title: "git commit",
+                locator: "git:HEAD",
+                role: "output",
+                version: null,
+                metadata: { command: trimmed.slice(0, 200) },
+            };
+            await this.config.store.appendArtifactRef(ref);
+            return;
+        }
+        // Redirect output: command > file or command >> file
+        const redirectMatch = trimmed.match(/>\s*(\S+)\s*$/);
+        if (redirectMatch) {
+            await this.recordFileArtifact(redirectMatch[1], "output", "file");
+            return;
+        }
+        // cp / mv — destination is an artifact
+        const cpMvMatch = trimmed.match(/^(?:cp|mv)\s+.*\s+(\S+)\s*$/);
+        if (cpMvMatch) {
+            await this.recordFileArtifact(cpMvMatch[1], "output", "file");
+            return;
+        }
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────
+function extractFileName(filePath) {
+    const parts = filePath.split("/");
+    return parts[parts.length - 1] || filePath;
+}

package/dist/run/CheckpointWriter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CheckpointWriter — extracts structured checkpoints from Engine execution.
+ *
+ * Checkpoint sources (per design doc §12):
+ *   1. Lifecycle — run started, resumed, completed (handled by RunManager)
+ *   2. Phase boundary — detected from assistant messages via keyword heuristics
+ *   3. Waiting — entering waiting_input / waiting_approval (handled by RunManager)
+ *   4. Final — terminal state (handled by RunManager)
+ *
+ * This writer handles #2 (phase boundary) and periodic turn-based checkpoints.
+ * It listens to StreamEvents and writes checkpoints to RunStore when triggered.
+ *
+ * Design constraints (§12.1):
+ *   - Do NOT checkpoint every tool call
+ *   - Do NOT depend on model real-time summarization
+ *   - Checkpoint = "state summary + pointers", not "full text copy"
+ */
+import type { StreamEvent } from "../types.js";
+import type { RunStore } from "./RunStore.js";
+export interface CheckpointWriterConfig {
+    runId: string;
+    objective: string;
+    store: RunStore;
+    /** Write a periodic checkpoint every N turns. 0 = disabled. Default: 10 */
+    turnInterval?: number;
+}
+export declare class CheckpointWriter {
+    private readonly config;
+    private readonly turnInterval;
+    private currentTurn;
+    private lastCheckpointTurn;
+    private touchedTools;
+    private lastAssistantText;
+    private sessionId;
+    private detectedPhases;
+    constructor(config: CheckpointWriterConfig);
+    /**
+     * Feed a StreamEvent to the writer. Called for every event during execution.
+     */
+    onStreamEvent(event: StreamEvent): Promise<void>;
+    /** Set the linked session ID (called once known after Engine.run starts). */
+    setSessionId(id: string): void;
+    /** Get accumulated touched tools for use in final checkpoint. */
+    getTouchedTools(): string[];
+    private checkPhaseBoundary;
+    private writePeriodicCheckpoint;
+    private writeCheckpoint;
+    /**
+     * Extract a short summary from assistant text.
+     * Takes the first ~300 chars, truncated at sentence boundary.
+     */
+    private extractSummary;
+}

package/dist/run/CheckpointWriter.js

@@ -0,0 +1,135 @@
+/**
+ * CheckpointWriter — extracts structured checkpoints from Engine execution.
+ *
+ * Checkpoint sources (per design doc §12):
+ *   1. Lifecycle — run started, resumed, completed (handled by RunManager)
+ *   2. Phase boundary — detected from assistant messages via keyword heuristics
+ *   3. Waiting — entering waiting_input / waiting_approval (handled by RunManager)
+ *   4. Final — terminal state (handled by RunManager)
+ *
+ * This writer handles #2 (phase boundary) and periodic turn-based checkpoints.
+ * It listens to StreamEvents and writes checkpoints to RunStore when triggered.
+ *
+ * Design constraints (§12.1):
+ *   - Do NOT checkpoint every tool call
+ *   - Do NOT depend on model real-time summarization
+ *   - Checkpoint = "state summary + pointers", not "full text copy"
+ */
+import { nanoid } from "nanoid";
+/**
+ * Known phase keywords — when an assistant message contains these patterns,
+ * we infer a phase transition and write a boundary checkpoint.
+ */
+const PHASE_PATTERNS = [
+    { pattern: /\bplan\b.*\b(ready|complete|done|finalized)\b/i, phase: "plan_ready" },
+    { pattern: /\bresearch\b.*\b(complete|done|finished)\b/i, phase: "research_complete" },
+    { pattern: /\banalysis\b.*\b(complete|done|finished)\b/i, phase: "analysis_complete" },
+    { pattern: /\bimplementation\b.*\b(complete|done|finished)\b/i, phase: "implementation_complete" },
+    { pattern: /\bdraft\b.*\b(generated|ready|complete)\b/i, phase: "draft_generated" },
+    { pattern: /\btests?\b.*\b(pass|passing|green|complete)\b/i, phase: "tests_passing" },
+    { pattern: /\breview\b.*\b(complete|done|finished)\b/i, phase: "review_complete" },
+    { pattern: /\brefactor\b.*\b(complete|done|finished)\b/i, phase: "refactor_complete" },
+];
+export class CheckpointWriter {
+    config;
+    turnInterval;
+    currentTurn = 0;
+    lastCheckpointTurn = 0;
+    touchedTools = new Set();
+    lastAssistantText = "";
+    sessionId = null;
+    detectedPhases = new Set();
+    constructor(config) {
+        this.config = config;
+        this.turnInterval = config.turnInterval ?? 10;
+    }
+    /**
+     * Feed a StreamEvent to the writer. Called for every event during execution.
+     */
+    async onStreamEvent(event) {
+        switch (event.type) {
+            case "stream_request_start":
+                this.currentTurn = event.turnNumber;
+                break;
+            case "tool_use_start":
+                this.touchedTools.add(event.toolCall.toolName);
+                break;
+            case "assistant_message": {
+                const text = typeof event.message.content === "string"
+                    ? event.message.content
+                    : event.message.content
+                        .filter((b) => b.type === "text")
+                        .map((b) => b.text ?? "")
+                        .join("");
+                this.lastAssistantText = text;
+                // Check for phase boundary
+                await this.checkPhaseBoundary(text);
+                break;
+            }
+            case "turn_complete":
+                // Periodic checkpoint
+                if (this.turnInterval > 0 &&
+                    this.currentTurn - this.lastCheckpointTurn >= this.turnInterval) {
+                    await this.writePeriodicCheckpoint();
+                }
+                break;
+        }
+    }
+    /** Set the linked session ID (called once known after Engine.run starts). */
+    setSessionId(id) {
+        this.sessionId = id;
+    }
+    /** Get accumulated touched tools for use in final checkpoint. */
+    getTouchedTools() {
+        return [...this.touchedTools];
+    }
+    // ─── Internal ──────────────────────────────────────────────────
+    async checkPhaseBoundary(text) {
+        for (const { pattern, phase } of PHASE_PATTERNS) {
+            if (pattern.test(text) && !this.detectedPhases.has(phase)) {
+                this.detectedPhases.add(phase);
+                await this.writeCheckpoint(phase, this.extractSummary(text));
+                break; // One phase per message
+            }
+        }
+    }
+    async writePeriodicCheckpoint() {
+        this.lastCheckpointTurn = this.currentTurn;
+        await this.writeCheckpoint(`turn_${this.currentTurn}`, this.extractSummary(this.lastAssistantText));
+    }
+    async writeCheckpoint(phase, summary) {
+        const checkpoint = {
+            checkpointId: nanoid(12),
+            runId: this.config.runId,
+            createdAt: Date.now(),
+            phase,
+            objective: this.config.objective,
+            summary,
+            nextAction: null,
+            linkedSessionId: this.sessionId,
+            touchedTools: [...this.touchedTools],
+            touchedArtifacts: [],
+            waitingFor: null,
+            evaluator: null,
+            metadata: { turn: this.currentTurn },
+        };
+        await this.config.store.saveCheckpoint(checkpoint);
+    }
+    /**
+     * Extract a short summary from assistant text.
+     * Takes the first ~300 chars, truncated at sentence boundary.
+     */
+    extractSummary(text) {
+        if (!text)
+            return "(no summary available)";
+        const truncated = text.slice(0, 400);
+        // Try to break at last sentence boundary
+        const lastPeriod = truncated.lastIndexOf(".");
+        const lastNewline = truncated.lastIndexOf("\n");
+        const breakPoint = Math.max(lastPeriod, lastNewline);
+        if (breakPoint > 100) {
+            return truncated.slice(0, breakPoint + 1).trim();
+        }
+        return truncated.trim() + (text.length > 400 ? "..." : "");
+    }
+}

package/dist/run/EngineRunner.d.ts

@@ -0,0 +1,72 @@
+/**
+ * EngineRunner — bridges a RunSnapshot into an Engine.run() call.
+ *
+ * Responsibilities:
+ *   - Prepare EngineConfig from run snapshot
+ *   - Start or resume a session
+ *   - Inject run-aware approval backend and askUser adapter
+ *   - Forward stream events to RunManager
+ *   - Return execution result (does NOT manage run state transitions)
+ */
+import { type EngineConfig, type EngineHookConfig } from "../engine/engine.js";
+import type { LLMConfig, RegisteredTool } from "../types.js";
+import type { RunSnapshot, RunExecutionContext, RunExecutionResult } from "./types.js";
+import { type RunLifecycleHooks } from "./RunApprovalBackend.js";
+/**
+ * Handles returned from execute() to allow RunManager to resolve
+ * pending approvals and user input while Engine is suspended.
+ */
+export interface RunExecutionHandle {
+    /** Resolve a pending tool approval. Returns false if nothing was pending. */
+    resolveApproval: (approved: boolean, reason?: string) => boolean;
+    /** Resolve a pending user input request. Returns false if nothing was pending. */
+    resolveInput: (answer: string) => boolean;
+    /** Check if there's a pending approval. */
+    hasPendingApproval: () => boolean;
+    /** Check if there's a pending input request. */
+    hasPendingInput: () => boolean;
+}
+/**
+ * The contract for executing a Run. RunManager delegates to this interface.
+ *
+ * EngineRunner is the built-in implementation (calls CodeShell's LLM Engine).
+ * External services can implement this to plug in any execution backend:
+ *   - CI/CD pipeline runners
+ *   - ETL orchestrators
+ *   - Multi-agent coordinators
+ *   - Custom API call chains
+ */
+export interface RunExecutor {
+    execute(run: RunSnapshot, context: RunExecutionContext, lifecycleHooks?: RunLifecycleHooks, onHandleReady?: (handle: RunExecutionHandle) => void): Promise<{
+        result: RunExecutionResult;
+        handle: RunExecutionHandle;
+    }>;
+}
+export interface CustomToolEntry {
+    definition: RegisteredTool;
+    execute: (args: Record<string, unknown>) => Promise<string>;
+}
+export interface EngineRunnerConfig {
+    llm: LLMConfig;
+    maxTurns?: number;
+    maxContextTokens?: number;
+    sessionStorageDir?: string;
+    permissionMode?: EngineConfig["permissionMode"];
+    enabledBuiltinTools?: string[];
+    disabledBuiltinTools?: string[];
+    customSystemPrompt?: string;
+    appendSystemPrompt?: string;
+    mcpServers?: EngineConfig["mcpServers"];
+    /** Custom tools registered by the product adapter. */
+    customTools?: CustomToolEntry[];
+    /** Hooks registered into each Engine instance before run execution. */
+    hooks?: EngineHookConfig[];
+}
+export declare class EngineRunner implements RunExecutor {
+    private readonly config;
+    constructor(config: EngineRunnerConfig);
+    execute(run: RunSnapshot, context: RunExecutionContext, lifecycleHooks?: RunLifecycleHooks, onHandleReady?: (handle: RunExecutionHandle) => void): Promise<{
+        result: RunExecutionResult;
+        handle: RunExecutionHandle;
+    }>;
+}

package/dist/run/EngineRunner.js

@@ -0,0 +1,119 @@
+/**
+ * EngineRunner — bridges a RunSnapshot into an Engine.run() call.
+ *
+ * Responsibilities:
+ *   - Prepare EngineConfig from run snapshot
+ *   - Start or resume a session
+ *   - Inject run-aware approval backend and askUser adapter
+ *   - Forward stream events to RunManager
+ *   - Return execution result (does NOT manage run state transitions)
+ */
+import { Engine } from "../engine/engine.js";
+import { RunApprovalBackend, createRunAskUserFn, } from "./RunApprovalBackend.js";
+import { createInProcessClient } from "../protocol/helpers.js";
+// ─── EngineRunner (built-in RunExecutor) ────────────────────────
+export class EngineRunner {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async execute(run, context, lifecycleHooks, onHandleReady) {
+        // Create run-aware approval backend
+        const approvalBackend = new RunApprovalBackend();
+        // Create run-aware askUser adapter
+        let resolveInputFn = () => false;
+        let hasPendingInputFn = () => false;
+        let askUserFn;
+        if (lifecycleHooks) {
+            approvalBackend.setHooks(lifecycleHooks);
+            const askAdapter = createRunAskUserFn(lifecycleHooks);
+            askUserFn = askAdapter.askUserFn;
+            resolveInputFn = askAdapter.resolveInput;
+            hasPendingInputFn = askAdapter.hasPendingInput;
+        }
+        const handle = {
+            resolveApproval: (approved, reason) => approvalBackend.resolveApproval(approved ? { approved: true } : { approved: false, reason }),
+            resolveInput: resolveInputFn,
+            hasPendingApproval: () => approvalBackend.hasPendingApproval(),
+            hasPendingInput: hasPendingInputFn,
+        };
+        // Expose handle immediately so RunManager can resolve approvals/input
+        // while Engine is suspended
+        onHandleReady?.(handle);
+        const engineConfig = {
+            llm: this.config.llm,
+            cwd: run.cwd,
+            maxTurns: this.config.maxTurns ?? 30,
+            maxContextTokens: this.config.maxContextTokens ?? 200_000,
+            permissionMode: this.config.permissionMode ?? "acceptEdits",
+            preset: run.preset,
+            enabledBuiltinTools: this.config.enabledBuiltinTools,
+            disabledBuiltinTools: this.config.disabledBuiltinTools,
+            customSystemPrompt: this.config.customSystemPrompt,
+            appendSystemPrompt: this.config.appendSystemPrompt,
+            sessionStorageDir: this.config.sessionStorageDir,
+            mcpServers: this.config.mcpServers,
+            hooks: this.config.hooks,
+            approvalBackend,
+            askUser: askUserFn,
+            ...context.engineConfigOverrides,
+        };
+        const engine = new Engine(engineConfig);
+        // Register custom tools from product adapter
+        if (this.config.customTools?.length) {
+            for (const ct of this.config.customTools) {
+                engine.registerCustomTool(ct.definition, ct.execute);
+            }
+        }
+        // Wrap the engine in an in-process AgentServer + AgentClient pair so
+        // the run path goes through the same protocol surface as REPL and
+        // headless CLI. Side effects unique to the server (TaskManager
+        // stream subscription, status notifications, in-process running
+        // lock) now apply to RunManager-launched runs too.
+        //
+        // Approval flow stays on the engineConfig.approvalBackend path that
+        // RunManager already wired — we don't subscribe client.onApprovalRequest
+        // because RunApprovalBackend intercepts approvals inside the engine
+        // before they reach the server's interactive-approval hook.
+        const { client, close } = createInProcessClient(engine, {
+            onStream: context.onStream,
+        });
+        // External AbortSignal → client.cancel. The signal is owned by
+        // RunManager (queue cancel, manual cancel); when it aborts we ask
+        // the server to stop the run, which aborts the underlying engine.run.
+        const onAbort = () => {
+            client.cancel().catch(() => {
+                // best-effort — server may already have torn down
+            });
+        };
+        if (context.signal) {
+            if (context.signal.aborted) {
+                onAbort();
+            }
+            else {
+                context.signal.addEventListener("abort", onAbort, { once: true });
+            }
+        }
+        try {
+            const result = await client.run(run.objective, {
+                cwd: run.cwd,
+                sessionId: run.sessionId ?? undefined,
+            });
+            return {
+                result: {
+                    text: result.text,
+                    reason: result.reason,
+                    sessionId: result.sessionId,
+                    turnCount: result.turnCount,
+                },
+                handle,
+            };
+        }
+        finally {
+            if (context.signal) {
+                context.signal.removeEventListener("abort", onAbort);
+            }
+            close();
+        }
+    }
+}

package/dist/run/Evaluator.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Evaluator — contract for run completion evaluation.
+ *
+ * An evaluator inspects a completed (or about-to-complete) run and produces
+ * a structured verdict. This enables:
+ *   - Automated quality gates before marking a run as "completed"
+ *   - Product-specific acceptance criteria
+ *   - CI/CD integration for agent-driven workflows
+ *
+ * The evaluator is intentionally decoupled from the Engine:
+ *   - It runs AFTER the Engine finishes, not during the turn loop
+ *   - It receives the run snapshot + final checkpoint, not raw messages
+ *   - Its result is written into the checkpoint's `evaluator` field
+ *
+ * Phase 5 provides the contract; concrete implementations are domain-specific.
+ */
+import type { RunSnapshot, RunCheckpoint, RunArtifactRef } from "./types.js";
+export type EvaluatorVerdict = "passed" | "failed" | "warning";
+export interface EvaluatorResult {
+    verdict: EvaluatorVerdict;
+    findings: string[];
+    /** Optional structured data for programmatic consumption. */
+    details?: Record<string, unknown>;
+}
+export interface EvaluatorContext {
+    run: RunSnapshot;
+    checkpoint: RunCheckpoint;
+    artifacts: RunArtifactRef[];
+}
+export interface Evaluator {
+    /** Human-readable name for logging and display. */
+    readonly name: string;
+    /**
+     * Evaluate a run's final state.
+     * Should NOT have side effects beyond reading files/state.
+     * Must be safe to call multiple times on the same run.
+     */
+    evaluate(context: EvaluatorContext): Promise<EvaluatorResult>;
+}
+/**
+ * Default evaluator that always passes. Used when no evaluator is configured.
+ */
+export declare class NoopEvaluator implements Evaluator {
+    readonly name = "noop";
+    evaluate(): Promise<EvaluatorResult>;
+}
+/**
+ * Runs multiple evaluators and merges their results.
+ * The overall verdict is the worst across all evaluators.
+ */
+export declare class CompositeEvaluator implements Evaluator {
+    readonly name: string;
+    private readonly evaluators;
+    constructor(evaluators: Evaluator[]);
+    evaluate(context: EvaluatorContext): Promise<EvaluatorResult>;
+}

package/dist/run/Evaluator.js

@@ -0,0 +1,62 @@
+/**
+ * Evaluator — contract for run completion evaluation.
+ *
+ * An evaluator inspects a completed (or about-to-complete) run and produces
+ * a structured verdict. This enables:
+ *   - Automated quality gates before marking a run as "completed"
+ *   - Product-specific acceptance criteria
+ *   - CI/CD integration for agent-driven workflows
+ *
+ * The evaluator is intentionally decoupled from the Engine:
+ *   - It runs AFTER the Engine finishes, not during the turn loop
+ *   - It receives the run snapshot + final checkpoint, not raw messages
+ *   - Its result is written into the checkpoint's `evaluator` field
+ *
+ * Phase 5 provides the contract; concrete implementations are domain-specific.
+ */
+// ─── Built-in: Noop Evaluator ────────────────────────────────────
+/**
+ * Default evaluator that always passes. Used when no evaluator is configured.
+ */
+export class NoopEvaluator {
+    name = "noop";
+    async evaluate() {
+        return { verdict: "passed", findings: [] };
+    }
+}
+// ─── Built-in: Composite Evaluator ──────────────────────────────
+/**
+ * Runs multiple evaluators and merges their results.
+ * The overall verdict is the worst across all evaluators.
+ */
+export class CompositeEvaluator {
+    name;
+    evaluators;
+    constructor(evaluators) {
+        this.evaluators = evaluators;
+        this.name = `composite(${evaluators.map((e) => e.name).join(", ")})`;
+    }
+    async evaluate(context) {
+        const allFindings = [];
+        let worstVerdict = "passed";
+        const details = {};
+        for (const evaluator of this.evaluators) {
+            const result = await evaluator.evaluate(context);
+            allFindings.push(...result.findings.map((f) => `[${evaluator.name}] ${f}`));
+            if (result.verdict === "failed") {
+                worstVerdict = "failed";
+            }
+            else if (result.verdict === "warning" && worstVerdict !== "failed") {
+                worstVerdict = "warning";
+            }
+            if (result.details) {
+                details[evaluator.name] = result.details;
+            }
+        }
+        return {
+            verdict: worstVerdict,
+            findings: allFindings,
+            details: Object.keys(details).length > 0 ? details : undefined,
+        };
+    }
+}

package/dist/run/FileRunStore.d.ts

@@ -0,0 +1,39 @@
+/**
+ * FileRunStore — local filesystem implementation of RunStore.
+ *
+ * Layout:
+ *   ~/.code-shell/runs/<runId>/
+ *     run.json              — current snapshot
+ *     events.jsonl          — append-only event log
+ *     checkpoints/<id>.json — structured checkpoints
+ *     approvals/<id>.json   — approval records
+ *     artifacts/refs.jsonl  — artifact reference log
+ */
+import type { RunStore } from "./RunStore.js";
+import type { RunSnapshot, RunEvent, RunCheckpoint, RunApproval, RunArtifactRef, ListRunsQuery } from "./types.js";
+export declare class FileRunStore implements RunStore {
+    private readonly runsDir;
+    constructor(storageDir?: string);
+    private runDir;
+    private ensureRunDir;
+    private writeJson;
+    private readJson;
+    /** Serializes concurrent JSONL appends per file path. */
+    private readonly appendLocks;
+    private appendJsonl;
+    private readJsonl;
+    create(snapshot: RunSnapshot): Promise<void>;
+    update(snapshot: RunSnapshot): Promise<void>;
+    get(runId: string): Promise<RunSnapshot | null>;
+    list(query?: ListRunsQuery): Promise<RunSnapshot[]>;
+    delete(runId: string): Promise<void>;
+    appendEvent(event: RunEvent): Promise<void>;
+    listEvents(runId: string): Promise<RunEvent[]>;
+    saveCheckpoint(cp: RunCheckpoint): Promise<void>;
+    getLatestCheckpoint(runId: string): Promise<RunCheckpoint | null>;
+    saveApproval(approval: RunApproval): Promise<void>;
+    getApproval(runId: string, approvalId: string): Promise<RunApproval | null>;
+    getPendingApproval(runId: string): Promise<RunApproval | null>;
+    appendArtifactRef(ref: RunArtifactRef): Promise<void>;
+    listArtifactRefs(runId: string): Promise<RunArtifactRef[]>;
+}