@tangle-network/sdk-cli-runner 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2025 Tangle Network
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. No part of this Software may be reproduced, distributed, or
+transmitted in any form or by any means, including photocopying, recording, or
+other electronic or mechanical methods, without the prior written permission of
+Tangle Network.
+
+For licensing inquiries, contact: hello@tangle.tools

package/dist/index.d.mts

@@ -0,0 +1,584 @@
+import { ChildProcess, SpawnOptions } from "node:child_process";
+
+//#region src/attachment-error.d.ts
+/** An attachment cannot be delivered to a native CLI. */
+declare class InvalidAttachmentError extends Error {
+  readonly code = "invalid_attachment";
+  readonly statusCode = 400;
+  constructor(message: string);
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Configuration for spawning a CLI process.
+ */
+interface CliSpawnConfig {
+  /** The command to execute */
+  command: string;
+  /** Arguments to pass to the command */
+  args: string[];
+  /** Working directory for the process */
+  cwd: string;
+  /** Additional environment variables. `undefined` values are an explicit
+   *  scrub signal — the runner deletes the corresponding key from
+   *  process.env before spawn. Use this to unset inherited auth vars
+   *  (e.g. ANTHROPIC_API_KEY in OAuth mode). */
+  env?: Record<string, string | undefined>;
+  /** Start from an empty environment instead of inheriting process.env. */
+  inheritEnv?: boolean;
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+  /** Wall-clock timeout in milliseconds (default: no timeout). Callers
+   *  usually bound a turn through `signal` instead. */
+  timeoutMs?: number;
+  /** Additional spawn options */
+  spawnOptions?: SpawnOptions;
+  /** Root executor only: drop supplementary groups and privilege before exec. */
+  isolatedIdentity?: {
+    uid: number;
+    gid: number;
+  };
+  /** Sidecar-owned append-only raw process stream, outside the child environment. */
+  rawCapturePath?: string;
+  /**
+   * With `rawCapturePath`: open the capture at `beginRawCapture`, not at spawn.
+   * A process started before the turn it serves (a held spare) opens it inside
+   * that turn, so its frames carry the turn's attempt identity and retention.
+   * What it prints before then is kept, in order, and written first; a process
+   * that prints more than 1 MiB before then is stopped.
+   */
+  rawCaptureDeferred?: boolean;
+  /**
+   * Start the child yourself (an executor slot, a jail) instead of `spawn`.
+   * Only `launchCliProcess` and `execCli` take it, because a launch may wait
+   * for capacity; the runner still owns capture, deadlines, abort and exit.
+   */
+  launcher?: CliLauncher;
+  /**
+   * Treat the CLI's whole process group as the run: members still alive when
+   * the leader exits are stopped before the exit is reported, and one that
+   * outlives SIGKILL fails the run. Off by default, because an agent's turn
+   * may start a process meant to outlive it (a dev server a preview serves).
+   */
+  ownProcessGroup?: boolean;
+  /**
+   * What a child that rejects its stdin (closes the pipe early) gets. "stop"
+   * (default) stops it, because an adapter's turn cannot continue without its
+   * input. "report" lets it exit on its own and reports `stdinError`, for a
+   * caller that judges the exit itself.
+   */
+  stdinFailure?: "stop" | "report";
+}
+/** What a consumer-owned launch is asked to start, after env assembly. */
+interface CliLaunchSpec {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string | undefined>;
+  stdio: Exclude<SpawnOptions["stdio"], undefined>;
+  detached: boolean;
+  signal?: AbortSignal;
+}
+/** A child a consumer started, and how its whole extent ends. */
+interface CliLaunch {
+  child: ChildProcess;
+  /** Stop everything the launch started (a container, a scope). Called once, on the first kill. */
+  terminate?(): Promise<void>;
+  /** Give back what the launch held (an executor slot). Called once, after exit. */
+  release?(): void;
+}
+/**
+ * Starts one CLI child. Resolve as soon as the child is spawned, with no
+ * further await: the runner attaches its exit and error listeners when the
+ * launch settles, and a spawn failure is emitted on the next tick.
+ */
+type CliLauncher = (spec: CliLaunchSpec) => CliLaunch | Promise<CliLaunch>;
+/**
+ * The bound that killed a process the runner timed out. The runner has one:
+ * the fixed `timeoutMs` wall clock.
+ */
+type CliTimeoutReason = "fixed";
+/**
+ * Result from a CLI process exit.
+ */
+interface CliExitResult {
+  /** Exit code (null if killed by signal) */
+  code: number | null;
+  /** Signal that killed the process (null if exited normally) */
+  signal: NodeJS.Signals | null;
+  /** Whether the process exited successfully (code 0) */
+  success: boolean;
+  /** Whether the process was killed by timeout */
+  timedOut: boolean;
+  /** The bound that killed the process. Set only when `timedOut` is true, so
+   *  a caller can branch on the cause instead of on a bare boolean. */
+  timeoutReason?: CliTimeoutReason;
+  /** What that bound observed: the command, the budget it exceeded and the
+   *  time it ran. Set only when `timedOut` is true. Callers put it in the
+   *  failure they raise, so the operator reads the cause and not "timed out".
+   */
+  timeoutDiagnostic?: string;
+  /** Message from the spawn-level `error` event (e.g. ENOENT when the
+   *  binary is not on PATH). Set only when the process failed to spawn or
+   *  was lost at the OS level — callers must surface this instead of
+   *  reporting a bare `code: null`, which is indistinguishable from a
+   *  signal kill. */
+  spawnError?: string;
+  /** The native child closed or rejected stdin before its input was delivered. */
+  stdinError?: string;
+  /** The errno code of `stdinError` (EPIPE for a pipe the child closed). */
+  stdinErrorCode?: string;
+  /** Raw evidence could not be written or flushed; the process is not a complete trace. */
+  captureError?: string;
+  /** The caller's abort signal fired before the process exited. */
+  aborted?: boolean;
+  /** Members of the process group outlived SIGKILL after the leader exited. */
+  processGroupError?: string;
+  /** A consumer launch's `terminate` failed. */
+  terminateError?: string;
+}
+/**
+ * Handle to a running CLI process.
+ */
+interface CliProcess {
+  /** Process ID */
+  pid: number | undefined;
+  /** The underlying child process */
+  process: ChildProcess;
+  /** Write data to stdin */
+  write(data: CliStdinValue): void;
+  /** Close stdin (signals end of input) */
+  closeInput(): void;
+  /** Kill the process */
+  kill(signal?: NodeJS.Signals): boolean;
+  /** Promise that resolves when the process exits */
+  exitPromise: Promise<CliExitResult>;
+  /**
+   * Open a deferred raw capture (`rawCaptureDeferred`) in the caller's attempt.
+   * Throws when the capture already failed (the process was told to stop); a
+   * no-op for any other process, or once the process has exited.
+   */
+  beginRawCapture?(): void;
+}
+/**
+ * Configuration for stream parsing.
+ *
+ * Three modes cover every CLI output shape we've encountered:
+ *
+ * - **"json"** (default): newline-delimited JSON. Each line is parsed via
+ *   `JSON.parse`, then passed to `transform`. Used by claude-code, codex.
+ * - **"lines"**: plaintext with one logical event per line. Each line is
+ *   passed to `transform` as a raw trimmed string with no JSON parsing.
+ *   Used by hermes quiet mode plaintext response lines.
+ * - **"raw"**: stdout chunks delivered verbatim with no per-line splitting.
+ *   `transform` is NOT called; instead the parser maintains a single
+ *   accumulating buffer that the consumer reads in `onComplete`. Used by
+ *   openclaw (`agent --json` emits one buffered JSON object across the
+ *   entire stdout stream — pretty-printed envelopes with embedded newlines
+ *   would corrupt under "lines" reassembly).
+ *
+ * Picking the right mode matters: "lines" reassembled via `+ "\n"` looks
+ * like raw mode but silently drops any internal blank lines (the line
+ * splitter trims them before transform). Use "raw" whenever the unit is
+ * the whole stream, not the line.
+ */
+interface StreamParserConfig<T> {
+  /**
+   * Parse mode. See the interface docstring for the contract per mode.
+   * Defaults to "json" for backwards compatibility with the original
+   * JSONL-only API.
+   */
+  parseAs?: "json" | "lines" | "raw";
+  /**
+   * Transform a parsed event to the desired type (return null to skip).
+   * In "json" mode the input is the JSON.parse result; in "lines" mode it
+   * is the raw trimmed line string. **Ignored in "raw" mode** — the
+   * consumer reads the full buffer via `onRawComplete`.
+   */
+  transform?: (raw: unknown) => T | null;
+  /** Called for each parsed event ("json" and "lines" modes only). */
+  onEvent: (event: T) => void;
+  /** Called on parse errors (only fires in "json" mode) */
+  onError?: (error: Error, rawLine: string) => void;
+  /**
+   * Called when the stream completes.
+   *
+   * In "raw" mode, the full untouched stdout buffer is passed as the
+   * argument so consumers can parse it however they want (single
+   * `JSON.parse`, regex extraction, etc). In "json" and "lines" modes the
+   * argument is undefined — events were already delivered via `onEvent`.
+   */
+  onComplete?: (rawBuffer?: string) => void;
+}
+/**
+ * A stream parser instance that can process chunks of data.
+ */
+interface StreamParser<_T> {
+  /** Process a chunk of data */
+  push(chunk: string): void;
+  /** Signal end of stream */
+  end(): void;
+}
+/**
+ * Result from execCli (one-shot execution).
+ */
+interface CliExecResult<T> {
+  /** Exit result from the process */
+  exit: CliExitResult;
+  /** Collected stdout (when no parser was given) */
+  stdout?: string;
+  /** Collected stderr */
+  stderr: string;
+  /** Collected events (if streaming parser was used) */
+  events?: T[];
+  /** Wall clock from launch to exit. */
+  durationMs: number;
+}
+/** Bounds of what `execCli` keeps in memory. */
+interface CliExecOptions {
+  /** Newest stdout and stderr bytes retained per stream. Default 64 MiB. */
+  maxOutputBytes?: number;
+  /** Written to the child's stdin, which then closes. Omitted: stdin stays as the config leaves it. */
+  stdin?: string;
+}
+/**
+ * One value the runner writes to a child process's standard input. A string
+ * goes through unchanged; any other value is serialized as JSON. The type is
+ * named so a caller cannot hand in an arbitrary object whose shape the runner
+ * cannot serialize.
+ */
+type CliStdinValue = string | Record<string, unknown>;
+//#endregion
+//#region src/cli-process.d.ts
+/**
+ * Spawns a CLI process with streaming support.
+ *
+ * @param config - Configuration for the process
+ * @param parserConfig - Optional streaming parser for stdout
+ * @returns Handle to the running process
+ */
+declare function spawnCliProcess<T = unknown>(config: CliSpawnConfig, parserConfig?: StreamParserConfig<T>): CliProcess;
+/**
+ * Start a CLI through the config's `launcher` (or `spawn` without one) and
+ * attach the same capture, deadlines, abort and exit handling as
+ * `spawnCliProcess`. The launcher receives the fully assembled environment.
+ */
+declare function launchCliProcess<T = unknown>(config: CliSpawnConfig, parserConfig?: StreamParserConfig<T>): Promise<CliProcess>;
+/**
+ * Executes a CLI command and waits for completion. Without a parser it
+ * returns stdout; stdout and stderr keep their newest `maxOutputBytes`.
+ */
+declare function execCli<T = unknown>(config: CliSpawnConfig, parserConfig?: StreamParserConfig<T>, options?: CliExecOptions): Promise<CliExecResult<T>>;
+//#endregion
+//#region src/held-spare.d.ts
+/** The process handle a spare keeps and a turn takes over. */
+type HeldSpareProcess = Pick<CliProcess, "pid" | "write" | "closeInput" | "kill" | "exitPromise" | "beginRawCapture"> & {
+  stderr?: NodeJS.ReadableStream;
+};
+/**
+ * A parser that holds the spare's output until a turn adopts the process, then
+ * hands the turn's own parser everything the CLI printed so far, in order.
+ */
+declare function createDeferredParser<T>(): {
+  config: StreamParserConfig<T>;
+  attach(target: StreamParserConfig<T>): void;
+};
+/** How long a spare no turn adopted keeps its process. */
+declare const HELD_SPARE_IDLE_MS = 120000;
+/** A spare is idle until a turn reserves or claims it, or it is stopped. */
+type HeldSpareState = "idle" | "reserved" | "claimed" | "stopped";
+interface HeldSpareFields<TEvent> {
+  /** Names the spare to whoever must tell its requests from a turn's. */
+  readonly id: string;
+  readonly home: string;
+  readonly workspaceRoot: string;
+  readonly args: readonly string[];
+  /** The spare's environment as a turn compares it (see launchDifferences). */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly process: HeldSpareProcess;
+  readonly parser: ReturnType<typeof createDeferredParser<TEvent>>;
+  readonly controller: AbortController;
+  readonly startedAt: number;
+  state: HeldSpareState;
+  idleTimer?: ReturnType<typeof setTimeout>;
+}
+/** A spare, plus what the harness records about its launch (`TExtra`). */
+type HeldSpare<TEvent, TExtra extends object = object> = HeldSpareFields<TEvent> & TExtra;
+interface HeldSpareRegistry<TEvent, TExtra extends object = object> {
+  /** The spare running or stopping in `home`, if any. */
+  spareFor(home: string | undefined): HeldSpare<TEvent, TExtra> | undefined;
+  register(spare: HeldSpare<TEvent, TExtra>): void;
+  /** True while a spare in `home` runs or is stopping: its HOME is not free. */
+  has(home: string): boolean;
+  /** Stop a spare no turn runs on and forget it. */
+  stop(spare: HeldSpare<TEvent, TExtra>): void;
+  /** A turn runs on the spare: it is the turn's process now, not a spare. */
+  claim(spare: HeldSpare<TEvent, TExtra>): void;
+  /**
+   * The turn takes the spare's process: the spare is claimed, its raw capture
+   * opens in the turn's attempt (what the process printed before is the
+   * turn's too), its output so far and from now on goes to the turn's parser,
+   * and the turn's abort signal stops it. Returns the handle the turn drives.
+   * Throws for a spare that is stopped or already claimed, and stops the spare
+   * and throws when its capture cannot open or already failed while held; the
+   * turn then starts its own process.
+   */
+  adopt(spare: HeldSpare<TEvent, TExtra>, turn: {
+    parser: StreamParserConfig<TEvent>;
+    signal: AbortSignal;
+  }): HeldSpareProcess;
+  /** Stop every spare no turn claimed, and wait for the processes to exit. */
+  discard(): Promise<void>;
+}
+declare function createHeldSpareRegistry<TEvent, TExtra extends object = object>(): HeldSpareRegistry<TEvent, TExtra>;
+/** The argument after `flag`, if any. */
+declare function argAfter(args: readonly string[], flag: string): string | undefined;
+/**
+ * Whether two launches are the same process. `comparable` maps an environment
+ * value to what must match (a harness drops the lines it allows to differ);
+ * the default compares values as they are. Returns the names of what differs
+ * (never values: environments hold credentials), empty when equal.
+ */
+declare function launchDifferences(spare: Pick<HeldSpareFields<unknown>, "args" | "env">, turn: {
+  args: readonly string[];
+  env: Readonly<Record<string, string | undefined>>;
+}, comparable?: (key: string, value: string | undefined) => string | undefined): string[];
+//#endregion
+//#region src/raw-capture.d.ts
+/** Hard encoded-byte bound across canonical JSON spool files, including live writers.
+ * Temporary trim copies and filesystem allocation are separate from this budget.
+ */
+declare const RAW_CAPTURE_TOTAL_CAP_BYTES: number;
+type RawCaptureMode = "none" | "tail" | "full";
+/** The root-private spool: one `<sha256(HOME)>/process-io.frames` per runtime HOME. */
+declare const RAW_CAPTURE_ROOT = "/root/.sidecar/raw-evidence";
+type RawCaptureAttempt = {
+  executionId: string;
+  ordinal: number;
+  providerSessionId: string;
+};
+/** Bind Sidecar-owned attempt identity before entering a provider adapter. */
+declare function withRawCaptureAttempt<T>(attempt: RawCaptureAttempt, run: () => Promise<T>): Promise<T>;
+/** The sidecar owns this directory; the CLI's writable HOME cannot contain its evidence. */
+declare function resolveRawCapturePath(runtimeHome: string): string;
+/**
+ * Opt one runtime HOME in to full capture, inside the shared byte budget, when
+ * the platform default is off. The Sidecar calls this for a session created with retention
+ * "workspace", whose retained evidence must include process I/O. An explicit
+ * SIDECAR_RAW_CAPTURE_MODE=none or PHI redaction still disables it.
+ */
+declare function allowRetainedRawCapture(runtimeHome: string): void;
+/** Delete a session's private spool only after its evidence has been archived. */
+declare function removeRawCapture(runtimeHome: string): void;
+type Stream = "stdin" | "stdout" | "stderr" | "protocol";
+/** One process appends exact byte frames to a sidecar-owned session file. */
+declare function openRawCapture(file: string, options?: {
+  unbound?: boolean;
+  mode?: RawCaptureMode;
+}): {
+  frame(_stream: Stream, _bytes: Buffer, _metadata?: Record<string, unknown>): void;
+  close(_result: Record<string, unknown>): void;
+};
+interface RawCaptureProcess {
+  processId: string;
+  executionId?: string;
+  ordinal?: number;
+  /** Bytes of this process's lines in the file. */
+  bytes: number;
+  /** `at` of its first frame, and its position in the file. */
+  firstAt: string;
+  firstOffset: number;
+  /** Its terminal record is in the file. */
+  closed: boolean;
+  /** This sidecar process still holds its writer; it is never trimmed. */
+  live: boolean;
+}
+/** The processes in one capture file, in file order, with their sizes. */
+declare function summarizeRawCapture(file: string): Promise<{
+  sizeBytes: number;
+  processes: RawCaptureProcess[];
+}>;
+/**
+ * Remove whole processes from a capture file. A process is dropped with all
+ * of its lines or not at all, so every remaining process still reads as a
+ * complete sequence. A process this sidecar is still writing is never
+ * dropped. Frames written while the file is rewritten are carried into the
+ * replacement before it takes the path.
+ */
+declare function trimRawCapture(file: string, drop: ReadonlySet<string>): Promise<{
+  beforeBytes: number;
+  afterBytes: number;
+  droppedBytes: number;
+}>;
+//#endregion
+//#region src/rpc-bridge-protocol.d.ts
+/**
+ * Long-running stdio JSON-RPC 2.0 client over NDJSON framing.
+ *
+ * Built for the Agent Client Protocol (ACP) — every ACP-compliant agent
+ * binary speaks JSON-RPC 2.0 over stdin/stdout with one envelope per line
+ * (`JSON.stringify(msg) + "\n"`, no Content-Length headers). Reusable for
+ * any future stdio-bridge CLI with the same wire format (LSP variants,
+ * MCP-over-stdio, custom protocols).
+ *
+ * Design contract:
+ *
+ * - **One bridge = one child process.** Callers own session isolation and
+ *   turn serialization. ACP uses one bridge per execute; protocols such as
+ *   Codex app-server can retain the bridge across serialized native threads.
+ *   A retained process binds capture separately for each admitted turn.
+ *
+ * - **Bounded.** Pending request map is capped (default 1024) to prevent
+ *   runaway memory if the agent hangs without responding. Stderr is
+ *   captured into a ring buffer (default 64 KiB) so a noisy agent can't
+ *   exhaust memory.
+ *
+ * - **Fail-loud on close.** Pending requests reject with `BridgeClosedError`
+ *   when the child exits — no silent hangs.
+ *
+ * - **Server-style request handlers.** ACP agents make reverse calls
+ *   (`fs/read_text_file`, `terminal/*`, `session/request_permission`).
+ *   `onRequest()` registers a handler that returns the JSON-RPC `result`
+ *   field; throws map to JSON-RPC errors. One handler per method (last
+ *   write wins is rejected — registration throws on duplicate).
+ */
+interface RpcBridgeLogger {
+  debug: (msg: string, meta?: Record<string, unknown>) => void;
+  warn: (msg: string, meta?: Record<string, unknown>) => void;
+  error: (msg: string, meta?: Record<string, unknown>) => void;
+}
+interface RpcBridgeConfig {
+  command: string;
+  args: string[];
+  cwd: string;
+  /** `undefined` scrubs an inherited variable; see `mergeSpawnEnv`. */
+  env?: Record<string, string | undefined>;
+  /** AbortSignal — closes the bridge when aborted. */
+  signal?: AbortSignal;
+  /** Cap on outstanding requests. Default 1024. */
+  maxPendingRequests?: number;
+  /** Stderr ring-buffer size in bytes. Default 65536. */
+  maxStderrBytes?: number;
+  /**
+   * Default per-request timeout (ms). Each `request()` rejects after this
+   * many ms if no response — protects callers from hanging forever when the
+   * agent silently drops a request. Per-call override available on
+   * `request(method, params, { timeoutMs })`. Default: 60_000.
+   */
+  defaultRequestTimeoutMs?: number;
+  /** Default grace window for `close()` if not specified at the call site. */
+  defaultCloseGraceMs?: number;
+  /**
+   * Hard wall-clock cap on `close()` — if the drain → SIGTERM → SIGKILL
+   * sequence has not completed, a logical close never claims physical exit.
+   * Unowned transports may retry escalation on a later close. Owned-process
+   * cleanup rejects on a live survivor or observation fault and retains that
+   * failure as its resource fence. Default: 10_000 ms.
+   */
+  hardCloseDeadlineMs?: number;
+  logger?: RpcBridgeLogger;
+  /** Trusted session-local file for exact process I/O frames. */
+  rawCapturePath?: string;
+  /** Keep lifetime bytes unbound; captureTurn binds each admitted retained-process turn. */
+  rawCapturePerTurn?: boolean;
+  uid?: number;
+  gid?: number;
+  /** Trusted root launch: use the maintained group scrub and privilege boundary. */
+  isolatedIdentity?: CliSpawnConfig["isolatedIdentity"];
+  /** Own a POSIX process group; on Linux, also track observed descendants that detach. Default false. */
+  detached?: boolean;
+  /** Wait for native EOF cleanup before forced termination. Default 0; included in the hard cap. */
+  stdinCloseGraceMs?: number;
+}
+interface RpcRequestOptions {
+  /** Override the bridge's default per-request timeout (ms). */
+  timeoutMs?: number;
+}
+type RpcNotificationHandler<TParams = unknown> = (params: TParams) => void | Promise<void>;
+type RpcRequestHandler<TParams = unknown, TResult = unknown> = (params: TParams) => TResult | Promise<TResult>;
+interface RpcCloseReason {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  error?: Error;
+  reason: "graceful" | "process-exit" | "process-error" | "aborted";
+}
+interface RpcBridge {
+  /** Capture one serialized turn in its caller's trusted execution context. */
+  captureTurn(path: string, metadata?: Record<string, unknown>): (result: Record<string, unknown>) => void;
+  request<TResult = unknown>(method: string, params?: unknown, options?: RpcRequestOptions): Promise<TResult>;
+  notify(method: string, params?: unknown): void;
+  /** Returns an unsubscribe function. Multiple handlers per method allowed. */
+  onNotification<TParams = unknown>(method: string, handler: RpcNotificationHandler<TParams>): () => void;
+  /** ONE handler per method. Throws on duplicate. Returns unsubscribe. */
+  onRequest<TParams = unknown, TResult = unknown>(method: string, handler: RpcRequestHandler<TParams, TResult>): () => void;
+  /** Fires once after closure and any owned cleanup attempt; failures carry process-error. */
+  onClose(handler: (reason: RpcCloseReason) => void): () => void;
+  /** Graceful close: stop accepting new requests, drain in-flight, then SIGTERM, then SIGKILL. */
+  close(graceMs?: number): Promise<void>;
+  /** Tail of stderr captured into the ring buffer. */
+  getStderrTail(): string;
+  readonly pid: number | undefined;
+  readonly closed: boolean;
+  readonly process: ChildProcess;
+}
+//#endregion
+//#region src/rpc-bridge-errors.d.ts
+declare class JsonRpcError extends Error {
+  readonly code: number;
+  readonly data?: unknown | undefined;
+  constructor(code: number, message: string, data?: unknown | undefined);
+}
+declare class BridgeClosedError extends Error {
+  /** The child's last stderr, bounded; kept off the message, which callers log. */
+  readonly stderrTail?: string;
+  constructor(reason: string, options?: {
+    cause?: Error;
+    stderrTail?: string;
+  });
+}
+declare class RpcRequestTimeoutError extends Error {
+  readonly method: string;
+  readonly timeoutMs: number;
+  constructor(method: string, timeoutMs: number);
+}
+//#endregion
+//#region src/rpc-stdio-process.d.ts
+/**
+ * Spawn an RpcBridge over a long-running stdio child process.
+ *
+ * The bridge is usable immediately after this call — outbound writes
+ * before the child has booted are buffered by Node's stdin pipe. Inbound
+ * dispatch starts as soon as the child writes its first line.
+ */
+declare function spawnRpcBridge(config: RpcBridgeConfig): RpcBridge;
+//#endregion
+//#region src/shell-quote.d.ts
+declare function shellQuote(value: string): string;
+//#endregion
+//#region src/spawn-env.d.ts
+/**
+ * Merge adapter environment overrides onto a base environment for `spawn`.
+ *
+ * An adapter scrubs an inherited variable by setting it to `undefined` (the
+ * claude-code and codex adapters strip a router key under OAuth so the CLI
+ * keeps its stored tokens). A plain spread keeps such a key in the object,
+ * and what the child then sees depends on the spawner. Deleting the key makes
+ * the scrub unconditional.
+ */
+declare function mergeSpawnEnv(base: NodeJS.ProcessEnv, overrides: Record<string, string | undefined> | undefined): Record<string, string | undefined>;
+//#endregion
+//#region src/stream-parser.d.ts
+/**
+ * Creates a stdout stream parser. Three modes:
+ *
+ * - "json"  (default): newline-delimited JSON, JSON.parse per line.
+ * - "lines": plaintext, raw trimmed line per `transform` call.
+ * - "raw":   no per-line splitting — accumulate the entire stream into a
+ *            single buffer and deliver it via `onComplete(buffer)`.
+ *
+ * See StreamParserConfig docstring for the full contract per mode.
+ */
+declare function createStreamParser<T>(config: StreamParserConfig<T>): StreamParser<T>;
+//#endregion
+export { BridgeClosedError, type CliExecOptions, type CliExecResult, type CliExitResult, type CliLaunch, type CliLaunchSpec, type CliLauncher, type CliProcess, type CliSpawnConfig, type CliStdinValue, HELD_SPARE_IDLE_MS, type HeldSpare, type HeldSpareRegistry, InvalidAttachmentError, JsonRpcError, RAW_CAPTURE_ROOT, RAW_CAPTURE_TOTAL_CAP_BYTES, type RawCaptureProcess, type RpcBridge, type RpcBridgeConfig, type RpcCloseReason, type RpcNotificationHandler, type RpcRequestHandler, type RpcRequestOptions, RpcRequestTimeoutError, type StreamParserConfig, allowRetainedRawCapture, argAfter, createDeferredParser, createHeldSpareRegistry, createStreamParser, execCli, launchCliProcess, launchDifferences, mergeSpawnEnv, openRawCapture, removeRawCapture, resolveRawCapturePath, shellQuote, spawnCliProcess, spawnRpcBridge, summarizeRawCapture, trimRawCapture, withRawCaptureAttempt };
+//# sourceMappingURL=index.d.mts.map