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

package/dist/protocol/transport.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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,
+ *                         e.g. agent daemon spawned as child)
+ */
+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/transport.js

@@ -0,0 +1,85 @@
+/**
+ * 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,
+ *                         e.g. agent daemon spawned as child)
+ */
+import { EventEmitter } from "node:events";
+import { createInterface } from "node:readline";
+// ─── In-Process Transport ───────────────────────────────────────────
+/**
+ * Creates a pair of linked transports for same-process use.
+ * Messages sent on one side are received on the other instantly.
+ */
+export function createInProcessTransport() {
+    const emitterA = new EventEmitter();
+    const emitterB = new EventEmitter();
+    const sideA = {
+        send(msg) {
+            // A sends → B receives
+            emitterB.emit("message", msg);
+        },
+        onMessage(handler) {
+            emitterA.on("message", handler);
+        },
+        close() {
+            emitterA.removeAllListeners();
+            emitterB.removeAllListeners();
+        },
+    };
+    const sideB = {
+        send(msg) {
+            // B sends → A receives
+            emitterA.emit("message", msg);
+        },
+        onMessage(handler) {
+            emitterB.on("message", handler);
+        },
+        close() {
+            emitterA.removeAllListeners();
+            emitterB.removeAllListeners();
+        },
+    };
+    return [sideA, sideB];
+}
+// ─── Stdio Transport ────────────────────────────────────────────────
+/**
+ * Transport over stdio streams (newline-delimited JSON).
+ * Used for cross-process communication.
+ */
+export class StdioTransport {
+    input;
+    output;
+    rl;
+    handlers = [];
+    constructor(input, output) {
+        this.input = input;
+        this.output = output;
+        this.rl = createInterface({ input: this.input });
+        this.rl.on("line", (line) => {
+            if (!line.trim())
+                return;
+            try {
+                const msg = JSON.parse(line);
+                for (const handler of this.handlers) {
+                    handler(msg);
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        });
+    }
+    send(message) {
+        this.output.write(JSON.stringify(message) + "\n");
+    }
+    onMessage(handler) {
+        this.handlers.push(handler);
+    }
+    close() {
+        this.rl.close();
+        this.handlers = [];
+    }
+}

package/dist/protocol/types.d.ts

@@ -0,0 +1,221 @@
+/**
+ * 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 Overloaded: -32001;
+    readonly SessionNotFound: -32002;
+    readonly SessionClosed: -32004;
+};
+/** Start an agent run with a user task. */
+export interface RunParams {
+    sessionId: string;
+    task: string;
+    /**
+     * Working directory for this run. When omitted, the Engine uses its
+     * configured cwd.
+     */
+    cwd?: string;
+    /**
+     * Per-run permission mode supplied by desktop/composer UIs.
+     * When omitted, the engine keeps its configured default.
+     */
+    permissionMode?: PermissionMode;
+    /**
+     * Per-run plan-mode flag. When true, the Engine enters plan mode for
+     * this run; when omitted, the engine keeps its configured default.
+     */
+    planMode?: boolean;
+}
+export interface RunResult {
+    text: string;
+    reason: TerminalReason;
+    sessionId: string;
+    turnCount: number;
+    usage: TokenUsage;
+}
+/** Respond to an approval request from the server. */
+export interface ApproveParams {
+    sessionId: string;
+    requestId: string;
+    decision: ApprovalResult;
+}
+/** Cancel a running agent turn. */
+export interface CancelParams {
+    sessionId: string;
+    reason?: string;
+}
+/** Close (destroy) a session. */
+export interface CloseSessionParams {
+    sessionId: string;
+}
+/** Inject context into a session transcript. */
+export interface InjectParams {
+    sessionId: string;
+    content: string;
+}
+/** Update runtime configuration. */
+export interface ConfigureParams {
+    /** When present, configure that specific chat session. Otherwise worker-global. */
+    sessionId?: string;
+    permissionMode?: PermissionMode;
+    planMode?: boolean;
+    bypassPermissions?: boolean;
+    effort?: string;
+    /** Switch active model by pool key (e.g. "sonnet", "haiku", "gpt"). */
+    model?: string;
+    /**
+     * Re-read settings (providers[]/models[]) into the engine's ModelPool before
+     * any model switch. Set after onboarding/login persists new entries so the
+     * running engine picks them up without a process restart.
+     */
+    reloadModels?: boolean;
+}
+/** Query server state. */
+export interface QueryParams {
+    type: "sessions" | "tools" | "config" | "session_detail" | "compact" | "config_set" | "config_get" | "permission_set" | "models" | "providers" | "arena_status" | "provider_add" | "provider_refresh" | "provider_delete" | "model_add" | "model_delete";
+    sessionId?: string;
+    /** Used by config_set / permission_set: dotted key path or mode field */
+    key?: string;
+    /** Used by config_set / permission_set: new value */
+    value?: unknown;
+    /** Used by provider_add: full ProviderConfig payload */
+    provider?: unknown;
+    /** Used by model_add: the new model entry */
+    model?: 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;
+    }>;
+}
+/** Shape of a model-pool entry returned by query("models"). */
+export interface ProtocolModelEntry {
+    key: string;
+    label: string;
+    model: string;
+    /**
+     * Protocol the LLM client speaks ("openai" or "anthropic"). DeepSeek,
+     * Mistral, etc. all use "openai" since they're OpenAI-compatible.
+     * NOT the brand/vendor — that's providerKey below.
+     */
+    protocol: string;
+    /**
+     * Pool entry's reference into settings.providers[]. Used by ModelManager
+     * to derive each provider's modelCount client-side ("how many models
+     * point at me"). Optional because auto-populated entries (autoPopulatePool)
+     * don't go through the wizard and have no providers[] row.
+     */
+    providerKey?: string;
+    active: boolean;
+    /** Max output tokens (0 or undefined = unknown). */
+    maxOutputTokens?: number;
+    /** Max context window size (0 or undefined = unknown). */
+    maxContextTokens?: number;
+}
+export interface ProtocolProviderEntry {
+    key: string;
+    label: string;
+    kind: string;
+    modelCount: number;
+    cachedModels?: number;
+    cachedAt?: string;
+}
+export interface ConfigResult {
+    permissionMode: PermissionMode;
+    planMode: boolean;
+    preset?: string;
+    model: string;
+    cwd: string;
+    maxContextTokens?: number;
+}
+/** Stream event forwarded from the engine (legacy, no sessionId). */
+export interface StreamEventNotification {
+    event: StreamEvent;
+}
+/** Multi-session stream event envelope — carries the originating sessionId. */
+export interface AgentStreamEventNotification {
+    sessionId: string;
+    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";
+    /** Close (destroy) a session. */
+    readonly CloseSession: "agent/closeSession";
+    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/protocol/types.js

@@ -0,0 +1,61 @@
+/**
+ * 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)
+ */
+// ─── Error Codes ────────────────────────────────────────────────────
+export const ErrorCodes = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+    // Custom codes
+    Overloaded: -32001,
+    SessionNotFound: -32002,
+    SessionClosed: -32004,
+};
+// ─── Method Names ───────────────────────────────────────────────────
+export const Methods = {
+    // Client → Server
+    Run: "agent/run",
+    Approve: "agent/approve",
+    Cancel: "agent/cancel",
+    Configure: "agent/configure",
+    Query: "agent/query",
+    /** Inject context into transcript without triggering LLM. */
+    Inject: "agent/inject",
+    /** Close (destroy) a session. */
+    CloseSession: "agent/closeSession",
+    // Server → Client (notifications, no id)
+    StreamEvent: "agent/streamEvent",
+    ApprovalRequest: "agent/approvalRequest",
+    Status: "agent/status",
+};
+// ─── Helpers ────────────────────────────────────────────────────────
+let _nextId = 1;
+export function createRequest(method, params) {
+    return { jsonrpc: "2.0", id: _nextId++, method, params };
+}
+export function createResponse(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+export function createErrorResponse(id, code, message, data) {
+    return { jsonrpc: "2.0", id, error: { code, message, data } };
+}
+export function createNotification(method, params) {
+    return { jsonrpc: "2.0", method, params };
+}
+export function isRequest(msg) {
+    return "method" in msg && "id" in msg;
+}
+export function isResponse(msg) {
+    return "id" in msg && !("method" in msg);
+}
+export function isNotification(msg) {
+    return "method" in msg && !("id" in msg);
+}

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/remote/bridge.js

@@ -0,0 +1,103 @@
+/**
+ * Remote bridge — NDJSON over SSH for remote code-shell sessions.
+ *
+ * Architecture:
+ *   Local terminal ←→ SSH ←→ Remote code-shell (NDJSON stdio mode)
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+export class RemoteBridge {
+    config;
+    ssh;
+    connected = false;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Connect to the remote host via SSH and start code-shell in NDJSON mode.
+     */
+    async connect() {
+        const sshArgs = this.buildSSHArgs();
+        const remoteCmd = this.config.remoteCommand ?? "code-shell run --output stream-json";
+        this.ssh = spawn("ssh", [...sshArgs, remoteCmd], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error("SSH connection timed out"));
+                this.disconnect();
+            }, 30000);
+            this.ssh.stdout?.once("data", () => {
+                clearTimeout(timer);
+                this.connected = true;
+                resolve();
+            });
+            this.ssh.on("error", (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+            this.ssh.on("exit", (code) => {
+                this.connected = false;
+                if (!this.connected) {
+                    clearTimeout(timer);
+                    reject(new Error(`SSH exited with code ${code}`));
+                }
+            });
+        });
+    }
+    /**
+     * Send a message to the remote code-shell.
+     */
+    send(message) {
+        if (!this.connected || !this.ssh?.stdin) {
+            throw new Error("Not connected");
+        }
+        this.ssh.stdin.write(JSON.stringify(message) + "\n");
+    }
+    /**
+     * Async iterator for messages from the remote code-shell.
+     */
+    async *messages() {
+        if (!this.ssh?.stdout)
+            return;
+        const rl = createInterface({ input: this.ssh.stdout, crlfDelay: Infinity });
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                yield JSON.parse(trimmed);
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+    }
+    /**
+     * Disconnect from the remote host.
+     */
+    disconnect() {
+        this.connected = false;
+        if (this.ssh) {
+            this.ssh.kill();
+            this.ssh = undefined;
+        }
+    }
+    get isConnected() {
+        return this.connected;
+    }
+    buildSSHArgs() {
+        const args = ["-T"]; // No pseudo-terminal
+        if (this.config.port)
+            args.push("-p", String(this.config.port));
+        if (this.config.identityFile)
+            args.push("-i", this.config.identityFile);
+        if (this.config.user) {
+            args.push(`${this.config.user}@${this.config.host}`);
+        }
+        else {
+            args.push(this.config.host);
+        }
+        return args;
+    }
+}

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;
+}