@cjhyy/code-shell 0.2.0 → 0.5.0-rc.1

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

@@ -1,110 +0,0 @@
-/**
- * ToolContext — runtime services injected into every tool execution.
- *
- * Replaces the legacy module-level singletons (`setAskUserFn`,
- * `setArenaLLMConfig`, `setSubAgentConfig`, `setToolSearchRegistry`).
- *
- * Each Engine instance builds its own ToolContext when run() starts and
- * passes it through ToolExecutor → ToolRegistry → executor function.
- * That makes concurrent Engine instances safe: tools never see another
- * Engine's askUser handler or LLM credentials.
- *
- * Tools that don't need any context (Read/Write/Bash/...) just ignore
- * the second argument; the type is purely additive.
- */
-import type { LLMConfig, StreamCallback } from "../types.js";
-import type { ModelPool } from "../llm/model-pool.js";
-import type { ToolRegistry } from "./registry.js";
-import type { AgentPresetName } from "../preset/index.js";
-import type { SandboxBackend } from "./sandbox/index.js";
-/** One choice in a multiple-choice AskUserQuestion. */
-export interface AskUserChoice {
-    label: string;
-    description: string;
-}
-/**
- * Optional rendering hints / multiple-choice options carried alongside the
- * question. Implementations may ignore unknown fields — they're additive.
- */
-export interface AskUserOptions {
-    /** Short chip-style label (≤12 chars) shown above the question. */
-    header?: string;
-    /** Multiple-choice options. When omitted, the UI falls back to free-text. */
-    options?: AskUserChoice[];
-    /** Allow the user to pick more than one option. Defaults to false. */
-    multiSelect?: boolean;
-}
-/**
- * Function the host UI / server uses to ask the user a question.
- *
- * Second argument is optional for backwards compatibility — callers that
- * only need free text can omit it; backends that don't support options
- * should ignore the field and prompt for free text.
- *
- * Return value:
- *   - Free-text mode: the user's typed answer (or "(user declined to answer)").
- *   - Multiple-choice mode: the selected label, or comma-separated labels for
- *     multiSelect, or "Other: <typed>" when the user picks the implicit
- *     Other... entry.
- */
-export type AskUserFn = (question: string, opts?: AskUserOptions) => Promise<string>;
-/** Spawn a sub-agent. Returns the produced text or throws. */
-export interface SubAgentSpawnRequest {
-    agentId: string;
-    description: string;
-    prompt: string;
-    maxTurns: number;
-    signal: AbortSignal;
-}
-export interface SubAgentSpawner {
-    /** Run a sub-agent synchronously and return its text output. */
-    spawn(req: SubAgentSpawnRequest): Promise<string>;
-    /** Stream callback to forward sub-agent events back to the parent UI. */
-    parentStream?: StreamCallback;
-    /** Static config used to describe what the spawned engine looks like. */
-    describe(): {
-        cwd: string;
-        preset?: AgentPresetName;
-        permissionMode: string;
-    };
-}
-/**
- * The full context object handed to every tool invocation.
- *
- * Optional fields are filled in by Engine.run(); some headless paths may
- * leave them undefined (e.g. running without UI → no askUser).
- */
-export interface ToolContext {
-    /** Active working directory for this Engine. */
-    cwd: string;
-    /** LLM credentials/endpoint for tools that need to make their own calls. */
-    llmConfig: LLMConfig;
-    /** Active model pool (Arena reads this to pick participants). */
-    modelPool?: ModelPool;
-    /** Tool registry (ToolSearch reads this to enumerate available tools). */
-    toolRegistry: ToolRegistry;
-    /** UI-backed AskUserQuestion handler. Undefined → headless mode. */
-    askUser?: AskUserFn;
-    /** Sub-agent spawner (Agent tool). Undefined → Agent tool unavailable. */
-    subAgentSpawner?: SubAgentSpawner;
-    /**
-     * Active sandbox backend for the Bash tool. Undefined falls back to "off"
-     * (plain spawn). Headless runs default to an OS-level sandbox; the REPL
-     * defaults to off because a human is in the loop to approve commands.
-     */
-    sandbox?: SandboxBackend;
-    /** Optional cancellation signal for the whole turn. */
-    signal?: AbortSignal;
-}
-/**
- * Per-Engine container that produces a fresh ToolContext on demand.
- * Engine creates one of these in run() and passes it to ToolExecutor.
- */
-export declare class ServiceContainer {
-    private readonly base;
-    constructor(base: ToolContext);
-    /** Snapshot of the context at this moment. */
-    get(): ToolContext;
-    /** Create a derived context with overridden fields (e.g. per-call signal). */
-    withSignal(signal: AbortSignal): ToolContext;
-}

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

@@ -1,49 +0,0 @@
-/**
- * Tool executor — orchestrates permission checks, hooks, and execution.
- */
-import type { ToolCall, ToolResult, Message } from "../types.js";
-import type { HookRegistry } from "../hooks/registry.js";
-import { ToolRegistry } from "./registry.js";
-import { PermissionClassifier } from "./permission.js";
-import { logger as rootLogger } from "../logging/logger.js";
-import type { ToolContext } from "./context.js";
-import type { InvestigationGuard } from "./investigation-guard.js";
-import type { TaskGuard } from "./task-guard.js";
-type Logger = typeof rootLogger;
-export declare class ToolExecutor {
-    private readonly registry;
-    private readonly permission;
-    private readonly hooks;
-    private signal?;
-    /** Per-Engine ToolContext injected for every tool call. */
-    private toolCtx?;
-    /**
-     * Turn-scoped logger set by TurnLoop at the top of each iteration.
-     * Falls back to the root logger so executor calls outside the turn loop
-     * (tests, ad-hoc tool runs) still write log lines, just without turn tags.
-     */
-    private log;
-    private guard?;
-    private taskGuard?;
-    constructor(registry: ToolRegistry, permission: PermissionClassifier, hooks: HookRegistry);
-    setInvestigationGuard(guard: InvestigationGuard | undefined): void;
-    getInvestigationGuard(): InvestigationGuard | undefined;
-    setTaskGuard(guard: TaskGuard | undefined): void;
-    getTaskGuard(): TaskGuard | undefined;
-    /** Set the abort signal for cascading cancellation. */
-    setSignal(signal?: AbortSignal): void;
-    /** Set the per-Engine ToolContext (askUser, llmConfig, modelPool, etc.). */
-    setContext(ctx: ToolContext | undefined): void;
-    /** Inject a turn-scoped logger so tool-execution lines carry turn/turnId. */
-    setLogger(log: Logger): void;
-    /** Check if a tool is safe for concurrent execution (read-only). */
-    isConcurrencySafe(toolName: string): boolean;
-    executeSingle(call: ToolCall): Promise<ToolResult>;
-    private isReadOnlyBashCommand;
-    executeAll(calls: ToolCall[]): Promise<ToolResult[]>;
-    /**
-     * Convert tool results into Message entries for the transcript.
-     */
-    resultsToMessages(toolCalls: ToolCall[], results: ToolResult[]): Message[];
-}
-export {};

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

@@ -1,46 +0,0 @@
-/**
- * Investigation Guard — runtime enforcement of read budgets.
- *
- * Background: prompt rules in coding.md ("never re-read the same file",
- * "after ~3 read-only calls, change strategy") describe a behavior the model
- * frequently violates under context pressure. This module turns those soft
- * rules into in-loop reminders/blocks delivered through tool results.
- *
- * Three independent counters share one guard instance per Engine:
- *   A) dedupe          — same Read offset hit ≥2 times → reminder; ≥3 times → block
- *   B) read-budget     — N consecutive read-only tools with no side-effecting
- *                        tool in between → reminder on the next read
- *   C) silent turns    — N consecutive turns of only read-only tools with no
- *                        text output → injected into the *next* turn's user
- *                        message by turn-loop (the guard just tracks state).
- *
- * Everything decays naturally on any write/Bash/AskUser tool (state reset).
- */
-import type { ToolCall, ToolResult } from "../types.js";
-export interface GuardDecision {
-    block?: string;
-    prepend?: string;
-}
-export declare class InvestigationGuard {
-    private readHistory;
-    private consecutiveReads;
-    private silentTurns;
-    private turnHasText;
-    private turnHasSideEffect;
-    private lastReminderSilent;
-    /**
-     * Soft mode replaces hard blocks (3rd-read dedupe) with a stronger
-     * reminder. Used in headless runs (`code-shell run …`) where there is
-     * no human to retry the task, so an unattended automation should not
-     * be killed by the guard — it should still get the signal to change
-     * strategy, but the tool call goes through.
-     */
-    private softMode;
-    setSoftMode(soft: boolean): void;
-    preToolCheck(call: ToolCall): GuardDecision | undefined;
-    noteText(text: string | undefined): void;
-    noteToolResult(_call: ToolCall, _result: ToolResult): void;
-    turnEnded(turnNumber: number): string | undefined;
-    private isMutatingTool;
-    private buildKey;
-}

package/dist/tool-system/mcp-manager.d.ts

@@ -1,50 +0,0 @@
-/**
- * MCP Server Manager — connects to external MCP servers and registers their tools.
- *
- * Supports stdio and streamable-http transports.
- */
-import type { MCPServerConfig } from "../types.js";
-import { ToolRegistry } from "./registry.js";
-export declare class MCPManager {
-    private readonly toolRegistry;
-    private static instance;
-    private connections;
-    constructor(toolRegistry: ToolRegistry);
-    static getInstance(): MCPManager;
-    /**
-     * Connect to all configured MCP servers and register their tools.
-     */
-    connectAll(servers: Record<string, MCPServerConfig>): Promise<void>;
-    /**
-     * Connect to a single MCP server.
-     */
-    connect(name: string, config: MCPServerConfig): Promise<void>;
-    /**
-     * Discover tools from an MCP server and register them.
-     */
-    private discoverTools;
-    /**
-     * Disconnect all MCP servers.
-     */
-    disconnectAll(): Promise<void>;
-    /**
-     * List connected servers.
-     */
-    listServers(): string[];
-    /**
-     * Call a tool on a specific MCP server.
-     */
-    callTool(serverName: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
-    /**
-     * List resources from MCP servers.
-     */
-    listResources(serverName?: string): Promise<Array<{
-        uri: string;
-        name: string;
-        description?: string;
-    }>>;
-    /**
-     * Read a resource from an MCP server.
-     */
-    readResource(serverName: string, uri: string): Promise<string>;
-}

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

@@ -1,104 +0,0 @@
-/**
- * Permission system — classifier + approval backend.
- */
-import type { PermissionDecision, PermissionMode, PermissionRule, ApprovalRequest, ApprovalResult } from "../types.js";
-import { logger as rootPermLogger } from "../logging/logger.js";
-export interface ApprovalBackend {
-    requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
-}
-export declare class HeadlessApprovalBackend implements ApprovalBackend {
-    private readonly mode;
-    constructor(mode: "approve-all" | "deny-all" | "approve-read-only");
-    requestApproval(req: ApprovalRequest): Promise<ApprovalResult>;
-}
-/**
- * Auto approval backend — uses fast-path heuristics to auto-approve safe operations.
- * Falls back to a delegate backend for uncertain cases.
- */
-export declare class AutoApprovalBackend implements ApprovalBackend {
-    private readonly delegate?;
-    constructor(delegate?: ApprovalBackend | undefined);
-    requestApproval(req: ApprovalRequest): Promise<ApprovalResult>;
-    private isSafeOperation;
-}
-/**
- * Interactive approval backend — prompts the user via a callback.
- *
- * Stores "always allow" decisions at two scopes:
- *   - session: in-memory map, lost when the process exits
- *   - project: persisted to <cwd>/.code-shell/settings.local.json so the
- *              same project remembers the rule across REPL restarts
- *
- * The classifier reads project rules from settings on session start (see
- * Engine.buildPermissionConfig), so persisted rules become "auto-allow"
- * the next time the user opens the project.
- */
-export declare class InteractiveApprovalBackend implements ApprovalBackend {
-    private sessionRules;
-    private promptFn;
-    private cwd;
-    private savedProjectRules;
-    private onProjectRules;
-    setPromptFn(fn: (request: ApprovalRequest) => Promise<ApprovalResult>): void;
-    /** Inject the project root so persistence writes to the right settings file. */
-    setCwd(cwd: string): void;
-    /**
-     * Inject a callback fired when the user approves "for this project". The
-     * callback receives the *full* accumulated list of project rules saved in
-     * this session, so the classifier can be reconfigured without losing
-     * earlier approvals.
-     */
-    setOnProjectRules(fn: (rules: PermissionRule[]) => void): void;
-    requestApproval(req: ApprovalRequest): Promise<ApprovalResult>;
-}
-export declare function getInteractiveApprovalBackend(): InteractiveApprovalBackend;
-export declare function setInteractiveApprovalFn(fn: (request: ApprovalRequest) => Promise<ApprovalResult>): void;
-type BashSafetyLevel = "safe-read" | "safe-write" | "unsafe" | "dangerous";
-export declare function classifyBashCommand(command: string): BashSafetyLevel;
-export declare class DenialTracker {
-    private denials;
-    private readonly periodMs;
-    private readonly maxDenials;
-    constructor(opts?: {
-        periodMs?: number;
-        maxDenials?: number;
-    });
-    record(toolName: string): void;
-    recordSuccess(toolName: string): void;
-    shouldWarn(toolName: string): boolean;
-    getWarningMessage(toolName: string): string;
-    clear(): void;
-}
-export declare function setRuntimeBypass(enabled: boolean): void;
-export declare function isRuntimeBypass(): boolean;
-export declare class PermissionClassifier {
-    private rules;
-    private defaultMode;
-    private approvalBackend;
-    private denialTracker;
-    /**
-     * Turn-scoped logger so permission events (ask/decision/auto-deny) are
-     * tagged with the current turn/turnId. Falls back to the root logger so
-     * tests and ad-hoc usages still write log lines.
-     */
-    private log;
-    constructor(rules: PermissionRule[], defaultMode?: PermissionMode, approvalBackend?: ApprovalBackend);
-    setLogger(log: typeof rootPermLogger): void;
-    /** Replace mode + backend in place so live tool execution sees the change. */
-    reconfigure(mode: PermissionMode, approvalBackend: ApprovalBackend, rules?: PermissionRule[]): void;
-    getMode(): PermissionMode;
-    classify(toolName: string, args: Record<string, unknown>): PermissionDecision;
-    handleAsk(toolName: string, args: Record<string, unknown>): Promise<boolean>;
-    /** Get denial warning message if the model keeps getting denied. */
-    getDenialWarning(toolName: string): string | undefined;
-    private matchesRule;
-    private isDangerousCommand;
-    private assessRisk;
-    /**
-     * Short, human-friendly subtitle. The UI shows this under the tool title;
-     * full args (command bodies, diffs, etc.) come from the args field, so this
-     * stays compact — no truncation here, just a label.
-     */
-    private describeToolCall;
-}
-export {};

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

@@ -1,32 +0,0 @@
-/**
- * Unified tool registry — built-in tools + MCP tools.
- */
-import type { RegisteredTool, ToolDefinition, ToolResult } from "../types.js";
-import { type BuiltinToolFn } from "./builtin/index.js";
-import type { ToolContext } from "./context.js";
-/**
- * Default execution timeout for any tool that does not declare its own
- * timeoutMs at registration time. Tools that need to run longer (Agent,
- * Arena, Bash, custom long-running tools) should set timeoutMs explicitly.
- */
-export declare const DEFAULT_TOOL_TIMEOUT_MS = 120000;
-export interface ToolRegistryOptions {
-    builtinTools?: readonly string[];
-}
-export declare class ToolRegistry {
-    private tools;
-    private builtinExecutors;
-    constructor(options?: ToolRegistryOptions);
-    private registerBuiltins;
-    registerTool(tool: RegisteredTool, executor?: BuiltinToolFn): void;
-    getToolDefinitions(): ToolDefinition[];
-    getTool(name: string): RegisteredTool | undefined;
-    hasTool(name: string): boolean;
-    executeTool(name: string, args: Record<string, unknown>, options?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-        ctx?: ToolContext;
-    }): Promise<ToolResult>;
-    listTools(): string[];
-    listToolsDetailed(): RegisteredTool[];
-}

package/dist/tool-system/sandbox/bwrap.d.ts

@@ -1,13 +0,0 @@
-/**
- * Linux bubblewrap backend.
- *
- * bwrap creates a fresh mount namespace, then bind-mounts only what we tell
- * it. We bind / read-only and overlay writableRoots as read-write. PID,
- * IPC, UTS, cgroup namespaces are unshared. Network is shared unless
- * config.network === "deny".
- *
- * Sensitive directories listed in deniedReads are shadowed with a tmpfs so
- * the inner process literally cannot see them even though `/` is mounted.
- */
-import type { SandboxBackend, SandboxConfig } from "./index.js";
-export declare function createBwrapBackend(config: SandboxConfig): SandboxBackend;

package/dist/tool-system/sandbox/index.d.ts

@@ -1,78 +0,0 @@
-/**
- * Sandbox backends for shell command execution.
- *
- * We wrap Bash-tool commands in an OS-level sandbox so a misbehaving (or
- * prompt-injected) model can't reach beyond the workspace. The sandbox runs
- * the user's command inside an isolated process tree with restricted file
- * and (optionally) network access. The Engine itself is NOT sandboxed; only
- * the spawned shell is. File-editing tools (Edit/Write) keep going through
- * the application-layer permission gate.
- *
- * Backends are platform-specific:
- *   - "seatbelt"  macOS sandbox-exec, built into macOS, zero install
- *   - "bwrap"     Linux bubblewrap, requires `apt install bubblewrap`
- *   - "off"       passthrough, no sandboxing (current behavior)
- *
- * "auto" picks per platform at startup; falls back to "off" with a warning
- * when no sandbox is available.
- */
-export type SandboxMode = "off" | "auto" | "seatbelt" | "bwrap";
-export type SandboxNetworkPolicy = "allow" | "deny";
-export interface SandboxConfig {
-    mode: SandboxMode;
-    writableRoots: string[];
-    deniedReads: string[];
-    network: SandboxNetworkPolicy;
-}
-export interface SandboxBackend {
-    /** Resolved backend name — "off" means no sandboxing. */
-    name: "off" | "seatbelt" | "bwrap";
-    /**
-     * Decide the binary + argv that should actually be spawned to run `command`
-     * under this sandbox. The shell still interprets `command`; we only swap
-     * the outer process.
-     */
-    wrap(command: string, opts: {
-        cwd: string;
-        shell: string;
-    }): {
-        file: string;
-        args: string[];
-        /**
-         * Optional callback the Bash tool calls after the child process exits.
-         * Backends that allocate per-command resources (e.g. seatbelt writes a
-         * profile file to a fresh temp dir) hang their cleanup here so a long
-         * session doesn't leak hundreds of temp dirs in /tmp.
-         */
-        cleanup?: () => void;
-    };
-    /**
-     * If `stderr` looks like a sandbox denial, return a short hint string that
-     * the Bash tool will append to its result so the model understands why.
-     */
-    hintForBlockedOutput?(stderr: string): string | undefined;
-}
-/**
- * Detect which sandbox mechanisms are available on the current host. Used by
- * "auto" mode and surfaced to the user via /sandbox status if desired.
- */
-export declare function detectSandboxCapabilities(): {
-    seatbelt: boolean;
-    bwrap: boolean;
-};
-/**
- * Expand `~` and `${workspace}` placeholders against the live cwd and home.
- */
-export declare function expandPath(p: string, cwd: string): string;
-export declare function expandConfig(config: SandboxConfig, cwd: string): SandboxConfig;
-export declare function defaultSandboxConfig(mode?: SandboxMode): SandboxConfig;
-/**
- * Resolve the active backend given user config + the current host.
- *
- *   "off"      → off backend
- *   "seatbelt" → seatbelt if available, else throws (explicit choice)
- *   "bwrap"    → bwrap if available, else throws
- *   "auto"     → seatbelt on macOS, bwrap on Linux with bwrap installed,
- *                else off + console warning
- */
-export declare function resolveSandboxBackend(config: SandboxConfig, cwd: string): Promise<SandboxBackend>;

package/dist/tool-system/sandbox/off.d.ts

@@ -1,2 +0,0 @@
-import type { SandboxBackend } from "./index.js";
-export declare function createOffBackend(): SandboxBackend;

package/dist/tool-system/sandbox/seatbelt.d.ts

@@ -1,18 +0,0 @@
-/**
- * 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 type { SandboxBackend, SandboxConfig } from "./index.js";
-export declare function createSeatbeltBackend(config: SandboxConfig): SandboxBackend;

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

@@ -1,30 +0,0 @@
-/**
- * TaskGuard — nudges the model to update stale in_progress tasks.
- *
- * Background: TaskCreate 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 task" signal gets diluted and the model finishes its work
- * without ever calling TaskUpdate(status="completed") — so the UI spinner runs
- * forever on a task that the model considers done.
- *
- * Same shape as InvestigationGuard.turnEnded: 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 (task, threshold) pair. A task
- * stale at turn 5 fires once; if the model still ignores it, we wait for it
- * to cross the next threshold (8, 11, …) before firing again. This keeps the
- * reminder from drowning out everything else when the model is genuinely
- * stuck on something unrelated.
- */
-import type { Task } from "./builtin/task.js";
-export declare class TaskGuard {
-    private taskListSource;
-    /** Last turn we nagged about a given task id. */
-    private lastNagTurn;
-    /** Turn the task was first observed in_progress (model-time, not wall-clock). */
-    private inProgressSince;
-    constructor(taskListSource: () => Task[]);
-    turnEnded(turnNumber: number): string | undefined;
-    reset(): void;
-}

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

@@ -1,5 +0,0 @@
-/**
- * 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;