agent-relay 6.0.21 → 6.2.0

package/dist/src/cli/commands/drive.d.ts

@@ -0,0 +1,222 @@
+/**
+ * `agent-relay drive <name>` — interactive read-write take-over client.
+ *
+ * Attaches to a running agent, flips it into `manual_flush` inbound delivery mode so the
+ * broker parks new relay messages in a per-worker queue, and forwards your
+ * keystrokes to the worker's PTY. You can drain the queue on demand with
+ * `Ctrl+G` and detach with `Ctrl+B D` (or `Ctrl+C` as a safety alias).
+ * Detaching restores the worker's previous inbound delivery mode and leaves the
+ * agent running under the broker — `drive` never kills the worker.
+ *
+ * Sequence of operations on attach:
+ *
+ *   1. Discover broker connection (CLI flag → env → connection.json).
+ *   2. `GET  /api/spawned/{name}/delivery-mode`  → remember the previous mode.
+ *   3. `PUT  /api/spawned/{name}/delivery-mode`  → switch to `manual_flush`.
+ *   4. `captureAndRenderSnapshot`       → repaint the agent's current screen.
+ *   5. `GET  /api/spawned/{name}/pending` → seed the status-line counter.
+ *   6. Open `/ws`, subscribe to events for this worker.
+ *   7. Switch local stdin to raw mode; forward bytes to `POST /api/input/{name}`.
+ *
+ * On detach (clean or abnormal), best-effort `PUT .../delivery-mode` restores the
+ * previous mode so the queue doesn't fill up indefinitely.
+ */
+import { Buffer } from 'node:buffer';
+import type { InboundDeliveryMode } from '@agent-relay/sdk';
+import { Command } from 'commander';
+import WebSocket from 'ws';
+import { captureAndRenderSnapshot, type AttachSnapshotConnection, type AttachSnapshotDeps } from '../lib/attach.js';
+import { type BrokerConnection } from '../lib/broker-connection.js';
+type ExitFn = (code: number) => never;
+/** Wire string for the broker's `InboundDeliveryMode` enum. */
+export type { InboundDeliveryMode };
+/** Minimal WebSocket surface we depend on — same shape as `view`'s. */
+export interface DriveWebSocket {
+    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 DriveWebSocketFactory = (url: string, headers: Record<string, string>) => DriveWebSocket;
+export interface DriveSignalRegistrar {
+    (signal: NodeJS.Signals, handler: () => void | Promise<void>): void;
+}
+/** Stdin surface — tests provide a fake that never touches the real TTY. */
+export interface DriveStdin {
+    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;
+}
+/**
+ * Local terminal-size source. Wraps `process.stdout` in production so
+ * the resize wiring reads the user's actual terminal dimensions and
+ * gets a SIGWINCH-equivalent `'resize'` event for free. Tests inject a
+ * controllable fake.
+ */
+export interface DriveTerminal {
+    /** Current `(rows, cols)`. Returns `null` when stdout is not a TTY,
+     *  in which case resize forwarding is skipped entirely. */
+    getSize(): {
+        rows: number;
+        cols: number;
+    } | null;
+    /** Subscribe to local-terminal resize events. Returns an unsubscribe
+     *  function the client calls during teardown. */
+    onResize(handler: () => void): () => void;
+}
+export interface DriveDependencies {
+    /** 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: DriveWebSocketFactory;
+    /** 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: DriveSignalRegistrar;
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    exit: ExitFn;
+    /** HTTP client used for mode/pending/flush/input calls. Defaults to global `fetch`. */
+    fetch: typeof globalThis.fetch;
+    /** Override for the snapshot-on-attach helper (tests substitute a stub). */
+    captureAndRenderSnapshot: (connection: AttachSnapshotConnection, name: string, deps: AttachSnapshotDeps) => ReturnType<typeof captureAndRenderSnapshot>;
+    /** Stdin handle — defaults to `process.stdin`. */
+    stdin: DriveStdin;
+    /** Local terminal size source — defaults to `process.stdout`. */
+    terminal: DriveTerminal;
+}
+/** ----- HTTP helpers ----- */
+/** `GET /api/spawned/{name}/delivery-mode` → `'manual_flush' | 'auto_inject'` or `null` on failure. */
+export declare function getInboundDeliveryMode(connection: BrokerConnection, name: string, fetchFn: typeof globalThis.fetch): Promise<InboundDeliveryMode | null>;
+/** Outcome of a `PUT /api/spawned/{name}/delivery-mode` call. */
+export interface SetInboundDeliveryModeResult {
+    ok: boolean;
+    status: number;
+    /** Server-reported number of pending messages drained on a `manual_flush→auto_inject` flip. */
+    flushed?: number;
+    /** Human-readable error message when `ok` is false. */
+    message?: string;
+}
+export declare function setInboundDeliveryMode(connection: BrokerConnection, name: string, mode: InboundDeliveryMode, fetchFn: typeof globalThis.fetch): Promise<SetInboundDeliveryModeResult>;
+/** `GET /api/spawned/{name}/pending` → count, or `0` on failure (best-effort). */
+export declare function getPendingCount(connection: BrokerConnection, name: string, fetchFn: typeof globalThis.fetch): Promise<number>;
+/** `POST /api/spawned/{name}/flush` → server returns `{ flushed: N }`. */
+export declare function flushPending(connection: BrokerConnection, name: string, fetchFn: typeof globalThis.fetch): Promise<{
+    ok: boolean;
+    flushed?: number;
+    message?: string;
+}>;
+/** `POST /api/input/{name}` body `{ data: "<bytes>" }`. */
+export declare function sendInput(connection: BrokerConnection, name: string, data: string, fetchFn: typeof globalThis.fetch): Promise<{
+    ok: boolean;
+    message?: string;
+}>;
+/**
+ * `POST /api/resize/{name}` body `{ rows, cols }`. Forwards the
+ * driver's local terminal dimensions so the agent's PTY (and any TUI
+ * running in it) sees the size the human is actually looking at.
+ * Called once on attach and again on every local-terminal resize.
+ */
+export declare function resizeWorker(connection: BrokerConnection, name: string, rows: number, cols: number, fetchFn: typeof globalThis.fetch): Promise<{
+    ok: boolean;
+    message?: string;
+}>;
+/** Discriminated union of the broker events `drive` cares about. */
+export type DriveWsEvent = {
+    kind: 'worker_stream';
+    chunk: string;
+} | {
+    kind: 'delivery_queued';
+} | {
+    kind: 'agent_pending_drained';
+    count?: number;
+} | {
+    kind: 'other';
+};
+/**
+ * Inspect a single WebSocket frame and classify it relative to the agent
+ * we're driving. Non-matching / malformed frames return `{ kind: 'other' }`
+ * so the caller can ignore them cheaply.
+ *
+ * Exported for unit testing the filter in isolation.
+ */
+export declare function classifyWsEvent(rawMessage: string, name: string): DriveWsEvent;
+/** ----- Keybind state machine ----- */
+/** Outcome of feeding one chunk to the keybind parser. */
+export interface KeybindOutcome {
+    /** Bytes that should be forwarded to the agent (may be empty). */
+    forward: Buffer;
+    /** Local actions the client should perform, in order. */
+    actions: KeybindAction[];
+}
+export type KeybindAction = 'flush' | 'detach' | 'toggle_help';
+/**
+ * Stateful parser that recognises the `Ctrl+B <key>` two-byte prefix
+ * sequence, plus the single-byte safety keybinds (`Ctrl+G` flush,
+ * `Ctrl+C` detach).
+ *
+ * The parser is intentionally tiny — no readline, no keypress — because
+ * the keybinds are all ASCII control characters, and pulling in a
+ * keypress parser would just add a dependency for no real benefit.
+ *
+ * Semantics:
+ *   - `Ctrl+G` (0x07)    → emit `flush`, never forwarded.
+ *   - `Ctrl+C` (0x03)    → emit `detach`, never forwarded.
+ *   - `Ctrl+B` (0x02)    → swallow, arm the prefix state.
+ *     Next byte (within the same chunk OR a subsequent chunk):
+ *       - 'd' / 'D' / 0x04 (Ctrl+D) → emit `detach`.
+ *       - '?'                       → emit `toggle_help`.
+ *       - anything else             → forward the original `Ctrl+B` byte
+ *                                     followed by the new byte, so the
+ *                                     agent isn't deprived if the user
+ *                                     hit Ctrl+B by accident.
+ *
+ * Multiple keybinds in one chunk are handled in order; bytes between
+ * them are forwarded normally.
+ */
+export declare class KeybindParser {
+    private pendingPrefix;
+    /** Process one chunk; returns bytes to forward + actions to take. */
+    feed(chunk: Buffer): KeybindOutcome;
+    /** Reset the parser (e.g. before tearing down). */
+    reset(): void;
+}
+/** ----- Status line rendering ----- */
+/**
+ * Render the bottom-of-terminal status line for `drive`. Uses ANSI
+ * save-cursor / restore-cursor so the agent's output isn't disturbed.
+ *
+ * Exported for unit testing — `runDriveSession` calls it on every
+ * pending-count change.
+ */
+export declare function renderStatusLine(opts: {
+    name: string;
+    mode: InboundDeliveryMode;
+    pending: number;
+    showHelp: boolean;
+    /** Terminal rows — defaults to 24 if unknown. The status line lands on row N. */
+    rows?: number;
+}): string;
+/** ----- Main session runner ----- */
+/**
+ * Open a `drive` 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 runDriveSession(agentName: string, options: {
+    brokerUrl?: string;
+    apiKey?: string;
+    stateDir?: string;
+}, deps: DriveDependencies): Promise<number>;
+/** Register `agent-relay drive <name>` on the supplied commander program. */
+export declare function registerDriveCommands(program: Command, overrides?: Partial<DriveDependencies>): void;
+//# sourceMappingURL=drive.d.ts.map

package/dist/src/cli/commands/drive.d.ts.map

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