@phnx-labs/agents-cli 1.20.64 → 1.20.65

package/dist/lib/secrets/remote.js

@@ -21,7 +21,36 @@ import { emit } from '../events.js';
 import { sshTargetFor } from '../hosts/types.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { isLoaderOrInterpreterEnv } from './bundles.js';
 const REMOTE_TIMEOUT_MS = 30_000;
+/**
+ * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
+ * is untrusted input: a compromised or misconfigured host could return keys that
+ * silently reshape THIS process's behavior once merged into the agent env
+ * (bundles.ts:251 `sanitizeProcessEnv` only strips loader vars from process.env,
+ * never the remote bundle). Block the dangerous-override classes here — at the
+ * source — so every consumer (`run --secrets b@host`, `secrets exec --host`) is
+ * protected, not just one call site:
+ *   - LD_* / DYLD_* / NODE_OPTIONS and the other loader/interpreter injections
+ *     (reuses the canonical bundles.ts predicate);
+ *   - GIT_*        — GIT_SSH_COMMAND et al. hijack every git subprocess;
+ *   - *_PROXY      — HTTP(S)_PROXY / ALL_PROXY reroute outbound traffic (MITM);
+ *   - *_BASE_URL   — ANTHROPIC_BASE_URL / OPENAI_BASE_URL redirect the model API.
+ * These keys are already rejected on the ADD side (validateEnvKey for loaders),
+ * so a legitimate bundle never carries them — only a hostile peer would.
+ */
+export function isDangerousRemoteEnvKey(name) {
+    const upper = name.toUpperCase();
+    if (isLoaderOrInterpreterEnv(upper))
+        return true;
+    if (upper.startsWith('GIT_'))
+        return true;
+    if (upper.endsWith('_PROXY'))
+        return true;
+    if (upper.endsWith('_BASE_URL'))
+        return true;
+    return false;
+}
 /** Remote OS for a host name or target string. Prefer the original host name
  * because enrolled inline hosts resolve to `user@address`, while the OS
  * registry is keyed by the host name. */
@@ -153,9 +182,20 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
         throw new Error(`Unexpected payload resolving '${bundle}' on ${target}.`);
     }
     const env = {};
+    const blocked = [];
     for (const [k, v] of Object.entries(parsed)) {
+        // Drop dangerous-override keys returned by the (untrusted) peer before they
+        // can reshape this process — see isDangerousRemoteEnvKey.
+        if (isDangerousRemoteEnvKey(k)) {
+            blocked.push(k);
+            continue;
+        }
         env[k] = typeof v === 'string' ? v : String(v);
     }
+    if (blocked.length > 0) {
+        process.stderr.write(`[secrets] Dropped ${blocked.length} dangerous key(s) from '${bundle}'@${target} ` +
+            `(remote override blocked): ${blocked.join(', ')}\n`);
+    }
     // The remote host audits its own `secrets export` read; this emit records the
     // event on the INITIATING host too (values were pulled into this process and
     // injected locally). Covers `secrets exec --host` and `run --secrets b@host`.

package/dist/lib/self-update.d.ts

@@ -83,6 +83,26 @@ export declare function installPackageIntoPrefix(spec: string, prefix: string):
  * package's postinstall hook.
  */
 export declare function installPackageWithBun(spec: string): Promise<void>;
+/**
+ * Verify a downloaded tarball's bytes against a Subresource Integrity (SRI)
+ * string of the form `sha512-<base64>` — npm's `dist.integrity`. Recomputes the
+ * digest over the actual bytes with the named algorithm and compares it, in
+ * constant time, to the decoded expected digest.
+ *
+ * Fails closed: a malformed SRI, an algorithm weaker than sha512, or any digest
+ * mismatch throws. This is the gate that makes self-update refuse a tampered or
+ * corrupted tarball *before* it is ever handed to a package manager to install.
+ */
+export declare function verifyTarballIntegrity(tarball: Buffer, integrity: string): void;
+/**
+ * Download the published tarball at `tarballUrl` and prove its bytes match
+ * `integrity` before returning a path to it on disk. The returned .tgz is safe
+ * to hand to `npm install`/`bun add` — it has been verified byte-for-byte
+ * against the registry attestation. Fails closed: a non-200, a download error,
+ * or a hash mismatch throws and no file path is returned, so the caller never
+ * installs an unverified artifact.
+ */
+export declare function downloadVerifiedTarball(tarballUrl: string, integrity: string, timeoutMs?: number): Promise<string>;
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export declare function readInstalledVersion(packageRoot: string): string;
 /**

package/dist/lib/self-update.js

@@ -14,6 +14,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { createHash, timingSafeEqual } from 'crypto';
 import { spawnSync } from 'child_process';
 import { compareVersions } from './versions.js';
 import { needsWindowsShell } from './platform/index.js';
@@ -164,7 +165,59 @@ export async function installPackageWithBun(spec) {
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
     // On Windows `bun` resolves to `bun.exe`/`bun.cmd`; force shell for the .cmd case.
-    await execFileAsync('bun', ['add', '-g', spec], { shell: needsWindowsShell('bun') });
+    // --ignore-scripts: the tarball has already been integrity-verified, but its
+    // lifecycle scripts must not run at install time (the caller refreshes shims
+    // explicitly via refreshAliasShims()) — same fail-closed posture as the npm path.
+    await execFileAsync('bun', ['add', '-g', spec, '--ignore-scripts'], { shell: needsWindowsShell('bun') });
+}
+/**
+ * Verify a downloaded tarball's bytes against a Subresource Integrity (SRI)
+ * string of the form `sha512-<base64>` — npm's `dist.integrity`. Recomputes the
+ * digest over the actual bytes with the named algorithm and compares it, in
+ * constant time, to the decoded expected digest.
+ *
+ * Fails closed: a malformed SRI, an algorithm weaker than sha512, or any digest
+ * mismatch throws. This is the gate that makes self-update refuse a tampered or
+ * corrupted tarball *before* it is ever handed to a package manager to install.
+ */
+export function verifyTarballIntegrity(tarball, integrity) {
+    const dash = integrity.indexOf('-');
+    if (dash <= 0) {
+        throw new Error(`malformed integrity string: ${JSON.stringify(integrity)}`);
+    }
+    const algorithm = integrity.slice(0, dash);
+    const expectedBase64 = integrity.slice(dash + 1);
+    // npm publishes sha512 SRI; refuse to verify against anything weaker rather
+    // than silently accepting a downgraded (e.g. sha1) attestation.
+    if (algorithm !== 'sha512') {
+        throw new Error(`unsupported integrity algorithm '${algorithm}' (expected sha512)`);
+    }
+    const expected = Buffer.from(expectedBase64, 'base64');
+    const actual = createHash('sha512').update(tarball).digest();
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+        throw new Error(`integrity check failed: tarball hash sha512-${actual.toString('base64')} ` +
+            `does not match expected ${integrity}`);
+    }
+}
+/**
+ * Download the published tarball at `tarballUrl` and prove its bytes match
+ * `integrity` before returning a path to it on disk. The returned .tgz is safe
+ * to hand to `npm install`/`bun add` — it has been verified byte-for-byte
+ * against the registry attestation. Fails closed: a non-200, a download error,
+ * or a hash mismatch throws and no file path is returned, so the caller never
+ * installs an unverified artifact.
+ */
+export async function downloadVerifiedTarball(tarballUrl, integrity, timeoutMs = 60_000) {
+    const response = await fetch(tarballUrl, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) {
+        throw new Error(`could not download tarball from ${tarballUrl} (HTTP ${response.status})`);
+    }
+    const tarball = Buffer.from(await response.arrayBuffer());
+    verifyTarballIntegrity(tarball, integrity);
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-cli-upgrade-'));
+    const file = path.join(dir, path.basename(new URL(tarballUrl).pathname) || 'package.tgz');
+    fs.writeFileSync(file, tarball);
+    return file;
 }
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export function readInstalledVersion(packageRoot) {

package/dist/lib/serve/control.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Authenticated `agents serve --control` server — the "anchor" the iOS/iPadOS
+ * cockpit talks to (RUSH-1731).
+ *
+ * It is the read-only {@link handleServeGet} surface plus a small mutation API,
+ * gated by a bearer token ({@link verifyControlToken}) on EVERY request because,
+ * unlike plain `agents serve`, this variant may bind beyond loopback (a tailnet
+ * address) so the phone can reach it. It adds no new execution machinery: a run
+ * request re-invokes the same `agents run` the CLI uses (inheriting host
+ * offload, secrets, detached dispatch), and a message re-invokes `agents
+ * message`. The server generates the run's session id so the run is immediately
+ * addressable for streaming (Phase 2) and steering.
+ *
+ * Both side-effecting operations are behind DI seams ({@link ControlOptions})
+ * so tests drive them without spawning real agents — mirroring the `snapshot`
+ * seam on the read-only server.
+ */
+import type http from 'http';
+import type { StdioOptions } from 'child_process';
+import { type ServeOptions } from './server.js';
+/** A request to start an agent run on this anchor (local or offloaded). */
+export interface RunRequest {
+    /** Agent to run: 'claude' | 'codex' | 'gemini' | … */
+    agent: string;
+    /** Headless prompt. */
+    prompt: string;
+    /** Permission mode: plan | edit | auto | skip. Defaults to the CLI default. */
+    mode?: string;
+    /** Offload onto a registered device / host (the executor). Omit → run on the anchor. */
+    host?: string;
+    /** Working directory (on the host when `host` is set). */
+    cwd?: string;
+}
+/** Identifiers by which the started run can later be streamed / messaged. */
+export interface RunResult {
+    /** Addressable session id (a UUID for claude; otherwise equals `name`). */
+    sessionId: string;
+    /** Durable run name seeded into the session label. */
+    name: string;
+}
+/** Starts a run and returns its addressable ids. */
+export type RunDispatcher = (req: RunRequest) => Promise<RunResult>;
+/** Delivers a message to a running/parked agent by id. */
+export type Messenger = (id: string, text: string, from?: string) => Promise<void>;
+export interface ControlOptions extends ServeOptions {
+    /** Bearer verifier. Defaults to {@link verifyControlToken}. */
+    verifyToken?: (presented: string | undefined) => boolean;
+    /** Run starter. Defaults to spawning `agents run …` detached. */
+    runner?: RunDispatcher;
+    /** Message sender. Defaults to spawning `agents message …`. */
+    messenger?: Messenger;
+    /** Poll cadence (ms) for the session event stream. Defaults to 300. */
+    streamPollMs?: number;
+    /** Resolve a session id to its NDJSON capture file. Defaults to {@link streamLogPath}. */
+    streamLogPathFor?: (sessionId: string) => string;
+}
+/**
+ * SSE stream of a session's normalized NDJSON events, offset-tailed from its
+ * capture file. Resumes from `?offset=<bytes>` or the `Last-Event-ID` header
+ * (each event's `id:` is its exact byte offset, so resume neither loses nor
+ * duplicates). Closes when a terminal (`result`/`error`) event is seen or the
+ * client disconnects. A not-yet-created file simply yields nothing until the
+ * run starts writing — the phone can open the stream the instant it dispatches.
+ */
+export declare function startSessionStream(file: string, req: http.IncomingMessage, res: http.ServerResponse, pollMs: number): void;
+/**
+ * Spawn a detached child and settle once it has either successfully spawned or
+ * failed to. Attaching an `'error'` listener is mandatory: a `ChildProcess` is
+ * an `EventEmitter`, so an `'error'` event (e.g. ENOENT from a stale/missing
+ * `agents` binary — a real condition `validateDaemonBinary` guards against)
+ * with no listener throws and would take down the whole anchor process, not
+ * just the one request. Mirrors the `once('spawn') / once('error')` pattern in
+ * `teams/agents.ts`. The `'error'` listener registered by `once` survives after
+ * a successful spawn, so a later error is absorbed rather than crashing.
+ */
+export declare function spawnDetached(command: string, args: string[], stdio?: StdioOptions): Promise<void>;
+/**
+ * Default run dispatcher: re-invoke `agents run` with a server-minted id so the
+ * run is addressable, detached so it outlives this request (and the anchor
+ * process). Local runs detach here; `--host` runs detach on the executor via
+ * the existing dispatch path.
+ */
+export declare const defaultRunner: RunDispatcher;
+/** Default messenger: re-invoke `agents message <id> <text>` and await its exit. */
+export declare const defaultMessenger: Messenger;
+/**
+ * Create (but do not start) the authenticated control server. Caller invokes
+ * `.listen(port, bind)`.
+ */
+export declare function createControlServer(opts?: ControlOptions): http.Server;
+/** Start the control server on `port`, bound to `bind`. Resolves the bound port. */
+export declare function startControlServer(port: number, bind: string, opts?: ControlOptions): Promise<{
+    server: http.Server;
+    port: number;
+}>;

package/dist/lib/serve/control.js

@@ -0,0 +1,260 @@
+import { createServer } from 'http';
+import fs from 'fs';
+import { spawn } from 'child_process';
+import { randomUUID, randomBytes } from 'crypto';
+import { getAgentsInvocation } from '../daemon.js';
+import { handleServeGet, resolveServeContext } from './server.js';
+import { verifyControlToken } from './token.js';
+import { readNewEvents, streamDir, streamLogPath } from './stream.js';
+const MAX_BODY_BYTES = 64 * 1024;
+const DEFAULT_STREAM_POLL_MS = 300;
+/** Pull the presented bearer token from either header form. */
+function presentedToken(req) {
+    const auth = req.headers['authorization'];
+    if (typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ')) {
+        return auth.slice(7).trim();
+    }
+    const x = req.headers['x-agents-token'];
+    return typeof x === 'string' ? x.trim() : undefined;
+}
+/** Read a JSON request body with a hard size cap. Rejects on overflow/parse error. */
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error('request body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf-8').trim();
+            if (!raw)
+                return resolve({});
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                reject(new Error('invalid JSON body'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+function sendJson(res, code, obj) {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(obj));
+}
+/**
+ * SSE stream of a session's normalized NDJSON events, offset-tailed from its
+ * capture file. Resumes from `?offset=<bytes>` or the `Last-Event-ID` header
+ * (each event's `id:` is its exact byte offset, so resume neither loses nor
+ * duplicates). Closes when a terminal (`result`/`error`) event is seen or the
+ * client disconnects. A not-yet-created file simply yields nothing until the
+ * run starts writing — the phone can open the stream the instant it dispatches.
+ */
+export function startSessionStream(file, req, res, pollMs) {
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+    });
+    const params = new URL(req.url ?? '/', 'http://anchor').searchParams;
+    const qOffset = Number.parseInt(params.get('offset') ?? '', 10);
+    const lastId = Number.parseInt(Array.isArray(req.headers['last-event-id'])
+        ? req.headers['last-event-id'][0]
+        : req.headers['last-event-id'] ?? '', 10);
+    // Clamp at the source: a negative/garbage offset (or Last-Event-ID) is
+    // meaningless and, worse, `Buffer.subarray(neg)` indexes from the END — so an
+    // unclamped negative offset would read nothing and never self-correct. A bad
+    // resume value replays from the start, the EventSource-friendly behavior.
+    const wanted = Number.isFinite(qOffset) ? qOffset : Number.isFinite(lastId) ? lastId : 0;
+    let offset = Math.max(0, wanted);
+    let closed = false;
+    let timer;
+    const stop = () => {
+        closed = true;
+        if (timer)
+            clearInterval(timer);
+    };
+    req.on('close', stop);
+    const tick = () => {
+        if (closed)
+            return;
+        const { events, newOffset, done } = readNewEvents(file, offset);
+        for (const { event, offset: at } of events) {
+            // `at` is the per-event resume point the CLIENT echoes as Last-Event-ID.
+            res.write(`id: ${at}\nevent: ${event.type}\ndata: ${JSON.stringify(event.raw)}\n\n`);
+        }
+        // The SERVER cursor always adopts newOffset — past every complete line,
+        // including trailing blank/non-JSON lines after the last event — so the
+        // stream always makes progress (even on an empty read) and never re-scans.
+        offset = newOffset;
+        if (done && !closed) {
+            res.write('event: end\ndata: {"ok":true}\n\n');
+            stop();
+            res.end();
+        }
+    };
+    tick(); // immediate catch-up from the resume offset
+    if (!closed)
+        timer = setInterval(tick, pollMs);
+}
+/**
+ * Spawn a detached child and settle once it has either successfully spawned or
+ * failed to. Attaching an `'error'` listener is mandatory: a `ChildProcess` is
+ * an `EventEmitter`, so an `'error'` event (e.g. ENOENT from a stale/missing
+ * `agents` binary — a real condition `validateDaemonBinary` guards against)
+ * with no listener throws and would take down the whole anchor process, not
+ * just the one request. Mirrors the `once('spawn') / once('error')` pattern in
+ * `teams/agents.ts`. The `'error'` listener registered by `once` survives after
+ * a successful spawn, so a later error is absorbed rather than crashing.
+ */
+export function spawnDetached(command, args, stdio = 'ignore') {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { detached: true, stdio, env: process.env });
+        child.once('spawn', () => {
+            child.unref();
+            resolve();
+        });
+        child.once('error', (err) => reject(err instanceof Error ? err : new Error(String(err))));
+    });
+}
+/**
+ * Default run dispatcher: re-invoke `agents run` with a server-minted id so the
+ * run is addressable, detached so it outlives this request (and the anchor
+ * process). Local runs detach here; `--host` runs detach on the executor via
+ * the existing dispatch path.
+ */
+export const defaultRunner = async (req) => {
+    if (!req.agent?.trim())
+        throw new Error('agent is required');
+    if (!req.prompt?.trim())
+        throw new Error('prompt is required');
+    const name = `ios-${randomBytes(3).toString('hex')}`;
+    // claude accepts an explicit session UUID; other agents resolve by --name.
+    const sessionId = req.agent === 'claude' ? randomUUID() : name;
+    const argv = ['run', req.agent, req.prompt, '--json', '--headless', '--quiet', '--name', name];
+    if (req.agent === 'claude')
+        argv.push('--session-id', sessionId);
+    if (req.mode)
+        argv.push('--mode', req.mode);
+    if (req.host)
+        argv.push('--host', req.host);
+    if (req.cwd)
+        argv.push('--cwd', req.cwd);
+    const inv = getAgentsInvocation(argv);
+    // Await spawn/error so a failed launch becomes a clean 400, never an
+    // unhandled 'error' that crashes the anchor for every other session.
+    //
+    // For an anchor-local run, capture the `--json` NDJSON to a per-session file
+    // so `GET /api/session/:id/stream` can offset-tail it. A `--host` run emits
+    // its NDJSON on the remote box (streaming that reuses pullRemoteLogDelta — a
+    // follow-up), so we don't capture the local dispatcher's output.
+    if (req.host) {
+        await spawnDetached(inv.command, inv.args);
+    }
+    else {
+        fs.mkdirSync(streamDir(), { recursive: true });
+        const fd = fs.openSync(streamLogPath(sessionId), 'a');
+        try {
+            await spawnDetached(inv.command, inv.args, ['ignore', fd, fd]);
+        }
+        finally {
+            // The child inherited the fd; the parent's copy is no longer needed.
+            fs.closeSync(fd);
+        }
+    }
+    return { sessionId, name };
+};
+/** Default messenger: re-invoke `agents message <id> <text>` and await its exit. */
+export const defaultMessenger = async (id, text, from) => {
+    const argv = ['message', id, text];
+    if (from)
+        argv.push('--from', from);
+    const inv = getAgentsInvocation(argv);
+    const code = await new Promise((resolve) => {
+        const child = spawn(inv.command, inv.args, { stdio: 'ignore', env: process.env });
+        child.on('exit', (c) => resolve(c ?? 1));
+        child.on('error', () => resolve(1));
+    });
+    if (code !== 0)
+        throw new Error(`agents message exited with code ${code}`);
+};
+/**
+ * Create (but do not start) the authenticated control server. Caller invokes
+ * `.listen(port, bind)`.
+ */
+export function createControlServer(opts = {}) {
+    const ctx = resolveServeContext(opts);
+    const verify = opts.verifyToken ?? verifyControlToken;
+    const runner = opts.runner ?? defaultRunner;
+    const messenger = opts.messenger ?? defaultMessenger;
+    const streamPollMs = opts.streamPollMs ?? DEFAULT_STREAM_POLL_MS;
+    const streamLogPathFor = opts.streamLogPathFor ?? streamLogPath;
+    return createServer(async (req, res) => {
+        // Auth gates EVERY request — this server may be reachable off-box.
+        if (!verify(presentedToken(req))) {
+            res.writeHead(401, { 'content-type': 'application/json', 'www-authenticate': 'Bearer' });
+            res.end(JSON.stringify({ error: 'unauthorized' }));
+            return;
+        }
+        const method = req.method ?? 'GET';
+        const url = (req.url || '/').split('?')[0];
+        if (method === 'GET') {
+            const streamMatch = /^\/api\/session\/([^/]+)\/stream$/.exec(url);
+            if (streamMatch) {
+                const id = decodeURIComponent(streamMatch[1]);
+                startSessionStream(streamLogPathFor(id), req, res, streamPollMs);
+                return;
+            }
+            const handled = await handleServeGet(url, req, res, ctx);
+            if (!handled)
+                sendJson(res, 404, { error: 'not found' });
+            return;
+        }
+        if (method === 'POST' && url === '/api/run') {
+            try {
+                const body = (await readJsonBody(req));
+                const result = await runner(body);
+                sendJson(res, 200, result);
+            }
+            catch (err) {
+                sendJson(res, 400, { error: String(err?.message ?? err) });
+            }
+            return;
+        }
+        const msgMatch = method === 'POST' && /^\/api\/session\/([^/]+)\/message$/.exec(url);
+        if (msgMatch) {
+            const id = decodeURIComponent(msgMatch[1]);
+            try {
+                const body = (await readJsonBody(req));
+                if (!body.text?.trim())
+                    throw new Error('text is required');
+                await messenger(id, body.text, body.from);
+                sendJson(res, 200, { ok: true, id });
+            }
+            catch (err) {
+                sendJson(res, 400, { error: String(err?.message ?? err) });
+            }
+            return;
+        }
+        sendJson(res, 404, { error: 'not found' });
+    });
+}
+/** Start the control server on `port`, bound to `bind`. Resolves the bound port. */
+export function startControlServer(port, bind, opts = {}) {
+    const server = createControlServer(opts);
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, bind, () => {
+            const addr = server.address();
+            const boundPort = typeof addr === 'object' && addr ? addr.port : port;
+            resolve({ server, port: boundPort });
+        });
+    });
+}

package/dist/lib/serve/server.d.ts

@@ -9,11 +9,26 @@
  *
  * The whole thing is a viewer over data other commands already own
  * ({@link assembleState}); it writes nothing.
+ *
+ * The GET routing is exported as {@link handleServeGet} so the authenticated
+ * `--control` variant (see control.ts) can reuse it verbatim rather than
+ * duplicate the state/SSE surface.
  */
-import http from 'http';
+import type http from 'http';
 import type { ServeState } from './data.js';
 /** Loopback address — the server binds here and nowhere else. */
 export declare const SERVE_HOST = "127.0.0.1";
+/**
+ * DNS-rebinding guard. The socket binds loopback, but binding alone does not
+ * stop a remote page: an attacker can point a hostname's DNS at 127.0.0.1 and
+ * drive the victim's browser to `GET /api/state`, which exposes uncommitted
+ * `git diff HEAD` of every worktree plus routine + cloud config. A browser
+ * always sends a `Host` header naming the site it *thinks* it reached, so we
+ * trust only a Host that is itself loopback. A missing Host (HTTP/1.0 or a raw
+ * non-browser client like curl-without-Host) is not a rebind vector and is
+ * allowed; any explicit non-loopback Host is rejected.
+ */
+export declare function isAllowedServeHost(hostHeader: string | undefined): boolean;
 /** Default port for `agents serve`. */
 export declare const DEFAULT_SERVE_PORT = 4477;
 /** Default SSE push cadence. */
@@ -31,6 +46,25 @@ export interface ServeOptions {
      */
     snapshot?: () => Promise<ServeState>;
 }
+/**
+ * Resolved GET-route context: the snapshot source and SSE cadence, with all
+ * defaults applied. Built once by {@link resolveServeContext}.
+ */
+export interface ServeContext {
+    snapshot: () => Promise<ServeState>;
+    intervalMs: number;
+}
+/** Apply defaults to {@link ServeOptions}, producing a {@link ServeContext}. */
+export declare function resolveServeContext(opts?: ServeOptions): ServeContext;
+/**
+ * Handle the shared read-only GET surface (`/`, `/api/state`, `/events`).
+ * Returns `true` when the route was recognized and a response was written (or
+ * begun, for SSE); `false` when the path is unknown so the caller can 404 or
+ * try its own routes first. Extracted so the `--control` server reuses the
+ * exact same state/SSE behavior — including the load-bearing SSE close/timer
+ * ordering below — without duplicating it.
+ */
+export declare function handleServeGet(url: string, req: http.IncomingMessage, res: http.ServerResponse, ctx: ServeContext): Promise<boolean>;
 /**
  * Create (but do not start) the read-only serve server. Caller invokes
  * `.listen(port, SERVE_HOST)`. Returned so tests can bind an ephemeral port.