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

package/dist/protocol/factories.js

@@ -0,0 +1,64 @@
+/**
+ * Typed factories — the recommended public entry points for business
+ * consumers of `@cjhyy/code-shell-core`.
+ *
+ * Standard §7 declares a stable API shape:
+ *
+ *   const [serverT, clientT] = createInProcessTransport();
+ *   const server = await createServer({ transport: serverT, cwd, llm });
+ *   const client = createClient({ transport: clientT });
+ *   client.onStreamEvent(({ sessionId, event }) => {});
+ *   await client.run({ sessionId: "main", task: "..." });
+ *
+ * Direct `new Engine(...)` / `new AgentServer(...)` / `new AgentClient(...)`
+ * remain supported for advanced cases, but most embedders should use these
+ * helpers. They:
+ *
+ *   - Construct the Engine for you from a flat config.
+ *   - Wire the AgentServer to the supplied transport.
+ *   - Return a `close()` lifecycle hook that cleans up in the right order.
+ *
+ * These factories deliberately accept a `Transport` rather than building
+ * one internally — they need to compose with `createInProcessTransport`
+ * (for in-process embedders), `StdioTransport` (for the worker), or a
+ * future `IpcAdapter`. A factory that hides the transport choice would
+ * preclude the multi-host story standard §S8 describes.
+ */
+import { Engine } from "../engine/engine.js";
+import { AgentServer } from "./server.js";
+import { AgentClient } from "./client.js";
+/**
+ * Build an `Engine` + `AgentServer` from a flat config and wire them to
+ * the caller's `Transport`. Most embedders should call this rather than
+ * instantiating the engine/server pair manually.
+ */
+export function createServer(options) {
+    const config = {
+        llm: options.llm,
+        cwd: options.cwd,
+        permissionMode: options.permissionMode,
+        ...options.engineOverrides,
+    };
+    const engine = new Engine(config);
+    const server = new AgentServer({ engine, transport: options.transport });
+    let closed = false;
+    return {
+        server,
+        engine,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            server.close();
+        },
+    };
+}
+/**
+ * Thin convenience wrapper around `new AgentClient`. Exists so the
+ * recommended public surface is fully createX-style, mirroring
+ * `createServer`. Future versions may add typed event subscriptions or
+ * stream-event filters here without breaking embedders.
+ */
+export function createClient(options) {
+    return new AgentClient({ transport: options.transport });
+}

package/dist/protocol/helpers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Helpers for spinning up an in-process AgentServer + AgentClient pair.
+ *
+ * All internal codeshell paths that want to run an engine should go through
+ * the protocol layer (AgentServer wraps the engine, AgentClient is the
+ * consumer-facing handle). This helper exists so callers don't repeat the
+ * 6-line "create transport / new server / new client / wire onStream /
+ * try-finally close" boilerplate at every call site.
+ *
+ * Existing call sites that should use this:
+ *   - src/cli/commands/run.ts        (headless CLI)
+ *   - src/run/EngineRunner.ts         (RunManager)
+ *
+ * The REPL builds its own server+client because it needs the long-lived
+ * AgentClient instance to drive the React UI's lifecycle (subscribing to
+ * stream events, approval requests, status changes). One-shot callers want
+ * the simpler "give me a client, hand back close()" shape this helper
+ * provides.
+ */
+import type { Engine } from "../engine/engine.js";
+import type { StreamCallback } from "../types.js";
+import { AgentClient } from "./client.js";
+export interface InProcessClientHandle {
+    /** The client; pass to `client.run(task, { cwd, sessionId })` to execute. */
+    readonly client: AgentClient;
+    /**
+     * Tear down server + client + transports. Call from a `finally` block.
+     * Safe to call multiple times; subsequent calls are no-ops.
+     */
+    close(): void;
+}
+export interface CreateInProcessClientOptions {
+    /** Stream callback to receive every event the server emits. */
+    onStream?: StreamCallback;
+}
+/**
+ * Wrap an Engine in an in-process AgentServer and return a client handle.
+ * The handle's `close()` tears the whole pair down in the correct order:
+ * client first (so its pending requests reject cleanly), then server (which
+ * aborts any active run and clears approval timers).
+ */
+export declare function createInProcessClient(engine: Engine, options?: CreateInProcessClientOptions): InProcessClientHandle;

package/dist/protocol/helpers.js

@@ -0,0 +1,55 @@
+/**
+ * Helpers for spinning up an in-process AgentServer + AgentClient pair.
+ *
+ * All internal codeshell paths that want to run an engine should go through
+ * the protocol layer (AgentServer wraps the engine, AgentClient is the
+ * consumer-facing handle). This helper exists so callers don't repeat the
+ * 6-line "create transport / new server / new client / wire onStream /
+ * try-finally close" boilerplate at every call site.
+ *
+ * Existing call sites that should use this:
+ *   - src/cli/commands/run.ts        (headless CLI)
+ *   - src/run/EngineRunner.ts         (RunManager)
+ *
+ * The REPL builds its own server+client because it needs the long-lived
+ * AgentClient instance to drive the React UI's lifecycle (subscribing to
+ * stream events, approval requests, status changes). One-shot callers want
+ * the simpler "give me a client, hand back close()" shape this helper
+ * provides.
+ */
+import { AgentServer } from "./server.js";
+import { AgentClient } from "./client.js";
+import { createInProcessTransport } from "./transport.js";
+/**
+ * Wrap an Engine in an in-process AgentServer and return a client handle.
+ * The handle's `close()` tears the whole pair down in the correct order:
+ * client first (so its pending requests reject cleanly), then server (which
+ * aborts any active run and clears approval timers).
+ */
+export function createInProcessClient(engine, options = {}) {
+    const [serverTransport, clientTransport] = createInProcessTransport();
+    const server = new AgentServer({ engine, transport: serverTransport });
+    const client = new AgentClient({ transport: clientTransport });
+    if (options.onStream) {
+        const cb = options.onStream;
+        client.onStreamEvent((envelope) => cb(envelope.event));
+    }
+    let closed = false;
+    return {
+        client,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            // Order matters: server.close() aborts the in-flight run AND emits
+            // a final "shutdown" status notification through the still-open
+            // transport pair. Then client.close() drains/rejects any pending
+            // requests and tears down its transport end. Reversing this order
+            // would silently drop the "shutdown" notification because the
+            // client's transport would already be closed when server.notify
+            // tries to send.
+            server.close();
+            client.close();
+        },
+    };
+}

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/index.js

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

package/dist/protocol/server.d.ts

@@ -0,0 +1,80 @@
+/**
+ * AgentServer — wraps ChatSessionManager 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 with sessionId envelope
+ *   - Manages per-session approval flow
+ *   - Dispatches agent/run through ChatSessionManager so multiple sessions
+ *     run concurrently without cross-talk
+ *
+ * Backward compat: an optional `engine` can be supplied for global operations
+ * (model list, config reads/writes, tool registry queries, etc.) that don't
+ * yet have a natural "which session" answer. When not supplied the server
+ * falls back to borrowing any live session's engine for those reads.
+ */
+import type { Transport } from "./transport.js";
+import type { Engine } from "../engine/engine.js";
+import type { ChatSessionManager } from "./chat-session-manager.js";
+export interface AgentServerOptions {
+    /**
+     * Multi-session manager. Required for the new multi-session protocol.
+     * When present, agent/run dispatches through the manager.
+     */
+    chatManager?: ChatSessionManager;
+    /**
+     * Legacy single-engine mode. When chatManager is not supplied the server
+     * falls back to the old single-engine behaviour (backwards compat for
+     * createInProcessClient and agent-server-stdio until T11).
+     */
+    engine?: Engine;
+    transport: Transport;
+}
+export declare class AgentServer {
+    private readonly chatManager;
+    private readonly legacyEngine;
+    private transport;
+    private running;
+    private abortController;
+    /** Pending approval requests: requestId → resolve function (legacy path) */
+    private pendingApprovals;
+    /** Timers for approval timeouts */
+    private approvalTimers;
+    /** Default approval timeout: 5 minutes */
+    private static readonly APPROVAL_TIMEOUT_MS;
+    /**
+     * Unsubscribe handle for the process-local `agentNotificationBus`
+     * subscription set up in the constructor. Called from `close()` so a
+     * shut-down server stops forwarding completion events even if the bus
+     * itself outlives the server (it's a process-local singleton).
+     */
+    private bgAgentBusUnsubscribe;
+    constructor(options: AgentServerOptions);
+    private handleRequest;
+    private handleRun;
+    private handleRunMulti;
+    private handleRunLegacy;
+    private handleApprove;
+    private handleCancel;
+    private handleCloseSession;
+    private handleConfigure;
+    private handleQuery;
+    private handleInject;
+    /**
+     * Ask the client to approve a tool operation (legacy single-engine path).
+     */
+    private requestApprovalFromClient;
+    /**
+     * Ask the client to answer a question from the agent (legacy single-engine path).
+     */
+    private requestAskUserFromClient;
+    private notify;
+    /**
+     * Get any available engine — used for global query ops when chatManager is
+     * present but no legacyEngine was supplied. Borrows the first live session.
+     */
+    private anyEngine;
+    close(): void;
+    private clearApprovalTimer;
+    private clearAllApprovalTimers;
+}