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

package/dist/runtime/safe-spawn.js

@@ -0,0 +1,268 @@
+/**
+ * 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 { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+export const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
+export const DEFAULT_IO_DRAIN_GRACE_MS = 100;
+const TIMEOUT_SIGKILL_GRACE_MS = 2000;
+/**
+ * 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 function safeSpawn(file, args, opts) {
+    return runLifecycle({
+        file,
+        args,
+        opts,
+        cleanup: undefined,
+    });
+}
+/**
+ * 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 function safeSpawnShell(command, opts) {
+    const shell = opts.shell ?? "/bin/bash";
+    let file;
+    let args;
+    let cleanup;
+    if (opts.sandbox) {
+        const wrapped = opts.sandbox.wrap(command, { cwd: opts.cwd, shell });
+        file = wrapped.file;
+        args = wrapped.args;
+        cleanup = wrapped.cleanup;
+    }
+    else {
+        file = shell;
+        args = ["-c", command];
+    }
+    return runLifecycle({ file, args, opts, cleanup });
+}
+function runLifecycle({ file, args, opts, cleanup }) {
+    const maxBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const abortGrace = opts.ioDrainGraceMs ?? DEFAULT_IO_DRAIN_GRACE_MS;
+    // Pre-spawn abort: don't pay spawn cost.
+    if (opts.signal?.aborted) {
+        safeCleanup(cleanup);
+        return Promise.resolve(emptyResult({ reason: "aborted", aborted: true }));
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            // Always release backend-allocated resources, regardless of exit path.
+            // cleanup is best-effort — see seatbelt backend for rationale.
+            safeCleanup(cleanup);
+            // Remove abort listener so a long-lived AbortSignal (multi-turn
+            // session reusing the same controller) doesn't accumulate listeners.
+            if (opts.signal && onAbort) {
+                opts.signal.removeEventListener("abort", onAbort);
+            }
+            resolve(result);
+        };
+        let child;
+        try {
+            child = spawn(file, args, { cwd: opts.cwd, env: opts.env });
+        }
+        catch (err) {
+            finish(emptyResult({ reason: "spawn_failed", spawnFailed: true, error: err.message }));
+            return;
+        }
+        const stdoutDec = new StringDecoder("utf-8");
+        const stderrDec = new StringDecoder("utf-8");
+        let stdout = "";
+        let stderr = "";
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        let timedOut = false;
+        let aborted = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill("SIGTERM");
+            }
+            catch { /* may already be dead */ }
+            setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { /* ignore */ }
+            }, TIMEOUT_SIGKILL_GRACE_MS).unref();
+        }, opts.timeoutMs);
+        let onAbort;
+        if (opts.signal) {
+            onAbort = () => {
+                aborted = true;
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch { /* may already be dead */ }
+                setTimeout(() => {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch { /* ignore */ }
+                }, abortGrace).unref();
+            };
+            opts.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        child.stdout?.on("data", (chunk) => {
+            if (stdoutTruncated)
+                return;
+            const piece = stdoutDec.write(chunk);
+            if (stdout.length + piece.length > maxBytes) {
+                stdoutTruncated = true;
+                stdout += piece.slice(0, maxBytes - stdout.length);
+            }
+            else {
+                stdout += piece;
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            if (stderrTruncated)
+                return;
+            const piece = stderrDec.write(chunk);
+            if (stderr.length + piece.length > maxBytes) {
+                stderrTruncated = true;
+                stderr += piece.slice(0, maxBytes - stderr.length);
+            }
+            else {
+                stderr += piece;
+            }
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            // Mid-stream child error (e.g. spawn race where the exec fails after
+            // the parent got the ChildProcess handle). SDK-wise this maps to the
+            // same "never got a clean lifecycle" meaning as the synchronous spawn
+            // throw above, so we surface the same reason. If timeout or abort
+            // fired concurrently, give those precedence — the user-facing cause
+            // is the cancel/timeout, not the resulting process death.
+            const reason = timedOut
+                ? "timeout"
+                : aborted
+                    ? "aborted"
+                    : "spawn_failed";
+            finish({
+                reason,
+                stdout,
+                stderr,
+                exitCode: null,
+                signal: null,
+                stdoutTruncated,
+                stderrTruncated,
+                timedOut,
+                aborted,
+                spawnFailed: true,
+                error: err.message,
+            });
+        });
+        child.on("close", (code, sig) => {
+            clearTimeout(timer);
+            // Flush trailing incomplete utf-8 (returns "" when last write completed
+            // a sequence). Skip when already truncated — preserves the cap exactly.
+            const tailOut = stdoutDec.end();
+            const tailErr = stderrDec.end();
+            if (tailOut && !stdoutTruncated) {
+                if (stdout.length + tailOut.length > maxBytes) {
+                    stdoutTruncated = true;
+                    stdout += tailOut.slice(0, maxBytes - stdout.length);
+                }
+                else {
+                    stdout += tailOut;
+                }
+            }
+            if (tailErr && !stderrTruncated) {
+                if (stderr.length + tailErr.length > maxBytes) {
+                    stderrTruncated = true;
+                    stderr += tailErr.slice(0, maxBytes - stderr.length);
+                }
+                else {
+                    stderr += tailErr;
+                }
+            }
+            const reason = timedOut
+                ? "timeout"
+                : aborted
+                    ? "aborted"
+                    : "ok";
+            finish({
+                reason,
+                stdout,
+                stderr,
+                exitCode: code,
+                signal: sig,
+                stdoutTruncated,
+                stderrTruncated,
+                timedOut,
+                aborted,
+                spawnFailed: false,
+            });
+        });
+    });
+}
+function safeCleanup(cleanup) {
+    if (!cleanup)
+        return;
+    try {
+        cleanup();
+    }
+    catch { /* best-effort */ }
+}
+function emptyResult(overrides) {
+    return {
+        // Callers always supply `reason` via overrides; the "ok" default is just
+        // a placeholder for the shape — it's never observed because every
+        // emptyResult() callsite sets reason explicitly.
+        reason: "ok",
+        stdout: "",
+        stderr: "",
+        exitCode: null,
+        signal: null,
+        stdoutTruncated: false,
+        stderrTruncated: false,
+        timedOut: false,
+        aborted: false,
+        spawnFailed: false,
+        ...overrides,
+    };
+}

package/dist/services/analytics.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Analytics service — event tracking and telemetry.
+ *
+ * Provides a lightweight analytics pipeline that queues events
+ * and flushes them to configured sinks (file, console, or remote).
+ */
+export interface AnalyticsEvent {
+    name: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+}
+type AnalyticsSink = (events: AnalyticsEvent[]) => void;
+declare class AnalyticsService {
+    private queue;
+    private sinks;
+    private flushTimer;
+    private initialized;
+    /**
+     * Initialize the analytics service with default file sink.
+     */
+    init(): void;
+    addSink(sink: AnalyticsSink): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    flush(): void;
+    shutdown(): void;
+}
+export declare const analytics: AnalyticsService;
+export declare function trackEvent(name: string, properties?: Record<string, unknown>): void;
+export {};

package/dist/services/analytics.js

@@ -0,0 +1,84 @@
+/**
+ * Analytics service — event tracking and telemetry.
+ *
+ * Provides a lightweight analytics pipeline that queues events
+ * and flushes them to configured sinks (file, console, or remote).
+ */
+import { appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+class AnalyticsService {
+    queue = [];
+    sinks = [];
+    flushTimer = null;
+    initialized = false;
+    /**
+     * Initialize the analytics service with default file sink.
+     */
+    init() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        // Default: file-based sink
+        this.addSink(fileAnalyticsSink());
+        // Flush every 30 seconds
+        this.flushTimer = setInterval(() => this.flush(), 30_000);
+        // Flush on exit
+        process.on("beforeExit", () => this.flush());
+    }
+    addSink(sink) {
+        this.sinks.push(sink);
+    }
+    track(name, properties) {
+        this.queue.push({
+            name,
+            properties,
+            timestamp: new Date().toISOString(),
+        });
+        // Auto-flush if queue gets large
+        if (this.queue.length >= 100) {
+            this.flush();
+        }
+    }
+    flush() {
+        if (this.queue.length === 0)
+            return;
+        const events = [...this.queue];
+        this.queue = [];
+        for (const sink of this.sinks) {
+            try {
+                sink(events);
+            }
+            catch {
+                // Silently ignore sink errors
+            }
+        }
+    }
+    shutdown() {
+        this.flush();
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+}
+function fileAnalyticsSink() {
+    const logDir = join(homedir(), ".code-shell", "analytics");
+    return (events) => {
+        if (!existsSync(logDir)) {
+            mkdirSync(logDir, { recursive: true });
+        }
+        const dateStr = new Date().toISOString().split("T")[0];
+        const logFile = join(logDir, `${dateStr}.jsonl`);
+        const lines = events
+            .map((e) => JSON.stringify({ ...e, ...e.properties, properties: undefined }))
+            .join("\n") + "\n";
+        appendFileSync(logFile, lines, "utf-8");
+    };
+}
+// Singleton
+export const analytics = new AnalyticsService();
+// Convenience
+export function trackEvent(name, properties) {
+    analytics.track(name, properties);
+}

package/dist/services/auto-dream.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AutoDream service — background memory consolidation.
+ *
+ * Periodically consolidates and organizes memories using the LLM,
+ * similar to the /dream command but running automatically.
+ */
+export interface AutoDreamConfig {
+    /** Minimum sessions between dream runs */
+    minSessionsBetween: number;
+    /** Minimum time between dream runs (ms) */
+    minTimeBetween: number;
+    /** Whether auto-dream is enabled */
+    enabled: boolean;
+}
+/**
+ * Check if auto-dream should run.
+ */
+export declare function shouldAutoDream(config?: AutoDreamConfig): boolean;
+/**
+ * Record that a session was completed (increment counter).
+ */
+export declare function recordSession(): void;
+/**
+ * Record that a dream run completed.
+ */
+export declare function recordDreamComplete(): void;
+/**
+ * System prompt for the auto-dream tool-call loop.
+ *
+ * Drives the LLM as a "memory consolidation assistant" that operates ONLY in
+ * the dream scope via the MemorySave/MemoryDelete tools. The user scope is
+ * read-only context — modifying it would need permission, which a background
+ * dream pass cannot obtain (no UI on the call path).
+ */
+export declare function buildDreamSystemPrompt(): string;
+/**
+ * Initial user prompt for the dream loop — gives the LLM the lay of the land
+ * (entries in both scopes, by name + description) without dumping every entry
+ * body. The LLM uses MemoryRead to fetch bodies for entries it wants to act on.
+ */
+export declare function buildDreamUserPrompt(userMemories: Array<{
+    name: string;
+    type: string;
+    description: string;
+}>, dreamMemories: Array<{
+    name: string;
+    type: string;
+    description: string;
+}>): string;

package/dist/services/auto-dream.js

@@ -0,0 +1,124 @@
+/**
+ * AutoDream service — background memory consolidation.
+ *
+ * Periodically consolidates and organizes memories using the LLM,
+ * similar to the /dream command but running automatically.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const DEFAULT_CONFIG = {
+    minSessionsBetween: 5,
+    minTimeBetween: 24 * 60 * 60 * 1000, // 24 hours
+    enabled: true,
+};
+function getStateFile() {
+    return join(homedir(), ".code-shell", "auto-dream-state.json");
+}
+function loadState() {
+    const stateFile = getStateFile();
+    if (existsSync(stateFile)) {
+        try {
+            return JSON.parse(readFileSync(stateFile, "utf-8"));
+        }
+        catch { }
+    }
+    return { lastDreamAt: null, sessionsSinceLastDream: 0 };
+}
+function saveState(state) {
+    const stateFile = getStateFile();
+    mkdirSync(join(homedir(), ".code-shell"), { recursive: true });
+    writeFileSync(stateFile, JSON.stringify(state, null, 2), "utf-8");
+}
+/**
+ * Check if auto-dream should run.
+ */
+export function shouldAutoDream(config = DEFAULT_CONFIG) {
+    if (!config.enabled)
+        return false;
+    const state = loadState();
+    // Check session count
+    if (state.sessionsSinceLastDream < config.minSessionsBetween)
+        return false;
+    // Check time
+    if (state.lastDreamAt) {
+        const elapsed = Date.now() - new Date(state.lastDreamAt).getTime();
+        if (elapsed < config.minTimeBetween)
+            return false;
+    }
+    return true;
+}
+/**
+ * Record that a session was completed (increment counter).
+ */
+export function recordSession() {
+    const state = loadState();
+    state.sessionsSinceLastDream++;
+    saveState(state);
+}
+/**
+ * Record that a dream run completed.
+ */
+export function recordDreamComplete() {
+    const state = loadState();
+    state.lastDreamAt = new Date().toISOString();
+    state.sessionsSinceLastDream = 0;
+    saveState(state);
+}
+/**
+ * System prompt for the auto-dream tool-call loop.
+ *
+ * Drives the LLM as a "memory consolidation assistant" that operates ONLY in
+ * the dream scope via the MemorySave/MemoryDelete tools. The user scope is
+ * read-only context — modifying it would need permission, which a background
+ * dream pass cannot obtain (no UI on the call path).
+ */
+export function buildDreamSystemPrompt() {
+    return [
+        "You are a memory consolidation assistant for the CodeShell memory system.",
+        "",
+        "Your job: clean up the `dream` scope by deduplicating, merging, removing stale, and improving descriptions.",
+        "",
+        "Tools available:",
+        "- MemoryList({ scope }): list memories in a scope",
+        "- MemoryRead({ scope, name }): read full content of an entry",
+        "- MemorySave({ scope: 'dream', ... }): create or overwrite a dream entry (auto-approved)",
+        "- MemoryDelete({ scope: 'dream', name }): soft-delete a dream entry (auto-approved, recoverable from trash)",
+        "",
+        "Rules — read carefully:",
+        "1. You may freely Save/Delete in the `dream` scope. These operations DO NOT prompt the user.",
+        "2. You may NOT Save/Delete in the `user` scope from this loop — those operations require interactive permission which is not available here. Treat user-scope entries as read-only context.",
+        "3. If you find user-scope entries that look stale, surface them in your final summary text — don't try to delete them.",
+        "4. Prefer fewer, higher-quality merged entries over many similar fragments.",
+        "5. When an entry has versioned variants (e.g. `*-v1`, `*-v2`, `*-v3`), keep only the latest.",
+        "6. Be conservative: if uncertain whether two entries are truly duplicates, leave them alone.",
+        "7. When you're done, stop calling tools and respond with a one-paragraph summary of what you changed.",
+    ].join("\n");
+}
+/**
+ * Initial user prompt for the dream loop — gives the LLM the lay of the land
+ * (entries in both scopes, by name + description) without dumping every entry
+ * body. The LLM uses MemoryRead to fetch bodies for entries it wants to act on.
+ */
+export function buildDreamUserPrompt(userMemories, dreamMemories) {
+    const fmt = (m) => `  - [${m.type}] ${m.name}: ${m.description}`;
+    const sections = [];
+    sections.push(`User-scope memories (READ-ONLY context, ${userMemories.length} entries):`);
+    if (userMemories.length === 0) {
+        sections.push("  (none)");
+    }
+    else {
+        sections.push(userMemories.map(fmt).join("\n"));
+    }
+    sections.push("");
+    sections.push(`Dream-scope memories (YOUR WORKSPACE, ${dreamMemories.length} entries):`);
+    if (dreamMemories.length === 0) {
+        sections.push("  (none — you may consolidate from user-scope by re-saving curated entries into dream)");
+    }
+    else {
+        sections.push(dreamMemories.map(fmt).join("\n"));
+    }
+    sections.push("");
+    sections.push("Begin consolidation. Use MemoryRead to inspect any entries whose names suggest duplication or staleness, then MemorySave/MemoryDelete in dream scope to clean up.");
+    return sections.join("\n");
+}

package/dist/services/diagnostics.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Diagnostics service — error tracking and system health monitoring.
+ *
+ * Collects and reports diagnostic information for debugging.
+ */
+export interface DiagnosticEntry {
+    timestamp: string;
+    level: "error" | "warn" | "info";
+    category: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+    stack?: string;
+}
+declare class DiagnosticsTracker {
+    private logDir;
+    private entries;
+    constructor();
+    /**
+     * Record a diagnostic event.
+     */
+    record(level: DiagnosticEntry["level"], category: string, message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Record an error with stack trace.
+     */
+    recordError(category: string, error: Error, metadata?: Record<string, unknown>): void;
+    /**
+     * Get recent diagnostic entries.
+     */
+    getRecent(count?: number): DiagnosticEntry[];
+    /**
+     * Get entries by category.
+     */
+    getByCategory(category: string): DiagnosticEntry[];
+    /**
+     * Generate a diagnostic report for troubleshooting.
+     */
+    generateReport(): string;
+    private persist;
+}
+export declare const diagnostics: DiagnosticsTracker;
+export {};

package/dist/services/diagnostics.js

@@ -0,0 +1,99 @@
+/**
+ * Diagnostics service — error tracking and system health monitoring.
+ *
+ * Collects and reports diagnostic information for debugging.
+ */
+import { appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+class DiagnosticsTracker {
+    logDir;
+    entries = [];
+    constructor() {
+        this.logDir = join(homedir(), ".code-shell", "diagnostics");
+    }
+    /**
+     * Record a diagnostic event.
+     */
+    record(level, category, message, metadata) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            category,
+            message,
+            metadata,
+        };
+        this.entries.push(entry);
+        this.persist(entry);
+    }
+    /**
+     * Record an error with stack trace.
+     */
+    recordError(category, error, metadata) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: "error",
+            category,
+            message: error.message,
+            stack: error.stack,
+            metadata,
+        };
+        this.entries.push(entry);
+        this.persist(entry);
+    }
+    /**
+     * Get recent diagnostic entries.
+     */
+    getRecent(count = 50) {
+        return this.entries.slice(-count);
+    }
+    /**
+     * Get entries by category.
+     */
+    getByCategory(category) {
+        return this.entries.filter((e) => e.category === category);
+    }
+    /**
+     * Generate a diagnostic report for troubleshooting.
+     */
+    generateReport() {
+        const lines = [
+            "=== Code Shell Diagnostic Report ===",
+            `Generated: ${new Date().toISOString()}`,
+            `Platform: ${process.platform} ${process.arch}`,
+            `Node: ${process.version}`,
+            `Memory: ${Math.round(process.memoryUsage().heapUsed / 1024 / 1024)}MB`,
+            "",
+        ];
+        const errors = this.entries.filter((e) => e.level === "error");
+        const warnings = this.entries.filter((e) => e.level === "warn");
+        lines.push(`Errors: ${errors.length}`);
+        lines.push(`Warnings: ${warnings.length}`);
+        lines.push(`Total events: ${this.entries.length}`);
+        lines.push("");
+        if (errors.length > 0) {
+            lines.push("Recent Errors:");
+            for (const err of errors.slice(-10)) {
+                lines.push(`  [${err.timestamp}] ${err.category}: ${err.message}`);
+                if (err.stack) {
+                    lines.push(`    ${err.stack.split("\n")[1]?.trim() ?? ""}`);
+                }
+            }
+        }
+        return lines.join("\n");
+    }
+    persist(entry) {
+        try {
+            if (!existsSync(this.logDir)) {
+                mkdirSync(this.logDir, { recursive: true });
+            }
+            const dateStr = entry.timestamp.split("T")[0];
+            const logFile = join(this.logDir, `${dateStr}.jsonl`);
+            appendFileSync(logFile, JSON.stringify(entry) + "\n", "utf-8");
+        }
+        catch {
+            // Best-effort persistence
+        }
+    }
+}
+export const diagnostics = new DiagnosticsTracker();