@qearlyao/familiar 0.2.4 → 0.3.0

package/dist/agent.js

@@ -1,257 +1,24 @@
-import { createHash } from "node:crypto";
-import { appendFile, mkdir, readdir, readFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
 import { Agent } from "@earendil-works/pi-agent-core";
 import { streamSimple } from "@earendil-works/pi-ai";
-import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@earendil-works/pi-coding-agent";
 import { setAddedModelsPath } from "./added-models.js";
-import { createBrowserTools } from "./browser-tools.js";
+import { normalizeProviderPayload } from "./agent/payload-normalizers.js";
+import { assertModelAllowed, deriveSessionId, formatModel, getLastAssistantText, getRequestApiKey, installProviderDebugFilter, isNoisyProviderDebug, logUsage, resolveModelName, userTextMessage, } from "./agent/session-helpers.js";
+import { createFamiliarTools, setReferenceAttachments } from "./agent/tools.js";
+import { loadStoredMessages, writePayloadLog, writeTranscriptLog } from "./agent/transcript-log.js";
 import { setConfigOverridesPath } from "./config-overrides.js";
 import { applyConfigOverridesToConfig } from "./config-registry.js";
 import { createGeneratedMediaSink } from "./generated-media.js";
-import { createImageGenTool } from "./image-gen.js";
-import { assertModelCanAuthenticate, clampConfiguredThinkingLevel, createConfiguredModel, isAllowedModel, isThinkingLevel, parseModelRef, resolveModel, resolveModelApiKey, supportedThinkingLevels, } from "./models.js";
+import { clampConfiguredThinkingLevel, createConfiguredModel, isThinkingLevel, parseModelRef, resolveModel, supportedThinkingLevels, } from "./models.js";
 import { buildSystemPrompt, loadPersona } from "./persona.js";
 import { formatFamiliarSkillsForPrompt, loadFamiliarSkills, logSkillDiagnostics } from "./skills.js";
-import { createTtsTool } from "./tts.js";
-import { isEnoent } from "./util/fs.js";
-import { isRecord } from "./util/guards.js";
-import { createWebTools } from "./web-tools.js";
-const BASH_DESCRIPTION = "run a bash command. defaults to the workspace; absolute paths and `~/...` reach anywhere else. returns stdout and stderr. output truncates to the last 2000 lines or 50KB, whichever hits first; full output lands in a temp file if cut. timeout in seconds optional.";
-const READ_DESCRIPTION = "read a file. paths resolve from the workspace, but absolute paths and `~/...` work too. text and images (jpg, png, gif, webp); images come back as attachments. text output truncates to 2000 lines or 50KB, whichever hits first — use offset and limit for long files, and keep paging until you have what you need.";
-const WRITE_DESCRIPTION = "write a file from scratch or replace it wholesale. creates the file if missing, overwrites if not, and makes parent directories as needed. paths resolve from the workspace; absolute and `~/...` also accepted.";
-const EDIT_DESCRIPTION = "edit a file with exact text replacement. each edits[].oldText must match a unique, non-overlapping slice of the original — overlapping or nested edits are rejected, so merge nearby changes into one entry rather than chaining them. don't pad oldText with large unchanged regions just to connect distant changes. paths resolve from the workspace; absolute and `~/...` also work.";
-function deriveSessionId(workspacePath, sessionKey) {
-    const digest = createHash("sha256").update(`${workspacePath}\0${sessionKey}`).digest("hex").slice(0, 32);
-    return `familiar-${digest}`;
-}
-function dailyLogPath(dataDir, streamName, now = new Date()) {
-    const date = now.toISOString().slice(0, 10);
-    return resolve(dataDir, streamName, `${date}.jsonl`);
-}
-async function appendJsonl(path, record) {
-    await mkdir(dirname(path), { recursive: true });
-    await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
-}
-function writePayloadLog(config, record) {
-    appendJsonl(dailyLogPath(config.workspace.dataDir, "payloads"), record).catch((err) => console.error("payload log write failed", err));
-}
-function writeTranscriptLog(config, record) {
-    appendJsonl(dailyLogPath(config.workspace.dataDir, "transcripts"), record).catch((err) => console.error("transcript log write failed", err));
-}
-function clonePayload(payload) {
-    if (typeof structuredClone === "function")
-        return structuredClone(payload);
-    return JSON.parse(JSON.stringify(payload));
-}
-// TODO: remove once pi-ai handles store:false reasoning replay upstream.
-function stripOpenAIStoredReasoningItems(payload, model) {
-    if (model.api !== "openai-responses" && model.api !== "azure-openai-responses")
-        return payload;
-    const nextPayload = clonePayload(payload);
-    if (!isRecord(nextPayload))
-        return nextPayload;
-    const request = nextPayload;
-    if (request.store !== false)
-        return nextPayload;
-    const input = request.input;
-    if (!Array.isArray(input))
-        return nextPayload;
-    request.input = input.filter((item) => {
-        if (!item || typeof item !== "object" || Array.isArray(item))
-            return true;
-        return item.type !== "reasoning";
-    });
-    return nextPayload;
-}
-function moveAnthropicCacheControlBeforeInjectedMemory(payload, model) {
-    if (model.api !== "anthropic-messages")
-        return payload;
-    if (!isRecord(payload) || !Array.isArray(payload.messages))
-        return payload;
-    const messages = payload.messages;
-    const lastMessage = messages.at(-1);
-    if (!isRecord(lastMessage) || lastMessage.role !== "user")
-        return payload;
-    const content = lastMessage.content;
-    if (!Array.isArray(content) || content.length < 2)
-        return payload;
-    const injectedBlock = content.at(-1);
-    const stableBlock = content.at(-2);
-    if (!isInjectedMemoryTextBlock(injectedBlock) || !isRecord(stableBlock))
-        return payload;
-    const cacheControl = injectedBlock.cache_control;
-    if (!cacheControl)
-        return payload;
-    delete injectedBlock.cache_control;
-    stableBlock.cache_control = cacheControl;
-    return payload;
-}
-function isInjectedMemoryTextBlock(value) {
-    if (!isRecord(value) || value.type !== "text" || typeof value.text !== "string")
-        return false;
-    return value.text.trim().startsWith("<injected_memory>");
-}
-function normalizeProviderPayload(payload, model) {
-    return moveAnthropicCacheControlBeforeInjectedMemory(stripOpenAIStoredReasoningItems(payload, model), model);
-}
 export const __agentTest = {
+    isNoisyProviderDebug,
     normalizeProviderPayload,
 };
-function isStoredMessageRecord(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const record = value;
-    return typeof record.ts === "string" && typeof record.sessionId === "string" && !!record.message;
-}
-function isStoredResetRecord(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const record = value;
-    return record.type === "reset" && typeof record.ts === "string" && typeof record.sessionId === "string";
-}
-async function loadStoredMessages(dataDir, sessionId) {
-    const transcriptsDir = resolve(dataDir, "transcripts");
-    let files;
-    try {
-        files = await readdir(transcriptsDir);
-    }
-    catch (error) {
-        if (isEnoent(error))
-            return [];
-        console.error("transcript history read failed", error);
-        return [];
-    }
-    const records = [];
-    for (const file of files.filter((entry) => entry.endsWith(".jsonl")).sort()) {
-        const path = resolve(transcriptsDir, file);
-        let contents;
-        try {
-            contents = await readFile(path, "utf8");
-        }
-        catch (error) {
-            console.error(`transcript file read failed: ${path}`, error);
-            continue;
-        }
-        for (const [index, line] of contents.split(/\r?\n/).entries()) {
-            if (!line.trim())
-                continue;
-            try {
-                const parsed = JSON.parse(line);
-                if (!isStoredMessageRecord(parsed) && !isStoredResetRecord(parsed)) {
-                    console.error(`skipping malformed transcript line: ${path}:${index + 1}`);
-                    continue;
-                }
-                if (parsed.sessionId !== sessionId)
-                    continue;
-                records.push(parsed);
-            }
-            catch (error) {
-                console.error(`skipping unparsable transcript line: ${path}:${index + 1}`, error);
-            }
-        }
-    }
-    records.sort((a, b) => a.ts.localeCompare(b.ts));
-    let lastResetIndex = -1;
-    for (let index = records.length - 1; index >= 0; index--) {
-        const record = records[index];
-        if (record && "type" in record && record.type === "reset") {
-            lastResetIndex = index;
-            break;
-        }
-    }
-    const activeRecords = lastResetIndex >= 0 ? records.slice(lastResetIndex + 1) : records;
-    return activeRecords.flatMap((record) => ("message" in record ? [record.message] : []));
-}
-function getRequestApiKey(config, model) {
-    const apiKey = resolveModelApiKey(config, model);
-    assertModelCanAuthenticate(config, model);
-    return apiKey;
-}
-function formatModel(model) {
-    return `${model.provider}/${model.id}`;
-}
-function resolveModelName(value, fallback) {
-    return value ?? formatModel(fallback);
-}
-function assertModelAllowed(config, ref) {
-    if (!isAllowedModel(config, ref))
-        throw new Error(`Model is not allowlisted: ${ref.key}`);
-}
-function extractText(message) {
-    if (!message || typeof message !== "object")
-        return "";
-    const record = message;
-    if (record.stopReason === "error" && typeof record.errorMessage === "string" && record.errorMessage.trim()) {
-        return `Model error: ${record.errorMessage}`;
-    }
-    if (!("content" in record))
-        return "";
-    const content = record.content;
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    return content
-        .filter((item) => {
-        return !!item && typeof item === "object" && item.type === "text";
-    })
-        .map((item) => item.text)
-        .join("");
-}
-function getLastAssistantText(agent) {
-    for (let i = agent.state.messages.length - 1; i >= 0; i--) {
-        const message = agent.state.messages[i];
-        if (message.role === "assistant")
-            return extractText(message);
-    }
-    return "";
-}
-function logUsage(event) {
-    if (event.type !== "message_end" || event.message.role !== "assistant")
-        return;
-    const usage = event.message.usage;
-    console.log(JSON.stringify({
-        type: "usage",
-        input: usage.input,
-        output: usage.output,
-        cacheRead: usage.cacheRead,
-        cacheWrite: usage.cacheWrite,
-        cost: usage.cost.total,
-    }));
-}
-function userTextMessage(text, timestamp = Date.now()) {
-    return {
-        role: "user",
-        content: [{ type: "text", text }],
-        timestamp,
-    };
-}
-function createFamiliarTools(config, mediaSink, referenceAttachments = () => [], memoryService) {
-    const bashTool = createBashTool(config.workspacePath);
-    bashTool.description = BASH_DESCRIPTION;
-    const readTool = createReadTool(config.workspacePath);
-    readTool.description = READ_DESCRIPTION;
-    const writeTool = createWriteTool(config.workspacePath);
-    writeTool.description = WRITE_DESCRIPTION;
-    const editTool = createEditTool(config.workspacePath);
-    editTool.description = EDIT_DESCRIPTION;
-    return [
-        bashTool,
-        readTool,
-        writeTool,
-        editTool,
-        createTtsTool(config, mediaSink),
-        ...(config.imageGen.enabled ? [createImageGenTool(config, mediaSink, { referenceAttachments })] : []),
-        ...createWebTools(config),
-        ...createBrowserTools(config, mediaSink),
-        ...(memoryService?.memoryTools() ?? []),
-    ];
-}
-function setReferenceAttachments(session, attachments = []) {
-    session.referenceAttachments.splice(0, session.referenceAttachments.length, ...attachments);
-}
+const PROVIDER_MAX_RETRIES = 2;
+const PROVIDER_MAX_RETRY_DELAY_MS = 60_000;
 export async function createFamiliarAgent(config, settings, memoryService, options = {}) {
+    installProviderDebugFilter();
     setAddedModelsPath(config.workspace.dataDir);
     setConfigOverridesPath(config.workspace.dataDir);
     applyConfigOverridesToConfig(config);
@@ -269,21 +36,8 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
     // activePromptOptions covers the synchronous promptMessage window; skipAmbientMessages
     // tags message identities so followUpMessage's fire-and-forget path also opts out.
     const activePromptOptions = new Map();
-    const softStopRequested = new Map();
     const skipAmbientMessages = new WeakSet();
     let reloadInProgress;
-    const installSoftStopHook = (sessionKey, agent) => {
-        const agentWithLoopConfig = agent;
-        const createLoopConfig = agentWithLoopConfig.createLoopConfig?.bind(agent);
-        if (!createLoopConfig)
-            return;
-        agentWithLoopConfig.createLoopConfig = ((options) => {
-            return {
-                ...createLoopConfig(options),
-                shouldStopAfterTurn: async () => softStopRequested.get(sessionKey) === true,
-            };
-        });
-    };
     const resolveChannelModel = (sessionKey) => {
         const override = settings.getChannelModel(sessionKey);
         const modelName = resolveModelName(override.value, defaultModel);
@@ -344,6 +98,8 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
                 ...options,
                 apiKey: getRequestApiKey(config, streamModel),
                 cacheRetention: config.agent.cacheRetention,
+                maxRetries: options?.maxRetries ?? PROVIDER_MAX_RETRIES,
+                maxRetryDelayMs: options?.maxRetryDelayMs ?? PROVIDER_MAX_RETRY_DELAY_MS,
                 onPayload: (payload, payloadModel) => {
                     const requestPayload = normalizeProviderPayload(payload, payloadModel);
                     writePayloadLog(config, {
@@ -381,7 +137,6 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
                 }
                 : undefined,
         });
-        installSoftStopHook(sessionKey, agent);
         agent.subscribe((event) => {
             logUsage(event);
             if (event.type === "message_end") {
@@ -465,25 +220,90 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
             };
         }));
     };
+    // Shared serialization wrapper for prompt/promptMessage: run after the prior turn
+    // settles on the session's promptQueue, keep the stored tail non-rejecting, and run
+    // teardown (onTurnEnd → reference reset → enterTurn's exit → unsubscribe) in a fixed
+    // order regardless of how the turn ends. enterTurn returns its own cleanup so callers
+    // can scope per-turn state (e.g. activePromptOptions) across the exact finally window.
+    const runPromptTurn = async (sessionKey, options, eventHandler, dispatch, enterTurn) => {
+        const session = await getSession(sessionKey);
+        const run = session.promptQueue.then(async () => {
+            session.mediaSink.drain();
+            setReferenceAttachments(session, options.referenceAttachments);
+            const unsubscribe = eventHandler ? session.agent.subscribe((event) => eventHandler(event)) : undefined;
+            const exitTurn = enterTurn?.();
+            try {
+                await dispatch(session);
+            }
+            finally {
+                try {
+                    await options.onTurnEnd?.();
+                }
+                catch (error) {
+                    console.error("turn end callback failed", error);
+                }
+                finally {
+                    setReferenceAttachments(session);
+                    exitTurn?.();
+                    unsubscribe?.();
+                }
+            }
+            return {
+                text: getLastAssistantText(session.agent),
+                attachments: session.mediaSink.drain(),
+            };
+        });
+        session.promptQueue = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const popLastAssistant = (session, action) => {
+        const messages = session.agent.state.messages;
+        const message = messages.at(-1);
+        if (!message || message.role !== "assistant") {
+            throw new Error(`No assistant message to ${action}`);
+        }
+        if (action === "retry" && message.stopReason === "aborted") {
+            throw new Error("Cannot retry an aborted assistant message");
+        }
+        session.agent.state.messages = messages.slice(0, -1);
+        writeTranscriptLog(config, {
+            ts: new Date().toISOString(),
+            sessionId: session.sessionId,
+            type: "supersede",
+            messageTimestamp: message.timestamp,
+        });
+    };
     return {
-        abort(sessionKey) {
+        async abort(sessionKey) {
             const session = sessions.get(sessionKey);
-            void session
-                ?.then((resolved) => {
+            if (!session)
+                return;
+            try {
+                const resolved = await session;
                 resolved.agent.abort();
                 resolved.agent.clearAllQueues();
-            })
-                .catch((error) => console.error(`failed to abort familiar session ${sessionKey}`, error));
+                await resolved.agent.waitForIdle();
+            }
+            catch (error) {
+                console.error(`failed to abort familiar session ${sessionKey}`, error);
+            }
+        },
+        async retryLastAssistant(sessionKey, eventHandler, options = {}) {
+            return runPromptTurn(sessionKey, options, eventHandler, async (session) => {
+                popLastAssistant(session, "retry");
+                await session.agent.continue();
+            });
         },
-        requestSoftStop(sessionKey) {
-            softStopRequested.set(sessionKey, true);
+        async deleteLastAssistant(sessionKey) {
+            const session = await getSession(sessionKey);
+            await session.promptQueue;
+            popLastAssistant(session, "delete");
         },
         async reset(sessionKey) {
             const existing = sessions.get(sessionKey);
             if (!existing)
                 return;
             const session = await existing;
-            softStopRequested.set(sessionKey, false);
             resetSession(session);
         },
         async reload() {
@@ -577,74 +397,23 @@ export async function createFamiliarAgent(config, settings, memoryService, optio
             return `Thinking set to ${clamped}${suffix} for this channel\nSupported: ${supportedThinkingLevels(model).join(", ")}`;
         },
         async prompt(sessionKey, input, imagesOrOnEvent, onEvent, options = {}) {
-            const session = await getSession(sessionKey);
             const images = Array.isArray(imagesOrOnEvent) ? imagesOrOnEvent : undefined;
             const eventHandler = Array.isArray(imagesOrOnEvent) ? onEvent : imagesOrOnEvent;
-            const run = session.promptQueue.then(async () => {
-                softStopRequested.set(sessionKey, false);
-                session.mediaSink.drain();
-                setReferenceAttachments(session, options.referenceAttachments);
-                const unsubscribe = eventHandler ? session.agent.subscribe((event) => eventHandler(event)) : undefined;
-                try {
-                    await session.agent.prompt(input, images);
-                }
-                finally {
-                    try {
-                        await options.onTurnEnd?.();
-                    }
-                    catch (error) {
-                        console.error("turn end callback failed", error);
-                    }
-                    finally {
-                        setReferenceAttachments(session);
-                        unsubscribe?.();
-                    }
-                }
-                return {
-                    text: getLastAssistantText(session.agent),
-                    attachments: session.mediaSink.drain(),
-                };
-            });
-            session.promptQueue = run.then(() => undefined, () => undefined);
-            return run;
+            return runPromptTurn(sessionKey, options, eventHandler, (session) => session.agent.prompt(input, images));
         },
         async promptMessage(sessionKey, message, onEvent, options = {}) {
-            const session = await getSession(sessionKey);
-            const run = session.promptQueue.then(async () => {
-                softStopRequested.set(sessionKey, false);
-                session.mediaSink.drain();
-                setReferenceAttachments(session, options.referenceAttachments);
-                const unsubscribe = onEvent ? session.agent.subscribe((event) => onEvent(event)) : undefined;
+            return runPromptTurn(sessionKey, options, onEvent, (session) => session.agent.prompt(message), () => {
                 const previousOptions = activePromptOptions.get(sessionKey);
                 activePromptOptions.set(sessionKey, options);
                 if (options.skipAmbient)
                     skipAmbientMessages.add(message);
-                try {
-                    await session.agent.prompt(message);
-                }
-                finally {
-                    try {
-                        await options.onTurnEnd?.();
-                    }
-                    catch (error) {
-                        console.error("turn end callback failed", error);
-                    }
-                    finally {
-                        setReferenceAttachments(session);
-                        if (previousOptions)
-                            activePromptOptions.set(sessionKey, previousOptions);
-                        else
-                            activePromptOptions.delete(sessionKey);
-                        unsubscribe?.();
-                    }
-                }
-                return {
-                    text: getLastAssistantText(session.agent),
-                    attachments: session.mediaSink.drain(),
+                return () => {
+                    if (previousOptions)
+                        activePromptOptions.set(sessionKey, previousOptions);
+                    else
+                        activePromptOptions.delete(sessionKey);
                 };
             });
-            session.promptQueue = run.then(() => undefined, () => undefined);
-            return run;
         },
         steer(sessionKey, input) {
             const session = sessions.get(sessionKey);

package/dist/browser-tools.js

@@ -142,6 +142,7 @@ function defaultBrowserRunner() {
             reject(new Error(`Browser command timed out after ${options.timeoutMs}ms.`));
         }, options.timeoutMs);
         const abort = () => {
+            clearTimeout(timeout);
             child.kill("SIGTERM");
             reject(new Error("Browser command aborted."));
         };
@@ -192,6 +193,15 @@ function parseJson(text) {
         return undefined;
     }
 }
+function parseOpenCliJsonOutput(result, context) {
+    if (result.json !== undefined)
+        return result.json;
+    const output = result.stdout.trim();
+    if (!output)
+        throw new Error(`OpenCLI ${context} returned no JSON output.`);
+    const tail = output.slice(-120).replace(/\s+/g, " ").trim();
+    throw new Error(`OpenCLI ${context} returned malformed JSON output near: ${tail || "(empty)"}`);
+}
 function stringArg(value) {
     if (value === undefined || value === null)
         return undefined;
@@ -522,24 +532,47 @@ function assertSiteAllowed(config, site) {
     if (!config.browser.allowedSites[site])
         throw new Error(`OpenCLI site is not allowlisted: ${site}`);
 }
+function commandInfoFromJson(json) {
+    if (!isRecord(json))
+        return undefined;
+    const name = stringArg(json.name);
+    if (!name)
+        return undefined;
+    return {
+        name,
+        access: stringArg(json.access) ?? "unknown",
+        description: stringArg(json.description),
+        usage: stringArg(json.usage),
+    };
+}
 function parseSiteCommands(json) {
     const commands = isRecord(json) && Array.isArray(json.commands) ? json.commands : [];
-    return commands.flatMap((command) => {
-        if (!isRecord(command))
-            return [];
-        const name = stringArg(command.name);
-        if (!name)
+    return {
+        commands: commands.flatMap((command) => {
+            const info = commandInfoFromJson(command);
+            return info ? [info] : [];
+        }),
+        complete: true,
+    };
+}
+function parsePlainSiteHelp(site, text) {
+    const commandSection = text.match(/Commands:\n(?<body>[\s\S]*?)(?:\n\n[A-Z][^\n]* options:|\n\nCommon options:|\n\nBrowser common options:|\n\nAgent tip:|$)/);
+    const body = commandSection?.groups?.body;
+    if (!body)
+        return undefined;
+    const commands = body.split("\n").flatMap((line) => {
+        const match = line.match(/^\s{2}(?<name>[A-Za-z0-9._-]+)\b.*\[(?<access>read|write|admin)\]/);
+        if (!match?.groups)
             return [];
-        const access = stringArg(command.access) ?? "unknown";
         return [
             {
-                name,
-                access,
-                description: stringArg(command.description),
-                usage: stringArg(command.usage),
+                name: match.groups.name,
+                access: match.groups.access,
+                usage: `opencli ${site} ${match.groups.name}`,
             },
         ];
     });
+    return { commands, complete: false };
 }
 async function loadSiteCommands(site, config, runner, signal) {
     const result = await runner(openCliSpec(config, [...baseArgs(config), site, "--help", "-f", "json"]), {
@@ -548,15 +581,35 @@ async function loadSiteCommands(site, config, runner, signal) {
     });
     if (!result.ok)
         throw new Error(formatBrowserResult(result, config.browser.maxOutputChars).text);
-    return parseSiteCommands(result.json);
+    try {
+        return parseSiteCommands(parseOpenCliJsonOutput(result, `${site} metadata`));
+    }
+    catch (error) {
+        const plainResult = await runner(openCliSpec(config, [...baseArgs(config), site, "--help"]), {
+            timeoutMs: config.browser.timeoutMs,
+            signal,
+        });
+        if (!plainResult.ok)
+            throw error;
+        const plainListing = parsePlainSiteHelp(site, plainResult.stdout);
+        if (!plainListing)
+            throw error;
+        return plainListing;
+    }
 }
-function findSiteCommand(commands, site, command) {
-    const match = commands.find((item) => item.name === command);
-    if (!match)
+async function loadSiteCommand(site, command, config, runner, signal) {
+    const result = await runner(openCliSpec(config, [...baseArgs(config), site, command, "--help", "-f", "json"]), {
+        timeoutMs: config.browser.timeoutMs,
+        signal,
+    });
+    if (!result.ok)
+        throw new Error(formatBrowserResult(result, config.browser.maxOutputChars).text);
+    const info = commandInfoFromJson(parseOpenCliJsonOutput(result, `${site} ${command} metadata`));
+    if (!info || info.name !== command)
         throw new Error(`OpenCLI site command is not available: ${site} ${command}`);
-    return match;
+    return info;
 }
-function buildSiteArgs(input, config, commandInfo) {
+function resolveSiteCommand(input, config) {
     const site = stringArg(input.site);
     const command = stringArg(input.command);
     if (!site || !command)
@@ -564,6 +617,10 @@ function buildSiteArgs(input, config, commandInfo) {
     assertSafeName(site, "browser.site");
     assertSafeName(command, "browser.command");
     assertSiteAllowed(config, site);
+    return { site, command };
+}
+function buildSiteArgs(input, config, commandInfo) {
+    const { site, command } = resolveSiteCommand(input, config);
     if (commandInfo.access === "write" && !config.browser.readWrite) {
         throw new Error(`OpenCLI write command is disabled until browser.read_write is true: ${site} ${command}`);
     }
@@ -596,15 +653,9 @@ function buildSiteArgs(input, config, commandInfo) {
     return args;
 }
 async function buildSiteRunSpec(input, config, runner, signal) {
-    const site = stringArg(input.site);
-    const command = stringArg(input.command);
-    if (!site || !command)
-        throw new Error("browser site mode requires site and command.");
-    assertSafeName(site, "browser.site");
-    assertSafeName(command, "browser.command");
-    assertSiteAllowed(config, site);
-    const commands = await loadSiteCommands(site, config, runner, signal);
-    return openCliSpec(config, buildSiteArgs(input, config, findSiteCommand(commands, site, command)));
+    const { site, command } = resolveSiteCommand(input, config);
+    const commandInfo = await loadSiteCommand(site, command, config, runner, signal);
+    return openCliSpec(config, buildSiteArgs(input, config, commandInfo));
 }
 function buildRunSpec(input, config) {
     const backend = pageBackend(input, config);
@@ -622,15 +673,16 @@ async function listCommands(input, config, runner, signal) {
     const sites = site ? [site] : Object.keys(config.browser.allowedSites);
     const lines = ["allowlisted site commands:"];
     for (const name of sites) {
-        const commands = await loadSiteCommands(name, config, runner, signal);
+        const listing = await loadSiteCommands(name, config, runner, signal);
         const groups = new Map();
-        for (const command of commands) {
+        for (const command of listing.commands) {
             const names = groups.get(command.access) ?? [];
             names.push(command.name);
             groups.set(command.access, names);
         }
         const parts = Array.from(groups.entries()).map(([access, names]) => `${access}=[${names.join(", ")}]`);
-        lines.push(`- ${name}: ${parts.join(" ")}`);
+        const suffix = listing.complete ? "" : " (from plain help)";
+        lines.push(`- ${name}: ${parts.join(" ")}${suffix}`);
     }
     return lines.join("\n");
 }