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

package/dist/tool-system/sandbox/seatbelt.js

@@ -0,0 +1,109 @@
+/**
+ * macOS Seatbelt backend.
+ *
+ * Builds a sandbox-exec profile that:
+ *   - Allows reading most of the filesystem (denying everything breaks tooling)
+ *   - Denies reads of sensitive credential directories
+ *   - Restricts writes to the workspace + writableRoots
+ *   - Optionally denies outbound network
+ *
+ * The profile is written to a fresh temp file per command (cheap; users can
+ * have arbitrary writableRoots so we can't cache). The spawned process and
+ * its entire subprocess tree inherit the profile via XNU's sandbox framework.
+ *
+ * sandbox-exec is technically deprecated by Apple but remains the only
+ * working OS-level sandbox on macOS and is what Codex CLI / Cursor use today.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export function createSeatbeltBackend(config) {
+    return {
+        name: "seatbelt",
+        wrap(command, opts) {
+            const profile = buildProfile(config);
+            const dir = mkdtempSync(join(tmpdir(), "codeshell-sandbox-"));
+            const profilePath = join(dir, "profile.sb");
+            writeFileSync(profilePath, profile, "utf-8");
+            return {
+                file: "/usr/bin/sandbox-exec",
+                args: ["-f", profilePath, opts.shell, "-c", command],
+                cleanup: () => {
+                    // sandbox-exec has already exited (this runs from Bash tool's
+                    // child `close` handler), so removing the profile file is safe.
+                    // force=true swallows ENOENT in case the dir was already cleaned
+                    // up out-of-band (e.g. system tmpwatch).
+                    try {
+                        rmSync(dir, { recursive: true, force: true });
+                    }
+                    catch {
+                        // Best-effort. A leftover dir is recoverable; throwing here
+                        // would mask the actual command output we just sent back.
+                    }
+                },
+            };
+        },
+        hintForBlockedOutput(stderr) {
+            if (/Operation not permitted|sandbox/.test(stderr)) {
+                return ("\n[sandbox:seatbelt] A syscall was blocked by the sandbox. " +
+                    "If this path should be writable or this network call legitimate, " +
+                    "ask the user to update sandbox.writableRoots / sandbox.network in settings.json.");
+            }
+            return undefined;
+        },
+    };
+}
+function buildProfile(config) {
+    const writeAllows = config.writableRoots
+        .map((p) => `  (subpath ${quote(p)})`)
+        .join("\n");
+    const readDenies = config.deniedReads
+        .map((p) => `  (subpath ${quote(p)})`)
+        .join("\n");
+    const networkClause = config.network === "deny" ? "(deny network-outbound)" : "(allow network*)";
+    // SBPL evaluation note: when a broad `(allow file-read*)` and a specific
+    // `(deny file-read* (subpath …))` both match, the more specific subpath
+    // rule wins — order between the two clauses does not matter. We tested
+    // this empirically (both orderings block reads of denied subpaths) and
+    // the integration test in tests/sandbox.test.ts uses `cat <secret>` to
+    // verify reads are actually blocked, not just `ls`. The only previously
+    // observed leak was when the denied path was given as `/tmp/...` while
+    // `/tmp` symlinks to `/private/tmp`; sandbox-exec matches subpaths on
+    // canonical paths, so `expandConfig()` runs `realpathSync` up front.
+    return `(version 1)
+(deny default)
+
+;; Process control
+(allow process-fork)
+(allow process-exec)
+(allow signal (target self))
+(allow signal (target children))
+
+;; Reads: broadly allowed, then explicit deny of sensitive paths
+(allow file-read*)
+${readDenies ? `(deny file-read*\n${readDenies})` : ""}
+
+;; Writes: workspace + listed roots only
+(allow file-write*
+${writeAllows})
+(allow file-write-data
+  (literal "/dev/null")
+  (literal "/dev/zero")
+  (literal "/dev/random")
+  (literal "/dev/urandom")
+  (literal "/dev/dtracehelper"))
+
+;; IPC & system services common tools need
+(allow mach-lookup)
+(allow ipc-posix-shm)
+(allow sysctl-read)
+(allow system-socket)
+(allow iokit-open)
+
+;; Network
+${networkClause}
+`;
+}
+function quote(path) {
+    return `"${path.replace(/"/g, '\\"')}"`;
+}

package/dist/tool-system/task-guard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * TaskGuard — nudges the model to update stale in_progress todos.
+ *
+ * Background: a TodoWrite snapshot is sticky in the model's working
+ * memory only for the first few turns. After enough intervening tool
+ * results (Read/Edit/Bash) the "I have an open todo" signal gets
+ * diluted and the model finishes its work without rewriting the
+ * snapshot — so the UI's pinned panel keeps showing an item as
+ * in_progress even though the model considers it done.
+ *
+ * Same shape as InvestigationGuard.turnEnded: the turn loop polls at
+ * the end of each turn; if anything is in_progress and hasn't been
+ * touched in N turns, we emit a <system-reminder> that lands at the
+ * top of the next turn.
+ *
+ * Re-nag policy: don't fire more than once per (todo, threshold)
+ * pair. Identity is the position-based id ("1", "2", …) carried on
+ * TaskInfo. Re-arranging the list creates a new identity, which is
+ * already a refresh, so the nag resets naturally.
+ */
+import type { TaskInfo } from "../types.js";
+export declare class TaskGuard {
+    private snapshotSource;
+    private lastNagTurn;
+    private inProgressSince;
+    constructor(snapshotSource: () => TaskInfo[]);
+    turnEnded(turnNumber: number): string | undefined;
+    reset(): void;
+}

package/dist/tool-system/task-guard.js

@@ -0,0 +1,70 @@
+/**
+ * TaskGuard — nudges the model to update stale in_progress todos.
+ *
+ * Background: a TodoWrite snapshot is sticky in the model's working
+ * memory only for the first few turns. After enough intervening tool
+ * results (Read/Edit/Bash) the "I have an open todo" signal gets
+ * diluted and the model finishes its work without rewriting the
+ * snapshot — so the UI's pinned panel keeps showing an item as
+ * in_progress even though the model considers it done.
+ *
+ * Same shape as InvestigationGuard.turnEnded: the turn loop polls at
+ * the end of each turn; if anything is in_progress and hasn't been
+ * touched in N turns, we emit a <system-reminder> that lands at the
+ * top of the next turn.
+ *
+ * Re-nag policy: don't fire more than once per (todo, threshold)
+ * pair. Identity is the position-based id ("1", "2", …) carried on
+ * TaskInfo. Re-arranging the list creates a new identity, which is
+ * already a refresh, so the nag resets naturally.
+ */
+const STALE_TURN_THRESHOLD = 3;
+const RENAG_INTERVAL = 3;
+export class TaskGuard {
+    snapshotSource;
+    lastNagTurn = new Map();
+    inProgressSince = new Map();
+    constructor(snapshotSource) {
+        this.snapshotSource = snapshotSource;
+    }
+    turnEnded(turnNumber) {
+        const tasks = this.snapshotSource();
+        const open = tasks.filter((t) => t.status === "in_progress");
+        const trackedIds = [...this.inProgressSince.keys()];
+        for (const id of trackedIds) {
+            const stillOpen = open.some((t) => t.id === id);
+            if (!stillOpen) {
+                this.inProgressSince.delete(id);
+                this.lastNagTurn.delete(id);
+            }
+        }
+        for (const t of open) {
+            if (!this.inProgressSince.has(t.id)) {
+                this.inProgressSince.set(t.id, turnNumber);
+            }
+        }
+        const stale = open
+            .map((t) => ({ task: t, age: turnNumber - (this.inProgressSince.get(t.id) ?? turnNumber) }))
+            .filter(({ task, age }) => {
+            if (age < STALE_TURN_THRESHOLD)
+                return false;
+            const last = this.lastNagTurn.get(task.id);
+            if (last === undefined)
+                return true;
+            return turnNumber - last >= RENAG_INTERVAL;
+        });
+        if (stale.length === 0)
+            return undefined;
+        for (const { task } of stale) {
+            this.lastNagTurn.set(task.id, turnNumber);
+        }
+        const lines = stale.map(({ task, age }) => `  - "${task.subject}" (in_progress for ${age} turns)`);
+        return (`<system-reminder>You have ${stale.length === 1 ? "an open" : `${stale.length} open`} in_progress todo${stale.length === 1 ? "" : "s"} that ${stale.length === 1 ? "has" : "have"} not been updated recently:\n` +
+            lines.join("\n") +
+            `\nCall TodoWrite again with the updated snapshot — mark items completed when done, or drop them if abandoned. The UI's pinned panel keeps showing in_progress until the next TodoWrite arrives.</system-reminder>`);
+    }
+    reset() {
+        this.lastNagTurn.clear();
+        this.inProgressSince.clear();
+    }
+}

package/dist/tool-system/validation.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Validate tool args against the tool's inputSchema.
+ * Returns null if valid, error string if invalid.
+ */
+export declare function validateToolArgs(toolName: string, args: Record<string, unknown>, schema: Record<string, unknown>): string | null;

package/dist/tool-system/validation.js

@@ -0,0 +1,39 @@
+/**
+ * Validate tool args against the tool's inputSchema.
+ * Returns null if valid, error string if invalid.
+ */
+export function validateToolArgs(toolName, args, schema) {
+    try {
+        const properties = schema.properties;
+        const required = schema.required ?? [];
+        if (!properties)
+            return null;
+        // Check required fields
+        for (const field of required) {
+            if (args[field] === undefined || args[field] === null) {
+                return `Missing required parameter: ${field}`;
+            }
+        }
+        // Type check each provided field
+        for (const [key, value] of Object.entries(args)) {
+            const propSchema = properties[key];
+            if (!propSchema)
+                continue; // Extra fields are OK
+            const expectedType = propSchema.type;
+            const actualType = typeof value;
+            if (expectedType === "string" && actualType !== "string") {
+                return `Parameter '${key}' must be a string, got ${actualType}`;
+            }
+            if (expectedType === "number" && actualType !== "number") {
+                return `Parameter '${key}' must be a number, got ${actualType}`;
+            }
+            if (expectedType === "boolean" && actualType !== "boolean") {
+                return `Parameter '${key}' must be a boolean, got ${actualType}`;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null; // Don't block on validation errors
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,376 @@
+/**
+ * Core type definitions for the code-shell orchestration framework.
+ */
+export interface ContentBlock {
+    type: "text" | "tool_use" | "tool_result" | "image" | "reasoning";
+    text?: string;
+    id?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    content?: string | ContentBlock[];
+    tool_use_id?: string;
+    source?: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+    reasoningContent?: string;
+}
+export interface Message {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ContentBlock[];
+    name?: string;
+    tool_call_id?: string;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ToolCall {
+    id: string;
+    toolName: string;
+    serverName?: string;
+    args: Record<string, unknown>;
+}
+export interface ToolResult {
+    id: string;
+    toolName: string;
+    result?: string;
+    error?: string;
+    isError?: boolean;
+}
+export type ToolSource = "builtin" | "mcp";
+export interface RegisteredTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    source: ToolSource;
+    serverName?: string;
+    permissionDefault: PermissionDecision;
+    isConcurrencySafe?: boolean;
+    isReadOnly?: boolean;
+    /**
+     * Override the default tool execution timeout (ms).
+     * Falls back to DEFAULT_TOOL_TIMEOUT_MS (120s) if unset.
+     * The caller of executeTool() can still override via options.timeoutMs.
+     */
+    timeoutMs?: number;
+}
+export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "turn_boundary" | "error";
+export interface TranscriptEvent {
+    id: string;
+    type: TranscriptEventType;
+    timestamp: number;
+    turnNumber: number;
+    data: Record<string, unknown>;
+}
+/**
+ * Session lifecycle state persisted in state.json. `"active"` means a run is
+ * currently in flight (or was, at the moment of the last heartbeat). All other
+ * values match the {@link TerminalReason} the last run returned, so callers
+ * can distinguish a user-cancelled session (`"aborted_streaming"`) from an
+ * actual error (`"model_error"`, `"prompt_too_long"`, ...).
+ */
+export type SessionStatus = "active" | "paused" | TerminalReason;
+export interface SessionState {
+    sessionId: string;
+    cwd: string;
+    startedAt: number;
+    model: string;
+    provider: string;
+    tokenUsage: TokenUsage;
+    turnCount: number;
+    invokedSkills: string[];
+    parentSessionId?: string;
+    status: SessionStatus;
+    /** Short summary derived from the first user message */
+    summary?: string;
+    /** Persisted cost tracking state (survives process restart). */
+    costState?: Record<string, unknown>;
+}
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+export interface CompiledInput {
+    messages: Message[];
+    rawText: string;
+    options: InputOptions;
+}
+export interface InputOptions {
+    slashCommand?: string;
+    attachments?: Attachment[];
+    mentionedFiles?: string[];
+    images?: ImageAttachment[];
+    allowedTools?: string[];
+    modelOverride?: string;
+}
+export interface Attachment {
+    path: string;
+    content: string;
+    mimeType: string;
+}
+export interface ImageAttachment {
+    data: string;
+    mediaType: string;
+}
+export type PermissionDecision = "allow" | "deny" | "ask";
+export type PermissionMode = "default" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "auto" | "plan";
+export interface PermissionRule {
+    tool: string;
+    argsPattern?: Record<string, string | RegExp>;
+    decision: PermissionDecision;
+    reason?: string;
+}
+export interface ApprovalRequest {
+    toolName: string;
+    args: Record<string, unknown>;
+    description: string;
+    riskLevel: "low" | "medium" | "high";
+}
+/**
+ * Scope of an "always allow" decision.
+ *   "once"    — this single call only (default when always not set)
+ *   "session" — remembered for the rest of the REPL session (in-memory)
+ *   "project" — persisted to <cwd>/.code-shell/settings.local.json so it
+ *               survives restart for the current project. Not committed.
+ */
+export type ApprovalScope = "once" | "session" | "project";
+export type ApprovalResult = {
+    approved: true;
+    permanent?: boolean;
+    always?: boolean;
+    scope?: ApprovalScope;
+    /** Used by AskUserQuestion to carry the user's free-text answer. */ answer?: string;
+} | {
+    approved: false;
+    reason?: string;
+    always?: boolean;
+    scope?: ApprovalScope;
+};
+export type TurnPhase = "pre_check" | "model_call" | "post_check" | "tool_exec" | "context_mgmt" | "hook_notify" | "complete" | "error";
+export interface TurnResult {
+    text: string;
+    toolCalls: ToolCall[];
+    status: "completed" | "tool_use" | "error" | "max_turns" | "aborted";
+    error?: string;
+}
+export type TerminalReason = "completed" | "stop_hook_prevented" | "hook_stopped" | "prompt_too_long" | "model_error" | "aborted_streaming" | "aborted_tools" | "max_turns" | "image_error";
+export interface TaskInfo {
+    id: string;
+    subject: string;
+    activeForm?: string;
+    status: "pending" | "in_progress" | "completed" | "stopped";
+}
+export type StreamEvent = {
+    type: "session_started";
+    sessionId: string;
+    promptTokens: number;
+} | {
+    type: "stream_request_start";
+    turnNumber: number;
+    agentId?: string;
+} | {
+    type: "text_delta";
+    text: string;
+    tokens?: number;
+    agentId?: string;
+} | {
+    type: "tool_use_start";
+    toolCall: ToolCall;
+    agentId?: string;
+} | {
+    type: "tool_use_args_delta";
+    toolCallId: string;
+    args: Record<string, unknown>;
+    agentId?: string;
+} | {
+    type: "tool_result";
+    result: ToolResult;
+    agentId?: string;
+} | {
+    type: "assistant_message";
+    message: Message;
+    agentId?: string;
+} | {
+    type: "turn_complete";
+    reason: TerminalReason;
+    agentId?: string;
+} | {
+    type: "error";
+    error: string;
+    agentId?: string;
+} | {
+    type: "tombstone";
+    messageId: string;
+} | {
+    type: "task_update";
+    tasks: TaskInfo[];
+} | {
+    type: "thinking_delta";
+    text: string;
+    agentId?: string;
+} | {
+    type: "agent_start";
+    agentId: string;
+    name?: string;
+    description: string;
+} | {
+    type: "agent_end";
+    agentId: string;
+    name?: string;
+    description: string;
+    text?: string;
+    error?: string;
+} | {
+    type: "tool_summary";
+    summary: string;
+} | {
+    type: "context_compact";
+    strategy: "micro" | "summary" | "window" | "snip" | "emergency";
+    before: number;
+    after: number;
+    agentId?: string;
+} | {
+    type: "usage_update";
+    promptTokens: number;
+    agentId?: string;
+} | {
+    type: "background_agent_completed";
+    agentId: string;
+    name?: string;
+    description: string;
+    status: "completed" | "failed";
+    /** Final assistant text (status === "completed" only). */
+    finalText?: string;
+    /** Error message (status === "failed" only). */
+    error?: string;
+    /** When the bg agent finished (Date.now() value). */
+    enqueuedAt: number;
+};
+/**
+ * Convenience extraction so SDK consumers and tests can import the
+ * `background_agent_completed` payload shape without re-destructuring
+ * the StreamEvent union themselves.
+ */
+export type BackgroundAgentCompletedEvent = Extract<StreamEvent, {
+    type: "background_agent_completed";
+}>;
+export type StreamCallback = (event: StreamEvent) => void | Promise<void>;
+export interface LLMConfig {
+    provider: string;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    timeout?: number;
+    retryMaxAttempts?: number;
+    enableStreaming?: boolean;
+    /**
+     * Default thinking-mode for DeepSeek V4. Per-call `options.thinking`
+     * (e.g. summarize sub-calls) overrides this. Ignored on other providers.
+     */
+    thinking?: "enabled" | "disabled";
+    /**
+     * The provider's `kind` (deepseek/openai/zai/openrouter/...). Used by
+     * the capability layer to look up per-(kind, model) request-shape rules
+     * (token-limit field, rejected sampling params, thinking shape, etc.).
+     * Distinct from `provider` above, which is the protocol family
+     * ("openai" or "anthropic") that picks which client class to use.
+     */
+    providerKind?: string;
+}
+export interface LLMResponse {
+    text: string;
+    toolCalls: ToolCall[];
+    usage?: TokenUsage;
+    stopReason?: string;
+    reasoningContent?: string;
+}
+export interface LLMStreamChunk {
+    type: "text" | "tool_use_start" | "tool_use_delta" | "tool_use_end" | "stop";
+    text?: string;
+    /** Token count for this text delta, when provider can compute it. */
+    tokens?: number;
+    toolCall?: Partial<ToolCall>;
+    stopReason?: string;
+}
+export type MCPTransport = "stdio" | "sse" | "streamable-http" | "inprocess";
+export interface MCPServerConfig {
+    name: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    transport?: MCPTransport;
+    headers?: Record<string, string>;
+}
+/**
+ * Shell-hook configuration entry from settings.json. Each entry binds
+ * a hook event to a shell command. The command runs as a child process
+ * on every emit (filtered by `matcher` when present), receives ctx
+ * JSON on stdin, and returns a HookResult JSON on stdout. See
+ * src/hooks/shell-runner.ts for the protocol spec.
+ */
+export interface SettingsHookConfig {
+    event: string;
+    command: string;
+    /**
+     * Optional regex (matched with new RegExp(matcher).test(toolName)) to
+     * filter which tools fire this hook. Currently honored for
+     * pre_tool_use / post_tool_use / on_tool_start / on_tool_end /
+     * on_permission_check / file_changed. Ignored for events without a
+     * meaningful toolName (session/turn/prompt/notification/compact).
+     */
+    matcher?: string;
+    /** Per-hook timeout in milliseconds. Defaults to 60_000. */
+    timeout_ms?: number;
+    /**
+     * Optional working directory for the spawned command. Defaults to
+     * Engine.cwd. Useful for hooks that need to run in a sibling repo.
+     */
+    cwd?: string;
+}
+export interface Settings {
+    model: {
+        provider: string;
+        name: string;
+        apiKey?: string;
+        baseUrl?: string;
+        temperature?: number;
+        maxTokens?: number;
+    };
+    permissions: {
+        defaultMode: PermissionMode;
+        rules: PermissionRule[];
+    };
+    context: {
+        maxTokens: number;
+        compactAtRatio: number;
+        summarizeAtRatio: number;
+    };
+    session: {
+        storageDir: string;
+        maxHistory: number;
+    };
+    mcpServers: Record<string, MCPServerConfig>;
+    instructions: {
+        fileName: string;
+        scanDirs: string[];
+    };
+    output: {
+        format: "text" | "json" | "jsonl" | "stream-json";
+    };
+    /**
+     * Optional shell-hook entries. Engine reads on construction and
+     * registers a wrapper handler per entry that spawns the command and
+     * parses the HookResult. Empty / missing = no shell hooks.
+     */
+    hooks?: SettingsHookConfig[];
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core type definitions for the code-shell orchestration framework.
+ */
+export {};