@lmctl-ai/lmctl 0.1.342 → 0.2.2

package/dist/providers/transports/codex-app-server.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Codex app-server transport.
+ *
+ * Spawns `codex app-server --listen stdio://` and communicates via
+ * JSON-RPC 2.0 over stdin/stdout. The process stays alive for the
+ * full conversation — no one-shot timeout.
+ *
+ * Protocol:
+ *   initialize → thread/start or thread/resume → turn/start
+ *   ← item/agentMessage/delta (streaming)
+ *   ← turn/completed
+ */
+import { type HoldOpenOptions } from "./hold-open.js";
+import { type PermissionMode } from "../yolo-contract.js";
+import { type CodexInitializePayload } from "../parsers/codex-app-server.js";
+export { buildCodexThreadResumeParams, buildCodexThreadStartParams, classifyCodexErrorDisposition, codexSandboxForPermissionMode, createCodexAgentAccumulator, createCodexTurnState, flushCodexAgentAccumulator, processCodexAgentNotification, recordCodexErrorNotification, resolveCodexTurnCompletion, } from "../parsers/codex-app-server.js";
+export type { AgentMessageItemState, AgentMessagePhase, CodexAgentAccumulatorState, CodexErrorDisposition, CodexInitializePayload, CodexItemMismatchInfo, CodexTurnState, } from "../parsers/codex-app-server.js";
+/**
+ * Build the JSON-RPC `initialize` params for the codex app-server.
+ * Mirrors the reference client at
+ * openai/codex-plugin-cc/plugins/codex/scripts/lib/app-server.mjs:25-41.
+ *
+ * Includes `clientInfo.title` and `capabilities.experimentalApi: false`
+ * explicitly. `version` is sourced from package.json at load time rather
+ * than a string literal so bumps aren't silently out-of-sync.
+ *
+ * We intentionally do NOT set `capabilities.optOutNotificationMethods`
+ * (which their plugin uses to suppress agentMessage/reasoning deltas) —
+ * lmctl consumes every delta for live `onDelta` progress.
+ */
+export declare function buildInitializePayload(): CodexInitializePayload;
+/**
+ * Backward-compat shim for the prior local helper. Forwards to
+ * `transportRpcErrorFromResponse` from the shared transport-errors
+ * module so existing tests / external callers continue to work.
+ *
+ * The returned object is now a `TransportRpcError` instance — still
+ * an `Error`, still has `.rpcCode` and `.data` (mapped to `.rpcData`),
+ * but the latter are typed and named consistently with the other
+ * transports.
+ *
+ * @deprecated Construct `TransportRpcError` directly via
+ * `transportRpcErrorFromResponse(message, errorObj)`.
+ */
+export declare function createRpcError(message: string, data?: unknown): Error & {
+    rpcCode?: number;
+    data?: unknown;
+};
+export interface CodexAppServerResult {
+    result: string;
+    threadId: string;
+    turnId: string;
+    durationMs: number;
+    exitCode: number | null;
+}
+export interface CodexAppServerOptions {
+    /** Codex thread ID to resume. If provided, uses thread/resume with writable sandbox. */
+    threadId?: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    /** Called for each text delta (for live output) */
+    onDelta?: (text: string) => void;
+    /** Called for each raw JSON-RPC event */
+    onEvent?: (event: Record<string, unknown>) => void;
+    /**
+     * Override the spawned codex binary path. Used for troubleshooting
+     * with a custom codex-rs build. When set, the transport spawns this
+     * exact path instead of looking up `codex` on PATH. (Task 63 fix 3.)
+     */
+    binaryPath?: string;
+    /** Abort signal — kills the provider process when aborted */
+    signal?: AbortSignal;
+    /** Provider-specific model name, passed through Codex config and RPC overrides. */
+    model?: string;
+    /**
+     * Teamfile alias of the spawned member. Used only as a fallback for
+     * old callers that did not pass `isLead`.
+     */
+    alias?: string;
+    /** Role-based Lead signal from teamfile resolution. */
+    isLead?: boolean;
+    /**
+     * Permission mode for this turn (default "yolo").
+     *
+     * Codex's permission selection is wire-protocol level — both
+     * `thread/start` and `thread/resume` carry a `sandbox` param:
+     *
+     *   yolo → "danger-full-access" (historical default)
+     *   plan → "read-only"          (codex refuses workspace writes)
+     *
+     * `approvalPolicy` stays `"never"` in both modes because lmctl
+     * has no UI for forwarding permission prompts.
+     */
+    permissionMode?: PermissionMode;
+}
+/**
+ * Fork a codex thread via the app-server `thread/fork` JSON-RPC method.
+ *
+ * Why app-server and not the bundled `codex fork` CLI: `codex fork` is
+ * unconditionally TUI-only (`run_interactive_tui` in
+ * codex-rs/cli/src/main.rs:793-817), refusing non-TTY stdin with
+ * "Error: stdin is not a terminal". The app-server protocol exposes
+ * the same fork capability as a clean RPC.
+ *
+ * Empirical response shape (Phase B0 verified, codex-cli 0.121.0):
+ *
+ *   { id, result: { thread: {
+ *       id: "<NEW-THREAD-ID>",
+ *       forkedFromId: "<source-id>",
+ *       path: "~/.codex/sessions/.../<new-id>.jsonl",
+ *       turns: [...carried-over history...],
+ *       cwd, status: { type: "idle" }, ... } } }
+ *
+ * The forked thread is persisted to disk by codex BEFORE the response
+ * returns — no `turn/start` needed to materialize it.
+ *
+ * @param sourceThreadId  Existing codex thread id to fork from.
+ * @param opts.cwd        Working directory for the spawned app-server.
+ *                        Codex inherits this into the forked thread's cwd.
+ * @param opts.binaryPath Optional override of the codex binary path.
+ * @returns The new thread id codex minted for the fork.
+ */
+export declare function forkCodexThread(sourceThreadId: string, opts?: {
+    cwd?: string;
+    binaryPath?: string;
+}): Promise<string>;
+/**
+ * Send a prompt to Codex via the app-server protocol.
+ * Returns the assembled response text when the turn completes.
+ */
+export declare function sendCodexPrompt(prompt: string, opts: CodexAppServerOptions): Promise<CodexAppServerResult>;
+export interface CodexSessionOptions extends CodexAppServerOptions {
+    /**
+     * Shutdown cap: how long close() waits for a natural exit after stdin
+     * EOF before escalating to the (internally bounded) terminate ladder.
+     * Default 2000ms.
+     */
+    closeTimeoutMs?: number;
+    /**
+     * Outstanding-work check run ONCE at close() before stdin ends (same
+     * policy as the ACP/stream-json bundles: the persistence IS the hold,
+     * close honors the final turn's background dispatches).
+     */
+    holdOpen?: HoldOpenOptions;
+}
+export interface CodexSessionTurnOptions {
+    onDelta?: (text: string) => void;
+    onEvent?: (event: Record<string, unknown>) => void;
+    /**
+     * Abort THIS turn: rejects the turn with `Error("Aborted")` and sends a
+     * best-effort `turn/interrupt` — the app-server has a real cancel verb,
+     * so the bundle stays usable for the next turn (unlike stream-json).
+     */
+    signal?: AbortSignal;
+}
+export interface CodexSessionTurnResult {
+    text: string;
+    sessionId: string;
+    turnId: string;
+    durationMs: number;
+}
+/**
+ * An open codex app-server bundle session: one process serving many
+ * prompts via repeated `turn/start` on the resumed thread. The lifecycle
+ * contract is in src/providers/bundle.ts; the codex-specific decisions:
+ *
+ *  - Per-turn completion boundary: the `turn/completed` notification
+ *    (codex's authoritative end-of-turn signal, including its deferred
+ *    terminal-error resolution via resolveCodexTurnCompletion).
+ *  - Identity: thread/resume must return the EXACT requested thread id.
+ *    The resume→thread/start fallback is DISABLED in bundle mode — a
+ *    failed resume aborts the open, never silently starts a new thread
+ *    (requireResume parity with the ACP bundle).
+ *  - Cancellation: `turn/interrupt` keeps the bundle usable.
+ */
+export interface CodexBundleSession {
+    readonly provider: "codex";
+    readonly sessionId: string;
+    readonly completedTurns: number;
+    sendTurn(prompt: string, opts?: CodexSessionTurnOptions): Promise<CodexSessionTurnResult>;
+    close(): Promise<void>;
+}
+/**
+ * Open a persistent codex app-server session. See {@link CodexBundleSession}.
+ */
+export declare function openCodexSession(opts: CodexSessionOptions): Promise<CodexBundleSession>;
+/**
+ * Check if a tool should use the Codex app-server transport.
+ */
+export declare function supportsCodexAppServer(tool: string): boolean;

package/dist/providers/transports/hold-open.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Transport-agnostic "hold stdin open past the turn's result while the session's
+ * own dispatched work is still outstanding" mechanism. Extracted verbatim from
+ * stream-json.ts (task #68) so every transport — stream-json AND acp — shares
+ * ONE copy of this subtle concurrency code instead of re-deriving it.
+ *
+ * The ALGORITHM lives here once; each transport supplies its own {@link
+ * HoldOpenHooks} over its own child/abort/event state. Behavior is identical to
+ * the original inline stream-json implementation (its full test suite is the
+ * regression proof).
+ */
+export type HoldOpenReleaseReason = "cleared" | "max-hold" | "check-error" | "child-exited" | "aborted";
+export interface HoldOpenOptions {
+    /**
+     * True while the session being run still has outstanding dispatched work
+     * that must survive this process. Checked once on the first result event
+     * (fast path: false → close immediately), then every `pollMs` while true.
+     * A thrown/rejected check counts as "no outstanding work" — the check
+     * must never be able to wedge the turn open. A check that never settles
+     * cannot wedge it either: each call races the remaining `maxHoldMs`
+     * budget and the abort signal, so the ceiling is a real hard bound.
+     */
+    hasOutstandingWork: () => Promise<boolean> | boolean;
+    /** Poll interval while work is outstanding. Default 2000ms. */
+    pollMs?: number;
+    /**
+     * Quiescence window required AFTER a hold before the close proceeds: the
+     * check must keep reporting "no outstanding work" for this long. Measured
+     * from the LATER of "the work cleared" and "the child last emitted an event",
+     * and never expires while a turn is mid-flight. Covers the dispatched work's
+     * lease-release → process-exit → completion-notification hand-off, which a
+     * window measured from the lease alone would close stdin in the middle of.
+     * Deliberately applies ONLY after an actual hold. Default 5000ms; 0 disables.
+     */
+    settleMs?: number;
+    /**
+     * Hard ceiling on how long the close may be deferred — last-resort insurance
+     * against a row that stays "live" forever. Callers default this to the
+     * agent_inflight TTL. On expiry the close proceeds (today's behavior), never
+     * a hang. Default 8 hours.
+     */
+    maxHoldMs?: number;
+    /**
+     * Short, bounded window to wait for the FIRST agent_inflight lease to appear
+     * when a background job was launched this turn (see
+     * HoldOpenHooks.wasBackgroundJobLaunched) but no lease has registered yet — a
+     * nested `lmctl chat` has real startup latency before it takes its lease.
+     * Only ever applies before any hold, and only when a background job was
+     * observed; short-circuits the instant the lease appears (zero cost to a
+     * fast-registering dispatch). Distinct from `maxHoldMs`: this bounds ONLY the
+     * first-appearance race, not a held wait. Default 1000ms.
+     */
+    backgroundGraceMs?: number;
+    /** Called once when the close is first deferred (for logging). */
+    onHold?: () => void;
+    /**
+     * Called EXACTLY ONCE per turn once the hold path has finished, including the
+     * fast path (`held: false`, reason `"cleared"`). Callers use it both to log
+     * and to dispose resources the check acquired, so it must not be conditional
+     * on having actually held — decide what is worth logging from `held`/`reason`.
+     */
+    onRelease?: (info: {
+        elapsedMs: number;
+        held: boolean;
+        reason: HoldOpenReleaseReason;
+    }) => void;
+}
+/**
+ * Per-transport state the hold loop reads. Each transport wires these to its own
+ * abort flag, child-exit flag, turn-in-flight tracking, last-activity timestamp,
+ * and stdin-close primitive.
+ */
+export interface HoldOpenHooks {
+    /** The turn was aborted (caller signalled). */
+    isAborted: () => boolean;
+    /** The child process has already exited on its own. */
+    hasChildExited: () => boolean;
+    /** A turn is currently mid-flight (events seen since the last result). The
+     * settle window never expires while this is true. */
+    isTurnInFlight: () => boolean;
+    /** Epoch ms of the child's last emitted event/notification. */
+    lastEventAtMs: () => number;
+    /** Close the child's stdin (idempotent / harmless if already gone). */
+    closeStdin: () => void;
+    /** Abort signal, raced inside each never-settling check. */
+    signal?: AbortSignal;
+    /** Provider label for the max-hold errorLog + verbose logs. */
+    label: string;
+    /**
+     * True once a background job (e.g. an ACP `run_in_background` tool call) was
+     * observed launching this turn, and stays true for the rest of the turn. When
+     * true, the first "nothing outstanding" result gets a short grace window for
+     * the nested lease to register instead of the zero-latency fast close. Absent
+     * (stream-json, and any turn with no background launch) ⇒ treated as false ⇒
+     * the fast path is byte-for-byte unchanged.
+     */
+    wasBackgroundJobLaunched?: () => boolean;
+}
+/** Shared with the result-grace-timeout fallback (transports/stream-json.ts)
+ * so the two independent uses of `hasOutstandingWork` can't drift apart. */
+export declare const DEFAULT_MAX_HOLD_MS: number;
+/** Sentinel for "the check did not settle within its allotted budget". */
+declare const CHECK_TIMED_OUT: unique symbol;
+/**
+ * Await `check` but never longer than `budgetMs`, and never past an abort.
+ * Without this a `hasOutstandingWork` that never settles would park the hold
+ * loop forever — `maxHoldMs` is only consulted between awaits, so it would not
+ * be the hard ceiling it advertises. Exported for the result-grace-timeout
+ * fallback (transports/stream-json.ts), which awaits the SAME
+ * `hasOutstandingWork` check and needs the identical never-wedge guarantee.
+ */
+export declare function settleCheckWithin(check: Promise<boolean> | boolean, budgetMs: number, signal: AbortSignal | undefined): Promise<boolean | typeof CHECK_TIMED_OUT>;
+/**
+ * Schedule the turn's stdin close, optionally deferred while the session's own
+ * dispatched work is outstanding. Without `hold` this is the exact pre-existing
+ * synchronous `closeStdin()` — no promise, no extra tick. Call AT MOST ONCE per
+ * turn (callers guard their own first-result transition).
+ */
+export declare function scheduleHoldOpenClose(hold: HoldOpenOptions | undefined, hooks: HoldOpenHooks): void;
+export {};

package/dist/providers/transports/manager.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Transport manager — selects and creates transport handles.
+ *
+ * Replaces the provider-specific if/else branching in work-cmd.ts
+ * with a single unified interface.
+ */
+import type { TransportHandle, TransportType, TransportOptions } from "./types.js";
+import type { UserConfig } from "../config/types.js";
+export declare function selectTransport(tool: string): TransportType;
+export declare function transportLabel(type: TransportType, tool: string): string;
+export interface CreateTransportOpts extends TransportOptions {
+    /** User config — needed for one-shot fallback command building */
+    userConfig?: UserConfig;
+    /** Profile override — for one-shot */
+    profile?: string;
+}
+/**
+ * Create a transport handle for the given tool.
+ * Automatically selects the best transport.
+ */
+export declare function createTransport(opts: CreateTransportOpts): TransportHandle;

package/dist/providers/transports/stream-json.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Claude Code stream-json transport.
+ *
+ * Spawns `claude -p --input-format stream-json --output-format stream-json`
+ * and communicates via NDJSON on stdin/stdout. The process stays alive for
+ * the full conversation — no one-shot timeout.
+ *
+ * Protocol (reverse-engineered from Claude Agent SDK):
+ *   stdin:  {"type":"user","message":{"role":"user","content":"..."}}
+ *   stdout: {"type":"system","subtype":"init",...}
+ *           {"type":"assistant","message":{...},...}
+ *           {"type":"result","subtype":"success","result":"...","session_id":"..."}
+ */
+import { type PermissionMode } from "../yolo-contract.js";
+import { type HoldOpenOptions } from "./hold-open.js";
+export type { HoldOpenReleaseReason } from "./hold-open.js";
+export type StreamJsonHoldOpenOptions = HoldOpenOptions;
+import { type StreamJsonResult } from "../parsers/stream-json.js";
+export { aggregateResultEvents, createStreamJsonProcessor, joinResultTurns, supportsStreamJson, } from "../parsers/stream-json.js";
+export type { AggregatedResultEvents, StreamJsonProcessor, StreamJsonResult, } from "../parsers/stream-json.js";
+/**
+ * Deferred stdin-close contract (BUG-chat-client-death-interrupts-receiver-
+ * live-session, "root cause pinned exactly" section).
+ *
+ * Closing `child.stdin` on the first `result` event makes `claude -p` exit
+ * the moment its visible turn text is done — with zero regard for any
+ * `run_in_background` dispatches the session fired during that turn. Those
+ * children die with the exiting host process and their completion
+ * notifications are never delivered. The durable signal for "this session
+ * still has outstanding dispatched work" is an `agent_inflight` row whose
+ * SENDER is this session's own identity, held by a live pid — state lmctl
+ * already owns.
+ *
+ * The transport stays DB-free: the caller supplies `hasOutstandingWork` as
+ * an opaque callback (queue-delivery builds it from the receiver identity +
+ * DAL). When the option is absent, the close is the same synchronous
+ * `child.stdin.end()` as before — zero added latency. When present, ONE
+ * check runs on the first result event; only if it reports outstanding work
+ * does the transport enter a poll loop.
+ */
+export interface StreamJsonOptions {
+    sessionId?: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    /** Called for each raw NDJSON event from stdout (for logging/debugging) */
+    onEvent?: (event: Record<string, unknown>) => void;
+    /** Called when streaming text arrives (for live output) */
+    onText?: (text: string) => void;
+    /**
+     * Permission mode for this turn.
+     *
+     *   - "yolo" (default) — historical behavior; append the provider's
+     *     permission-bypass flag (`--dangerously-skip-permissions` for
+     *     claude, `--approval-mode yolo` for qwen). Required for
+     *     non-interactive runs; if the provider asks for a permission
+     *     mid-turn lmctl has no UI to forward the request.
+     *   - "plan"            — append the provider's plan-mode flag
+     *     instead (`--permission-mode plan` for claude,
+     *     `--approval-mode plan` for qwen). The provider should refuse
+     *     workspace-modifying tool calls in this mode. Use for research /
+     *     exploration sessions.
+     *
+     * Default is "yolo" so callers that omit the field preserve the
+     * pre-existing argv shape exactly.
+     */
+    permissionMode?: PermissionMode;
+    /** Tool name — determines the binary and permission flags */
+    tool?: string;
+    /**
+     * Override the spawned binary path. When set, this exact path is
+     * spawned instead of looking up `tool` in TOOL_BINARY. Permission
+     * flags are still resolved via `tool`. Used for troubleshooting
+     * with custom Claude Code builds. (Task 63 fix 3.)
+     */
+    binaryPath?: string;
+    /** Abort signal — kills the provider process when aborted */
+    signal?: AbortSignal;
+    /** Provider-specific model name, appended as `--model <name>`. */
+    model?: string;
+    /**
+     * When set, the first-result stdin close is deferred while the caller
+     * reports outstanding dispatched work. See {@link StreamJsonHoldOpenOptions}.
+     */
+    holdOpen?: StreamJsonHoldOpenOptions;
+}
+export declare function formatProviderNoResultError(params: {
+    tool: string;
+    exitCode: number | null;
+    stderr: string;
+}): string;
+/**
+ * Send a prompt via the stream-json protocol (Claude Code / Qwen).
+ * Returns the final result text when the turn completes.
+ */
+export declare function sendPrompt(prompt: string, opts: StreamJsonOptions): Promise<StreamJsonResult>;
+export interface StreamJsonSessionOptions extends StreamJsonOptions {
+    /**
+     * Shutdown cap: how long close() waits for a natural exit after stdin
+     * EOF before escalating to the (internally bounded) terminate ladder.
+     * Also bounds the open-phase wait for the provider's init event.
+     * Default 2000ms (close) / 30000ms (init).
+     */
+    closeTimeoutMs?: number;
+    /**
+     * Override the session-file roots used by the bundle identity check.
+     * Default: the provider's standard projects dir under the user home
+     * (`~/.claude/projects`, `~/.qwen/projects`). Exists for tests and
+     * custom provider homes.
+     */
+    sessionFileRoots?: string[];
+}
+export interface StreamJsonSessionTurnOptions {
+    onText?: (text: string) => void;
+    onEvent?: (event: Record<string, unknown>) => void;
+    /**
+     * Abort THIS turn. stream-json has no verified cancel verb, so
+     * cancellation is TERMINAL for the bundle: the turn rejects with
+     * `Error("Aborted")` and the child gets the same graceful-shutdown
+     * ladder a one-shot abort gets. Later turns fail fast.
+     */
+    signal?: AbortSignal;
+}
+export interface StreamJsonSessionTurnResult {
+    result: string;
+    sessionId: string;
+    durationMs: number;
+    numTurns: number;
+    /** Stall-grace fallback marker (text_done), same convention as
+     *  StreamJsonResult.warnings. */
+    warnings?: string[];
+}
+/**
+ * An open stream-json bundle session: one provider process serving many
+ * prompts. The lifecycle contract is in src/providers/bundle.ts; the
+ * transport-specific decisions:
+ *
+ *  - Per-turn completion boundary: the turn's `result` event. A fresh
+ *    StreamJsonProcessor per turn, so accumulated text/results never leak
+ *    across turns; events arriving with no turn in flight update activity
+ *    bookkeeping only (never accumulated, never armed timers).
+ *  - The stall-grace machinery (text_done / tool_use_silence timers) is
+ *    retained and re-armed per turn; a text_done fire resolves the turn
+ *    from accumulated text with a warning exactly like the one-shot path
+ *    (and ends the process, so the bundle is dead afterwards).
+ *  - Identity: the session FILE's header is checked at open (requireResume
+ *    parity — no file, no bundle) and re-checked before every sendTurn
+ *    (catches an external re-seed mid-bundle); the provider's init event
+ *    must agree with the requested session id.
+ *  - Cancellation is terminal (no verified cancel verb in stream-json).
+ */
+export interface StreamJsonSession {
+    readonly tool: string;
+    readonly sessionId: string;
+    readonly completedTurns: number;
+    sendTurn(prompt: string, opts?: StreamJsonSessionTurnOptions): Promise<StreamJsonSessionTurnResult>;
+    close(): Promise<void>;
+}
+/**
+ * Open a persistent stream-json session (`claude`/`qwen`). See
+ * {@link StreamJsonSession} for the contract.
+ */
+export declare function openStreamJsonSession(opts: StreamJsonSessionOptions): Promise<StreamJsonSession>;

package/dist/providers/transports/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared transport interfaces.
+ *
+ * All provider transports implement TransportHandle so the caller
+ * (work-cmd, serve) doesn't need provider-specific branching.
+ */
+export type TransportType = "stream-json" | "codex-app-server" | "acp" | "one-shot";
+export interface TurnResult {
+    text: string;
+    sessionId: string;
+    durationMs: number;
+    stopReason?: string;
+    numTurns?: number;
+}
+export interface TransportOptions {
+    sessionId?: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    tool: string;
+    /**
+     * If true, the transport must resume the given sessionId or fail.
+     * If false, a failed resume may fall back to a new session.
+     * Set to true for `--session`, false for `--team` or new sessions.
+     */
+    requireResume?: boolean;
+    /**
+     * Called with each text delta as it arrives from the provider.
+     * Used by the SSE streaming endpoint to push incremental text to the browser.
+     */
+    onDelta?: (text: string) => void;
+    /**
+     * Signal to abort/cancel the turn. When aborted, the transport should
+     * kill the provider process and reject the sendTurn promise.
+     */
+    signal?: AbortSignal;
+    /** Provider-specific model override, when the selected transport supports it. */
+    model?: string;
+    /** Provider-specific effort / variant override, when the selected transport supports it. */
+    effort?: string;
+    /** Teamfile alias, when provider setup needs alias-specific behavior. */
+    alias?: string;
+    /** Provider binary override. */
+    progPath?: string;
+    /**
+     * Permission mode — `"yolo"` (default) or `"plan"`. The transport
+     * substitutes the per-provider argv / JSON-RPC params accordingly.
+     * See `src/providers/yolo-contract.ts`.
+     */
+    permissionMode?: import("../yolo-contract.js").PermissionMode;
+}
+export interface TransportHandle {
+    readonly type: TransportType;
+    readonly tool: string;
+    /** Send a prompt and get the response. Manages the full lifecycle internally. */
+    sendTurn(prompt: string): Promise<TurnResult>;
+}