@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/providers/claude/transport/pty.d.ts

@@ -0,0 +1,153 @@
+import type { HookEvent } from "@hyperdrive.bot/fleet-protocol/messages";
+import { type CapturePaneOptions } from "./tmux.js";
+import type { AgentTransport, AgentTransportContext, AgentTransportSpawnOptions } from "./types.js";
+type NodePtyModule = typeof import("node-pty");
+/**
+ * Input provenance sink.
+ *
+ * Every byte paseo puts into a claude terminal passes through write()/writeRaw(), so this
+ * is the ONE seam no code path can bypass. That matters: an earlier trace was placed at
+ * sendPromptToAgent, which looked like the seam every prompt crosses, and a `/compact`
+ * reached a session at 22:01:44 without ever appearing in it. Slash commands are written
+ * directly to the transport from at least two other places (`/model`, `/effort` in
+ * agent.ts), so a prompt-level trace was always going to have holes.
+ *
+ * Wired as a module-level sink rather than a constructor arg so it can be installed
+ * without touching every construction site, and so it is a no-op (one null check) when
+ * nobody is listening.
+ */
+export interface PtyInputEvent {
+    /** "write" = bracketed paste (a prompt); "writeRaw" = keystrokes (Enter, control chords). */
+    kind: "write" | "writeRaw";
+    /** First token only when the payload is a slash command, else null. */
+    command: string | null;
+    /** Payload length; the body itself is never captured. */
+    length: number;
+    /** Call site, so the responsible code path names itself. */
+    stack: string;
+    /**
+     * The session this write actually went to.
+     *
+     * Carried on the EVENT because the sink is installed once, module-level, with whichever
+     * logger belonged to the first agent to spawn a PTY. That logger's `agentId` is therefore
+     * the installer's for every later write, which read as a cross-agent write during a live
+     * investigation on 2026-08-29. The event has to name its own target.
+     */
+    sessionId: string | null;
+}
+/** Install (or clear, with null) the input-provenance sink. */
+export declare function setPtyInputSink(sink: ((event: PtyInputEvent) => void) | null): void;
+export declare function __setNodePtyForTesting(stub: NodePtyModule | null): void;
+/**
+ * Thrown when something tries to write to a pty whose process has already exited.
+ *
+ * This has a dedicated type because the two failure modes read identically at the call site
+ * and must not: "never spawned" is a programming error, while "already exited" is a normal
+ * runtime event that the layer above has to react to by failing the turn. Before this class
+ * existed, `doWrite` happily called `_pty.write()` on a dead pty, node-pty swallowed it, and
+ * the post-write settle (then misleadingly named `waitForEcho`) reported success - so paseo typed prompts into a corpse for
+ * fourteen retries and then told the user "the session itself is still running".
+ */
+export declare class PtyExitedError extends Error {
+    readonly code = "PTY_EXITED";
+    /** How the process died, so a caller can report it without a second lookup. */
+    readonly exitCode: number | null;
+    readonly exitSignal: NodeJS.Signals | null;
+    constructor(op: string, exitCode?: number | null, exitSignal?: NodeJS.Signals | null);
+}
+export declare class PtyTransport implements AgentTransport {
+    private _pty;
+    private _cwd;
+    private _cols;
+    private _rows;
+    private _killed;
+    private _exited;
+    private _exitInfo;
+    private exitHandlers;
+    private injectChain;
+    private hookHandlers;
+    private hookBuffer;
+    private bridgeClose;
+    private systemPromptFilePath;
+    /** Set only when PASEO_PTY_TMUX=1 wrapped this spawn. Null means a bare pty. */
+    /** Session behind this PTY, so an input-provenance event can name its own target. */
+    private spawnSessionId;
+    private tmux;
+    /**
+     * Has the child process exited?
+     *
+     * Public because guarding the write paths fixes the symptom but leaves the question
+     * unanswerable: `_exited` was private, so no caller could ask a transport whether its
+     * child was alive without provoking an error. `AgentTransport` now declares it.
+     */
+    get exited(): boolean;
+    /** Exit status once the child is gone, else null. */
+    get exitInfo(): {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | null;
+    /**
+     * Bridge-side / test entry point — push a hook event into this transport's
+     * stream. If no `onHookEvent` handler is registered yet, the event is
+     * buffered and flushed on the first registration (or on `kill()`).
+     */
+    pushHookEvent(event: HookEvent): void;
+    /**
+     * Hook bridge cleanup. The daemon-side hook bridge calls this so PtyTransport
+     * can release the per-agent Unix socket handler during kill(). Idempotent.
+     */
+    setBridgeCloseHook(close: (() => void | Promise<void>) | null): void;
+    private deliverEvent;
+    private drainBuffer;
+    spawn(opts: AgentTransportSpawnOptions): Promise<void>;
+    write(text: string): Promise<void>;
+    /**
+     * Write raw bytes (no bracketed-paste framing) — for real keypresses like
+     * control chords (e.g. Claude Code's `ctrl+x ctrl+k` kill chord) that must
+     * reach the TUI as keystrokes, not pasted text. Serialized through the same
+     * inject chain as write() so it can't interleave mid-paste.
+     */
+    writeRaw(data: string): Promise<void>;
+    private doWriteRaw;
+    private bracketedPaste;
+    private doWrite;
+    /**
+     * Settle briefly after handing bytes to the pty, so two writes queued back to back on the
+     * inject chain do not arrive faster than the TUI redraws between them.
+     *
+     * This is NOT a delivery check and must never be mistaken for one. It cannot fail, it
+     * inspects nothing, and it tells the caller only that time passed. Delivery is confirmed
+     * one layer up by PtyQuery.receiptSince(), which watches the transcript for the `user`
+     * record claude appends when it actually accepts a turn.
+     *
+     * The distinction is load-bearing. This was called `waitForEcho` and carried a comment
+     * promising a "marker-based approach in Phase 5 hardening", which read like a delivery
+     * check somebody had not finished yet. That misreading reached a tech-debt entry proposing
+     * to give it a real echo check - a change that would have duplicated receiptSince(), added
+     * a round trip to every keystroke, and fixed nothing, because the dead-pty bug was the
+     * missing exit gate above, not this delay.
+     */
+    private settleAfterWrite;
+    kill(timeoutMs?: number): Promise<void>;
+    onHookEvent(handler: (event: HookEvent) => void): () => void;
+    onData(handler: (chunk: string) => void): () => void;
+    onExit(handler: (code: number | null, signal: NodeJS.Signals | null) => void): () => void;
+    /**
+     * The settled, rendered screen as text, read OUT OF BAND, or null when unavailable.
+     *
+     * This is the reason to run tmux at all. Everything paseo knows about the screen today is
+     * scraped from the live byte stream it is simultaneously racing, which is why the queued
+     * footer match is fragile to wrapping and ANSI interleaving. Null on a bare pty and on any
+     * tmux error, so a caller must always keep its stream-based path: a diagnostic that can
+     * fail a turn is worse than no diagnostic.
+     */
+    capturePane(options?: CapturePaneOptions): Promise<string | null>;
+    /** Multiplexer identity, for logs and tests. Null on a bare pty. */
+    get multiplexer(): {
+        socket: string;
+        session: string;
+    } | null;
+    context(): AgentTransportContext;
+}
+export {};
+//# sourceMappingURL=pty.d.ts.map

package/dist/server/server/agent/providers/claude/transport/pty.js

@@ -0,0 +1,367 @@
+import { unlink } from "node:fs";
+import { createRequire } from "node:module";
+import { setTimeout as delay } from "node:timers/promises";
+import { redactChunk } from "./redact.js";
+import { assertTmuxUsable, capturePane, DEFAULT_PTY_DIMS, killSession, tmuxEnabled, wrapWithTmux, } from "./tmux.js";
+const DEFAULT_KILL_TIMEOUT_MS = 5000;
+/** Pause after each write so back-to-back writes do not outrun the TUI's redraw. */
+const WRITE_SETTLE_MS = 50;
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+let ptyInputSink = null;
+/** Install (or clear, with null) the input-provenance sink. */
+export function setPtyInputSink(sink) {
+    ptyInputSink = sink;
+}
+function reportInput(kind, payload, sessionId) {
+    if (!ptyInputSink)
+        return;
+    const trimmed = payload.trim();
+    // Only slash commands are named. Ordinary prompt text is never captured, only its length.
+    const command = trimmed.startsWith("/") ? (trimmed.split(/\s/, 1)[0] ?? null) : null;
+    const stack = (new Error().stack ?? "")
+        .split("\n")
+        .slice(2, 8)
+        .map((l) => l.trim())
+        .join(" | ");
+    try {
+        ptyInputSink({ kind, command, length: payload.length, stack, sessionId });
+    }
+    catch {
+        // Telemetry must never break input delivery.
+    }
+}
+let nodePty = null;
+function getNodePty() {
+    if (nodePty)
+        return nodePty;
+    try {
+        const req = createRequire(import.meta.url);
+        nodePty = req("node-pty");
+    }
+    catch {
+        throw new Error("claude PTY transport unavailable: node-pty failed to load");
+    }
+    return nodePty;
+}
+// Test-only injection point. The lazy `require` above bypasses ESM module
+// mocks (e.g. vitest's `vi.mock`), so tests inject a stub here instead.
+export function __setNodePtyForTesting(stub) {
+    nodePty = stub;
+}
+/**
+ * Thrown when something tries to write to a pty whose process has already exited.
+ *
+ * This has a dedicated type because the two failure modes read identically at the call site
+ * and must not: "never spawned" is a programming error, while "already exited" is a normal
+ * runtime event that the layer above has to react to by failing the turn. Before this class
+ * existed, `doWrite` happily called `_pty.write()` on a dead pty, node-pty swallowed it, and
+ * the post-write settle (then misleadingly named `waitForEcho`) reported success - so paseo typed prompts into a corpse for
+ * fourteen retries and then told the user "the session itself is still running".
+ */
+export class PtyExitedError extends Error {
+    constructor(op, exitCode = null, exitSignal = null) {
+        super(`PtyTransport.${op} called after the pty process exited`);
+        this.code = "PTY_EXITED";
+        this.name = "PtyExitedError";
+        this.exitCode = exitCode;
+        this.exitSignal = exitSignal;
+    }
+}
+export class PtyTransport {
+    constructor() {
+        this._pty = null;
+        this._cwd = "";
+        this._cols = DEFAULT_PTY_DIMS.cols;
+        this._rows = DEFAULT_PTY_DIMS.rows;
+        this._killed = false;
+        this._exited = false;
+        this._exitInfo = null;
+        this.exitHandlers = [];
+        this.injectChain = Promise.resolve();
+        this.hookHandlers = [];
+        this.hookBuffer = [];
+        this.bridgeClose = null;
+        this.systemPromptFilePath = null;
+        /** Set only when PASEO_PTY_TMUX=1 wrapped this spawn. Null means a bare pty. */
+        /** Session behind this PTY, so an input-provenance event can name its own target. */
+        this.spawnSessionId = null;
+        this.tmux = null;
+    }
+    /**
+     * Has the child process exited?
+     *
+     * Public because guarding the write paths fixes the symptom but leaves the question
+     * unanswerable: `_exited` was private, so no caller could ask a transport whether its
+     * child was alive without provoking an error. `AgentTransport` now declares it.
+     */
+    get exited() {
+        return this._exited;
+    }
+    /** Exit status once the child is gone, else null. */
+    get exitInfo() {
+        return this._exitInfo ? { ...this._exitInfo } : null;
+    }
+    /**
+     * Bridge-side / test entry point — push a hook event into this transport's
+     * stream. If no `onHookEvent` handler is registered yet, the event is
+     * buffered and flushed on the first registration (or on `kill()`).
+     */
+    pushHookEvent(event) {
+        if (this.hookHandlers.length === 0) {
+            this.hookBuffer.push(event);
+            return;
+        }
+        this.deliverEvent(event);
+    }
+    /**
+     * Hook bridge cleanup. The daemon-side hook bridge calls this so PtyTransport
+     * can release the per-agent Unix socket handler during kill(). Idempotent.
+     */
+    setBridgeCloseHook(close) {
+        this.bridgeClose = close;
+    }
+    deliverEvent(event) {
+        for (const h of this.hookHandlers) {
+            try {
+                h(event);
+            }
+            catch {
+                // handler errors must not break siblings
+            }
+        }
+    }
+    drainBuffer() {
+        if (this.hookBuffer.length === 0)
+            return;
+        const events = this.hookBuffer.splice(0, this.hookBuffer.length);
+        for (const event of events)
+            this.deliverEvent(event);
+    }
+    async spawn(opts) {
+        const pty = getNodePty();
+        const cols = opts.dims?.cols ?? DEFAULT_PTY_DIMS.cols;
+        const rows = opts.dims?.rows ?? DEFAULT_PTY_DIMS.rows;
+        this._cwd = opts.cwd;
+        this._cols = cols;
+        this._rows = rows;
+        this.systemPromptFilePath = opts.systemPromptFilePath ?? null;
+        // Optionally run the agent inside tmux. The daemon's pty then holds a tmux CLIENT rather
+        // than the agent itself, so the agent survives this process: `new-session -A` reattaches
+        // an existing session and creates one otherwise, which is the reattach a daemon restart
+        // needs. Exit detection is unaffected - when the agent exits, its tmux session ends, our
+        // client exits, and node-pty's onExit fires exactly as before.
+        let binary = opts.binary;
+        this.spawnSessionId = opts.sessionId ?? null;
+        let args = opts.args;
+        if (tmuxEnabled(opts.env)) {
+            // Assert at the boundary where a missing binary actually matters. wrapWithTmux() stays
+            // pure so it can be unit-tested on a host without tmux (CI runs node:24-slim).
+            assertTmuxUsable();
+            const wrap = wrapWithTmux({
+                binary: opts.binary,
+                args: opts.args,
+                cwd: opts.cwd,
+                sessionId: opts.sessionId ?? `${process.pid}-${this._cols}x${this._rows}`,
+                dims: { cols, rows },
+                env: opts.env,
+            });
+            binary = wrap.binary;
+            args = wrap.args;
+            this.tmux = { socket: wrap.socket, session: wrap.session };
+        }
+        this._pty = pty.spawn(binary, args, {
+            name: "xterm-256color",
+            cols,
+            rows,
+            cwd: opts.cwd,
+            env: opts.env,
+        });
+        // ONE internal subscription owns exit state and fans it out to every public onExit()
+        // handler. Registering handlers straight onto node-pty (the previous shape) meant a
+        // subscriber that attached AFTER the child had already died heard nothing at all -- and
+        // a PtyQuery attaches to a long-lived terminal, not only to a fresh boot, so that is a
+        // reachable case and not a theoretical one.
+        this._pty.onExit(({ exitCode, signal }) => {
+            const code = typeof exitCode === "number" ? exitCode : null;
+            const sig = signal ?? null;
+            this._exited = true;
+            this._exitInfo = { code, signal: sig };
+            for (const h of this.exitHandlers) {
+                try {
+                    h(code, sig);
+                }
+                catch {
+                    // one bad subscriber must not stop the others hearing about the death
+                }
+            }
+        });
+    }
+    write(text) {
+        reportInput("write", text, this.spawnSessionId);
+        this.injectChain = this.injectChain.then(() => this.doWrite(text));
+        return this.injectChain;
+    }
+    /**
+     * Write raw bytes (no bracketed-paste framing) — for real keypresses like
+     * control chords (e.g. Claude Code's `ctrl+x ctrl+k` kill chord) that must
+     * reach the TUI as keystrokes, not pasted text. Serialized through the same
+     * inject chain as write() so it can't interleave mid-paste.
+     */
+    writeRaw(data) {
+        reportInput("writeRaw", data, this.spawnSessionId);
+        this.injectChain = this.injectChain.then(() => this.doWriteRaw(data));
+        return this.injectChain;
+    }
+    async doWriteRaw(data) {
+        if (!this._pty) {
+            throw new Error("PtyTransport.writeRaw called before spawn()");
+        }
+        if (this._exited) {
+            throw new PtyExitedError("writeRaw", this._exitInfo?.code ?? null, this._exitInfo?.signal ?? null);
+        }
+        this._pty.write(data);
+        await this.settleAfterWrite();
+    }
+    bracketedPaste(text) {
+        return `${BRACKETED_PASTE_START}${text}${BRACKETED_PASTE_END}`;
+    }
+    async doWrite(text) {
+        if (!this._pty) {
+            throw new Error("PtyTransport.write called before spawn()");
+        }
+        if (this._exited) {
+            throw new PtyExitedError("write", this._exitInfo?.code ?? null, this._exitInfo?.signal ?? null);
+        }
+        this._pty.write(this.bracketedPaste(text));
+        await this.settleAfterWrite();
+    }
+    /**
+     * Settle briefly after handing bytes to the pty, so two writes queued back to back on the
+     * inject chain do not arrive faster than the TUI redraws between them.
+     *
+     * This is NOT a delivery check and must never be mistaken for one. It cannot fail, it
+     * inspects nothing, and it tells the caller only that time passed. Delivery is confirmed
+     * one layer up by PtyQuery.receiptSince(), which watches the transcript for the `user`
+     * record claude appends when it actually accepts a turn.
+     *
+     * The distinction is load-bearing. This was called `waitForEcho` and carried a comment
+     * promising a "marker-based approach in Phase 5 hardening", which read like a delivery
+     * check somebody had not finished yet. That misreading reached a tech-debt entry proposing
+     * to give it a real echo check - a change that would have duplicated receiptSince(), added
+     * a round trip to every keystroke, and fixed nothing, because the dead-pty bug was the
+     * missing exit gate above, not this delay.
+     */
+    async settleAfterWrite() {
+        await delay(WRITE_SETTLE_MS);
+    }
+    async kill(timeoutMs = DEFAULT_KILL_TIMEOUT_MS) {
+        if (this._killed)
+            return;
+        this._killed = true;
+        // Flush any buffered hook events to registered handlers before teardown so
+        // late-arriving observations aren't dropped on swap/close.
+        this.drainBuffer();
+        // Drop the injectChain reference so any pending writes don't extend the
+        // chain past kill(). The current chain promise still settles on its own.
+        this.injectChain = Promise.resolve();
+        if (this.bridgeClose) {
+            try {
+                await this.bridgeClose();
+            }
+            catch {
+                // bridge close errors must not block teardown
+            }
+            this.bridgeClose = null;
+        }
+        // Under tmux, killing our client only DETACHES: the agent would keep running forever,
+        // which is the design working against us here. kill() has to mean kill, so end the
+        // session first and let the client fall out with it.
+        if (this.tmux) {
+            killSession(this.tmux.socket, this.tmux.session);
+        }
+        if (!this._pty)
+            return;
+        try {
+            this._pty.kill("SIGTERM");
+        }
+        catch {
+            // already dead
+        }
+        await delay(timeoutMs);
+        if (!this._exited) {
+            try {
+                this._pty.kill("SIGKILL");
+            }
+            catch {
+                // already dead
+            }
+        }
+        if (this.systemPromptFilePath) {
+            const p = this.systemPromptFilePath;
+            this.systemPromptFilePath = null;
+            // Best-effort cleanup — never fail kill() if the file is already gone.
+            unlink(p, () => { });
+        }
+    }
+    onHookEvent(handler) {
+        this.hookHandlers.push(handler);
+        this.drainBuffer();
+        return () => {
+            this.hookHandlers = this.hookHandlers.filter((h) => h !== handler);
+        };
+    }
+    onData(handler) {
+        if (!this._pty) {
+            throw new Error("PtyTransport.onData called before spawn()");
+        }
+        const disposable = this._pty.onData((raw) => handler(redactChunk(raw)));
+        return () => disposable.dispose();
+    }
+    onExit(handler) {
+        if (!this._pty) {
+            throw new Error("PtyTransport.onExit called before spawn()");
+        }
+        this.exitHandlers.push(handler);
+        // Already dead: fire, rather than never. Deferred a microtask so a subscriber that
+        // registers from a constructor (PtyQuery does) cannot be re-entered before it has
+        // finished building itself.
+        if (this._exited) {
+            const info = this._exitInfo;
+            queueMicrotask(() => handler(info?.code ?? null, info?.signal ?? null));
+        }
+        return () => {
+            this.exitHandlers = this.exitHandlers.filter((h) => h !== handler);
+        };
+    }
+    /**
+     * The settled, rendered screen as text, read OUT OF BAND, or null when unavailable.
+     *
+     * This is the reason to run tmux at all. Everything paseo knows about the screen today is
+     * scraped from the live byte stream it is simultaneously racing, which is why the queued
+     * footer match is fragile to wrapping and ANSI interleaving. Null on a bare pty and on any
+     * tmux error, so a caller must always keep its stream-based path: a diagnostic that can
+     * fail a turn is worse than no diagnostic.
+     */
+    async capturePane(options = {}) {
+        if (!this.tmux)
+            return null;
+        return capturePane(this.tmux.socket, this.tmux.session, options);
+    }
+    /** Multiplexer identity, for logs and tests. Null on a bare pty. */
+    get multiplexer() {
+        return this.tmux ? { ...this.tmux } : null;
+    }
+    context() {
+        if (!this._pty) {
+            throw new Error("PtyTransport.context called before spawn()");
+        }
+        return {
+            transport: "pty",
+            pid: this._pty.pid,
+            cwd: this._cwd,
+            dims: { cols: this._cols, rows: this._rows },
+        };
+    }
+}
+//# sourceMappingURL=pty.js.map

package/dist/server/server/agent/providers/claude/transport/redact.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strip credentials from text about to be persisted or shown to a user. Used for PTY
+ * output (see {@link redactChunk}) and for provider error text lifted out of the session
+ * transcript, which is the one path on which a key can reach the timeline.
+ */
+export declare function redactSecrets(text: string): string;
+export declare function redactChunk(chunk: string): string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/server/server/agent/providers/claude/transport/redact.js

@@ -0,0 +1,33 @@
+const JWT_PATTERN = /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g;
+/**
+ * Bearer-style credentials that turn up in provider error text and terminal output.
+ *
+ * Deliberately prefix-anchored rather than "any long random-looking string": provider
+ * errors carry plenty of high-entropy non-secrets (request ids, uuids, session ids) and
+ * scrubbing those would make a surfaced error useless for diagnosis. Each entry is a
+ * credential shape that actually reaches this path:
+ *   - `sk-ant-…`  Anthropic API keys
+ *   - `cp_…`      claude-proxy client keys (paseo `agents.providers.*.env`)
+ *   - `hd_sk_…`   hyperdrive CI tokens
+ */
+const SECRET_PATTERNS = [
+    [/sk-ant-[A-Za-z0-9_-]{16,}/g, "[REDACTED-KEY]"],
+    [/\bcp_[A-Za-z0-9_-]{16,}/g, "[REDACTED-KEY]"],
+    [/\bhd_sk_[A-Za-z0-9_-]{16,}/g, "[REDACTED-KEY]"],
+];
+/**
+ * Strip credentials from text about to be persisted or shown to a user. Used for PTY
+ * output (see {@link redactChunk}) and for provider error text lifted out of the session
+ * transcript, which is the one path on which a key can reach the timeline.
+ */
+export function redactSecrets(text) {
+    let out = text.replace(JWT_PATTERN, "[REDACTED-JWT]");
+    for (const [pattern, replacement] of SECRET_PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    return out;
+}
+export function redactChunk(chunk) {
+    return redactSecrets(chunk);
+}
+//# sourceMappingURL=redact.js.map

package/dist/server/server/agent/providers/claude/transport/sdk.d.ts

@@ -0,0 +1,65 @@
+import { query, type Options, type Query } from "@anthropic-ai/claude-agent-sdk";
+import type { Logger } from "pino";
+import type { HookEvent } from "@hyperdrive.bot/fleet-protocol/messages";
+import { type ProviderRuntimeSettings } from "../../../provider-launch-config.js";
+import type { AgentTransport, AgentTransportContext, AgentTransportSpawnOptions } from "./types.js";
+export type ClaudeOptions = Options;
+export type ClaudeQueryInput = Parameters<typeof query>[0] & {
+    options: ClaudeOptions;
+};
+export type ClaudeQueryFactory = (input: ClaudeQueryInput) => Query;
+export interface ClaudeQueryContext {
+    runtimeSettings?: ProviderRuntimeSettings;
+    launchEnv?: Record<string, string>;
+    queryFactory?: ClaudeQueryFactory;
+}
+/**
+ * Construct a raw SDK Query with the project-standard runtime-settings/env handling
+ * applied. Kept as a free function for tests that exercise the SDK call directly
+ * (see `sdk-behavior.test.ts`, `agent.integration.test.ts`).
+ */
+export declare function claudeQuery(input: ClaudeQueryInput, context?: ClaudeQueryContext): Query;
+export interface SdkTransportOptions {
+    runtimeSettings?: ProviderRuntimeSettings;
+    launchEnv?: Record<string, string>;
+    queryFactory?: ClaudeQueryFactory;
+    logger?: Logger;
+}
+/**
+ * SDK transport — wraps the @anthropic-ai/claude-agent-sdk `query()` call behind
+ * the shared `AgentTransport` interface so `ClaudeAgentSession` can dispatch
+ * between SDK and PTY transports uniformly in Story 3.2+.
+ *
+ * In Story 3.1 the pump still consumes the raw `Query` object directly; this
+ * class exists primarily for type-compatibility and to centralize SDK spawn
+ * configuration. `createQuery()` is the transitional helper agent.ts uses to
+ * fetch the underlying `Query` while preserving today's behavior.
+ */
+export declare class SdkTransport implements AgentTransport {
+    private readonly runtimeSettings?;
+    private readonly launchEnv?;
+    private readonly queryFactory?;
+    private _cwd;
+    private _query;
+    private _killed;
+    private _exited;
+    private exitHandlers;
+    constructor(opts?: SdkTransportOptions);
+    /**
+     * Transitional helper for Story 3.1 — agent.ts uses this in `ensureQuery()` to
+     * obtain the underlying `Query` while the pump continues to consume it
+     * directly. Story 3.2 will pivot the pump onto `onHookEvent` and remove this.
+     */
+    createQuery(input: ClaudeQueryInput): Query;
+    spawn(opts: AgentTransportSpawnOptions): Promise<void>;
+    write(text: string): Promise<void>;
+    /** True once the SDK query has been closed/returned. Mirrors PtyTransport.exited. */
+    get exited(): boolean;
+    kill(timeoutMs?: number): Promise<void>;
+    onHookEvent(_handler: (event: HookEvent) => void): () => void;
+    onData(_handler: (chunk: string) => void): () => void;
+    onExit(handler: (code: number | null, signal: NodeJS.Signals | null) => void): () => void;
+    private fireExit;
+    context(): AgentTransportContext;
+}
+//# sourceMappingURL=sdk.d.ts.map