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

package/dist/protocol/chat-session-manager.d.ts

@@ -0,0 +1,33 @@
+import { ChatSession } from "./chat-session.js";
+import type { Engine } from "../engine/engine.js";
+import type { EngineRuntime } from "../engine/runtime.js";
+import type { EngineConfig } from "../engine/engine.js";
+export type EngineConfigSlice = Pick<EngineConfig, "permissionMode" | "preset" | "customSystemPrompt" | "appendSystemPrompt" | "maxTurns" | "maxContextTokens" | "cwd">;
+export interface ChatSessionManagerOptions {
+    /**
+     * Shared runtime, supplied here so callers and engineFactory closures
+     * derived from these options can reference one canonical instance. The
+     * manager itself does not retain it — engineFactory captures it via closure.
+     */
+    runtime: EngineRuntime;
+    /** Build an Engine. Tests inject a fake; production passes a runtime-backed Engine factory. */
+    engineFactory: (slice: EngineConfigSlice) => Engine;
+    maxSessions?: number;
+    idleTtlMs?: number;
+}
+export declare class ChatSessionManager {
+    private readonly sessions;
+    private readonly factory;
+    private readonly maxSessions;
+    private readonly idleTtlMs;
+    private sweeper;
+    constructor(opts: ChatSessionManagerOptions);
+    getOrCreate(sessionId: string, slice: EngineConfigSlice): ChatSession;
+    get(sessionId: string): ChatSession | undefined;
+    close(sessionId: string): void;
+    closeAll(): void;
+    sessionCount(): number;
+    sweepIdle(): void;
+    startIdleSweeper(intervalMs?: number): void;
+    stopIdleSweeper(): void;
+}

package/dist/protocol/chat-session-manager.js

@@ -0,0 +1,65 @@
+import { ChatSession } from "./chat-session.js";
+export class ChatSessionManager {
+    sessions = new Map();
+    factory;
+    maxSessions;
+    idleTtlMs;
+    sweeper = null;
+    constructor(opts) {
+        this.factory = opts.engineFactory;
+        this.maxSessions = opts.maxSessions ?? 16;
+        this.idleTtlMs = opts.idleTtlMs ?? 30 * 60 * 1000;
+    }
+    getOrCreate(sessionId, slice) {
+        const existing = this.sessions.get(sessionId);
+        if (existing) {
+            existing.lastActivityAt = Date.now();
+            return existing;
+        }
+        if (this.sessions.size >= this.maxSessions) {
+            const err = new Error(`Overloaded: maxSessions=${this.maxSessions} reached`);
+            err.code = -32001;
+            throw err;
+        }
+        const engine = this.factory(slice);
+        const session = new ChatSession({ id: sessionId, engine });
+        this.sessions.set(sessionId, session);
+        return session;
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    close(sessionId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            return;
+        s.cancel();
+        this.sessions.delete(sessionId);
+    }
+    closeAll() {
+        for (const id of [...this.sessions.keys()])
+            this.close(id);
+    }
+    sessionCount() {
+        return this.sessions.size;
+    }
+    sweepIdle() {
+        const cutoff = Date.now() - this.idleTtlMs;
+        for (const [id, s] of [...this.sessions]) {
+            if (s.lastActivityAt < cutoff && !s.isBusy())
+                this.close(id);
+        }
+    }
+    startIdleSweeper(intervalMs = 60_000) {
+        if (this.sweeper)
+            return;
+        this.sweeper = setInterval(() => this.sweepIdle(), intervalMs);
+        // Allow the process to exit even if sweeper is pending.
+        this.sweeper?.unref?.();
+    }
+    stopIdleSweeper() {
+        if (this.sweeper)
+            clearInterval(this.sweeper);
+        this.sweeper = null;
+    }
+}

package/dist/protocol/chat-session.d.ts

@@ -0,0 +1,49 @@
+import type { Engine, EngineResult } from "../engine/engine.js";
+import type { StreamEvent } from "../types.js";
+export interface ChatSessionOptions {
+    id: string;
+    engine: Engine;
+    onStream?: (event: StreamEvent) => void;
+}
+export interface TurnOpts {
+    /** Working directory override for this turn. If omitted, Engine uses its
+     *  configured cwd. */
+    cwd?: string;
+    onStream?: (event: StreamEvent) => void;
+}
+/**
+ * One ChatSession per UI chat tab. Owns a single Engine, an AbortController
+ * for the active turn, and a FIFO queue so a fast second send waits for the
+ * first turn to finish instead of being silently rejected.
+ */
+export declare class ChatSession {
+    readonly id: string;
+    readonly engine: Engine;
+    /**
+     * Per-session approval callbacks indexed by tool-call requestId.
+     * `readonly` guards the Map reference (preventing reassignment); the
+     * contents are mutated by `.set()` / `.delete()` as approvals come and go.
+     * Task 10 will register entries here when the Engine raises an approval
+     * request and clean them up on response.
+     */
+    readonly pendingApprovals: Map<string, (decision: unknown) => void>;
+    lastActivityAt: number;
+    private queue;
+    private active;
+    private controller;
+    private readonly defaultOnStream?;
+    constructor(opts: ChatSessionOptions);
+    enqueueTurn(task: string, opts: TurnOpts): Promise<EngineResult>;
+    /**
+     * Abort the in-flight turn and drain queued turns.
+     *
+     * Relies on `engine.run()` honouring the `AbortSignal`. If `engine.run` were
+     * to swallow the abort and resolve successfully, the caller of the in-flight
+     * `enqueueTurn` would observe success — not a cancellation. The queued turns
+     * are always rejected regardless.
+     */
+    cancel(): void;
+    isBusy(): boolean;
+    queueDepth(): number;
+    private pump;
+}

package/dist/protocol/chat-session.js

@@ -0,0 +1,86 @@
+/**
+ * One ChatSession per UI chat tab. Owns a single Engine, an AbortController
+ * for the active turn, and a FIFO queue so a fast second send waits for the
+ * first turn to finish instead of being silently rejected.
+ */
+export class ChatSession {
+    id;
+    engine;
+    /**
+     * Per-session approval callbacks indexed by tool-call requestId.
+     * `readonly` guards the Map reference (preventing reassignment); the
+     * contents are mutated by `.set()` / `.delete()` as approvals come and go.
+     * Task 10 will register entries here when the Engine raises an approval
+     * request and clean them up on response.
+     */
+    pendingApprovals = new Map();
+    lastActivityAt = Date.now();
+    queue = [];
+    active = null;
+    controller = null;
+    defaultOnStream;
+    constructor(opts) {
+        this.id = opts.id;
+        this.engine = opts.engine;
+        this.defaultOnStream = opts.onStream;
+    }
+    enqueueTurn(task, opts) {
+        this.lastActivityAt = Date.now();
+        return new Promise((resolve, reject) => {
+            this.queue.push({ task, opts, resolve, reject });
+            this.pump();
+        });
+    }
+    /**
+     * Abort the in-flight turn and drain queued turns.
+     *
+     * Relies on `engine.run()` honouring the `AbortSignal`. If `engine.run` were
+     * to swallow the abort and resolve successfully, the caller of the in-flight
+     * `enqueueTurn` would observe success — not a cancellation. The queued turns
+     * are always rejected regardless.
+     */
+    cancel() {
+        this.controller?.abort();
+        // Drain queued turns as cancelled
+        const drained = this.queue.splice(0);
+        for (const t of drained) {
+            t.reject(new Error("cancelled: session aborted before turn ran"));
+        }
+    }
+    isBusy() {
+        return this.active !== null;
+    }
+    queueDepth() {
+        return this.queue.length;
+    }
+    async pump() {
+        if (this.active)
+            return;
+        const next = this.queue.shift();
+        if (!next)
+            return;
+        this.active = next;
+        this.controller = new AbortController();
+        try {
+            const onStream = next.opts.onStream ?? this.defaultOnStream;
+            const result = await this.engine.run(next.task, {
+                cwd: next.opts.cwd,
+                sessionId: this.id,
+                signal: this.controller.signal,
+                onStream,
+            });
+            this.lastActivityAt = Date.now();
+            next.resolve(result);
+        }
+        catch (err) {
+            next.reject(err);
+        }
+        finally {
+            this.active = null;
+            this.controller = null;
+            // Drain the next turn if one is waiting.
+            if (this.queue.length > 0)
+                void this.pump();
+        }
+    }
+}

package/dist/protocol/client.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 RunParams, type RunResult, type AgentStreamEventNotification, type ConfigureParams, type QueryParams, type QueryResult } from "./types.js";
+import type { ApprovalRequest, ApprovalResult, PermissionMode, BackgroundAgentCompletedEvent } from "../types.js";
+export interface AgentClientEvents {
+    /** Multi-session envelope: carries sessionId + event. */
+    stream: (envelope: AgentStreamEventNotification) => void;
+    approvalRequest: (requestId: string, request: ApprovalRequest) => void;
+    status: (status: string, message?: string) => void;
+}
+export interface AgentRunOptions {
+    cwd?: string;
+    sessionId?: string;
+    permissionMode?: PermissionMode;
+    planMode?: boolean;
+}
+export type BackgroundAgentCompletedHandler = (sessionId: string, event: BackgroundAgentCompletedEvent) => void;
+export declare class AgentClient {
+    private transport;
+    private emitter;
+    private pendingRequests;
+    /**
+     * Map from a user-supplied `BackgroundAgentCompletedHandler` to the
+     * internal envelope-filtering wrapper actually registered on the
+     * EventEmitter. Lets `offBackgroundAgentCompleted` look up the real
+     * listener so removal is symmetric with subscription.
+     */
+    private bgAgentHandlers;
+    constructor(options: {
+        transport: Transport;
+    });
+    /**
+     * Run an agent task. Resolves when the agent completes.
+     * Stream events arrive via the onStreamEvent callback.
+     *
+     * Accepts either the new object form `{ sessionId, task, ... }` (required
+     * for multi-session servers) or the legacy string form `(task, sessionId?)`
+     * for backward compatibility with createInProcessClient callers.
+     */
+    run(taskOrParams: string | RunParams, sessionIdOrOptions?: string | AgentRunOptions): Promise<RunResult>;
+    /**
+     * Respond to an approval request from the server.
+     *
+     * Multi-session form: approve(sessionId, requestId, decision)
+     * Legacy form:        approve(requestId, decision)
+     */
+    approve(sessionId: string, requestId: string, decision: ApprovalResult): Promise<void>;
+    approve(requestId: string, decision: ApprovalResult): Promise<void>;
+    /**
+     * Cancel a running agent.
+     *
+     * Multi-session form: cancel(sessionId, reason?)
+     * Legacy form:        cancel(reason?)
+     */
+    cancel(sessionId?: string, reason?: string): Promise<void>;
+    /**
+     * Update runtime configuration on the server.
+     */
+    configure(params: ConfigureParams): Promise<Record<string, unknown>>;
+    /**
+     * Query server state.
+     */
+    query(type: QueryParams["type"], arg?: string | Record<string, unknown>, ...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>;
+    /**
+     * Register a handler for stream event notifications.
+     * The handler receives the full envelope `{ sessionId, event }` so callers
+     * can route events to the correct tab/session.
+     */
+    onStreamEvent(handler: (envelope: AgentStreamEventNotification) => void): void;
+    offStreamEvent(handler: (envelope: AgentStreamEventNotification) => 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;
+    /**
+     * Typed convenience for the B2.2 `background_agent_completed` stream
+     * event. Internally wraps `onStreamEvent`, so catch-all stream
+     * consumers keep seeing the same envelope; this just adds a typed
+     * entry point so SDK callers don't have to switch on `event.type`
+     * themselves.
+     */
+    onBackgroundAgentCompleted(handler: BackgroundAgentCompletedHandler): void;
+    offBackgroundAgentCompleted(handler: BackgroundAgentCompletedHandler): void;
+    private request;
+    private handleResponse;
+    private handleNotification;
+    close(): void;
+}

package/dist/protocol/client.js

@@ -0,0 +1,260 @@
+/**
+ * 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 { Methods, createRequest, isResponse, isNotification, } from "./types.js";
+import { EventEmitter } from "node:events";
+import { logger } from "../logging/logger.js";
+export class AgentClient {
+    transport;
+    emitter = new EventEmitter();
+    pendingRequests = new Map();
+    /**
+     * Map from a user-supplied `BackgroundAgentCompletedHandler` to the
+     * internal envelope-filtering wrapper actually registered on the
+     * EventEmitter. Lets `offBackgroundAgentCompleted` look up the real
+     * listener so removal is symmetric with subscription.
+     */
+    bgAgentHandlers = new Map();
+    constructor(options) {
+        this.transport = options.transport;
+        this.transport.onMessage((msg) => {
+            if (isResponse(msg)) {
+                this.handleResponse(msg);
+            }
+            else if (isNotification(msg)) {
+                this.handleNotification(msg);
+            }
+        });
+    }
+    // ─── Requests ───────────────────────────────────────────────────
+    /**
+     * Run an agent task. Resolves when the agent completes.
+     * Stream events arrive via the onStreamEvent callback.
+     *
+     * Accepts either the new object form `{ sessionId, task, ... }` (required
+     * for multi-session servers) or the legacy string form `(task, sessionId?)`
+     * for backward compatibility with createInProcessClient callers.
+     */
+    async run(taskOrParams, sessionIdOrOptions) {
+        let params;
+        if (typeof taskOrParams === "string") {
+            // Form: run(task, sessionId | options?)
+            const options = typeof sessionIdOrOptions === "string"
+                ? { sessionId: sessionIdOrOptions }
+                : sessionIdOrOptions;
+            params = {
+                task: taskOrParams,
+                sessionId: options?.sessionId ?? "",
+                ...(options ?? {}),
+            };
+        }
+        else {
+            // Form: run({ sessionId, task, ... }). The caller-provided fields
+            // win; the empty-string default only fills in when sessionId is
+            // truly absent (cold start).
+            params = { ...taskOrParams, sessionId: taskOrParams.sessionId ?? "" };
+        }
+        // If the caller provided a session id, stamp it on the logger eagerly
+        // so client-side log lines emitted during this run (before the server
+        // response arrives) carry the right sid. The server-resolved id from
+        // the response below takes precedence — they only differ on the
+        // first call of a brand-new session, when sessionId is undefined.
+        if (params.sessionId)
+            logger.setSid(params.sessionId);
+        const result = (await this.request(Methods.Run, params));
+        if (result.sessionId)
+            logger.setSid(result.sessionId);
+        return result;
+    }
+    approve(...args) {
+        if (args.length === 3) {
+            const [sessionId, requestId, decision] = args;
+            return this.request(Methods.Approve, {
+                sessionId,
+                requestId,
+                decision,
+            });
+        }
+        const [requestId, decision] = args;
+        return this.request(Methods.Approve, {
+            requestId,
+            decision,
+        });
+    }
+    /**
+     * Cancel a running agent.
+     *
+     * Multi-session form: cancel(sessionId, reason?)
+     * Legacy form:        cancel(reason?)
+     */
+    async cancel(sessionId, reason) {
+        await this.request(Methods.Cancel, { sessionId, reason });
+    }
+    /**
+     * Update runtime configuration on the server.
+     */
+    async configure(params) {
+        return this.request(Methods.Configure, params);
+    }
+    /**
+     * Query server state.
+     */
+    async query(type, arg, ...extra) {
+        const params = { type };
+        // Per-type argument mapping. The second positional param overloads:
+        //   - "models" / "sessions" / "providers" / "permission_state": (sessionId?)
+        //   - "config_set": (key, value)
+        //   - "config_get": (key)
+        //   - "permission_set": (mode) — server reads `params.value`
+        //   - "provider_add" / "model_add" / "provider_refresh" /
+        //     "provider_delete" / "model_delete": ({ ...payload }) — the object
+        //     is spread into the top-level params so the server can read
+        //     `params.key` / `params.provider` / `params.model` directly.
+        if (type === "config_set" && extra.length >= 1) {
+            params.key = arg;
+            params.value = extra[0];
+        }
+        else if (type === "config_get") {
+            params.key = arg;
+        }
+        else if (type === "permission_set") {
+            params.value = arg;
+        }
+        else if (type === "provider_add" ||
+            type === "model_add" ||
+            type === "provider_refresh" ||
+            type === "provider_delete" ||
+            type === "model_delete") {
+            if (arg && typeof arg === "object")
+                Object.assign(params, arg);
+        }
+        else {
+            params.sessionId = arg;
+        }
+        return this.request(Methods.Query, params);
+    }
+    /**
+     * Inject context into the session transcript without triggering a LLM turn.
+     * Used to make arena results, tool outputs, etc. visible to subsequent LLM calls.
+     */
+    async inject(sessionId, content) {
+        await this.request(Methods.Inject, { sessionId, content });
+    }
+    // ─── Event Handlers ─────────────────────────────────────────────
+    /**
+     * Register a handler for stream event notifications.
+     * The handler receives the full envelope `{ sessionId, event }` so callers
+     * can route events to the correct tab/session.
+     */
+    onStreamEvent(handler) {
+        this.emitter.on("stream", handler);
+    }
+    offStreamEvent(handler) {
+        this.emitter.off("stream", handler);
+    }
+    onApprovalRequest(handler) {
+        this.emitter.on("approvalRequest", handler);
+    }
+    offApprovalRequest(handler) {
+        this.emitter.off("approvalRequest", handler);
+    }
+    onStatus(handler) {
+        this.emitter.on("status", handler);
+    }
+    offStatus(handler) {
+        this.emitter.off("status", handler);
+    }
+    /**
+     * Typed convenience for the B2.2 `background_agent_completed` stream
+     * event. Internally wraps `onStreamEvent`, so catch-all stream
+     * consumers keep seeing the same envelope; this just adds a typed
+     * entry point so SDK callers don't have to switch on `event.type`
+     * themselves.
+     */
+    onBackgroundAgentCompleted(handler) {
+        const wrapper = (envelope) => {
+            if (envelope.event.type === "background_agent_completed") {
+                handler(envelope.sessionId, envelope.event);
+            }
+        };
+        this.bgAgentHandlers.set(handler, wrapper);
+        this.emitter.on("stream", wrapper);
+    }
+    offBackgroundAgentCompleted(handler) {
+        const wrapper = this.bgAgentHandlers.get(handler);
+        if (!wrapper)
+            return;
+        this.bgAgentHandlers.delete(handler);
+        this.emitter.off("stream", wrapper);
+    }
+    // ─── Internals ──────────────────────────────────────────────────
+    request(method, params) {
+        return new Promise((resolve, reject) => {
+            const req = createRequest(method, params);
+            this.pendingRequests.set(req.id, { resolve, reject });
+            this.transport.send(req);
+        });
+    }
+    handleResponse(res) {
+        const pending = this.pendingRequests.get(res.id);
+        if (!pending)
+            return;
+        this.pendingRequests.delete(res.id);
+        if (res.error) {
+            // Attach both message and code so callers can do toMatchObject({ code }).
+            const err = new Error(`[${res.error.code}] ${res.error.message}`);
+            err.code = res.error.code;
+            pending.reject(err);
+        }
+        else {
+            pending.resolve(res.result);
+        }
+    }
+    handleNotification(notif) {
+        const params = (notif.params ?? {});
+        switch (notif.method) {
+            case Methods.StreamEvent: {
+                const event = params.event;
+                const sessionId = params.sessionId ?? "";
+                if (event) {
+                    const envelope = { sessionId, event };
+                    this.emitter.emit("stream", envelope);
+                }
+                break;
+            }
+            case Methods.ApprovalRequest: {
+                const requestId = params.requestId;
+                const request = params.request;
+                if (requestId && request) {
+                    this.emitter.emit("approvalRequest", requestId, request);
+                }
+                break;
+            }
+            case Methods.Status: {
+                const status = params.status;
+                const message = params.message;
+                this.emitter.emit("status", status, message);
+                break;
+            }
+        }
+    }
+    close() {
+        // Reject all pending requests
+        for (const [, pending] of this.pendingRequests) {
+            pending.reject(new Error("Client closed"));
+        }
+        this.pendingRequests.clear();
+        this.bgAgentHandlers.clear();
+        this.emitter.removeAllListeners();
+        this.transport.close();
+    }
+}

package/dist/protocol/factories.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 type { LLMConfig } from "../types.js";
+import { Engine, type EngineConfig } from "../engine/engine.js";
+import { AgentServer } from "./server.js";
+import { AgentClient } from "./client.js";
+import type { Transport } from "./transport.js";
+export interface CreateServerOptions {
+    /**
+     * Transport the server reads requests from and writes notifications to.
+     * Pair it with the matching client transport from
+     * `createInProcessTransport()` (in-process embed) or a `StdioTransport`
+     * (worker process).
+     */
+    transport: Transport;
+    /**
+     * LLM provider/model credentials. Forwarded to `EngineConfig.llm`.
+     * Required because there is no useful default — every embedder needs
+     * to choose a provider.
+     */
+    llm: LLMConfig;
+    /** Working directory the Engine treats as the project root. */
+    cwd?: string;
+    /** Permission mode for the Engine. Defaults to "default". */
+    permissionMode?: EngineConfig["permissionMode"];
+    /**
+     * Escape hatch for embedders who need to set EngineConfig fields the
+     * stable surface doesn't expose. Anything passed here is shallow-merged
+     * over the factory's computed config. Use sparingly — fields outside
+     * this options bag are not part of the stable API contract and may
+     * move to `internal` in a future version.
+     */
+    engineOverrides?: Partial<EngineConfig>;
+}
+export interface ServerHandle {
+    /**
+     * The constructed AgentServer. Most embedders only need `close()`; this
+     * is exposed for advanced cases (custom hook registration, dynamic tool
+     * registry updates) that the typed surface doesn't yet cover.
+     */
+    readonly server: AgentServer;
+    /**
+     * The Engine instance the server wraps. Same caveat as `server` —
+     * direct access is supported but not recommended.
+     */
+    readonly engine: Engine;
+    /**
+     * Tear down the server (which aborts any active run + emits the final
+     * shutdown notification). Safe to call multiple times.
+     */
+    close(): void;
+}
+/**
+ * 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 declare function createServer(options: CreateServerOptions): ServerHandle;
+export interface CreateClientOptions {
+    /** Transport paired with the server's. */
+    transport: Transport;
+}
+/**
+ * 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 declare function createClient(options: CreateClientOptions): AgentClient;