agent-relay 7.1.0 → 8.0.0

package/dist/cli/lib/attach-passthrough.d.ts

@@ -0,0 +1,148 @@
+/**
+ * `agent-relay passthrough <name>` — read-write attach in passthrough session.
+ *
+ * The broker auto-injects inbound relay messages into the agent's PTY
+ * while the human also types; both writers race. That's the point —
+ * passthrough is for observe-and-occasionally-nudge sessions
+ * while the broker does its coordination thing. For exclusive
+ * deterministic control with no auto-inject, use `drive` instead.
+ *
+ * On attach, ensures the worker is in `auto_inject` delivery mode (it's the
+ * broker default, but if someone left a `drive` session the worker may
+ * be in `manual_flush` mode — `passthrough` flips it back for the session's
+ * duration and restores the prior mode on detach). On detach, restores
+ * the prior mode and leaves the agent running.
+ *
+ * The session loop (snapshot-on-attach, raw stdin, resize forwarding,
+ * detach keybind, Ctrl+C-as-detach safety alias) mirrors the shape of
+ * `drive.ts` minus the pending-queue UI and `Ctrl+G` flush binding
+ * (there's no queue in passthrough session). `drive.ts` is the more
+ * heavily-commented version of the shared shape; this module
+ * duplicates rather than abstracts because the trimmed surface is
+ * small enough that an extra layer of indirection would cost more
+ * clarity than it saves.
+ */
+import { Buffer } from 'node:buffer';
+import WebSocket from 'ws';
+import { captureAndRenderSnapshot, type AttachSnapshotConnection, type AttachSnapshotDeps } from '../lib/attach.js';
+import { type BrokerConnection } from '../lib/broker-connection.js';
+import { type CliPtyInputStream, type InboundDeliveryMode } from './attach-drive.js';
+type ExitFn = (code: number) => never;
+/** Minimal WebSocket surface we depend on — same shape as `drive`'s. */
+export interface PassthroughWebSocket {
+    on(event: 'open', listener: () => void): unknown;
+    on(event: 'message', listener: (data: WebSocket.RawData) => void): unknown;
+    on(event: 'close', listener: (code: number, reason: Buffer) => void): unknown;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+    close(code?: number, reason?: string): void;
+}
+export type PassthroughWebSocketFactory = (url: string, headers: Record<string, string>) => PassthroughWebSocket;
+export interface PassthroughSignalRegistrar {
+    (signal: NodeJS.Signals, handler: () => void | Promise<void>): void | (() => void);
+}
+export interface PassthroughStdin {
+    setRawMode?: (mode: boolean) => unknown;
+    isTTY?: boolean;
+    resume(): unknown;
+    pause(): unknown;
+    on(event: 'data', listener: (chunk: Buffer) => void): unknown;
+    off?(event: 'data', listener: (chunk: Buffer) => void): unknown;
+    removeListener?(event: 'data', listener: (chunk: Buffer) => void): unknown;
+}
+export interface PassthroughTerminal {
+    getSize(): {
+        rows: number;
+        cols: number;
+    } | null;
+    onResize(handler: () => void): () => void;
+}
+export interface PassthroughDependencies {
+    readConnectionFile: (stateDir: string) => unknown;
+    getDefaultStateDir: () => string;
+    env: NodeJS.ProcessEnv;
+    createWebSocket: PassthroughWebSocketFactory;
+    writeChunk: (chunk: string) => void;
+    onSignal: PassthroughSignalRegistrar;
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    exit: ExitFn;
+    fetch: typeof globalThis.fetch;
+    captureAndRenderSnapshot: (connection: AttachSnapshotConnection, name: string, deps: AttachSnapshotDeps) => ReturnType<typeof captureAndRenderSnapshot>;
+    stdin: PassthroughStdin;
+    terminal: PassthroughTerminal;
+    /** Opens the SDK PTY input stream used for raw human keystrokes. */
+    openInputStream: (connection: BrokerConnection, name: string) => CliPtyInputStream;
+}
+/** Discriminated union of broker events the `passthrough` client cares
+ *  about. No `delivery_queued` / `agent_pending_drained` — there's no
+ *  queue in passthrough session, so those events (which the broker doesn't
+ *  emit while the worker is in `auto_inject`) would be `other`. */
+export type PassthroughWsEvent = {
+    kind: 'worker_stream';
+    chunk: string;
+} | {
+    kind: 'other';
+};
+/**
+ * Inspect a single WebSocket frame and classify it relative to the
+ * agent we're following. Non-matching / malformed frames return
+ * `{ kind: 'other' }` so the caller can ignore them cheaply.
+ */
+export declare function classifyWsEvent(rawMessage: string, name: string): PassthroughWsEvent;
+/** ----- Keybind state machine ----- */
+export interface PassthroughKeybindOutcome {
+    forward: Buffer;
+    actions: PassthroughKeybindAction[];
+}
+export type PassthroughKeybindAction = 'detach' | 'toggle_help';
+/**
+ * Stateful parser for the passthrough client's keybind vocabulary.
+ * Smaller than `drive`'s because there's no queue to flush — no
+ * `Ctrl+G` binding.
+ *
+ * Semantics:
+ *   - `Ctrl+C` (0x03)    → emit `detach`, never forwarded.
+ *   - `Ctrl+B` (0x02)    → swallow, arm the prefix state.
+ *     Next byte:
+ *       - 'd' / 'D' / 0x04 (Ctrl+D) → emit `detach`.
+ *       - '?'                       → emit `toggle_help`.
+ *       - anything else             → forward `Ctrl+B` + the byte so
+ *                                     TUI apps using `Ctrl+B` themselves
+ *                                     aren't deprived.
+ */
+export declare class PassthroughKeybindParser {
+    private pendingPrefix;
+    feed(chunk: Buffer): PassthroughKeybindOutcome;
+    reset(): void;
+}
+/** ----- Status line rendering ----- */
+/**
+ * Render the bottom-of-terminal status line for `passthrough`. Same
+ * save/restore-cursor trick as `drive`, no pending counter (there
+ * isn't one in passthrough session).
+ */
+export declare function renderStatusLine(opts: {
+    name: string;
+    mode: InboundDeliveryMode;
+    showHelp: boolean;
+    rows?: number;
+}): string;
+/** ----- Main session runner ----- */
+/**
+ * Open a `passthrough` session. Resolves with the exit code the CLI
+ * should propagate. Cleans up its own stdin raw-mode and best-effort
+ * restores the worker's previous inbound delivery mode on any exit path.
+ */
+export declare function runPassthroughSession(agentName: string, options: {
+    brokerUrl?: string;
+    apiKey?: string;
+    stateDir?: string;
+}, deps: PassthroughDependencies): Promise<number>;
+/** Run a passthrough session with default dependencies. Used by `runtime agent attach --mode passthrough`. */
+export declare function attachPassthrough(name: string, options: {
+    brokerUrl?: string;
+    apiKey?: string;
+    stateDir?: string;
+}, overrides?: Partial<PassthroughDependencies>): Promise<number>;
+export {};
+//# sourceMappingURL=attach-passthrough.d.ts.map

package/dist/cli/lib/attach-passthrough.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-passthrough.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/attach-passthrough.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/attach-passthrough.js

@@ -0,0 +1,393 @@
+/**
+ * `agent-relay passthrough <name>` — read-write attach in passthrough session.
+ *
+ * The broker auto-injects inbound relay messages into the agent's PTY
+ * while the human also types; both writers race. That's the point —
+ * passthrough is for observe-and-occasionally-nudge sessions
+ * while the broker does its coordination thing. For exclusive
+ * deterministic control with no auto-inject, use `drive` instead.
+ *
+ * On attach, ensures the worker is in `auto_inject` delivery mode (it's the
+ * broker default, but if someone left a `drive` session the worker may
+ * be in `manual_flush` mode — `passthrough` flips it back for the session's
+ * duration and restores the prior mode on detach). On detach, restores
+ * the prior mode and leaves the agent running.
+ *
+ * The session loop (snapshot-on-attach, raw stdin, resize forwarding,
+ * detach keybind, Ctrl+C-as-detach safety alias) mirrors the shape of
+ * `drive.ts` minus the pending-queue UI and `Ctrl+G` flush binding
+ * (there's no queue in passthrough session). `drive.ts` is the more
+ * heavily-commented version of the shared shape; this module
+ * duplicates rather than abstracts because the trimmed surface is
+ * small enough that an extra layer of indirection would cost more
+ * clarity than it saves.
+ */
+import { Buffer } from 'node:buffer';
+import WebSocket from 'ws';
+import { captureAndRenderSnapshot, captureInitialSnapshot, pickInitialTerminalRows, prepareAttachTarget, switchInboundDeliveryModeOrAbort, syncInitialPtySize, } from '../lib/attach.js';
+import { defaultStateDir, readConnectionFileFromDisk, toWsUrl, } from '../lib/broker-connection.js';
+import { defaultExit, runSignalHandler } from '../lib/exit.js';
+import { openPtyInputStream, resizeWorker, setInboundDeliveryMode, } from './attach-drive.js';
+function withDefaults(overrides = {}) {
+    const fetchFn = overrides.fetch ?? ((input, init) => fetch(input, init));
+    return {
+        readConnectionFile: readConnectionFileFromDisk,
+        getDefaultStateDir: defaultStateDir,
+        env: process.env,
+        createWebSocket: (url, headers) => new WebSocket(url, { headers }),
+        writeChunk: (chunk) => {
+            process.stdout.write(chunk);
+        },
+        onSignal: (signal, handler) => {
+            const listener = () => runSignalHandler(handler);
+            process.on(signal, listener);
+            return () => process.off(signal, listener);
+        },
+        log: (...args) => console.error(...args),
+        error: (...args) => console.error(...args),
+        exit: defaultExit,
+        fetch: fetchFn,
+        captureAndRenderSnapshot,
+        stdin: process.stdin,
+        terminal: {
+            getSize: () => {
+                const stdout = process.stdout;
+                if (!stdout.isTTY)
+                    return null;
+                const rows = stdout.rows;
+                const cols = stdout.columns;
+                if (typeof rows !== 'number' || typeof cols !== 'number')
+                    return null;
+                return { rows, cols };
+            },
+            onResize: (handler) => {
+                process.stdout.on('resize', handler);
+                return () => process.stdout.off('resize', handler);
+            },
+        },
+        openInputStream: (connection, name) => openPtyInputStream(connection, name, fetchFn),
+        ...overrides,
+    };
+}
+/** ----- WS message classification ----- */
+function isStringObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Inspect a single WebSocket frame and classify it relative to the
+ * agent we're following. Non-matching / malformed frames return
+ * `{ kind: 'other' }` so the caller can ignore them cheaply.
+ */
+export function classifyWsEvent(rawMessage, name) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawMessage);
+    }
+    catch {
+        return { kind: 'other' };
+    }
+    if (!isStringObject(parsed))
+        return { kind: 'other' };
+    if (parsed.name !== name)
+        return { kind: 'other' };
+    if (parsed.kind === 'worker_stream') {
+        const chunk = parsed.chunk;
+        if (typeof chunk !== 'string')
+            return { kind: 'other' };
+        return { kind: 'worker_stream', chunk };
+    }
+    return { kind: 'other' };
+}
+/**
+ * Stateful parser for the passthrough client's keybind vocabulary.
+ * Smaller than `drive`'s because there's no queue to flush — no
+ * `Ctrl+G` binding.
+ *
+ * Semantics:
+ *   - `Ctrl+C` (0x03)    → emit `detach`, never forwarded.
+ *   - `Ctrl+B` (0x02)    → swallow, arm the prefix state.
+ *     Next byte:
+ *       - 'd' / 'D' / 0x04 (Ctrl+D) → emit `detach`.
+ *       - '?'                       → emit `toggle_help`.
+ *       - anything else             → forward `Ctrl+B` + the byte so
+ *                                     TUI apps using `Ctrl+B` themselves
+ *                                     aren't deprived.
+ */
+export class PassthroughKeybindParser {
+    pendingPrefix = false;
+    feed(chunk) {
+        const forward = [];
+        const actions = [];
+        for (const byte of chunk) {
+            if (this.pendingPrefix) {
+                this.pendingPrefix = false;
+                if (byte === 0x44 /* 'D' */ || byte === 0x64 /* 'd' */ || byte === 0x04 /* Ctrl+D */) {
+                    actions.push('detach');
+                    continue;
+                }
+                if (byte === 0x3f /* '?' */) {
+                    actions.push('toggle_help');
+                    continue;
+                }
+                forward.push(0x02);
+                forward.push(byte);
+                continue;
+            }
+            if (byte === 0x03 /* Ctrl+C */) {
+                actions.push('detach');
+                continue;
+            }
+            if (byte === 0x02 /* Ctrl+B */) {
+                this.pendingPrefix = true;
+                continue;
+            }
+            forward.push(byte);
+        }
+        return { forward: Buffer.from(forward), actions };
+    }
+    reset() {
+        this.pendingPrefix = false;
+    }
+}
+/** ----- Status line rendering ----- */
+/**
+ * Render the bottom-of-terminal status line for `passthrough`. Same
+ * save/restore-cursor trick as `drive`, no pending counter (there
+ * isn't one in passthrough session).
+ */
+export function renderStatusLine(opts) {
+    const row = Math.max(opts.rows ?? 24, 1);
+    const help = opts.showHelp ? ' | Ctrl+B D detach | Ctrl+B ? hide help' : ' | Ctrl+B D detach';
+    const text = `[passthrough ${opts.name} | delivery=${opts.mode}${help}]`;
+    return `\x1b7\x1b[${row};1H\x1b[2K\x1b[7m${text}\x1b[0m\x1b8`;
+}
+/** ----- Main session runner ----- */
+/**
+ * Open a `passthrough` session. Resolves with the exit code the CLI
+ * should propagate. Cleans up its own stdin raw-mode and best-effort
+ * restores the worker's previous inbound delivery mode on any exit path.
+ */
+export async function runPassthroughSession(agentName, options, deps) {
+    const target = prepareAttachTarget(agentName, options, deps);
+    if (!target)
+        return 1;
+    const { name, connection } = target;
+    // Even when the worker is already in `auto_inject` we still issue the
+    // PUT — it's idempotent on the broker and gives us an early hard
+    // failure on missing-agent before we touch the terminal.
+    const flipResult = await switchInboundDeliveryModeOrAbort(connection, name, 'auto_inject', `ensure '${name}' is in passthrough session`, deps);
+    if (!flipResult)
+        return 1;
+    const { previousMode } = flipResult;
+    const snapshotResult = await captureInitialSnapshot(connection, name, previousMode, 'passthrough', 'attach to', {
+        fetch: deps.fetch,
+        writeChunk: deps.writeChunk,
+        log: deps.log,
+        error: deps.error,
+        captureAndRenderSnapshot: deps.captureAndRenderSnapshot,
+    });
+    if (!snapshotResult)
+        return 1;
+    let showHelp = false;
+    const initialLocalSize = deps.terminal.getSize();
+    let terminalRows = pickInitialTerminalRows(initialLocalSize, snapshotResult.snapshotRows);
+    const paintStatus = () => {
+        deps.writeChunk(renderStatusLine({ name, mode: 'auto_inject', showHelp, rows: terminalRows }));
+    };
+    paintStatus();
+    await syncInitialPtySize(connection, name, initialLocalSize, 'passthrough', deps);
+    const wsUrl = toWsUrl(connection.url);
+    const headers = {};
+    if (connection.apiKey) {
+        headers['X-API-Key'] = connection.apiKey;
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let rawModeWasSet = false;
+        let unsubscribeResize = null;
+        const parser = new PassthroughKeybindParser();
+        let inputStream = null;
+        const cleanupSignals = [];
+        const resizeHandler = () => {
+            const size = deps.terminal.getSize();
+            if (!size)
+                return;
+            terminalRows = size.rows;
+            void resizeWorker(connection, name, size.rows, size.cols, deps.fetch).then((res) => {
+                if (!res.ok) {
+                    deps.log(`[passthrough] resize forward failed: ${res.message ?? 'unknown error'}`);
+                }
+            });
+            paintStatus();
+        };
+        const stdinDataHandler = (chunk) => {
+            const outcome = parser.feed(chunk);
+            if (outcome.forward.length > 0) {
+                const stream = inputStream;
+                if (!stream) {
+                    deps.log('[passthrough] input stream is not ready');
+                    return;
+                }
+                void stream.send(outcome.forward.toString('utf-8')).catch((err) => {
+                    if (settled)
+                        return;
+                    const message = err instanceof Error ? err.message : String(err);
+                    deps.log(`[passthrough] input stream send failed: ${message}`);
+                });
+            }
+            for (const action of outcome.actions) {
+                switch (action) {
+                    case 'detach':
+                        finish(0);
+                        return;
+                    case 'toggle_help':
+                        showHelp = !showHelp;
+                        paintStatus();
+                        break;
+                }
+            }
+        };
+        const teardownStdin = () => {
+            try {
+                if (deps.stdin.off) {
+                    deps.stdin.off('data', stdinDataHandler);
+                }
+                else if (deps.stdin.removeListener) {
+                    deps.stdin.removeListener('data', stdinDataHandler);
+                }
+            }
+            catch {
+                // best effort
+            }
+            try {
+                if (rawModeWasSet && typeof deps.stdin.setRawMode === 'function') {
+                    deps.stdin.setRawMode(false);
+                }
+            }
+            catch {
+                // best effort
+            }
+            try {
+                deps.stdin.pause();
+            }
+            catch {
+                // best effort
+            }
+            try {
+                if (unsubscribeResize) {
+                    unsubscribeResize();
+                    unsubscribeResize = null;
+                }
+            }
+            catch {
+                // best effort
+            }
+            rawModeWasSet = false;
+        };
+        const closeInputStream = () => {
+            const stream = inputStream;
+            inputStream = null;
+            if (!stream)
+                return;
+            try {
+                stream.close(1000, 'passthrough client exiting');
+            }
+            catch {
+                // best effort
+            }
+        };
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            for (const cleanup of cleanupSignals.splice(0)) {
+                try {
+                    cleanup();
+                }
+                catch {
+                    // best effort
+                }
+            }
+            teardownStdin();
+            closeInputStream();
+            try {
+                socket.close(1000, 'passthrough client exiting');
+            }
+            catch {
+                // best effort
+            }
+            // Restore the worker's previous mode (no-op if it was already
+            // auto-inject, which is the common case).
+            void setInboundDeliveryMode(connection, name, previousMode ?? 'auto_inject', deps.fetch).finally(() => {
+                resolve(code);
+            });
+        };
+        const socket = deps.createWebSocket(wsUrl, headers);
+        const openInputStreamAndTakeStdin = async () => {
+            try {
+                inputStream = deps.openInputStream(connection, name);
+                await inputStream.waitUntilOpen();
+                if (settled) {
+                    closeInputStream();
+                    return;
+                }
+                if (typeof deps.stdin.setRawMode === 'function' && deps.stdin.isTTY !== false) {
+                    deps.stdin.setRawMode(true);
+                    rawModeWasSet = true;
+                }
+                deps.stdin.resume();
+                deps.stdin.on('data', stdinDataHandler);
+                unsubscribeResize = deps.terminal.onResize(resizeHandler);
+            }
+            catch (err) {
+                if (settled)
+                    return;
+                const message = err instanceof Error ? err.message : String(err);
+                deps.error(`[passthrough] could not open PTY input stream: ${message}`);
+                finish(1);
+            }
+        };
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            const cleanup = deps.onSignal(signal, () => finish(0));
+            if (typeof cleanup === 'function')
+                cleanupSignals.push(cleanup);
+        }
+        socket.on('open', () => {
+            deps.log(`[passthrough] attached to ${name} via ${connection.url} (Ctrl+B D to detach)`);
+            void openInputStreamAndTakeStdin();
+        });
+        socket.on('message', (data) => {
+            const text = typeof data === 'string' ? data : Buffer.isBuffer(data) ? data.toString('utf-8') : String(data);
+            const event = classifyWsEvent(text, name);
+            switch (event.kind) {
+                case 'worker_stream':
+                    deps.writeChunk(event.chunk);
+                    paintStatus();
+                    break;
+                case 'other':
+                    break;
+            }
+        });
+        socket.on('error', (err) => {
+            deps.error(`[passthrough] WebSocket error: ${err.message}`);
+            finish(1);
+        });
+        socket.on('close', (code, reason) => {
+            if (settled)
+                return;
+            const reasonText = reason && reason.length > 0 ? reason.toString('utf-8') : '';
+            if (code === 1000 || code === 1005) {
+                finish(0);
+            }
+            else {
+                deps.error(`[passthrough] connection closed (code: ${code}${reasonText ? `, reason: ${reasonText}` : ''})`);
+                finish(1);
+            }
+        });
+    });
+}
+/** Run a passthrough session with default dependencies. Used by `runtime agent attach --mode passthrough`. */
+export function attachPassthrough(name, options, overrides = {}) {
+    return runPassthroughSession(name, options, withDefaults(overrides));
+}
+//# sourceMappingURL=attach-passthrough.js.map

package/dist/cli/lib/attach-passthrough.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-passthrough.js","sourceRoot":"","sources":["../../../src/cli/lib/attach-passthrough.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/attach-view.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `agent-relay view <name>` — read-only PTY stream client.
+ *
+ * Connects to a running broker's `/ws` WebSocket, filters the event stream
+ * for `worker_stream` frames matching the requested agent name, and writes
+ * each chunk's raw bytes to stdout (preserving ANSI escapes).
+ *
+ * No keystrokes are forwarded — the broker keeps doing whatever it's doing.
+ * Ctrl+C exits the client cleanly; the agent keeps running under the broker.
+ */
+import WebSocket from 'ws';
+import { captureAndRenderSnapshot, type AttachSnapshotConnection, type AttachSnapshotDeps } from '../lib/attach.js';
+type ExitFn = (code: number) => never;
+/** Subset of the broker's `BrokerEvent` we actually care about for `view`. */
+export interface ViewableWorkerStreamEvent {
+    kind: 'worker_stream';
+    name: string;
+    stream: string;
+    chunk: string;
+}
+/** Connection metadata discovered from `connection.json` or CLI/env overrides. */
+export interface ViewBrokerConnection {
+    url: string;
+    apiKey?: string;
+}
+export interface ViewWebSocket {
+    on(event: 'open', listener: () => void): unknown;
+    on(event: 'message', listener: (data: WebSocket.RawData) => void): unknown;
+    on(event: 'close', listener: (code: number, reason: Buffer) => void): unknown;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+    close(code?: number, reason?: string): void;
+}
+export type ViewWebSocketFactory = (url: string, headers: Record<string, string>) => ViewWebSocket;
+export interface ViewSignalRegistrar {
+    (signal: NodeJS.Signals, handler: () => void | Promise<void>): void | (() => void);
+}
+export interface ViewDependencies {
+    /** Reads `<state-dir>/connection.json` and returns parsed JSON, or null. */
+    readConnectionFile: (stateDir: string) => unknown;
+    /** Project paths helper — used to pick the default state dir. */
+    getDefaultStateDir: () => string;
+    /** Environment variables (so tests can inject). */
+    env: NodeJS.ProcessEnv;
+    /** Factory for the WebSocket — overridden in tests with a mock. */
+    createWebSocket: ViewWebSocketFactory;
+    /** Where the PTY chunks get written. Defaults to `process.stdout.write`. */
+    writeChunk: (chunk: string) => void;
+    /** Signal registration (so tests can drive SIGINT without killing the test). */
+    onSignal: ViewSignalRegistrar;
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    exit: ExitFn;
+    /** HTTP client used by the snapshot-on-attach call. Defaults to global `fetch`. */
+    fetch: typeof globalThis.fetch;
+    /** Override for the snapshot-on-attach helper (tests substitute a stub). */
+    captureAndRenderSnapshot: (connection: AttachSnapshotConnection, agentName: string, deps: AttachSnapshotDeps) => ReturnType<typeof captureAndRenderSnapshot>;
+}
+/**
+ * Resolve the broker connection to use for `view`, in priority order:
+ *
+ *  1. `--broker-url` / `--api-key` CLI flags
+ *  2. `RELAY_BROKER_URL` / `RELAY_BROKER_API_KEY` environment variables
+ *  3. `<state-dir>/connection.json` (default `.agentworkforce/relay/connection.json`)
+ *
+ * Matches the resolution order used by `agent-relay-broker dump-pty` so users
+ * don't have to learn two patterns.
+ */
+export declare function resolveViewBrokerConnection(options: {
+    brokerUrl?: string;
+    apiKey?: string;
+    stateDir?: string;
+}, deps: ViewDependencies): ViewBrokerConnection | null;
+/** Convert an `http(s)://host:port` base URL to the matching `ws(s)://…/ws`. */
+export declare function toWsUrl(baseUrl: string): string;
+/**
+ * Inspect a single WebSocket message and, if it's a `worker_stream` event for
+ * the requested agent, return the raw chunk string. Returns `null` for events
+ * that don't match (other kinds, other agents, malformed JSON, etc.) so the
+ * caller can ignore them.
+ *
+ * Exported for unit testing the filter in isolation from any WebSocket.
+ */
+export declare function extractMatchingChunk(rawMessage: string, agentName: string): string | null;
+/**
+ * Open the read-only view stream and run until the WebSocket closes, the
+ * caller signals SIGINT/SIGTERM, or an unrecoverable error occurs. Resolves
+ * with the exit code the CLI should propagate.
+ */
+export declare function runViewSession(agentName: string, options: {
+    brokerUrl?: string;
+    apiKey?: string;
+    stateDir?: string;
+}, deps: ViewDependencies): Promise<number>;
+/** Run a view session with default dependencies. Used by `runtime agent attach --mode view`. */
+export declare function attachView(name: string, options: {
+    brokerUrl?: string;
+    apiKey?: string;
+    stateDir?: string;
+}, overrides?: Partial<ViewDependencies>): Promise<number>;
+export {};
+//# sourceMappingURL=attach-view.d.ts.map