operon-agents 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,55 @@
+MIT License
+
+Copyright (c) 2026 Yingjie Qiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+-------------------------------------------------------------------------------
+
+THIRD-PARTY LICENSES
+
+Portions of this software were adapted from kimi-code, which is distributed
+under the MIT License. Its copyright and permission notice is reproduced below.
+
+-------------------------------------------------------------------------------
+
+kimi-code
+
+MIT License
+
+Copyright (c) 2026 Moonshot AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# operon-agents
+
+Public SDK entrypoint for building agents.
+
+```ts
+import { Agent, Runner, Session, ChatModel, tool } from "operon-agents";
+```
+
+Use `operon-agents` from applications. `operon-agents-core` is the lower-level
+engine package.
+
+Focused subpaths are available for larger capability areas:
+
+```ts
+import { TransportMCPServer } from "operon-agents/mcp";
+import { bashTool, readTool } from "operon-agents/tools";
+import { OTelTracingProcessor } from "operon-agents/tracing";
+```

package/dist/app-server/client.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Reference TypeScript client for the app-server protocol.
+ *
+ * It is both (1) a drop-in-ish, Harness-shaped wrapper around a spawned
+ * `operon-app-server` process and (2) the executable spec other-language clients
+ * mirror. The transport is injectable, so it also runs over `pairedTransports`
+ * in-process for tests.
+ */
+import { type ChildProcess } from "node:child_process";
+import type { AgentEvent, ApprovalRequest, ApprovalResponse, QuestionRequest, QuestionResult, RunResult, SessionSummary } from "operon-agents-core";
+import { type JsonRpcTransport } from "./codec.ts";
+import { type ClientCapabilities, type InitializeResult, type SessionFollowUpResult, type SessionInfo, type SessionSnapshotResult, type SessionSteerResult } from "./protocol.ts";
+export type ApprovalHandler = (request: ApprovalRequest, sessionId: string) => Promise<ApprovalResponse> | ApprovalResponse;
+export type QuestionHandler = (request: QuestionRequest, sessionId: string, options: {
+    readonly signal: AbortSignal;
+}) => Promise<QuestionResult> | QuestionResult;
+export type EventListener = (event: AgentEvent) => void;
+export interface SpawnOptions {
+    readonly command?: string;
+    readonly args?: readonly string[];
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly cwd?: string;
+}
+export declare class AppServerClient {
+    private readonly transport;
+    private readonly child?;
+    private readonly pending;
+    private readonly eventListeners;
+    private readonly inboundAbort;
+    private seq;
+    private approvalHandler;
+    private questionHandler;
+    private closed;
+    constructor(transport: JsonRpcTransport, child?: ChildProcess);
+    /** Spawn the app-server binary and connect over its stdio. */
+    static spawn(opts?: SpawnOptions): AppServerClient;
+    private readLoop;
+    private onResponse;
+    private onNotification;
+    private onReverseRequest;
+    private dispatchReverse;
+    private request;
+    private failAllPending;
+    initialize(capabilities?: ClientCapabilities, info?: {
+        name: string;
+        version?: string;
+    }): Promise<InitializeResult>;
+    newSession(opts?: {
+        workDir?: string;
+        title?: string;
+        model?: string;
+    }): Promise<SessionInfo>;
+    resumeSession(sessionId: string): Promise<SessionInfo>;
+    forkSession(sessionId: string, opts?: {
+        title?: string;
+    }): Promise<SessionInfo>;
+    listSessions(): Promise<readonly SessionSummary[]>;
+    closeSession(sessionId: string): Promise<unknown>;
+    prompt(sessionId: string, input: string): Promise<RunResult>;
+    /** The session's folded state. Exact late-join seam: events received before this
+     *  resolves are already in the snapshot; events after it are not (see protocol doc). */
+    snapshot(sessionId: string, opts?: {
+        addresses?: readonly string[];
+        maxMessages?: number;
+    }): Promise<SessionSnapshotResult>;
+    /** Continue a durably-interrupted run: `answers` maps each pending `toolCallId` (from the
+     *  prior result's `interruptions`) to an approval decision. The session must be open. */
+    respond(sessionId: string, answers: Record<string, ApprovalResponse>): Promise<RunResult>;
+    steer(sessionId: string, text: string): Promise<SessionSteerResult>;
+    followUp(sessionId: string, text: string): Promise<SessionFollowUpResult>;
+    cancel(sessionId: string): Promise<unknown>;
+    /** Call a whitelisted control-plane method (see `INVOKABLE_METHODS`). */
+    invoke<R = unknown>(sessionId: string, method: string, ...args: unknown[]): Promise<R>;
+    onEvent(listener: EventListener): () => void;
+    setApprovalHandler(handler: ApprovalHandler | undefined): void;
+    setQuestionHandler(handler: QuestionHandler | undefined): void;
+    /** Close the transport and (if spawned) the child process. */
+    close(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/app-server/client.js

@@ -0,0 +1,187 @@
+/**
+ * Reference TypeScript client for the app-server protocol.
+ *
+ * It is both (1) a drop-in-ish, Harness-shaped wrapper around a spawned
+ * `operon-app-server` process and (2) the executable spec other-language clients
+ * mirror. The transport is injectable, so it also runs over `pairedTransports`
+ * in-process for tests.
+ */
+import { spawn } from "node:child_process";
+import { classify, isFailure, nodeStreamTransport, request as makeRequest, RpcError, success, } from "./codec.js";
+import { Method, PROTOCOL_VERSION, } from "./protocol.js";
+export class AppServerClient {
+    transport;
+    child;
+    pending = new Map();
+    eventListeners = new Set();
+    inboundAbort = new Map();
+    seq = 0;
+    approvalHandler;
+    questionHandler;
+    closed = false;
+    constructor(transport, child) {
+        this.transport = transport;
+        this.child = child;
+        void this.readLoop();
+    }
+    /** Spawn the app-server binary and connect over its stdio. */
+    static spawn(opts = {}) {
+        const command = opts.command ?? process.execPath;
+        const args = [...(opts.args ?? [])];
+        const child = spawn(command, args, {
+            stdio: ["pipe", "pipe", "inherit"],
+            ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+            env: { ...process.env, ...opts.env },
+        });
+        const transport = nodeStreamTransport(child.stdout, child.stdin);
+        return new AppServerClient(transport, child);
+    }
+    async readLoop() {
+        for await (const message of this.transport.incoming()) {
+            const c = classify(message);
+            if (c.kind === "response")
+                this.onResponse(c.message);
+            else if (c.kind === "request")
+                void this.onReverseRequest(c.message.id, c.message.method, c.message.params);
+            else if (c.kind === "notification")
+                this.onNotification(c.message.method, c.message.params);
+        }
+        this.failAllPending(new RpcError(-32011, "transport closed"));
+    }
+    onResponse(response) {
+        const pending = this.pending.get(response.id);
+        if (!pending)
+            return;
+        this.pending.delete(response.id);
+        if (isFailure(response))
+            pending.reject(new RpcError(response.error.code, response.error.message, response.error.data));
+        else
+            pending.resolve(response.result);
+    }
+    onNotification(method, params) {
+        if (method === Method.SessionEvent) {
+            const event = params;
+            for (const listener of this.eventListeners)
+                listener(event);
+            return;
+        }
+        if (method === Method.ClientCancelRequest) {
+            const { id } = (params ?? {});
+            this.inboundAbort.get(id)?.abort();
+            this.inboundAbort.delete(id);
+        }
+    }
+    async onReverseRequest(id, method, params) {
+        const controller = new AbortController();
+        this.inboundAbort.set(id, controller);
+        try {
+            const result = await this.dispatchReverse(method, params, controller.signal);
+            this.transport.send(success(id, result));
+        }
+        catch (error) {
+            const body = error instanceof RpcError ? error.toBody() : { code: -32603, message: error instanceof Error ? error.message : String(error) };
+            this.transport.send({ jsonrpc: "2.0", id, error: body });
+        }
+        finally {
+            this.inboundAbort.delete(id);
+        }
+    }
+    async dispatchReverse(method, params, signal) {
+        if (method === Method.ClientRequestApproval) {
+            const p = params;
+            if (!this.approvalHandler)
+                return { decision: "rejected", feedback: "no approval handler" };
+            return this.approvalHandler(p.request, p.sessionId);
+        }
+        if (method === Method.ClientRequestQuestion) {
+            const p = params;
+            if (!this.questionHandler)
+                return null;
+            return this.questionHandler(p.request, p.sessionId, { signal });
+        }
+        throw new RpcError(-32601, `unknown reverse method: ${method}`);
+    }
+    request(method, params) {
+        if (this.closed)
+            return Promise.reject(new RpcError(-32011, "client closed"));
+        const id = `c-${++this.seq}`;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.transport.send(makeRequest(id, method, params));
+        });
+    }
+    failAllPending(error) {
+        for (const pending of this.pending.values())
+            pending.reject(error);
+        this.pending.clear();
+    }
+    // ── Public API (mirrors the in-process Harness) ──────────────────────────────
+    initialize(capabilities = { approval: true, question: true }, info) {
+        return this.request(Method.Initialize, {
+            protocolVersion: PROTOCOL_VERSION,
+            clientInfo: info ?? { name: "app-server-client", version: "0.0.0" },
+            clientCapabilities: capabilities,
+        });
+    }
+    newSession(opts = {}) {
+        return this.request(Method.SessionNew, opts);
+    }
+    resumeSession(sessionId) {
+        return this.request(Method.SessionResume, { sessionId });
+    }
+    forkSession(sessionId, opts = {}) {
+        return this.request(Method.SessionFork, { sessionId, ...opts });
+    }
+    listSessions() {
+        return this.request(Method.SessionList, {});
+    }
+    closeSession(sessionId) {
+        return this.request(Method.SessionClose, { sessionId });
+    }
+    prompt(sessionId, input) {
+        return this.request(Method.SessionPrompt, { sessionId, input });
+    }
+    /** The session's folded state. Exact late-join seam: events received before this
+     *  resolves are already in the snapshot; events after it are not (see protocol doc). */
+    snapshot(sessionId, opts = {}) {
+        return this.request(Method.SessionSnapshot, { sessionId, ...opts });
+    }
+    /** Continue a durably-interrupted run: `answers` maps each pending `toolCallId` (from the
+     *  prior result's `interruptions`) to an approval decision. The session must be open. */
+    respond(sessionId, answers) {
+        return this.request(Method.SessionRespond, { sessionId, answers });
+    }
+    steer(sessionId, text) {
+        return this.request(Method.SessionSteer, { sessionId, text });
+    }
+    followUp(sessionId, text) {
+        return this.request(Method.SessionFollowUp, { sessionId, text });
+    }
+    cancel(sessionId) {
+        return this.request(Method.SessionCancel, { sessionId });
+    }
+    /** Call a whitelisted control-plane method (see `INVOKABLE_METHODS`). */
+    invoke(sessionId, method, ...args) {
+        return this.request(Method.SessionInvoke, { sessionId, method, args }).then((r) => r.value);
+    }
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    setApprovalHandler(handler) {
+        this.approvalHandler = handler;
+    }
+    setQuestionHandler(handler) {
+        this.questionHandler = handler;
+    }
+    /** Close the transport and (if spawned) the child process. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.failAllPending(new RpcError(-32011, "client closed"));
+        this.transport.close();
+        this.child?.kill();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/app-server/codec.d.ts

@@ -0,0 +1,52 @@
+import type { Readable, Writable } from "node:stream";
+import { type JsonRpcErrorBody, type JsonRpcFailure, type JsonRpcId, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type JsonRpcSuccess } from "./protocol.ts";
+export interface JsonRpcTransport {
+    /** Queue a message for delivery (respects backpressure internally). */
+    send(message: JsonRpcMessage): void;
+    /** Inbound messages, in order, until the peer closes. Consume once. */
+    incoming(): AsyncIterable<JsonRpcMessage>;
+    /** Stop reading/writing and release resources. */
+    close(): void;
+}
+export type ClassifiedMessage = {
+    readonly kind: "request";
+    readonly message: JsonRpcRequest;
+} | {
+    readonly kind: "response";
+    readonly message: JsonRpcResponse;
+} | {
+    readonly kind: "notification";
+    readonly message: JsonRpcNotification;
+} | {
+    readonly kind: "invalid";
+    readonly raw: unknown;
+};
+export declare function classify(raw: unknown): ClassifiedMessage;
+export declare function isFailure(response: JsonRpcResponse): response is JsonRpcFailure;
+export declare function request(id: JsonRpcId, method: string, params?: unknown): JsonRpcRequest;
+export declare function notification(method: string, params?: unknown): JsonRpcNotification;
+export declare function success(id: JsonRpcId, result: unknown): JsonRpcSuccess;
+export declare function failure(id: JsonRpcId, error: JsonRpcErrorBody): JsonRpcFailure;
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+    toBody(): JsonRpcErrorBody;
+}
+/** Map any thrown value to a JSON-RPC error body. */
+export declare function errorToBody(error: unknown): JsonRpcErrorBody;
+/** Recursively coerce a value into something `JSON.stringify` can handle without
+ *  throwing or leaking host objects: Error → plain object, circular refs and
+ *  functions/symbols/undefined dropped, depth bounded. */
+export declare function toWireSafe(value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
+export declare function encode(message: JsonRpcMessage): string;
+/** NDJSON JSON-RPC over a Readable/Writable pair (e.g. a child's stdout/stdin, or
+ *  this process's stdin/stdout). Malformed lines are dropped with an onError hook. */
+export declare function nodeStreamTransport(input: Readable, output: Writable, opts?: {
+    readonly onParseError?: (line: string, error: unknown) => void;
+}): JsonRpcTransport;
+/** Two transports wired back-to-back: what `a` sends, `b` receives, and vice
+ *  versa. Messages still round-trip through `toWireSafe` so tests exercise the
+ *  same serialization path as real stdio. */
+export declare function pairedTransports(): readonly [JsonRpcTransport, JsonRpcTransport];
+//# sourceMappingURL=codec.d.ts.map

package/dist/app-server/codec.js

@@ -0,0 +1,252 @@
+/**
+ * Transport + framing for the app-server protocol.
+ *
+ * - `JsonRpcTransport` is the seam the server and client both sit on, so neither
+ *   hardcodes stdio: real processes use `nodeStreamTransport`, tests use
+ *   `pairedTransports`.
+ * - NDJSON framing: one JSON value per line. `JSON.stringify` never emits a bare
+ *   newline, so a line is always one whole message.
+ * - `toWireSafe` sanitizes values before they cross the wire (Error → plain
+ *   object, circular refs / functions / undefined dropped) so a stray `error.cause`
+ *   or a tool display can't crash serialization.
+ */
+import { createInterface } from "node:readline";
+import { isGuardrailTripwireError } from "operon-agents-core";
+import { ErrorCode, } from "./protocol.js";
+export function classify(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return { kind: "invalid", raw };
+    const m = raw;
+    const hasId = "id" in m && (typeof m.id === "string" || typeof m.id === "number");
+    const hasMethod = typeof m.method === "string";
+    const hasResult = "result" in m;
+    const hasError = "error" in m;
+    if (hasMethod && hasId)
+        return { kind: "request", message: raw };
+    if (hasMethod)
+        return { kind: "notification", message: raw };
+    if (hasId && (hasResult || hasError))
+        return { kind: "response", message: raw };
+    return { kind: "invalid", raw };
+}
+export function isFailure(response) {
+    return "error" in response;
+}
+// ── Envelope builders ────────────────────────────────────────────────────────
+export function request(id, method, params) {
+    return params === undefined ? { jsonrpc: "2.0", id, method } : { jsonrpc: "2.0", id, method, params };
+}
+export function notification(method, params) {
+    return params === undefined ? { jsonrpc: "2.0", method } : { jsonrpc: "2.0", method, params };
+}
+export function success(id, result) {
+    return { jsonrpc: "2.0", id, result: result === undefined ? null : result };
+}
+export function failure(id, error) {
+    return { jsonrpc: "2.0", id, error };
+}
+// ── Errors ───────────────────────────────────────────────────────────────────
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "RpcError";
+        this.code = code;
+        this.data = data;
+    }
+    toBody() {
+        return this.data === undefined
+            ? { code: this.code, message: this.message }
+            : { code: this.code, message: this.message, data: toWireSafe(this.data) };
+    }
+}
+/** Map any thrown value to a JSON-RPC error body. */
+export function errorToBody(error) {
+    if (error instanceof RpcError)
+        return error.toBody();
+    // A guardrail tripwire is a policy block, not an internal failure — give it a distinct code
+    // and structured data so the host can distinguish it (and locate the run) from a crash.
+    if (isGuardrailTripwireError(error)) {
+        return {
+            code: ErrorCode.GuardrailBlocked,
+            message: error.message,
+            data: toWireSafe({
+                stage: error.stage,
+                guardrail: error.guardrailName,
+                agent: error.agentName,
+                sessionId: error.sessionId,
+                address: error.address,
+            }),
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { code: ErrorCode.InternalError, message };
+}
+// ── Wire-safe serialization ──────────────────────────────────────────────────
+const MAX_DEPTH = 64;
+/** Recursively coerce a value into something `JSON.stringify` can handle without
+ *  throwing or leaking host objects: Error → plain object, circular refs and
+ *  functions/symbols/undefined dropped, depth bounded. */
+export function toWireSafe(value, seen = new WeakSet(), depth = 0) {
+    if (value === null)
+        return null;
+    const t = typeof value;
+    if (t === "string" || t === "boolean")
+        return value;
+    if (t === "number")
+        return Number.isFinite(value) ? value : null;
+    if (t === "bigint")
+        return value.toString();
+    if (t === "undefined" || t === "function" || t === "symbol")
+        return undefined;
+    if (value instanceof Error) {
+        return { name: value.name, message: value.message, stack: value.stack };
+    }
+    if (depth >= MAX_DEPTH)
+        return undefined;
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return undefined;
+        seen.add(value);
+        const out = value.map((v) => {
+            const safe = toWireSafe(v, seen, depth + 1);
+            return safe === undefined ? null : safe;
+        });
+        seen.delete(value);
+        return out;
+    }
+    if (t === "object") {
+        const obj = value;
+        if (seen.has(obj))
+            return undefined;
+        // Honor toJSON (Date, etc.) before generic object walking.
+        const maybe = obj;
+        if (typeof maybe.toJSON === "function")
+            return toWireSafe(maybe.toJSON(), seen, depth + 1);
+        seen.add(obj);
+        const out = {};
+        for (const key of Object.keys(obj)) {
+            const safe = toWireSafe(obj[key], seen, depth + 1);
+            if (safe !== undefined)
+                out[key] = safe;
+        }
+        seen.delete(obj);
+        return out;
+    }
+    return undefined;
+}
+export function encode(message) {
+    return `${JSON.stringify(toWireSafe(message))}\n`;
+}
+// ── A minimal async queue (single producer / single consumer) ────────────────
+class AsyncQueue {
+    buffer = [];
+    waiters = [];
+    closed = false;
+    push(value) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter({ value, done: false });
+        else
+            this.buffer.push(value);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const w of this.waiters.splice(0))
+            w({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const next = this.buffer.shift();
+                if (next !== undefined)
+                    return Promise.resolve({ value: next, done: false });
+                if (this.closed)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+        };
+    }
+}
+// ── Node stdio transport ─────────────────────────────────────────────────────
+/** NDJSON JSON-RPC over a Readable/Writable pair (e.g. a child's stdout/stdin, or
+ *  this process's stdin/stdout). Malformed lines are dropped with an onError hook. */
+export function nodeStreamTransport(input, output, opts = {}) {
+    const queue = new AsyncQueue();
+    const rl = createInterface({ input, crlfDelay: Number.POSITIVE_INFINITY });
+    rl.on("line", (line) => {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (error) {
+            opts.onParseError?.(trimmed, error);
+            return;
+        }
+        queue.push(parsed);
+    });
+    rl.once("close", () => queue.close());
+    input.once("error", () => queue.close());
+    // Serialize writes; respect backpressure by chaining on `drain`.
+    let writeChain = Promise.resolve();
+    let closed = false;
+    const writeLine = (text) => {
+        writeChain = writeChain.then(() => new Promise((resolve) => {
+            if (closed || output.writableEnded)
+                return resolve();
+            const ok = output.write(text);
+            if (ok)
+                resolve();
+            else
+                output.once("drain", () => resolve());
+        }));
+    };
+    return {
+        send(message) {
+            writeLine(encode(message));
+        },
+        incoming() {
+            return queue;
+        },
+        close() {
+            closed = true;
+            rl.close();
+            queue.close();
+        },
+    };
+}
+// ── Paired in-memory transports (for tests / embedding) ──────────────────────
+/** Two transports wired back-to-back: what `a` sends, `b` receives, and vice
+ *  versa. Messages still round-trip through `toWireSafe` so tests exercise the
+ *  same serialization path as real stdio. */
+export function pairedTransports() {
+    const aIn = new AsyncQueue();
+    const bIn = new AsyncQueue();
+    const hop = (message) => JSON.parse(JSON.stringify(toWireSafe(message)));
+    const a = {
+        send: (m) => bIn.push(hop(m)),
+        incoming: () => aIn,
+        close: () => {
+            aIn.close();
+            bIn.close();
+        },
+    };
+    const b = {
+        send: (m) => aIn.push(hop(m)),
+        incoming: () => bIn,
+        close: () => {
+            aIn.close();
+            bIn.close();
+        },
+    };
+    return [a, b];
+}
+//# sourceMappingURL=codec.js.map

package/dist/app-server/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * app-server — drive the harness from another process (any language) over an
+ * NDJSON JSON-RPC 2.0 stdio protocol, so non-JS hosts can `spawn` the binary
+ * and talk to it.
+ *
+ *   // host side (TypeScript reference client)
+ *   import { AppServerClient } from "operon-agents/app-server"
+ *   const client = AppServerClient.spawn({ args: ["--workdir", "/repo", "--model", "anthropic/claude-opus-4-8"] })
+ *   await client.initialize()
+ *   const { sessionId } = await client.newSession()
+ *   client.onEvent(render)
+ *   client.setApprovalHandler(askUser)
+ *   const result = await client.prompt(sessionId, "fix the bug")
+ *
+ * `./protocol` (wire types + constants) is the single source of truth for clients
+ * in other languages.
+ */
+export * from "./protocol.ts";
+export { type JsonRpcTransport, nodeStreamTransport, pairedTransports, RpcError, toWireSafe, classify, } from "./codec.ts";
+export { AppServer, type AppServerOptions } from "./server.ts";
+export { AppServerClient, type ApprovalHandler, type EventListener, type QuestionHandler, type SpawnOptions, } from "./client.ts";
+//# sourceMappingURL=index.d.ts.map