@cjhyy/code-shell 0.1.0-alpha.0

package/dist/product/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Product Adapter — the contract for turning CodeShell into a domain-specific agent.
+ *
+ * A "product" is a concrete agent application built on top of CodeShell.
+ * Examples:
+ *   - Code reviewer agent
+ *   - Data pipeline orchestrator
+ *   - DevOps deployment agent
+ *   - Documentation writer
+ *   - Security audit agent
+ *
+ * To build a product, an external repo provides:
+ *
+ *   1. **Preset** (brain)     — system prompt, tool set, permission rules
+ *   2. **Adapter** (hands)    — custom tools, MCP servers, domain-specific IO
+ *   3. **Contract** (quality) — evaluator, completion criteria, artifact specs
+ *
+ * These three layers compose into a ProductDefinition that CodeShell's
+ * `defineProduct()` function turns into a fully configured RunManager.
+ */
+import type { PermissionRule, MCPServerConfig } from "../types.js";
+import type { Evaluator } from "../run/Evaluator.js";
+import type { HookEventName } from "../hooks/events.js";
+import type { RegisteredTool } from "../types.js";
+export interface ProductPreset {
+    /** Unique name for this product's preset. */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** One-line description. */
+    description: string;
+    /**
+     * System prompt for the agent. Two options:
+     *   - `sections`: reuse CodeShell's built-in markdown sections (e.g. ["base", "orchestration"])
+     *   - `customPrompt`: provide a full custom system prompt string
+     * If both are provided, customPrompt takes precedence.
+     */
+    sections?: string[];
+    customPrompt?: string;
+    /** Additional text appended after the main system prompt. */
+    appendPrompt?: string;
+    /** Whether to inject git status into system context. Default: false */
+    injectGitStatus?: boolean;
+}
+export interface CustomTool {
+    /** Tool definition (name, description, inputSchema). */
+    definition: RegisteredTool;
+    /** Tool executor function. */
+    execute: (args: Record<string, unknown>) => Promise<string>;
+}
+export interface ProductAdapter {
+    /**
+     * Custom tools specific to this product domain.
+     * These are registered in addition to the preset's builtin tools.
+     */
+    tools?: CustomTool[];
+    /**
+     * MCP servers to connect (external tool providers).
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Builtin tools to explicitly enable (add to preset defaults).
+     */
+    enableTools?: string[];
+    /**
+     * Builtin tools to explicitly disable (remove from preset defaults).
+     */
+    disableTools?: string[];
+    /**
+     * Permission rules specific to this product.
+     * Applied on top of the preset's default rules.
+     */
+    permissionRules?: PermissionRule[];
+    /**
+     * Hooks to register for this product.
+     * Key: hook event name, Value: handler function.
+     */
+    hooks?: Array<{
+        event: HookEventName;
+        handler: (context: Record<string, unknown>) => Promise<Record<string, unknown>>;
+        priority?: number;
+        name?: string;
+    }>;
+}
+export interface ProductContract {
+    /**
+     * Evaluator(s) to run on completion.
+     * Can be a single Evaluator or an array (composed automatically).
+     */
+    evaluator?: Evaluator | Evaluator[];
+    /**
+     * Default tags applied to every run submitted through this product.
+     */
+    defaultTags?: string[];
+    /**
+     * Default metadata attached to every run.
+     */
+    defaultMetadata?: Record<string, unknown>;
+    /**
+     * Maximum turns per run. Overrides the default 30.
+     */
+    maxTurns?: number;
+    /**
+     * Maximum context tokens. Overrides the default 200_000.
+     */
+    maxContextTokens?: number;
+    /**
+     * Queue concurrency. Default: 1.
+     */
+    concurrency?: number;
+}
+export interface ProductDefinition {
+    preset: ProductPreset;
+    adapter?: ProductAdapter;
+    contract?: ProductContract;
+}

package/dist/prompt/composer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Prompt composer — assembles system prompt from sections.
+ *
+ * Following Claude Code's dual-chain architecture:
+ *   system chain → API request "system" field
+ *   messages chain → API request "messages" field (userContext prepended)
+ */
+import type { ToolDefinition, Message } from "../types.js";
+import { type ScanOptions } from "./instruction-scanner.js";
+import { type AgentPreset } from "../preset/index.js";
+export interface ComposerOptions {
+    cwd: string;
+    model: string;
+    instructionOptions?: ScanOptions;
+    /** Resolved preset — used to load section-based prompt. */
+    preset?: AgentPreset;
+    customSystemPrompt?: string;
+    appendSystemPrompt?: string;
+}
+export declare class PromptComposer {
+    private readonly options;
+    private sectionCache;
+    private cachedInstructions;
+    constructor(options: ComposerOptions);
+    /**
+     * Build the system prompt from sections.
+     */
+    buildSystemPrompt(tools: ToolDefinition[]): Promise<string>;
+    /**
+     * Build the userContext prefix message (CLAUDE.md content as <system-reminder>).
+     */
+    buildUserContextMessage(): Message | null;
+    /**
+     * Build the systemContext (gitStatus etc.) to append to system prompt.
+     * Only injects git status if the resolved preset opts in.
+     */
+    buildSystemContext(): Promise<string>;
+    invalidateCache(sectionName?: string): void;
+    private getSections;
+    private getInstructions;
+    private getMemoryContext;
+}

package/dist/prompt/instruction-scanner.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Instruction scanner — discovers instruction files up the directory tree.
+ *
+ * Supports layered instruction files with priority ordering:
+ *   1. managed  — shipped defaults (~/.code-shell/CODESHELL.md)
+ *   2. user     — user-level (~/.code-shell/CODESHELL.md, ~/.code-shell/rules/)
+ *   3. project  — project-level (from git root to cwd, walking down)
+ *   4. local    — local overrides (CODESHELL.local.md, not version-controlled)
+ *
+ * Entries carry a `depth` field: 0 = git root / top-most, increasing toward cwd.
+ * The scanner stops at the git repository root (not filesystem root).
+ *
+ * File name search order per directory:
+ *   CODESHELL.md → .codeshell/CODESHELL.md → .codeshell/rules/*.md
+ *   CLAUDE.md    → .claude/CLAUDE.md       → .claude/rules/*.md      (compat)
+ */
+export interface InstructionEntry {
+    /** Absolute path to the file */
+    path: string;
+    /** Raw file content */
+    content: string;
+    /** Where the file came from */
+    source: "managed" | "user" | "project" | "local";
+    /**
+     * Depth relative to the project root.
+     * 0 = git root (or scan ceiling), increases toward cwd.
+     * user/managed entries have depth -1.
+     */
+    depth: number;
+}
+export interface ScanOptions {
+    /** Primary instruction file name (default: "CODESHELL.md") */
+    fileName?: string;
+    /** Extra directory names to probe alongside .codeshell/ */
+    scanDirs?: string[];
+    /** Compatibility file names to also look for (default: ["CLAUDE.md"]) */
+    compatFileNames?: string[];
+    /** If true, do NOT stop at git root — scan all the way to / */
+    ignoreGitBoundary?: boolean;
+}
+/**
+ * Scan for instruction files from cwd up to the project root,
+ * plus user-level and managed-level instructions.
+ *
+ * Returns entries ordered by priority: managed → user → project (root→cwd) → local.
+ */
+export declare function scanInstructions(cwd: string, options?: ScanOptions): InstructionEntry[];
+/**
+ * Combine all instruction entries into a single string.
+ *
+ * Entries are grouped by source with headers, making it clear
+ * where each instruction block originates.
+ */
+export declare function combineInstructions(entries: InstructionEntry[]): string;

package/dist/prompt/section-cache.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Per-section prompt caching.
+ * Mirrors Claude Code's systemPromptSectionCache — each section cached independently.
+ */
+export interface PromptSection {
+    name: string;
+    compute: () => string | Promise<string>;
+    cacheBreak?: boolean;
+}
+export declare class SectionCache {
+    private cache;
+    resolve(sections: PromptSection[]): Promise<string[]>;
+    invalidate(name?: string): void;
+    has(name: string): boolean;
+}

package/dist/prompt/section-loader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Load prompt section markdown files.
+ *
+ * Sections are inlined as text strings at build time via tsup's .md loader,
+ * so they work in both dev (tsx) and built output (dist/) without needing
+ * to copy files. Custom sections registered at runtime are also supported.
+ */
+/**
+ * Register a custom prompt section at runtime.
+ * This allows external presets to add their own sections.
+ */
+export declare function registerSection(name: string, content: string): void;
+/**
+ * Read a named prompt section. Returns the trimmed markdown content.
+ * Looks up built-in sections first, then custom-registered sections.
+ * Throws if the section name is not found.
+ */
+export declare function loadSection(name: string): string;
+/**
+ * Load multiple sections and join them with double newlines.
+ */
+export declare function loadSections(names: readonly string[]): string;
+/**
+ * List all available section names (built-in + custom).
+ */
+export declare function availableSections(): string[];

package/dist/protocol/client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentClient — the UI-side interface to the agent server.
+ *
+ * Replaces direct Engine usage in the UI. Communicates with AgentServer
+ * over a Transport (in-process or cross-process).
+ *
+ * Usage:
+ *   const client = new AgentClient({ transport });
+ *   client.onStreamEvent((event) => { ... });
+ *   client.onApprovalRequest((reqId, request) => { ... });
+ *   const result = await client.run("fix the bug");
+ */
+import type { Transport } from "./transport.js";
+import { type RunResult, type ConfigureParams, type QueryParams, type QueryResult } from "./types.js";
+import type { StreamEvent, ApprovalRequest, ApprovalResult } from "../types.js";
+export interface AgentClientEvents {
+    stream: (event: StreamEvent) => void;
+    approvalRequest: (requestId: string, request: ApprovalRequest) => void;
+    status: (status: string, message?: string) => void;
+}
+export declare class AgentClient {
+    private transport;
+    private emitter;
+    private pendingRequests;
+    constructor(options: {
+        transport: Transport;
+    });
+    /**
+     * Run an agent task. Resolves when the agent completes.
+     * Stream events arrive via the onStreamEvent callback.
+     */
+    run(task: string, sessionId?: string): Promise<RunResult>;
+    /**
+     * Respond to an approval request from the server.
+     */
+    approve(requestId: string, decision: ApprovalResult): Promise<void>;
+    /**
+     * Cancel a running agent.
+     */
+    cancel(reason?: string): Promise<void>;
+    /**
+     * Update runtime configuration on the server.
+     */
+    configure(params: ConfigureParams): Promise<Record<string, unknown>>;
+    /**
+     * Query server state.
+     */
+    query(type: QueryParams["type"], sessionId?: string, ...extra: unknown[]): Promise<QueryResult>;
+    /**
+     * Inject context into the session transcript without triggering a LLM turn.
+     * Used to make arena results, tool outputs, etc. visible to subsequent LLM calls.
+     */
+    inject(sessionId: string, content: string): Promise<void>;
+    onStreamEvent(handler: (event: StreamEvent) => void): void;
+    offStreamEvent(handler: (event: StreamEvent) => void): void;
+    onApprovalRequest(handler: (requestId: string, request: ApprovalRequest) => void): void;
+    offApprovalRequest(handler: (requestId: string, request: ApprovalRequest) => void): void;
+    onStatus(handler: (status: string, message?: string) => void): void;
+    offStatus(handler: (status: string, message?: string) => void): void;
+    private request;
+    private handleResponse;
+    private handleNotification;
+    close(): void;
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,4 @@
+export { AgentServer, type AgentServerOptions } from "./server.js";
+export { AgentClient } from "./client.js";
+export { createInProcessTransport, StdioTransport, type Transport } from "./transport.js";
+export { Methods, ErrorCodes, type RpcMessage, type RunResult } from "./types.js";

package/dist/protocol/server.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AgentServer — wraps Engine and exposes it over the protocol.
+ *
+ * Responsibilities:
+ *   - Handles RPC requests from the client (run, approve, cancel, configure, query)
+ *   - Forwards StreamEvents to the client as notifications
+ *   - Manages approval flow: engine → server → client → server → engine
+ *   - Owns all mutable runtime state (plan mode, bypass, etc.)
+ */
+import type { Transport } from "./transport.js";
+import type { Engine } from "../engine/engine.js";
+export interface AgentServerOptions {
+    engine: Engine;
+    transport: Transport;
+}
+export declare class AgentServer {
+    private engine;
+    private transport;
+    private running;
+    private abortController;
+    /** Pending approval requests: requestId → resolve function */
+    private pendingApprovals;
+    /** Timers for approval timeouts */
+    private approvalTimers;
+    /** Default approval timeout: 5 minutes */
+    private static readonly APPROVAL_TIMEOUT_MS;
+    constructor(options: AgentServerOptions);
+    private handleRequest;
+    private handleRun;
+    private handleApprove;
+    private handleCancel;
+    private handleConfigure;
+    private handleQuery;
+    private handleInject;
+    /**
+     * Ask the client to approve a tool operation.
+     * Sends a notification, returns a promise that resolves when client responds.
+     */
+    private requestApprovalFromClient;
+    /**
+     * Ask the client to answer a question from the agent.
+     * Reuses the approval flow with a synthetic request.
+     */
+    private requestAskUserFromClient;
+    private notify;
+    close(): void;
+    private clearApprovalTimer;
+    private clearAllApprovalTimers;
+}

package/dist/protocol/transport.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Transport layer — abstracts how messages travel between client and server.
+ *
+ * Two implementations:
+ *   - InProcessTransport: direct function calls (same process, zero overhead)
+ *   - StdioTransport: newline-delimited JSON over stdin/stdout (cross-process)
+ */
+import type { RpcMessage } from "./types.js";
+import type { Readable, Writable } from "node:stream";
+export interface Transport {
+    /** Send a message to the other side. */
+    send(message: RpcMessage): void;
+    /** Register a handler for incoming messages. */
+    onMessage(handler: (message: RpcMessage) => void): void;
+    /** Clean up resources. */
+    close(): void;
+}
+/**
+ * Creates a pair of linked transports for same-process use.
+ * Messages sent on one side are received on the other instantly.
+ */
+export declare function createInProcessTransport(): [Transport, Transport];
+/**
+ * Transport over stdio streams (newline-delimited JSON).
+ * Used for cross-process communication.
+ */
+export declare class StdioTransport implements Transport {
+    private readonly input;
+    private readonly output;
+    private rl;
+    private handlers;
+    constructor(input: Readable, output: Writable);
+    send(message: RpcMessage): void;
+    onMessage(handler: (message: RpcMessage) => void): void;
+    close(): void;
+}

package/dist/protocol/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Agent protocol — JSON-RPC-style messages for client-server communication.
+ *
+ * The protocol separates the agent engine (server) from the UI (client).
+ * Communication is bidirectional:
+ *   Client → Server: requests (run, approve, cancel, configure, query)
+ *   Server → Client: notifications (stream events, approval requests)
+ *   Server → Client: responses (results of requests)
+ */
+import type { StreamEvent, TokenUsage, TerminalReason, ApprovalRequest, ApprovalResult, PermissionMode } from "../types.js";
+export interface RpcRequest {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface RpcResponse {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: RpcError;
+}
+export interface RpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface RpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export type RpcMessage = RpcRequest | RpcResponse | RpcNotification;
+export declare const ErrorCodes: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly EngineNotReady: -32001;
+    readonly SessionNotFound: -32002;
+    readonly AlreadyRunning: -32003;
+    readonly NotRunning: -32004;
+};
+/** Start an agent run with a user task. */
+export interface RunParams {
+    task: string;
+    sessionId?: string;
+}
+export interface RunResult {
+    text: string;
+    reason: TerminalReason;
+    sessionId: string;
+    turnCount: number;
+    usage: TokenUsage;
+}
+/** Respond to an approval request from the server. */
+export interface ApproveParams {
+    requestId: string;
+    decision: ApprovalResult;
+}
+/** Cancel a running agent. */
+export interface CancelParams {
+    reason?: string;
+}
+/** Inject context into a session transcript. */
+export interface InjectParams {
+    sessionId: string;
+    content: string;
+}
+/** Update runtime configuration. */
+export interface ConfigureParams {
+    permissionMode?: PermissionMode;
+    planMode?: boolean;
+    bypassPermissions?: boolean;
+    effort?: string;
+    /** Switch active model by pool key (e.g. "sonnet", "haiku", "gpt"). */
+    model?: string;
+}
+/** Query server state. */
+export interface QueryParams {
+    type: "sessions" | "tools" | "config" | "session_detail" | "compact" | "config_set" | "models";
+    sessionId?: string;
+    /** Used by config_set: dotted key path */
+    key?: string;
+    /** Used by config_set: new value */
+    value?: unknown;
+}
+export interface QueryResult {
+    type: string;
+    data: unknown;
+}
+/** List / get session info. */
+export interface SessionListResult {
+    sessions: Array<{
+        sessionId: string;
+        cwd: string;
+        startedAt: number;
+        model: string;
+        status: string;
+        turnCount: number;
+    }>;
+}
+export interface ToolListResult {
+    tools: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+export interface ConfigResult {
+    permissionMode: PermissionMode;
+    planMode: boolean;
+    preset?: string;
+    model: string;
+    cwd: string;
+    maxContextTokens?: number;
+}
+/** Stream event forwarded from the engine. */
+export interface StreamEventNotification {
+    event: StreamEvent;
+}
+/** Server requests approval from the client (UI). */
+export interface ApprovalRequestNotification {
+    requestId: string;
+    request: ApprovalRequest;
+}
+/** Server status changed. */
+export interface StatusNotification {
+    status: "ready" | "running" | "error" | "shutdown";
+    message?: string;
+}
+export declare const Methods: {
+    readonly Run: "agent/run";
+    readonly Approve: "agent/approve";
+    readonly Cancel: "agent/cancel";
+    readonly Configure: "agent/configure";
+    readonly Query: "agent/query";
+    /** Inject context into transcript without triggering LLM. */
+    readonly Inject: "agent/inject";
+    readonly StreamEvent: "agent/streamEvent";
+    readonly ApprovalRequest: "agent/approvalRequest";
+    readonly Status: "agent/status";
+};
+export declare function createRequest(method: string, params?: Record<string, unknown>): RpcRequest;
+export declare function createResponse(id: string | number, result: unknown): RpcResponse;
+export declare function createErrorResponse(id: string | number, code: number, message: string, data?: unknown): RpcResponse;
+export declare function createNotification(method: string, params?: Record<string, unknown>): RpcNotification;
+export declare function isRequest(msg: RpcMessage): msg is RpcRequest;
+export declare function isResponse(msg: RpcMessage): msg is RpcResponse;
+export declare function isNotification(msg: RpcMessage): msg is RpcNotification;

package/dist/react-compiler-runtime-shim.d.ts

@@ -0,0 +1 @@
+export declare function c(size: number): any[];

package/dist/remote/bridge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Remote bridge — NDJSON over SSH for remote code-shell sessions.
+ *
+ * Architecture:
+ *   Local terminal ←→ SSH ←→ Remote code-shell (NDJSON stdio mode)
+ */
+export interface BridgeConfig {
+    host: string;
+    user?: string;
+    port?: number;
+    identityFile?: string;
+    remoteCommand?: string;
+}
+export declare class RemoteBridge {
+    private readonly config;
+    private ssh;
+    private connected;
+    constructor(config: BridgeConfig);
+    /**
+     * Connect to the remote host via SSH and start code-shell in NDJSON mode.
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a message to the remote code-shell.
+     */
+    send(message: Record<string, unknown>): void;
+    /**
+     * Async iterator for messages from the remote code-shell.
+     */
+    messages(): AsyncGenerator<Record<string, unknown>>;
+    /**
+     * Disconnect from the remote host.
+     */
+    disconnect(): void;
+    get isConnected(): boolean;
+    private buildSSHArgs;
+}

package/dist/run/ArtifactTracker.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ArtifactTracker — records meaningful artifact refs during run execution.
+ *
+ * Listens to StreamEvents and identifies:
+ *   - Files written or edited (Write / Edit tool results)
+ *   - Files created by Bash commands (mkdir, touch, cp, git commit, etc.)
+ *   - Structured outputs (e.g., generated configs, test results)
+ *
+ * Design constraint (§14):
+ *   - Only record artifacts valuable for recovery, display, evaluation, or audit
+ *   - Do NOT record every Read or every tool output
+ *   - Judgment: file writes are artifacts, reads are not
+ */
+import type { StreamEvent } from "../types.js";
+import type { RunStore } from "./RunStore.js";
+export interface ArtifactTrackerConfig {
+    runId: string;
+    store: RunStore;
+}
+export declare class ArtifactTracker {
+    private readonly config;
+    private readonly pendingCalls;
+    private readonly recordedPaths;
+    constructor(config: ArtifactTrackerConfig);
+    /**
+     * Feed a StreamEvent to the tracker.
+     */
+    onStreamEvent(event: StreamEvent): Promise<void>;
+    /** Get all recorded artifact paths. */
+    getRecordedPaths(): string[];
+    private processToolResult;
+    private recordFileArtifact;
+    /**
+     * Extract artifact refs from Bash commands.
+     * Only track commands that clearly produce files.
+     */
+    private extractBashArtifacts;
+}