@dikshanty94/webnav 0.2.0

package/dist/agent/loop.js

@@ -0,0 +1,267 @@
+import { z } from 'zod';
+import { walkRoute } from '../router/walk.js';
+import { findPath } from '../router/path.js';
+import { matchState } from '../explorer/fingerprint.js';
+import { parseSnapshot } from '../playwright/snapshot.js';
+function text(t) {
+    return { content: [{ type: 'text', text: t }] };
+}
+// Friendly narrate labels for the panel (crit #3b). The SDK exposes webnav's tools as
+// an in-process MCP server, so tool_use block names arrive as `mcp__webnav__<tool>`;
+// that raw string must never reach the user. Strip the prefix and humanize the couple
+// of internal-sounding verbs (click/type/goto already read fine). The panel also strips
+// defensively — this keeps the label clean at the source.
+function friendlyLabel(raw) {
+    const name = raw.replace(/^mcp__webnav__/, '');
+    const friendly = {
+        check_route: 'checking the map',
+        get_page_ax: 'reading the page',
+        list_routes: 'listing known routes',
+    };
+    return friendly[name] ?? name;
+}
+// Build the webnav tools. Each handler drives the injected browser/store; before
+// returning it emits a human-readable `narrate` line so the panel shows what the
+// agent did. This is DISPLAY-ONLY — the browser's own dispatch (the real CDP
+// commands) goes over the channel as `action` events (server.ts), never from here.
+function buildTools(args) {
+    const { browser, store, states, emit } = args;
+    return [
+        {
+            name: 'get_page_ax',
+            description: 'Return the current page as an accessibility snapshot (YAML). Read this to see refs before clicking or typing.',
+            shape: {},
+            handler: async () => {
+                const snap = await browser.snapshot();
+                emit({ type: 'narrate', label: friendlyLabel('get_page_ax'), detail: 'read page' });
+                return text(snap);
+            },
+        },
+        {
+            name: 'click',
+            description: 'Click the element with the given ref (from get_page_ax).',
+            shape: { ref: z.string().describe('element ref, e.g. e5') },
+            handler: async (a) => {
+                const ref = String(a.ref);
+                await browser.act(ref, null);
+                emit({ type: 'narrate', label: 'click', detail: ref });
+                return text('clicked ' + ref);
+            },
+        },
+        {
+            name: 'type',
+            description: 'Type text into the field with the given ref.',
+            shape: { ref: z.string().describe('field ref'), text: z.string().describe('text to type') },
+            handler: async (a) => {
+                const ref = String(a.ref);
+                const val = String(a.text ?? '');
+                if (!browser.typeText) {
+                    return text('cannot type: this browser has no free-text input; field ' + ref + ' was NOT filled');
+                }
+                await browser.typeText(ref, val);
+                emit({ type: 'narrate', label: 'type', detail: '"' + val + '" into ' + ref });
+                return text('typed "' + val + '" into ' + ref);
+            },
+        },
+        {
+            name: 'goto',
+            description: 'Navigate the tab directly to a URL.',
+            shape: { url: z.string().describe('absolute URL') },
+            handler: async (a) => {
+                const url = String(a.url);
+                if (!browser.goto)
+                    return text('this browser cannot goto a URL');
+                // Two modes: Ask gated the whole run up front; Act drives freely. Commit points
+                // (Place Order / Pay / Delete) are STILL never auto-fired — walkRoute halts on them
+                // regardless of mode — so autonomy here is bounded by that hard safety floor.
+                await browser.goto(url, null);
+                emit({ type: 'narrate', label: 'goto', detail: url });
+                return text('navigated to ' + url);
+            },
+        },
+        {
+            name: 'scroll',
+            description: 'Scroll the current page by dy pixels (positive = down, negative = up) to reveal content below or above the fold, then re-read with get_page_ax.',
+            shape: { dy: z.number().describe('pixels to scroll; positive scrolls down, negative up (e.g. 600)') },
+            handler: async (a) => {
+                const dy = Number(a.dy);
+                if (!browser.scroll)
+                    return text('this browser cannot scroll');
+                await browser.scroll(dy);
+                emit({ type: 'narrate', label: 'scroll', detail: (dy >= 0 ? 'down ' : 'up ') + Math.abs(dy) + 'px' });
+                return text('scrolled ' + (dy >= 0 ? 'down ' : 'up ') + Math.abs(dy) + 'px');
+            },
+        },
+        {
+            name: 'list_routes',
+            description: 'List the recallable destination states webnav already knows for the CURRENT site. Call this FIRST to discover which goal state ids exist, then pass one to check_route. Returns id + name per destination.',
+            shape: {},
+            handler: async () => {
+                // ZERO-LLM: pure filtering of the in-memory states. Current site = the nodeId of
+                // whatever known state the live page matches (fingerprint-based, so account-id URL
+                // differences never matter). If the page matches no state, fall back to ALL sites'
+                // destinations so the agent still sees what maps exist. A real destination has a
+                // NON-EMPTY fingerprint (mirrors matchState: _shell + empty-fp stubs identify nothing).
+                const match = matchState(parseSnapshot(await browser.snapshot()), states);
+                const site = match.status === 'matched' ? match.state.nodeId : null;
+                const dests = states.filter((s) => s.fingerprint.length > 0 && (site === null || s.nodeId === site));
+                emit({ type: 'narrate', label: friendlyLabel('list_routes'), detail: dests.length + ' destination(s)' });
+                if (dests.length === 0)
+                    return text('no recallable destinations known for this site — drive manually with click/type/goto.');
+                const lines = dests.map((s) => '- ' + s.id + ' — ' + s.semanticName);
+                return text('known destinations (pass an id to check_route):\n' + lines.join('\n'));
+            },
+        },
+        {
+            name: 'check_route',
+            description: 'RECALL-FIRST: check whether the map already knows a deterministic route from the current page to a goal state. On a hit, webnav walks it for you and reports the result; on a miss, drive manually with click/type/goto.',
+            shape: { goalStateId: z.string().describe('id of the destination state, e.g. sd:cart') },
+            handler: async (a) => {
+                const goalStateId = String(a.goalStateId);
+                // ZERO-LLM: parse the live snapshot, match it to a known state, ask findPath.
+                const nodes = parseSnapshot(await browser.snapshot());
+                const match = matchState(nodes, states);
+                if (match.status !== 'matched') {
+                    emit({ type: 'narrate', label: friendlyLabel('check_route'), detail: 'current page not on a known state' });
+                    return text('no route: current page is not on a known map state — drive manually with click/type/goto.');
+                }
+                const start = match.state.id;
+                const path = findPath(store, start, goalStateId);
+                if (!path) {
+                    emit({ type: 'narrate', label: friendlyLabel('check_route'), detail: 'no route ' + start + ' -> ' + goalStateId });
+                    return text('no route from ' + start + ' to ' + goalStateId + ' in the map — drive manually.');
+                }
+                emit({ type: 'narrate', label: friendlyLabel('check_route'), detail: path.join(' -> ') });
+                // THE PAYOFF: hand the found route to the deterministic replay (walkRoute
+                // UNMODIFIED), then narrate its terminal RecallResponse back to the agent.
+                const res = await walkRoute({
+                    goalName: 'agent:' + args.goal,
+                    startStateId: start,
+                    goalStateId,
+                    store,
+                    states,
+                    browser,
+                    path,
+                });
+                return text('route found [' + path.join(' -> ') + ']; walked: ' + summarizeRecall(res));
+            },
+        },
+    ];
+}
+// One-line summary of a walk's terminal response for the agent to read as a tool result.
+function summarizeRecall(res) {
+    switch (res.status) {
+        case 'done': return 'done';
+        case 'needs-navigation': return 'needs-navigation at step ' + res.at + ': ' + res.question;
+        case 'needs-classification': return 'needs-classification: ' + res.action;
+        case 'needs-auth': return 'needs-auth (login required) at ' + res.loginUrl;
+        case 'checkpoint': return 'checkpoint at ' + res.state;
+        case 'failed': return 'failed: ' + res.reason;
+        default: return res.status;
+    }
+}
+// The default QueryFn: wire the tools into a real SDK MCP server and run query().
+// Imported lazily so unit tests (which inject a fake) never load the SDK.
+const defaultQuery = async function* ({ prompt, tools, model, resume, signal }) {
+    const { tool, createSdkMcpServer, query } = await import('@anthropic-ai/claude-agent-sdk');
+    const sdkTools = tools.map((t) => tool(t.name, t.description, t.shape, async (a, extra) => t.handler(a, extra)));
+    const server = createSdkMcpServer({ name: 'webnav', tools: sdkTools });
+    const allowedTools = tools.map((t) => 'mcp__webnav__' + t.name);
+    yield* query({
+        prompt,
+        options: {
+            mcpServers: { webnav: server },
+            allowedTools,
+            permissionMode: 'default',
+            // Only pass `model` when the user picked one; omit → SDK default (never '').
+            ...(model ? { model } : {}),
+            // Continue a prior conversation (Options.resume) when a session id is carried over.
+            ...(resume ? { resume } : {}),
+            ...(signal ? { abortController: abortFromSignal(signal) } : {}),
+        },
+    });
+};
+// The SDK wants an AbortController; the loop is handed an AbortSignal (for /stop).
+// Bridge them so aborting the signal aborts the query.
+function abortFromSignal(signal) {
+    const ctrl = new AbortController();
+    if (signal.aborted)
+        ctrl.abort();
+    else
+        signal.addEventListener('abort', () => ctrl.abort(), { once: true });
+    return ctrl;
+}
+const SYSTEM = [
+    'You navigate a live browser tab to accomplish the user goal.',
+    'RECALL FIRST: call list_routes to discover the destination state ids webnav already knows for this site, then call check_route with the relevant id — if the map knows a route, webnav walks it deterministically and reports the result. You do NOT need to guess ids; list_routes shows the real ones.',
+    'Only if list_routes is empty or check_route reports no route: call get_page_ax to see the page, then drive manually with click/type/goto by ref.',
+    'Irreversible actions (Place Order, Pay, Delete) are never fired automatically — if the walk hits one it stops and hands back to you.',
+].join(' ');
+/**
+ * Run one agent goal. Streams SDK narration back as AgentEvents:
+ *  - assistant text  -> { type: 'turn', text }
+ *  - tool-use blocks -> { type: 'narrate', label } (display-only; the REAL CDP `action`
+ *                       events come from the channel in server.ts, never from here)
+ *  - final result    -> { type: 'done', summary }
+ *  - any throw        -> { type: 'error', message }
+ *
+ * Ask/Auto/Act gate semantics (crit #3/#4 — these three are OBSERVABLY different):
+ *  - ACT:  no confirmations. Drives freely. (Commit points are still protected by
+ *          walkRoute's needs-classification — never auto-fired.)
+ *  - AUTO: drives freely EXCEPT it pauses for approval before a goto to a NEW ORIGIN
+ *          (cross-site navigation = the cheap "meaningful action" signal). Gate lives in
+ *          the goto tool handler (buildTools). Same-origin driving is never gated.
+ *  - ASK:  emit the plan, then BLOCK the whole run on awaitApproval() BEFORE the query's
+ *          first driving tool can run. Approve → run. Deny → emit a "denied" done and
+ *          return without ever starting the query (nothing drives).
+ */
+export async function runAgentGoal(args) {
+    const { goal, mode, emit } = args;
+    const query = args.query ?? defaultQuery;
+    const tools = buildTools(args);
+    // Turn 1 (fresh): send SYSTEM + goal. Resumed turn: send JUST the goal — the SDK
+    // already holds the system prompt + history from the resumed session, so re-injecting
+    // SYSTEM would make Claude re-orient and re-list routes every message (the whole bug).
+    const prompt = args.resumeSessionId ? goal : SYSTEM + '\n\nGoal: ' + goal;
+    if (mode === 'ask') {
+        emit({ type: 'plan', steps: ['Check the map for a known route, then drive the tab step by step toward: ' + goal] });
+        // HARD GATE: block before the first drive. The SDK query does not start until the
+        // user approves — that is what makes Ask genuinely different from Auto/Act.
+        const ok = args.awaitApproval ? await args.awaitApproval() : true;
+        if (!ok) {
+            emit({ type: 'done', summary: 'denied — nothing was done' });
+            return;
+        }
+    }
+    try {
+        let finalText = '';
+        let sdkSessionSeen = false;
+        for await (const msg of query({ prompt, tools, mode, model: args.model, resume: args.resumeSessionId, emit, signal: args.signal })) {
+            const m = msg;
+            // Capture the SDK session id off the message stream (every SDKMessage carries it).
+            // Report it ONCE so the caller can persist it and resume this conversation next turn.
+            if (!sdkSessionSeen && typeof m.session_id === 'string' && m.session_id) {
+                sdkSessionSeen = true;
+                args.onSdkSession?.(m.session_id);
+            }
+            if (m.type === 'assistant') {
+                for (const block of m.message?.content ?? []) {
+                    if (block.type === 'text' && block.text)
+                        emit({ type: 'turn', text: block.text });
+                    // NOTE: we deliberately do NOT narrate the tool_use block here. Each tool's
+                    // handler (buildTools) emits its OWN narrate with the RESULT detail (e.g.
+                    // "listing known routes: 46 destination(s)"); narrating the announcement too
+                    // produced a duplicate bare line per action. The handler narrate is the one.
+                }
+            }
+            else if (m.type === 'result') {
+                if (m.subtype === 'success')
+                    finalText = m.result ?? finalText;
+            }
+        }
+        emit({ type: 'done', summary: finalText || undefined });
+    }
+    catch (e) {
+        emit({ type: 'error', message: e instanceof Error ? e.message : String(e) });
+    }
+}

package/dist/agent/server.d.ts

@@ -0,0 +1,60 @@
+import http from 'node:http';
+import type { AgentChannel } from '../router/live-extension-browser.js';
+import type { RecordStore } from '../mapstore/record.js';
+export interface ScreencastFrame {
+    data: string;
+    timestampMs: number;
+}
+export type AgentCommand = {
+    kind: 'get-ax';
+} | {
+    kind: 'click';
+    nodeId: string;
+} | {
+    kind: 'type';
+    nodeId: string;
+    text?: string;
+} | {
+    kind: 'goto';
+    url: string;
+} | {
+    kind: 'scroll';
+    dy: number;
+} | {
+    kind: 'current-url';
+};
+export type AgentEvent = {
+    type: 'turn';
+    text: string;
+} | {
+    type: 'narrate';
+    label: string;
+    detail?: string;
+} | {
+    type: 'action';
+    id: string;
+    cmd: AgentCommand;
+} | {
+    type: 'done';
+    summary?: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'plan';
+    steps: string[];
+};
+export interface AgentGoalBody {
+    goal: string;
+    sessionId: string;
+    mode: string;
+    model?: string;
+    newChat?: boolean;
+}
+export interface ServeAgentOpts {
+    onGoal?: (goal: AgentGoalBody, channel: AgentChannel, emit: (e: AgentEvent) => void, awaitApproval: () => Promise<boolean>, signal: AbortSignal, resumeSessionId: string | undefined, onSdkSession: (sdkSessionId: string) => void) => Promise<void>;
+    onScreencast?: (sessionId: string, frames: ScreencastFrame[]) => Promise<void>;
+    commandTimeoutMs?: number;
+    token?: string;
+}
+export declare function serveAgent(port: number, store: RecordStore, opts?: ServeAgentOpts): http.Server;

package/dist/agent/server.js

@@ -0,0 +1,254 @@
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { ingestAX } from '../recorder/ingest.js';
+// Minimal drivable landing page (served unauthenticated at GET /landing). On-brand
+// (the webnav map-pin), both light + dark via prefers-color-scheme, self-contained (the
+// extension CSP + a bare browser tab: no external anything). It's just a neutral,
+// debugger-attachable place for the agent to start when the launch tab wasn't drivable —
+// the agent navigates onward from here immediately.
+const LANDING_HTML = `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>webnav — ready</title>
+<style>
+  :root { color-scheme: light dark; --bg:#eef1f6; --ink:#1a2230; --ink-soft:#4a5568; --accent:#2f6fe0; }
+  @media (prefers-color-scheme: dark) { :root { --bg:#0d1017; --ink:#e7ecf4; --ink-soft:#a4aec0; --accent:#5b9dff; } }
+  html,body { height:100%; margin:0; }
+  body { display:flex; flex-direction:column; align-items:center; justify-content:center; gap:14px;
+    background:var(--bg); color:var(--ink); font:15px/1.5 ui-sans-serif,-apple-system,system-ui,sans-serif; }
+  svg { width:40px; height:40px; }
+  h1 { font-size:16px; font-weight:650; margin:0; letter-spacing:-.01em; }
+  p { margin:0; color:var(--ink-soft); font-size:13px; }
+</style></head><body>
+  <svg viewBox="0 0 24 24" fill="none" stroke="var(--accent)" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M12 22c4.5-5 7-8.4 7-12A7 7 0 0 0 5 10c0 3.6 2.5 7 7 12z"/><circle cx="12" cy="10" r="2.6" fill="var(--accent)" stroke="none"/>
+  </svg>
+  <h1>webnav — ready</h1>
+  <p>Give the agent a goal in the side panel; it will navigate from here.</p>
+</body></html>`;
+export function serveAgent(port, store, opts = {}) {
+    const commandTimeoutMs = opts.commandTimeoutMs ?? 30_000;
+    // `||` not `??`: an explicitly-passed empty string must still fall back to a random
+    // token — token:'' would make authorized('') true and disable auth entirely.
+    const token = opts.token || crypto.randomBytes(16).toString('hex');
+    // LAST-CONNECTION-WINS (single-panel guard): two open panels (or a reopened panel
+    // racing the old EventSource's close) must not both receive+execute every `action` —
+    // that double-fires CDP clicks. Only the newest /events connection is kept live; a
+    // fresh connection evicts+ends whatever was there before.
+    let current = null;
+    const emit = (e) => current?.send(e);
+    const pending = new Map();
+    let seq = 0;
+    // Single outstanding approval gate (one goal runs at a time). onGoal is handed an
+    // awaitApproval() that parks here until /approve (or /stop, which denies) resolves it.
+    // ponytail: one slot, not a per-goal map — the server drives one goal at a time.
+    let pendingApproval = null;
+    // Single outstanding run's abort controller (one goal at a time, same as the approval
+    // slot). /stop aborts it so the SDK query is cancelled, not just the pending commands.
+    let currentGoalAbort = null;
+    // Panel conversation key → last SDK session id, so a follow-up goal resumes the same
+    // conversation (Claude remembers what it did + the page it's on). Keyed by the panel's
+    // `sessionId`; the New-chat button rotates that key (or sends newChat:true) → fresh.
+    // ponytail: in-memory Map — one process per agent-serve, no persistence needed.
+    const sdkSessions = new Map();
+    function awaitApproval() {
+        // A fresh goal supersedes any stale unresolved gate (deny it so nothing leaks).
+        if (pendingApproval)
+            pendingApproval(false);
+        return new Promise((resolve) => { pendingApproval = resolve; });
+    }
+    function resolveApproval(approved) {
+        const p = pendingApproval;
+        pendingApproval = null;
+        p?.(approved);
+    }
+    function rejectAllPending(message) {
+        for (const [id, p] of pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(message));
+            pending.delete(id);
+        }
+        resolveApproval(false); // /stop also denies an outstanding approval gate
+    }
+    // The real AgentChannel: every call becomes an `action` SSE event, resolved when
+    // the extension POSTs to /api/agent/command-result (or timed out).
+    function makeChannel() {
+        function dispatchCommand(cmd) {
+            const id = 'cmd' + (++seq);
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    reject(new Error(`agent-serve: command "${id}" timed out after ${commandTimeoutMs}ms`));
+                }, commandTimeoutMs);
+                pending.set(id, { resolve, reject, timer });
+                emit({ type: 'action', id, cmd });
+            });
+        }
+        return {
+            getAX: () => dispatchCommand({ kind: 'get-ax' }),
+            dispatch: async (cmd) => { await dispatchCommand(cmd); },
+            goto: async (url) => { await dispatchCommand({ kind: 'goto', url }); },
+            scroll: async (dy) => { await dispatchCommand({ kind: 'scroll', dy }); },
+            currentUrl: () => dispatchCommand({ kind: 'current-url' }),
+        };
+    }
+    // Constant-time token check. The extension sends the secret as an `x-webnav-token`
+    // header on POSTs; EventSource can't set headers, so the SSE GET carries it as a
+    // `?token=` query param. No CORS headers are emitted at all — this server is only
+    // reached by the extension (a privileged context whose fetch/EventSource are NOT
+    // page-CORS-gated), so `*` was never needed; dropping it blocks any web page from
+    // reading responses cross-origin, and the token blocks driving the browser without
+    // the secret (closes the DNS-rebind / local-process attack).
+    const authorized = (req) => {
+        const url = new URL(req.url ?? '', 'http://x');
+        const presented = req.headers['x-webnav-token'] ?? url.searchParams.get('token') ?? '';
+        const a = Buffer.from(presented);
+        const b = Buffer.from(token);
+        return a.length === b.length && crypto.timingSafeEqual(a, b);
+    };
+    const server = http.createServer((req, res) => {
+        const sendJson = (code, body) => res.writeHead(code, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+        // Drivable landing page — the one route that is NOT token-gated. When the agent must
+        // open a fresh tab (the user launched from a chrome:// / New Tab page that CDP can't
+        // drive), it lands HERE instead of an arbitrary google.com: a minimal, on-brand,
+        // http(s) (therefore debugger-attachable) page. It's a static page with NO capability,
+        // NO data, NO command surface — safe to serve unauthenticated (a browser tab can't send
+        // the x-webnav-token header anyway). The agent immediately goto()s to the real target.
+        if (req.method === 'GET' && (req.url === '/landing' || req.url === '/')) {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(LANDING_HTML);
+            return;
+        }
+        if (!authorized(req))
+            return sendJson(401, { ok: false, error: 'unauthorized' });
+        if (req.method === 'GET' && (req.url ?? '').startsWith('/api/agent/events')) {
+            // Evict whatever connection was previously current — last-connection-wins.
+            current?.res.end();
+            res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+            res.write(': connected\n\n');
+            const send = (e) => res.write('data: ' + JSON.stringify(e) + '\n\n');
+            const self = { send, res };
+            current = self;
+            const beat = setInterval(() => res.write(': ping\n\n'), 15000);
+            req.on('close', () => { clearInterval(beat); if (current === self)
+                current = null; });
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/api/agent/goal') {
+            readBody(req).then((raw) => {
+                let body;
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    return sendJson(400, { ok: false, error: 'invalid JSON body' });
+                }
+                if (!body.goal || !body.sessionId)
+                    return sendJson(400, { ok: false, error: 'goal and sessionId required' });
+                sendJson(200, { ok: true });
+                if (opts.onGoal) {
+                    const channel = makeChannel();
+                    // A fresh goal supersedes any prior run's abort controller.
+                    const abort = new AbortController();
+                    currentGoalAbort = abort;
+                    // New-chat: forget the prior SDK conversation for this key → this run cold-starts.
+                    if (body.newChat)
+                        sdkSessions.delete(body.sessionId);
+                    const resumeSessionId = sdkSessions.get(body.sessionId);
+                    const onSdkSession = (id) => { sdkSessions.set(body.sessionId, id); };
+                    opts.onGoal(body, channel, emit, awaitApproval, abort.signal, resumeSessionId, onSdkSession)
+                        .catch((e) => emit({ type: 'error', message: String(e) }))
+                        .finally(() => { if (currentGoalAbort === abort)
+                        currentGoalAbort = null; });
+                }
+            });
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/api/agent/command-result') {
+            readBody(req).then((raw) => {
+                let body;
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    return sendJson(400, { ok: false, error: 'invalid JSON body' });
+                }
+                const p = body.id ? pending.get(body.id) : undefined;
+                if (!p)
+                    return sendJson(404, { ok: false, error: 'unknown command id' });
+                clearTimeout(p.timer);
+                pending.delete(body.id);
+                p.resolve(body.result);
+                sendJson(200, { ok: true });
+            });
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/api/agent/approve') {
+            readBody(req).then((raw) => {
+                let body;
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    return sendJson(400, { ok: false, error: 'invalid JSON body' });
+                }
+                resolveApproval(body.approved === true);
+                sendJson(200, { ok: true });
+            });
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/api/agent/stop') {
+            // Stop must ACTUALLY stop: reject in-flight browser commands AND abort the SDK
+            // query (via the per-goal signal threaded to runAgentGoal). Rejecting pending
+            // commands alone only fails the next browser call — the SDK turn keeps running.
+            rejectAllPending('agent-serve: stopped');
+            currentGoalAbort?.abort();
+            sendJson(200, { ok: true });
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/ingest-ax') {
+            readBody(req).then((raw) => {
+                try {
+                    const body = JSON.parse(raw);
+                    if (!body.sessionId || !Array.isArray(body.steps))
+                        throw new Error('sessionId and steps[] required');
+                    const appended = ingestAX(body, store);
+                    sendJson(200, { ok: true, appended });
+                }
+                catch (e) {
+                    sendJson(400, { ok: false, error: String(e) });
+                }
+            });
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/api/agent/screencast') {
+            readBody(req).then(async (raw) => {
+                try {
+                    const body = JSON.parse(raw);
+                    if (!body.sessionId || !Array.isArray(body.frames))
+                        throw new Error('sessionId and frames[] required');
+                    // Empty frames (nothing captured) is a no-op success, not an error.
+                    if (body.frames.length && opts.onScreencast)
+                        await opts.onScreencast(body.sessionId, body.frames);
+                    sendJson(200, { ok: true, frames: body.frames.length });
+                }
+                catch (e) {
+                    sendJson(400, { ok: false, error: String(e) });
+                }
+            });
+            return;
+        }
+        sendJson(404, { ok: false, error: 'not found' });
+    });
+    server.listen(port, '127.0.0.1');
+    return server;
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        // ponytail: 50MB cap mirrors serveIngest's precedent — a goal run can carry
+        // full AX trees per step.
+        req.on('data', (c) => { data += c; if (data.length > 50_000_000)
+            req.destroy(); });
+        req.on('end', () => resolve(data));
+        req.on('error', reject);
+    });
+}

package/dist/cli-help.d.ts

@@ -0,0 +1,3 @@
+export declare function topLevelHelp(): string;
+export declare function devHelp(): string;
+export declare function commandHelp(name: string): string;