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

package/dist/run/FileRunStore.js

@@ -0,0 +1,176 @@
+/**
+ * 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 { mkdirSync, existsSync, readFileSync, writeFileSync, appendFileSync, readdirSync, renameSync, rmSync, } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+export class FileRunStore {
+    runsDir;
+    constructor(storageDir) {
+        this.runsDir = storageDir ?? join(homedir(), ".code-shell", "runs");
+        mkdirSync(this.runsDir, { recursive: true });
+    }
+    // ─── Helpers ───────────────────────────────────────────────────
+    runDir(runId) {
+        return join(this.runsDir, runId);
+    }
+    ensureRunDir(runId) {
+        const dir = this.runDir(runId);
+        mkdirSync(dir, { recursive: true });
+        mkdirSync(join(dir, "checkpoints"), { recursive: true });
+        mkdirSync(join(dir, "approvals"), { recursive: true });
+        mkdirSync(join(dir, "artifacts"), { recursive: true });
+        return dir;
+    }
+    writeJson(filePath, data) {
+        const tmp = filePath + ".tmp";
+        writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+        // Atomic rename — prevents partial writes on crash
+        renameSync(tmp, filePath);
+    }
+    readJson(filePath) {
+        if (!existsSync(filePath))
+            return null;
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    /** Serializes concurrent JSONL appends per file path. */
+    appendLocks = new Map();
+    async appendJsonl(filePath, data) {
+        // Serialize writes to the same file to prevent interleaved output
+        const prev = this.appendLocks.get(filePath) ?? Promise.resolve();
+        const current = prev.then(() => {
+            appendFileSync(filePath, JSON.stringify(data) + "\n", "utf-8");
+        });
+        this.appendLocks.set(filePath, current);
+        await current;
+    }
+    readJsonl(filePath) {
+        if (!existsSync(filePath))
+            return [];
+        const content = readFileSync(filePath, "utf-8");
+        if (!content)
+            return [];
+        return content
+            .split("\n")
+            .filter((line) => line.trim())
+            .map((line) => JSON.parse(line));
+    }
+    // ─── Snapshot ──────────────────────────────────────────────────
+    async create(snapshot) {
+        const dir = this.ensureRunDir(snapshot.runId);
+        this.writeJson(join(dir, "run.json"), snapshot);
+    }
+    async update(snapshot) {
+        const dir = this.runDir(snapshot.runId);
+        if (!existsSync(dir)) {
+            throw new Error(`Run not found: ${snapshot.runId}`);
+        }
+        this.writeJson(join(dir, "run.json"), snapshot);
+    }
+    async get(runId) {
+        return this.readJson(join(this.runDir(runId), "run.json"));
+    }
+    async list(query) {
+        if (!existsSync(this.runsDir))
+            return [];
+        const entries = readdirSync(this.runsDir, { withFileTypes: true });
+        const snapshots = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const snapshot = this.readJson(join(this.runsDir, entry.name, "run.json"));
+            if (!snapshot)
+                continue;
+            // Filter by status
+            if (query?.status) {
+                const statuses = Array.isArray(query.status) ? query.status : [query.status];
+                if (!statuses.includes(snapshot.status))
+                    continue;
+            }
+            // Filter by tag
+            if (query?.tag && !snapshot.tags.includes(query.tag))
+                continue;
+            snapshots.push(snapshot);
+        }
+        // Sort by createdAt descending (newest first)
+        snapshots.sort((a, b) => b.createdAt - a.createdAt);
+        // Pagination
+        const offset = query?.offset ?? 0;
+        const limit = query?.limit ?? 50;
+        return snapshots.slice(offset, offset + limit);
+    }
+    async delete(runId) {
+        const dir = this.runDir(runId);
+        if (existsSync(dir)) {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    // ─── Events ────────────────────────────────────────────────────
+    async appendEvent(event) {
+        this.ensureRunDir(event.runId);
+        const dir = this.runDir(event.runId);
+        await this.appendJsonl(join(dir, "events.jsonl"), event);
+    }
+    async listEvents(runId) {
+        return this.readJsonl(join(this.runDir(runId), "events.jsonl"));
+    }
+    // ─── Checkpoints ───────────────────────────────────────────────
+    async saveCheckpoint(cp) {
+        const dir = this.runDir(cp.runId);
+        this.writeJson(join(dir, "checkpoints", `${cp.checkpointId}.json`), cp);
+    }
+    async getLatestCheckpoint(runId) {
+        const cpDir = join(this.runDir(runId), "checkpoints");
+        if (!existsSync(cpDir))
+            return null;
+        const files = readdirSync(cpDir).filter((f) => f.endsWith(".json"));
+        if (files.length === 0)
+            return null;
+        // Find the latest by createdAt
+        let latest = null;
+        for (const file of files) {
+            const cp = this.readJson(join(cpDir, file));
+            if (cp && (!latest || cp.createdAt > latest.createdAt)) {
+                latest = cp;
+            }
+        }
+        return latest;
+    }
+    // ─── Approvals ─────────────────────────────────────────────────
+    async saveApproval(approval) {
+        const dir = this.runDir(approval.runId);
+        this.writeJson(join(dir, "approvals", `${approval.approvalId}.json`), approval);
+    }
+    async getApproval(runId, approvalId) {
+        return this.readJson(join(this.runDir(runId), "approvals", `${approvalId}.json`));
+    }
+    async getPendingApproval(runId) {
+        const approvalDir = join(this.runDir(runId), "approvals");
+        if (!existsSync(approvalDir))
+            return null;
+        const files = readdirSync(approvalDir).filter((f) => f.endsWith(".json"));
+        for (const file of files) {
+            const approval = this.readJson(join(approvalDir, file));
+            if (approval?.status === "pending")
+                return approval;
+        }
+        return null;
+    }
+    // ─── Artifact Refs ─────────────────────────────────────────────
+    async appendArtifactRef(ref) {
+        this.ensureRunDir(ref.runId);
+        const dir = this.runDir(ref.runId);
+        await this.appendJsonl(join(dir, "artifacts", "refs.jsonl"), ref);
+    }
+    async listArtifactRefs(runId) {
+        return this.readJsonl(join(this.runDir(runId), "artifacts", "refs.jsonl"));
+    }
+}

package/dist/run/Heartbeat.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Heartbeat — periodic timestamp writer for run liveness detection.
+ *
+ * While a run is executing, the heartbeat writes a timestamp file at regular
+ * intervals. Crash recovery uses this to determine if a "running" run is
+ * actually alive or if its process died without cleanup.
+ *
+ * File: ~/.code-shell/runs/<runId>/heartbeat
+ * Content: JSON { pid, timestamp, runId }
+ */
+export interface HeartbeatConfig {
+    runsDir?: string;
+    /** Heartbeat interval in ms. Default: 5_000 (5 seconds) */
+    intervalMs?: number;
+}
+export interface HeartbeatData {
+    pid: number;
+    timestamp: number;
+    runId: string;
+}
+export declare class Heartbeat {
+    private readonly runsDir;
+    private readonly intervalMs;
+    private timers;
+    constructor(config?: HeartbeatConfig);
+    /**
+     * Start heartbeat for a run. Writes immediately, then repeats on interval.
+     */
+    start(runId: string): void;
+    /**
+     * Stop heartbeat for a run and remove the heartbeat file.
+     */
+    stop(runId: string): void;
+    /**
+     * Stop all heartbeats.
+     */
+    stopAll(): void;
+    /**
+     * Read the last heartbeat for a run. Returns null if no heartbeat exists.
+     */
+    read(runId: string): HeartbeatData | null;
+    /**
+     * Check if a run's heartbeat is stale (older than threshold).
+     * Returns true if stale or missing, false if recent.
+     */
+    isStale(runId: string, thresholdMs?: number): boolean;
+    /**
+     * Check if the process that wrote the heartbeat is still alive.
+     */
+    isProcessAlive(runId: string): boolean;
+    private write;
+    private remove;
+    private filePath;
+}

package/dist/run/Heartbeat.js

@@ -0,0 +1,123 @@
+/**
+ * Heartbeat — periodic timestamp writer for run liveness detection.
+ *
+ * While a run is executing, the heartbeat writes a timestamp file at regular
+ * intervals. Crash recovery uses this to determine if a "running" run is
+ * actually alive or if its process died without cleanup.
+ *
+ * File: ~/.code-shell/runs/<runId>/heartbeat
+ * Content: JSON { pid, timestamp, runId }
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+export class Heartbeat {
+    runsDir;
+    intervalMs;
+    timers = new Map();
+    constructor(config) {
+        this.runsDir = config?.runsDir ?? join(homedir(), ".code-shell", "runs");
+        this.intervalMs = config?.intervalMs ?? 5_000;
+    }
+    /**
+     * Start heartbeat for a run. Writes immediately, then repeats on interval.
+     */
+    start(runId) {
+        // Write first heartbeat immediately
+        this.write(runId);
+        // Schedule periodic heartbeats
+        const timer = setInterval(() => this.write(runId), this.intervalMs);
+        // Unref so the timer doesn't prevent process exit
+        if (typeof timer === "object" && "unref" in timer) {
+            timer.unref();
+        }
+        this.timers.set(runId, timer);
+    }
+    /**
+     * Stop heartbeat for a run and remove the heartbeat file.
+     */
+    stop(runId) {
+        const timer = this.timers.get(runId);
+        if (timer) {
+            clearInterval(timer);
+            this.timers.delete(runId);
+        }
+        this.remove(runId);
+    }
+    /**
+     * Stop all heartbeats.
+     */
+    stopAll() {
+        for (const [runId] of this.timers) {
+            this.stop(runId);
+        }
+    }
+    /**
+     * Read the last heartbeat for a run. Returns null if no heartbeat exists.
+     */
+    read(runId) {
+        const filePath = this.filePath(runId);
+        if (!existsSync(filePath))
+            return null;
+        try {
+            return JSON.parse(readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if a run's heartbeat is stale (older than threshold).
+     * Returns true if stale or missing, false if recent.
+     */
+    isStale(runId, thresholdMs) {
+        const threshold = thresholdMs ?? this.intervalMs * 3;
+        const data = this.read(runId);
+        if (!data)
+            return true;
+        return Date.now() - data.timestamp > threshold;
+    }
+    /**
+     * Check if the process that wrote the heartbeat is still alive.
+     */
+    isProcessAlive(runId) {
+        const data = this.read(runId);
+        if (!data)
+            return false;
+        try {
+            // Sending signal 0 checks if process exists without actually signaling it
+            process.kill(data.pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    write(runId) {
+        const data = {
+            pid: process.pid,
+            timestamp: Date.now(),
+            runId,
+        };
+        try {
+            writeFileSync(this.filePath(runId), JSON.stringify(data), "utf-8");
+        }
+        catch {
+            // Run directory may have been deleted
+        }
+    }
+    remove(runId) {
+        try {
+            const filePath = this.filePath(runId);
+            if (existsSync(filePath)) {
+                unlinkSync(filePath);
+            }
+        }
+        catch {
+            // Already removed
+        }
+    }
+    filePath(runId) {
+        return join(this.runsDir, runId, "heartbeat");
+    }
+}

package/dist/run/RunApprovalBackend.d.ts

@@ -0,0 +1,53 @@
+/**
+ * RunApprovalBackend — bridges Engine's approval system into Run lifecycle.
+ *
+ * When Engine requests tool approval:
+ *   1. Creates a RunApproval record
+ *   2. Notifies RunManager to transition the run to waiting_approval
+ *   3. Suspends the Engine's promise until the user resumes the run
+ *
+ * Similarly for AskUser:
+ *   1. Notifies RunManager to transition the run to waiting_input
+ *   2. Suspends until the user provides input via resume
+ */
+import type { ApprovalRequest, ApprovalResult } from "../types.js";
+import type { ApprovalBackend } from "../tool-system/permission.js";
+import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
+export interface PendingApproval {
+    resolve: (result: ApprovalResult) => void;
+    request: ApprovalRequest;
+}
+export interface PendingInput {
+    resolve: (answer: string) => void;
+    question: string;
+}
+export interface RunLifecycleHooks {
+    onApprovalNeeded: (request: ApprovalRequest) => Promise<{
+        approvalId: string;
+    }>;
+    onInputNeeded: (question: string) => Promise<void>;
+    onApprovalResolved?: (approvalId: string, result: ApprovalResult) => void;
+    onInputResolved?: (answer: string) => void;
+}
+export declare class RunApprovalBackend implements ApprovalBackend {
+    private pendingApproval;
+    private hooks;
+    setHooks(hooks: RunLifecycleHooks): void;
+    /** Max time (ms) to wait for approval before auto-rejecting. Default: 24h */
+    private timeoutMs;
+    setTimeout(ms: number): void;
+    requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
+    /**
+     * Called by RunManager when the user resumes with an approval decision.
+     */
+    resolveApproval(result: ApprovalResult): boolean;
+    hasPendingApproval(): boolean;
+}
+/**
+ * Creates an AskUserFn that suspends the run when user input is needed.
+ */
+export declare function createRunAskUserFn(hooks: RunLifecycleHooks): {
+    askUserFn: AskUserFn;
+    resolveInput: (answer: string) => boolean;
+    hasPendingInput: () => boolean;
+};

package/dist/run/RunApprovalBackend.js

@@ -0,0 +1,85 @@
+/**
+ * RunApprovalBackend — bridges Engine's approval system into Run lifecycle.
+ *
+ * When Engine requests tool approval:
+ *   1. Creates a RunApproval record
+ *   2. Notifies RunManager to transition the run to waiting_approval
+ *   3. Suspends the Engine's promise until the user resumes the run
+ *
+ * Similarly for AskUser:
+ *   1. Notifies RunManager to transition the run to waiting_input
+ *   2. Suspends until the user provides input via resume
+ */
+// ─── RunApprovalBackend ──────────────────────────────────────────
+export class RunApprovalBackend {
+    pendingApproval = null;
+    hooks = null;
+    setHooks(hooks) {
+        this.hooks = hooks;
+    }
+    /** Max time (ms) to wait for approval before auto-rejecting. Default: 24h */
+    timeoutMs = 24 * 60 * 60 * 1000;
+    setTimeout(ms) {
+        this.timeoutMs = ms;
+    }
+    async requestApproval(request) {
+        if (!this.hooks) {
+            // No hooks wired — fall back to auto-approve (shouldn't happen in practice)
+            return { approved: true };
+        }
+        // Notify RunManager that approval is needed
+        const { approvalId } = await this.hooks.onApprovalNeeded(request);
+        // Suspend execution until resolved (with timeout safety net)
+        return new Promise((resolve) => {
+            this.pendingApproval = { resolve, request };
+            const timer = setTimeout(() => {
+                if (this.pendingApproval?.resolve === resolve) {
+                    this.pendingApproval = null;
+                    resolve({ approved: false, reason: "approval timed out" });
+                }
+            }, this.timeoutMs);
+            if (typeof timer === "object" && "unref" in timer) {
+                timer.unref();
+            }
+        });
+    }
+    /**
+     * Called by RunManager when the user resumes with an approval decision.
+     */
+    resolveApproval(result) {
+        if (!this.pendingApproval)
+            return false;
+        const { resolve } = this.pendingApproval;
+        this.pendingApproval = null;
+        resolve(result);
+        return true;
+    }
+    hasPendingApproval() {
+        return this.pendingApproval !== null;
+    }
+}
+// ─── RunAskUserAdapter ───────────────────────────────────────────
+/**
+ * Creates an AskUserFn that suspends the run when user input is needed.
+ */
+export function createRunAskUserFn(hooks) {
+    let pending = null;
+    const askUserFn = async (question) => {
+        // Notify RunManager
+        await hooks.onInputNeeded(question);
+        // Suspend execution until user provides input
+        return new Promise((resolve) => {
+            pending = { resolve, question };
+        });
+    };
+    const resolveInput = (answer) => {
+        if (!pending)
+            return false;
+        const { resolve } = pending;
+        pending = null;
+        resolve(answer);
+        return true;
+    };
+    const hasPendingInput = () => pending !== null;
+    return { askUserFn, resolveInput, hasPendingInput };
+}

package/dist/run/RunLock.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RunLock — file-based locking to prevent multiple workers from executing
+ * the same run concurrently.
+ *
+ * Uses proper-lockfile (via lazy wrapper) for cross-process safe locking.
+ * Each run gets a lock on its run.json file.
+ */
+export interface RunLockConfig {
+    /** Base directory for runs. Default: ~/.code-shell/runs */
+    runsDir?: string;
+    /** Stale lock timeout in ms. Default: 60_000 (1 minute) */
+    staleMs?: number;
+}
+export declare class RunLock {
+    private readonly runsDir;
+    private readonly staleMs;
+    private readonly releaseFns;
+    constructor(config?: RunLockConfig);
+    /**
+     * Acquire a lock for a run. Returns true if acquired, false if already held.
+     */
+    acquire(runId: string): Promise<boolean>;
+    /**
+     * Release the lock for a run.
+     */
+    release(runId: string): Promise<void>;
+    /**
+     * Check if a run is currently locked by any process.
+     */
+    isLocked(runId: string): Promise<boolean>;
+    /**
+     * Force-unlock a stale lock (e.g., after crash recovery).
+     */
+    forceUnlock(runId: string): Promise<void>;
+    /**
+     * Release all locks held by this instance.
+     */
+    releaseAll(): Promise<void>;
+    private lockTarget;
+}

package/dist/run/RunLock.js

@@ -0,0 +1,98 @@
+/**
+ * RunLock — file-based locking to prevent multiple workers from executing
+ * the same run concurrently.
+ *
+ * Uses proper-lockfile (via lazy wrapper) for cross-process safe locking.
+ * Each run gets a lock on its run.json file.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { lock, check, unlock } from "../utils/lockfile.js";
+import { logger } from "../logging/logger.js";
+export class RunLock {
+    runsDir;
+    staleMs;
+    releaseFns = new Map();
+    constructor(config) {
+        this.runsDir = config?.runsDir ?? join(homedir(), ".code-shell", "runs");
+        this.staleMs = config?.staleMs ?? 60_000;
+    }
+    /**
+     * Acquire a lock for a run. Returns true if acquired, false if already held.
+     */
+    async acquire(runId) {
+        const lockTarget = this.lockTarget(runId);
+        if (!existsSync(lockTarget))
+            return false;
+        try {
+            const release = await lock(lockTarget, {
+                stale: this.staleMs,
+                retries: 0,
+            });
+            this.releaseFns.set(runId, release);
+            logger.info("run.lock.acquired", { runId });
+            return true;
+        }
+        catch {
+            // Lock already held by another process
+            return false;
+        }
+    }
+    /**
+     * Release the lock for a run.
+     */
+    async release(runId) {
+        const releaseFn = this.releaseFns.get(runId);
+        if (releaseFn) {
+            try {
+                await releaseFn();
+            }
+            catch {
+                // Lock may already be released (stale cleanup)
+            }
+            this.releaseFns.delete(runId);
+            logger.info("run.lock.released", { runId });
+        }
+    }
+    /**
+     * Check if a run is currently locked by any process.
+     */
+    async isLocked(runId) {
+        const lockTarget = this.lockTarget(runId);
+        if (!existsSync(lockTarget))
+            return false;
+        try {
+            return await check(lockTarget, { stale: this.staleMs });
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Force-unlock a stale lock (e.g., after crash recovery).
+     */
+    async forceUnlock(runId) {
+        const lockTarget = this.lockTarget(runId);
+        if (!existsSync(lockTarget))
+            return;
+        try {
+            await unlock(lockTarget);
+            logger.info("run.lock.force_unlocked", { runId });
+        }
+        catch {
+            // Already unlocked
+        }
+    }
+    /**
+     * Release all locks held by this instance.
+     */
+    async releaseAll() {
+        for (const [runId] of this.releaseFns) {
+            await this.release(runId);
+        }
+    }
+    lockTarget(runId) {
+        return join(this.runsDir, runId, "run.json");
+    }
+}