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

package/dist/run/RunQueue.d.ts

@@ -0,0 +1,27 @@
+/**
+ * RunQueue — simple in-process FIFO queue with configurable concurrency.
+ *
+ * Phase 1: single-process, no persistence.
+ * The queue holds run IDs; the actual execution is delegated to a callback.
+ */
+export interface RunQueueConfig {
+    concurrency?: number;
+}
+export type RunQueueExecutor = (runId: string) => Promise<void>;
+export declare class RunQueue {
+    private readonly concurrency;
+    private readonly pending;
+    private readonly active;
+    private executor;
+    private draining;
+    constructor(config?: RunQueueConfig);
+    setExecutor(fn: RunQueueExecutor): void;
+    enqueue(runId: string): void;
+    cancel(runId: string): boolean;
+    isActive(runId: string): boolean;
+    isPending(runId: string): boolean;
+    get activeCount(): number;
+    get pendingCount(): number;
+    private drain;
+    private processNext;
+}

package/dist/run/RunQueue.js

@@ -0,0 +1,73 @@
+/**
+ * RunQueue — simple in-process FIFO queue with configurable concurrency.
+ *
+ * Phase 1: single-process, no persistence.
+ * The queue holds run IDs; the actual execution is delegated to a callback.
+ */
+export class RunQueue {
+    concurrency;
+    pending = [];
+    active = new Set();
+    executor = null;
+    draining = false;
+    constructor(config) {
+        this.concurrency = config?.concurrency ?? 1;
+    }
+    setExecutor(fn) {
+        this.executor = fn;
+    }
+    enqueue(runId) {
+        if (this.pending.includes(runId) || this.active.has(runId))
+            return;
+        this.pending.push(runId);
+        this.drain();
+    }
+    cancel(runId) {
+        const idx = this.pending.indexOf(runId);
+        if (idx !== -1) {
+            this.pending.splice(idx, 1);
+            return true;
+        }
+        return false;
+    }
+    isActive(runId) {
+        return this.active.has(runId);
+    }
+    isPending(runId) {
+        return this.pending.includes(runId);
+    }
+    get activeCount() {
+        return this.active.size;
+    }
+    get pendingCount() {
+        return this.pending.length;
+    }
+    drain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        // Schedule on next microtask to batch enqueues
+        queueMicrotask(() => {
+            this.draining = false;
+            this.processNext();
+        });
+    }
+    processNext() {
+        if (!this.executor)
+            return;
+        while (this.active.size < this.concurrency && this.pending.length > 0) {
+            const runId = this.pending.shift();
+            this.active.add(runId);
+            this.executor(runId)
+                .catch((err) => {
+                // Executor (RunManager.executeRun) handles state transitions
+                // in its own try/catch. Log here as a safety net.
+                console.error(`[RunQueue] Executor error for run ${runId}:`, err);
+            })
+                .finally(() => {
+                this.active.delete(runId);
+                this.processNext();
+            });
+        }
+    }
+}

package/dist/run/RunStore.d.ts

@@ -0,0 +1,25 @@
+/**
+ * RunStore — persistence interface for Run lifecycle data.
+ *
+ * Implementations must guarantee:
+ *   - Snapshot writes are atomic (no partial state on crash)
+ *   - Event appends are append-only and ordered
+ *   - Checkpoint / approval reads return the latest version
+ */
+import type { RunSnapshot, RunEvent, RunCheckpoint, RunApproval, RunArtifactRef, ListRunsQuery } from "./types.js";
+export interface RunStore {
+    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[]>;
+}

package/dist/run/RunStore.js

@@ -0,0 +1,9 @@
+/**
+ * RunStore — persistence interface for Run lifecycle data.
+ *
+ * Implementations must guarantee:
+ *   - Snapshot writes are atomic (no partial state on crash)
+ *   - Event appends are append-only and ordered
+ *   - Checkpoint / approval reads return the latest version
+ */
+export {};

package/dist/run/factory.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SDK convenience factory — create a RunManager with sensible defaults.
+ *
+ * Usage from an external repo:
+ * ```ts
+ * import { createRunManager } from "code-shell";
+ *
+ * const manager = createRunManager({
+ *   llm: {
+ *     provider: "openai",
+ *     model: "anthropic/claude-sonnet-4",
+ *     apiKey: process.env.OPENROUTER_API_KEY,
+ *     baseUrl: "https://openrouter.ai/api/v1",
+ *   },
+ * });
+ *
+ * const run = await manager.submit({ objective: "Refactor the auth module" });
+ * ```
+ */
+import type { LLMConfig, PermissionMode } from "../types.js";
+import type { EngineConfig, EngineHookConfig } from "../engine/engine.js";
+import type { Evaluator } from "./Evaluator.js";
+import { RunManager } from "./RunManager.js";
+export interface CreateRunManagerOptions {
+    /** LLM configuration (required). */
+    llm: LLMConfig;
+    /** Working directory. Default: process.cwd() */
+    cwd?: string;
+    /** Max turns per engine execution. Default: 30 */
+    maxTurns?: number;
+    /** Max context tokens. Default: 200_000 */
+    maxContextTokens?: number;
+    /** Permission mode. Default: "acceptEdits" */
+    permissionMode?: PermissionMode;
+    /** Queue concurrency. Default: 1 */
+    concurrency?: number;
+    /** Custom storage directory for runs. Default: ~/.code-shell/runs */
+    runsDir?: string;
+    /** Custom storage directory for sessions. Default: ~/.code-shell/sessions */
+    sessionStorageDir?: string;
+    /** MCP servers to connect. */
+    mcpServers?: EngineConfig["mcpServers"];
+    /** Enabled builtin tools (add to preset defaults). */
+    enabledBuiltinTools?: string[];
+    /** Disabled builtin tools (remove from preset defaults). */
+    disabledBuiltinTools?: string[];
+    /** Custom system prompt (replaces preset prompt). */
+    customSystemPrompt?: string;
+    /** Append to system prompt (added after preset prompt). */
+    appendSystemPrompt?: string;
+    /** Optional evaluator for run completion. */
+    evaluator?: Evaluator;
+    /** Hooks registered into each Engine instance before run execution. */
+    hooks?: EngineHookConfig[];
+    /** Tags applied to every submitted run unless already present. */
+    defaultTags?: string[];
+    /** Metadata merged into every submitted run. Submit input wins on conflicts. */
+    defaultMetadata?: Record<string, unknown>;
+}
+/**
+ * Create a fully configured RunManager with one call.
+ */
+export declare function createRunManager(options: CreateRunManagerOptions): RunManager;

package/dist/run/factory.js

@@ -0,0 +1,51 @@
+/**
+ * SDK convenience factory — create a RunManager with sensible defaults.
+ *
+ * Usage from an external repo:
+ * ```ts
+ * import { createRunManager } from "code-shell";
+ *
+ * const manager = createRunManager({
+ *   llm: {
+ *     provider: "openai",
+ *     model: "anthropic/claude-sonnet-4",
+ *     apiKey: process.env.OPENROUTER_API_KEY,
+ *     baseUrl: "https://openrouter.ai/api/v1",
+ *   },
+ * });
+ *
+ * const run = await manager.submit({ objective: "Refactor the auth module" });
+ * ```
+ */
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { RunManager } from "./RunManager.js";
+import { FileRunStore } from "./FileRunStore.js";
+/**
+ * Create a fully configured RunManager with one call.
+ */
+export function createRunManager(options) {
+    const runsDir = options.runsDir ?? join(homedir(), ".code-shell", "runs");
+    const store = new FileRunStore(runsDir);
+    return new RunManager({
+        store,
+        executor: {
+            llm: options.llm,
+            maxTurns: options.maxTurns ?? 30,
+            maxContextTokens: options.maxContextTokens ?? 200_000,
+            permissionMode: options.permissionMode ?? "acceptEdits",
+            sessionStorageDir: options.sessionStorageDir,
+            mcpServers: options.mcpServers,
+            enabledBuiltinTools: options.enabledBuiltinTools,
+            disabledBuiltinTools: options.disabledBuiltinTools,
+            customSystemPrompt: options.customSystemPrompt,
+            appendSystemPrompt: options.appendSystemPrompt,
+            hooks: options.hooks,
+        },
+        concurrency: options.concurrency ?? 1,
+        runsDir,
+        evaluator: options.evaluator,
+        defaultTags: options.defaultTags,
+        defaultMetadata: options.defaultMetadata,
+    });
+}

package/dist/run/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Run module — managed agent run lifecycle.
+ */
+export type { RunStatus, RunSnapshot, RunEventType, RunEvent, RunCheckpoint, ApprovalStatus, ApprovalCategory, RunApproval, ArtifactKind, ArtifactRole, RunArtifactRef, SubmitRunInput, ResumeRunInput, ListRunsQuery, RunExecutionContext, RunExecutionResult, RunStreamEvent, RunStreamCallback, DetachFn, } from "./types.js";
+export { VALID_TRANSITIONS } from "./types.js";
+export type { RunStore } from "./RunStore.js";
+export { FileRunStore } from "./FileRunStore.js";
+export { RunQueue } from "./RunQueue.js";
+export { RunApprovalBackend, createRunAskUserFn, type RunLifecycleHooks, type PendingApproval, type PendingInput, } from "./RunApprovalBackend.js";
+export { CheckpointWriter, type CheckpointWriterConfig } from "./CheckpointWriter.js";
+export { ArtifactTracker, type ArtifactTrackerConfig } from "./ArtifactTracker.js";
+export { RunLock, type RunLockConfig } from "./RunLock.js";
+export { Heartbeat, type HeartbeatConfig, type HeartbeatData } from "./Heartbeat.js";
+export { NoopEvaluator, CompositeEvaluator, type Evaluator, type EvaluatorResult, type EvaluatorVerdict, type EvaluatorContext, } from "./Evaluator.js";
+export { EngineRunner, type EngineRunnerConfig, type RunExecutionHandle, type RunExecutor, type CustomToolEntry, } from "./EngineRunner.js";
+export { RunManager, type RunManagerConfig } from "./RunManager.js";
+export { createRunManager, type CreateRunManagerOptions } from "./factory.js";

package/dist/run/index.js

@@ -0,0 +1,23 @@
+/**
+ * Run module — managed agent run lifecycle.
+ */
+export { VALID_TRANSITIONS } from "./types.js";
+export { FileRunStore } from "./FileRunStore.js";
+// Queue
+export { RunQueue } from "./RunQueue.js";
+// Approval / Input adapters
+export { RunApprovalBackend, createRunAskUserFn, } from "./RunApprovalBackend.js";
+// Checkpoint & Artifacts
+export { CheckpointWriter } from "./CheckpointWriter.js";
+export { ArtifactTracker } from "./ArtifactTracker.js";
+// Hardening
+export { RunLock } from "./RunLock.js";
+export { Heartbeat } from "./Heartbeat.js";
+// Evaluator
+export { NoopEvaluator, CompositeEvaluator, } from "./Evaluator.js";
+// Runner
+export { EngineRunner, } from "./EngineRunner.js";
+// Manager
+export { RunManager } from "./RunManager.js";
+// Factory
+export { createRunManager } from "./factory.js";

package/dist/run/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Run — managed lifecycle types for long-running agent tasks.
+ *
+ * A Run wraps one or more Engine executions with queue, state machine,
+ * checkpoint, approval, and artifact tracking.
+ */
+import type { AgentPresetName } from "../preset/index.js";
+export type RunStatus = "queued" | "running" | "waiting_input" | "waiting_approval" | "blocked" | "completed" | "failed" | "cancelled";
+export interface RunSnapshot {
+    runId: string;
+    objective: string;
+    preset: AgentPresetName;
+    cwd: string;
+    status: RunStatus;
+    createdAt: number;
+    updatedAt: number;
+    startedAt: number | null;
+    finishedAt: number | null;
+    parentRunId: string | null;
+    sessionId: string | null;
+    childSessionIds: string[];
+    attemptCount: number;
+    latestCheckpointId: string | null;
+    latestApprovalId: string | null;
+    summary: string | null;
+    error: string | null;
+    tags: string[];
+    metadata: Record<string, unknown>;
+}
+export type RunEventType = "run_created" | "run_queued" | "run_started" | "session_linked" | "checkpoint_written" | "artifact_recorded" | "approval_requested" | "approval_resolved" | "run_blocked" | "run_resumed" | "run_completed" | "run_failed" | "run_cancelled";
+export interface RunEvent {
+    eventId: string;
+    runId: string;
+    type: RunEventType;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+export interface RunCheckpoint {
+    checkpointId: string;
+    runId: string;
+    createdAt: number;
+    phase: string;
+    objective: string;
+    summary: string;
+    nextAction: string | null;
+    linkedSessionId: string | null;
+    touchedTools: string[];
+    touchedArtifacts: string[];
+    waitingFor: null | {
+        kind: "input";
+        prompt: string;
+    } | {
+        kind: "approval";
+        approvalId: string;
+    };
+    evaluator: null | {
+        status: "pending" | "passed" | "failed";
+        findings: string[];
+    };
+    metadata: Record<string, unknown>;
+}
+export type ApprovalStatus = "pending" | "approved" | "rejected";
+export type ApprovalCategory = "tool" | "artifact_publish" | "workflow_transition" | "custom";
+export interface RunApproval {
+    approvalId: string;
+    runId: string;
+    createdAt: number;
+    resolvedAt: number | null;
+    status: ApprovalStatus;
+    category: ApprovalCategory;
+    title: string;
+    description: string;
+    payload: Record<string, unknown>;
+}
+export type ArtifactKind = "file" | "document" | "diagram" | "prototype" | "resource" | "custom";
+export type ArtifactRole = "input" | "output" | "checkpoint" | "supporting";
+export interface RunArtifactRef {
+    artifactRefId: string;
+    runId: string;
+    kind: ArtifactKind;
+    title: string;
+    locator: string;
+    role: ArtifactRole;
+    version: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface SubmitRunInput {
+    objective: string;
+    preset?: AgentPresetName;
+    cwd?: string;
+    parentRunId?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ResumeRunInput {
+    userInput?: string;
+    approvalDecision?: {
+        approvalId: string;
+        approved: boolean;
+        reason?: string;
+    };
+}
+export interface ListRunsQuery {
+    status?: RunStatus | RunStatus[];
+    tag?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface RunExecutionContext {
+    onStream?: import("../types.js").StreamCallback;
+    signal?: AbortSignal;
+    engineConfigOverrides?: Record<string, unknown>;
+}
+export interface RunExecutionResult {
+    text: string;
+    reason: import("../types.js").TerminalReason;
+    sessionId: string;
+    turnCount: number;
+}
+export type RunStreamEvent = {
+    type: "run_status_changed";
+    run: RunSnapshot;
+} | {
+    type: "run_event";
+    event: RunEvent;
+} | {
+    type: "engine_stream";
+    event: import("../types.js").StreamEvent;
+};
+export type RunStreamCallback = (event: RunStreamEvent) => void | Promise<void>;
+export type DetachFn = () => void;
+/**
+ * Valid state transitions for a Run.
+ * Key = current status, Value = allowed next statuses.
+ */
+export declare const VALID_TRANSITIONS: Record<RunStatus, RunStatus[]>;

package/dist/run/types.js

@@ -0,0 +1,28 @@
+/**
+ * Run — managed lifecycle types for long-running agent tasks.
+ *
+ * A Run wraps one or more Engine executions with queue, state machine,
+ * checkpoint, approval, and artifact tracking.
+ */
+// ─── State Machine ───────────────────────────────────────────────
+/**
+ * Valid state transitions for a Run.
+ * Key = current status, Value = allowed next statuses.
+ */
+export const VALID_TRANSITIONS = {
+    queued: ["running", "cancelled"],
+    running: [
+        "waiting_input",
+        "waiting_approval",
+        "blocked",
+        "completed",
+        "failed",
+        "cancelled",
+    ],
+    waiting_input: ["queued", "cancelled"],
+    waiting_approval: ["queued", "cancelled"],
+    blocked: ["queued", "cancelled"],
+    completed: [],
+    failed: [],
+    cancelled: [],
+};

package/dist/runtime/safe-spawn.d.ts

@@ -0,0 +1,118 @@
+/**
+ * SafeSpawn — unified subprocess lifecycle wrapper.
+ *
+ * Responsibilities:
+ *   1. Optional sandbox wrap (Seatbelt / bubblewrap) via {@link SandboxBackend}.
+ *   2. UTF-8 IO drain via {@link StringDecoder} (no half-character corruption
+ *      when a multi-byte sequence spans two `data` events).
+ *   3. Per-stream byte cap with a `truncated` flag (no unbounded buffer fill).
+ *   4. `ctx.signal` abort cascade — SIGTERM, then SIGKILL after
+ *      `ioDrainGraceMs` (default 100ms). This is the snappy path because
+ *      the user is waiting on the cancel.
+ *   5. Hard timeout — SIGTERM, then SIGKILL after 2s. Longer grace because
+ *      we expect the child to be wedged.
+ *   6. Listener cleanup on every exit path (no MaxListeners leak across a
+ *      long session that reuses one AbortSignal across many spawns).
+ *
+ * Explicit non-goals:
+ *
+ *   - Permission classification. {@link ToolExecutor} already classifies
+ *     builtin tools BEFORE the tool function runs; re-classifying here
+ *     would double-prompt. Install/marketplace paths (gitOps) are consented
+ *     at user-initiated install time; see docs/architecture/17.
+ *   - Retries. The caller decides retry policy if any.
+ *   - Output formatting. SafeSpawn returns structured fields and lets the
+ *     caller compose its own user-facing string (Bash's "STDERR:\n…" /
+ *     "Exit code: N" / "Killed by signal: X" formatting lives in bash.ts;
+ *     REPL/PowerShell have their own messages).
+ *
+ * Two entry points, both share the same internal lifecycle:
+ *   - {@link safeSpawn}(file, args, opts) — direct argv spawn. Use from
+ *     REPL, PowerShell, gitOps where the binary + args are known.
+ *   - {@link safeSpawnShell}(command, opts) — runs `command` through the
+ *     sandbox backend (or a plain shell if no sandbox). Use from Bash
+ *     where the LLM provides a free-form shell string.
+ */
+import type { SandboxBackend } from "../tool-system/sandbox/index.js";
+export interface SafeSpawnOptions {
+    /** Process working directory. Required — callers know their cwd; SafeSpawn does not fall back to process.cwd(). */
+    cwd: string;
+    /** Environment for the child. Required — callers decide whether to forward host env (Bash builds a hardened env; REPL/PowerShell/gitOps forward process.env). */
+    env: NodeJS.ProcessEnv;
+    /** Hard timeout in ms. On expiry: SIGTERM, then SIGKILL after 2s. */
+    timeoutMs: number;
+    /** Per-stream max bytes captured. Stream output beyond this is dropped and a `truncated` flag is set. Default {@link DEFAULT_MAX_OUTPUT_BYTES}. */
+    maxOutputBytes?: number;
+    /**
+     * Grace period after SIGTERM before SIGKILL when ABORTING via ctx.signal.
+     * Defaults to {@link DEFAULT_IO_DRAIN_GRACE_MS}. The timeout path uses a
+     * fixed 2s grace because the caller has been waiting; abort comes from
+     * a user cancel where snappiness matters.
+     */
+    ioDrainGraceMs?: number;
+    /** Optional cancellation signal. If already aborted, SafeSpawn resolves immediately without spawning. */
+    signal?: AbortSignal;
+}
+export interface SafeSpawnShellOptions extends SafeSpawnOptions {
+    /** Optional sandbox to wrap the command through. Required for shell-mode. If omitted, the command runs through `shell ?? /bin/bash -c`. */
+    sandbox?: SandboxBackend;
+    /** Shell to invoke when no sandbox is provided (also forwarded to sandbox.wrap()). Default `/bin/bash`. */
+    shell?: string;
+}
+/**
+ * Outcome discriminant for {@link SafeSpawnResult}. Lets SDK callers
+ * `switch (result.reason)` instead of reading three booleans and
+ * deciding which one to branch on first. `ok` is the normal-exit case
+ * (any `exitCode`, including non-zero); `spawn_failed` covers both
+ * synchronous `spawn()` throws and the child's `error` event mid-stream
+ * — both mean "we never got a clean lifecycle". The existing boolean
+ * flags (`timedOut`, `aborted`, `spawnFailed`) are preserved so the
+ * per-tool output formatting in Bash/REPL/PowerShell keeps working;
+ * `reason` is additive.
+ */
+export type SafeSpawnReason = "ok" | "timeout" | "aborted" | "spawn_failed";
+export interface SafeSpawnResult {
+    /**
+     * Discriminant for the outcome. `ok` means the process exited
+     * normally (any `exitCode`, including non-zero). Mutually exclusive
+     * by construction with the boolean flags below — e.g.
+     * `reason === "timeout"` ⇒ `timedOut === true`.
+     */
+    reason: SafeSpawnReason;
+    /** UTF-8 decoded stdout (truncated to `maxOutputBytes` characters when over). */
+    stdout: string;
+    /** UTF-8 decoded stderr (truncated to `maxOutputBytes` characters when over). */
+    stderr: string;
+    /** null when killed by signal without an exit code. */
+    exitCode: number | null;
+    /** Set when the OS reports the child died from a signal. */
+    signal: NodeJS.Signals | null;
+    /** True when stdout was capped. */
+    stdoutTruncated: boolean;
+    /** True when stderr was capped. */
+    stderrTruncated: boolean;
+    /** True when the timeoutMs fired. */
+    timedOut: boolean;
+    /** True when ctx.signal aborted us (including pre-spawn). */
+    aborted: boolean;
+    /** True when the spawn itself failed (file not found, permission). `error` carries the message. */
+    spawnFailed: boolean;
+    /** Spawn error message when spawnFailed is set. */
+    error?: string;
+}
+export declare const DEFAULT_MAX_OUTPUT_BYTES = 1000000;
+export declare const DEFAULT_IO_DRAIN_GRACE_MS = 100;
+/**
+ * Spawn `(file, args)` directly under the unified lifecycle policy. Use this
+ * when you know the binary and args (REPL, PowerShell, gitOps). For shell-
+ * string spawning under a sandbox, see {@link safeSpawnShell}.
+ */
+export declare function safeSpawn(file: string, args: string[], opts: SafeSpawnOptions): Promise<SafeSpawnResult>;
+/**
+ * Spawn a shell `command` string under an optional sandbox. The sandbox
+ * backend decides the actual `(file, args)` (e.g. Seatbelt becomes
+ * `/usr/bin/sandbox-exec -f profile shell -c command`). The backend's
+ * `cleanup` callback is invoked on every exit path — close, error,
+ * abort, timeout, pre-spawn-abort. Used by the Bash tool.
+ */
+export declare function safeSpawnShell(command: string, opts: SafeSpawnShellOptions): Promise<SafeSpawnResult>;