codex-chatgpt-control 0.1.0-alpha.1 → 0.2.0-alpha.1

package/dist/src/commands/registry.js

@@ -8,10 +8,10 @@ const descriptors = [
         `await chatgpt.askInThread({ thread: { type: "url", url: "https://chatgpt.com/c/<conversation-id>" }, existingTab: true, prompt: "Continue." });`
     ]),
     workflow("askWithFiles", "Attach absolute local file paths, optionally set mode, ask, wait, and read.", [
-        `await chatgpt.askWithFiles({ thread: { type: "url", url: "https://chatgpt.com/c/<conversation-id>" }, existingTab: true, mode: { effort: "Thinking" }, files: ["/absolute/path/brief.md"], prompt: "Summarize this.", wait: true, read: { format: "markdown" } });`
+        `await chatgpt.askWithFiles({ thread: { type: "url", url: "https://chatgpt.com/c/<conversation-id>" }, existingTab: true, mode: { model: "Pro" }, files: ["/absolute/host/path/brief.md"], prompt: "Summarize this.", wait: true, read: { format: "markdown" } });`
     ]),
     workflow("askAndDownload", "Ask ChatGPT to produce a visible downloadable output and save the latest exposed file.", [
-        `await chatgpt.askAndDownload({ prompt: "Create a CSV.", download: { destDir: "/tmp/out" }, wait: true });`
+        `await chatgpt.askAndDownload({ prompt: "Create a CSV.", download: { destDir: "/absolute/host/output" }, wait: true });`
     ]),
     workflow("runMessages", "Run sequential prompts where later prompts can use earlier step data.", [
         `await chatgpt.runMessages({ messages: [{ id: "first", prompt: "alpha" }, { id: "second", prompt: "beta" }] });`
@@ -39,10 +39,10 @@ const descriptors = [
         `await chatgpt.runPlan({ name: "find-open-copy-latest", input: { query: "SDK Design Proposal" } });`
     ]),
     workflow("attach-ask-read", "Named macro: open a new thread, attach files, ask, wait, and read Markdown.", [
-        `await chatgpt.runPlan({ name: "attach-ask-read", input: { files: ["/absolute/path.md"], prompt: "Summarize." } });`
+        `await chatgpt.runPlan({ name: "attach-ask-read", input: { files: ["/absolute/host/path.md"], prompt: "Summarize." } });`
     ]),
     workflow("ask-and-download", "Named macro: ask in a new thread and download the latest file affordance.", [
-        `await chatgpt.runPlan({ name: "ask-and-download", input: { prompt: "Create a CSV.", destDir: "/tmp/out" } });`
+        `await chatgpt.runPlan({ name: "ask-and-download", input: { prompt: "Create a CSV.", destDir: "/absolute/host/output" } });`
     ]),
     workflow("two-turn", "Named macro: run two sequential prompts in a new thread.", [
         `await chatgpt.runPlan({ name: "two-turn", input: { first: "alpha", second: "beta" } });`
@@ -53,11 +53,14 @@ const descriptors = [
     report("redacted-run-report", "Named macro: create a redacted report for a supplied CommandResult.", [
         `await chatgpt.runPlan({ name: "redacted-run-report", input: { result } });`
     ]),
-    diagnostic("doctor", "Preflight browser bridge, login, upload, download, clipboard, mode, and tool readiness.", [
-        `await chatgpt.doctor({ check: ["bridge", "login", "upload"] });`
+    diagnostic("doctor", "Preflight browser bridge, login, upload, local files, existing-tab, artifact, localization, report, and selector readiness.", [
+        `await chatgpt.doctor({ check: ["bridge", "login", "upload"] });`,
+        `await chatgpt.doctor({ check: ["existing_tab"], existingTab: { target: { type: "conversationId", conversationId: "<conversation-id>" }, ifMissing: "block" } });`,
+        `await chatgpt.doctor({ check: ["file_preflight"], files: ["/absolute/host/path.md"] });`,
+        `await chatgpt.doctor({ check: ["localization", "reports"], report: { destDir: "/absolute/host/reports" } });`
     ]),
     report("createReport", "Write a durable redacted run report for a command result.", [
-        `await chatgpt.createReport(result, { destDir: "/tmp/reports" });`
+        `await chatgpt.createReport(result, { destDir: "/absolute/host/reports" });`
     ]),
     primitive("session.bootstrap", "Attach to ChatGPT in Chrome and detect login/blocker state.", 30000),
     primitive("threads.new", "Open a new ChatGPT thread.", 30000),
@@ -69,10 +72,17 @@ const descriptors = [
     primitive("messages.wait", "Wait for the latest assistant response to stabilize.", 120000),
     primitive("messages.readLatest", "Read the latest message as Markdown, normalized text, blocks, or HTML.", 30000),
     primitive("messages.waitAndRead", "Wait for completion and read the latest message.", 120000),
+    primitive("artifacts.listLatest", "Detect the latest visible generated ChatGPT artifact, such as an image-only result.", 30000),
+    primitive("artifacts.wait", "Wait for a visible generated ChatGPT artifact to appear and stabilize.", 120000),
+    primitive("artifacts.downloadLatest", "Download or save the latest visible generated ChatGPT artifact.", 120000),
+    primitive("files.preflight", "Validate local file paths, size limits, duplicates, zero-byte files, and extension-based MIME/category guesses without opening ChatGPT.", 30000),
     primitive("files.attach", "Attach absolute local file paths through visible ChatGPT upload controls.", 180000),
     primitive("files.downloadLatest", "Download the latest visible ChatGPT file affordance.", 120000),
+    primitive("projects.sources.list", "Open or claim a visible ChatGPT Project Sources tab and list source names/statuses without source contents.", 30000),
+    primitive("projects.sources.planAdd", "Dry-run an append-only Project Sources file add from explicit local files without opening ChatGPT.", 30000),
+    primitive("projects.sources.add", "Append explicit local files to a visible ChatGPT Project Sources list after confirmMutation: true.", 180000),
     primitive("response.copy", "Click Copy response and return clipboard Markdown, with DOM fallback.", 5000),
-    primitive("modes.set", "Select a visible model or effort candidate when unambiguous.", 30000),
+    primitive("modes.set", "Select a visible model, intelligence, effort, or nested model-version candidate when unambiguous.", 30000),
     primitive("tools.select", "Select a visible ChatGPT tool when unambiguous.", 30000)
 ];
 export function commandDescriptors() {
@@ -186,7 +196,7 @@ function workflowArgs(name) {
             prompt: "message to send after files are attached",
             thread: "optional thread selector",
             existingTab: "true or explicit policy to claim a user-open Chrome tab instead of opening a replacement",
-            mode: "optional visible mode selection, e.g. { effort: \"Thinking\" }",
+            mode: "optional visible mode selection, e.g. { model: \"Pro\" } or { intelligence: \"Pro\", modelVersion: \"5.4\" }",
             wait: "true or wait options; defaults to true",
             read: "true or read options such as { format: \"markdown\" }; defaults to Markdown",
             report: "optional redacted report settings"
@@ -209,7 +219,12 @@ function workflowDefaults(name) {
 function diagnosticArgs(name) {
     if (name === "doctor-upload")
         return {};
-    return { check: "optional list of readiness checks" };
+    return {
+        check: "optional list of readiness checks",
+        existingTab: "optional exact existing-tab policy for check: [\"existing_tab\"]",
+        files: "optional file paths for check: [\"file_preflight\"]",
+        report: "optional report output policy for check: [\"reports\"]"
+    };
 }
 function reportArgs(name) {
     if (name === "redacted-run-report")
@@ -219,16 +234,33 @@ function reportArgs(name) {
 function primitiveArgs(name) {
     if (name === "messages.readLatest")
         return { role: "assistant or user", format: "markdown, normalized_text, visible_text, html, blocks, or all" };
+    if (name === "artifacts.listLatest")
+        return { kind: "artifact kind; currently image", max: "maximum artifacts to return" };
+    if (name === "artifacts.wait")
+        return { kind: "artifact kind; currently image", afterArtifactCount: "baseline artifact count", requireDownload: "wait until a download affordance is visible" };
+    if (name === "artifacts.downloadLatest")
+        return { destDir: "download destination directory", prefer: "download_control or visible_image_source" };
     if (name === "response.copy")
         return { prefer: "clipboard or dom", format: "markdown, normalized_text, visible_text, html, blocks, or all" };
     if (name.startsWith("threads.search"))
         return { query: "history search query" };
+    if (name === "files.preflight")
+        return { paths: "absolute local file paths", maxBytesPerFile: "optional local per-file byte limit", maxTotalBytes: "optional local total byte limit" };
     if (name.startsWith("files.attach"))
         return { paths: "absolute local file paths" };
+    if (name === "projects.sources.list")
+        return { projectUrl: "ChatGPT Project URL such as https://chatgpt.com/g/g-p-.../project", existingTab: "optional exact existing-tab policy", timeoutMs: "optional browser timeout" };
+    if (name === "projects.sources.planAdd")
+        return { projectUrl: "ChatGPT Project URL", files: "explicit absolute local file paths", batchSize: "optional upload batch size" };
+    if (name === "projects.sources.add")
+        return { projectUrl: "ChatGPT Project URL", files: "explicit absolute local file paths", confirmMutation: "must be true to mutate Project Sources", batchSize: "optional upload batch size" };
     if (name === "modes.set") {
         return {
-            effort: "visible effort label such as Thinking or Extended",
-            model: "visible model label such as Instant, Pro, or another available model",
+            effort: "visible legacy effort label such as Thinking or Extended",
+            intelligence: "visible intelligence label such as Medium, High, Extra High, or Pro",
+            model: "visible model label such as Pro, GPT-5.5, or another available model",
+            modelVersion: "visible nested model version such as 5.5, 5.4, 4.5, or o3",
+            version: "alias for modelVersion",
             timeoutMs: "optional timeout for opening and selecting the visible mode menu"
         };
     }
@@ -237,20 +269,50 @@ function primitiveArgs(name) {
 function primitiveExamples(name) {
     if (name === "modes.set") {
         return [
+            `await chatgpt.modes.set({ model: "Pro" });`,
+            `await chatgpt.modes.set({ intelligence: "Pro", modelVersion: "5.4" });`,
             `await chatgpt.modes.set({ effort: "Thinking" });`,
-            `await chatgpt.askWithFiles({ mode: { effort: "Thinking" }, files: ["/absolute/path.jpg"], prompt: "Describe this image.", wait: true });`
+            `await chatgpt.askWithFiles({ mode: { model: "Pro" }, files: ["/absolute/host/path.jpg"], prompt: "Describe this image.", wait: true });`
+        ];
+    }
+    if (name === "files.preflight") {
+        return [
+            `await chatgpt.files.preflight({ paths: ["/absolute/host/path.md"] });`
         ];
     }
     if (name === "files.attach") {
-        return [`await chatgpt.files.attach({ paths: ["/absolute/path.jpg"] });`];
+        return [
+            `await chatgpt.files.attach({ paths: ["/absolute/host/path.jpg"] });`,
+            String.raw `// On Windows backend hosts, use paths such as C:\Users\you\Pictures\image.jpg.`
+        ];
+    }
+    if (name === "projects.sources.list") {
+        return [`await chatgpt.projects.sources.list({ projectUrl: "https://chatgpt.com/g/g-p-example/project" });`];
+    }
+    if (name === "projects.sources.planAdd") {
+        return [`await chatgpt.projects.sources.planAdd({ projectUrl: "https://chatgpt.com/g/g-p-example/project", files: ["/absolute/host/path.md"] });`];
+    }
+    if (name === "projects.sources.add") {
+        return [`await chatgpt.projects.sources.add({ projectUrl: "https://chatgpt.com/g/g-p-example/project", files: ["/absolute/host/path.md"], confirmMutation: true });`];
+    }
+    if (name.startsWith("artifacts.")) {
+        return [`await chatgpt.artifacts.downloadLatest({ destDir: "/absolute/host/output" });`];
     }
     return [];
 }
 function primitiveBlockers(name) {
+    if (name === "files.preflight")
+        return ["not_found", "permission", "upload_failed"];
     if (name.startsWith("files.attach"))
         return ["browser_bridge_unavailable", "login_required", "permission", "upload_failed"];
     if (name.startsWith("files.download"))
         return ["browser_bridge_unavailable", "login_required", "download_unavailable"];
+    if (name === "projects.sources.planAdd")
+        return ["not_found", "permission", "upload_failed"];
+    if (name.startsWith("projects.sources."))
+        return ["browser_bridge_unavailable", "login_required", "selector_drift", "confirmation", "permission", "upload_failed"];
+    if (name.startsWith("artifacts."))
+        return ["browser_bridge_unavailable", "login_required", "artifact_unavailable", "artifact_selector_drift", "artifact_download_unavailable"];
     if (name.startsWith("modes.") || name.startsWith("tools."))
         return ["browser_bridge_unavailable", "login_required", "selector_drift"];
     return commonBlockers();

package/dist/src/commands/reports.d.ts

@@ -1,14 +1,23 @@
+import { type IntegritySidecar } from "../safety/untrusted-output.js";
 import type { CommandResult, RuntimeEnv } from "../types.js";
+export type RunReportIntegrityOptions = {
+    inputPaths?: string[];
+    prompt?: string;
+    outputText?: string;
+};
 export type RunReportOptions = {
     enabled?: boolean;
     destDir?: string;
     basename?: string;
     includeContent?: boolean;
     maxPreviewChars?: number;
+    integrity?: boolean | RunReportIntegrityOptions;
 };
 export type RunReportData = {
     path: string;
     bytes: number;
     includeContent: boolean;
+    metaPath?: string;
+    integrity?: Pick<IntegritySidecar, "schemaVersion" | "target" | "prompt" | "output" | "inputs">;
 };
 export declare function createRunReport(env: RuntimeEnv, result: CommandResult<unknown>, options?: RunReportOptions): Promise<CommandResult<RunReportData>>;

package/dist/src/commands/reports.js

@@ -1,13 +1,14 @@
-import { mkdir, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { resultError, resultOk } from "../errors.js";
 import { redactReportValue } from "../safety/report-redaction.js";
+import { writeFileAtomicNoOverwrite, writeJsonArtifactWithIntegrity } from "../safety/untrusted-output.js";
 import { contextFromPage } from "./context.js";
 export async function createRunReport(env, result, options = {}) {
     try {
         const destDir = options.destDir ?? "reports/runs";
-        await mkdir(destDir, { recursive: true });
-        const stamp = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+        const now = env.now?.() ?? new Date();
+        const createdAt = now.toISOString();
+        const stamp = createdAt.replaceAll(":", "-").replaceAll(".", "-");
         const safeBase = sanitizeBasename(options.basename ?? "chatgpt-run-report");
         const path = join(destDir, `${stamp}-${safeBase}.json`);
         const includeContent = options.includeContent === true;
@@ -31,9 +32,36 @@ export async function createRunReport(env, result, options = {}) {
             })),
             data: redactReportValue(result.data, options)
         };
-        await writeFile(path, `${JSON.stringify(report, null, 2)}\n`, "utf8");
-        const saved = await stat(path);
-        return resultOk({ path, bytes: saved.size, includeContent }, await contextFromPage(env.page));
+        if (options.integrity === false) {
+            const payload = `${JSON.stringify(report, null, 2)}\n`;
+            await writeFileAtomicNoOverwrite(path, payload);
+            return resultOk({ path, bytes: Buffer.byteLength(payload, "utf8"), includeContent }, await contextFromPage(env.page));
+        }
+        const integrity = integrityOptions(result, options.integrity);
+        const writeOptions = { createdAt };
+        if (integrity.prompt !== undefined)
+            writeOptions.prompt = integrity.prompt;
+        if (integrity.outputText !== undefined)
+            writeOptions.outputText = integrity.outputText;
+        if (integrity.inputPaths !== undefined)
+            writeOptions.inputPaths = integrity.inputPaths;
+        const saved = await writeJsonArtifactWithIntegrity(path, report, writeOptions);
+        const reportIntegrity = {
+            schemaVersion: saved.sidecar.schemaVersion,
+            target: saved.sidecar.target,
+            inputs: saved.sidecar.inputs
+        };
+        if (saved.sidecar.prompt !== undefined)
+            reportIntegrity.prompt = saved.sidecar.prompt;
+        if (saved.sidecar.output !== undefined)
+            reportIntegrity.output = saved.sidecar.output;
+        return resultOk({
+            path,
+            bytes: saved.bytes,
+            includeContent,
+            metaPath: saved.metaPath,
+            integrity: reportIntegrity
+        }, await contextFromPage(env.page));
     }
     catch (error) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(env.page));
@@ -45,3 +73,52 @@ function sanitizeBasename(name) {
         .replace(/^-+|-+$/g, "")
         || "chatgpt-run-report";
 }
+function integrityOptions(result, options) {
+    if (typeof options === "object") {
+        const normalized = {
+            inputPaths: [...new Set(options.inputPaths ?? [])]
+        };
+        const prompt = options.prompt ?? promptFromResult(result);
+        const outputText = options.outputText ?? outputTextFromResult(result);
+        if (prompt !== undefined)
+            normalized.prompt = prompt;
+        if (outputText !== undefined)
+            normalized.outputText = outputText;
+        return normalized;
+    }
+    const normalized = {
+        inputPaths: []
+    };
+    const prompt = promptFromResult(result);
+    const outputText = outputTextFromResult(result);
+    if (prompt !== undefined)
+        normalized.prompt = prompt;
+    if (outputText !== undefined)
+        normalized.outputText = outputText;
+    return normalized;
+}
+function promptFromResult(result) {
+    return findStringByKey(result.data, new Set(["prompt", "input", "userTurnText"]));
+}
+function outputTextFromResult(result) {
+    if (typeof result.output_text === "string")
+        return result.output_text;
+    return findStringByKey(result.data, new Set(["responseText", "markdown", "text", "normalizedText", "visibleText"]));
+}
+function findStringByKey(value, keys) {
+    if (!isRecord(value))
+        return undefined;
+    for (const [key, child] of Object.entries(value)) {
+        if (keys.has(key) && typeof child === "string" && child.length > 0)
+            return child;
+    }
+    for (const child of Object.values(value)) {
+        const nested = findStringByKey(child, keys);
+        if (nested !== undefined)
+            return nested;
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/src/commands/response-actions.js

@@ -1,4 +1,5 @@
 import { readSystemClipboard, waitForClipboardChange } from "../browser/clipboard.js";
+import { readAssistantGenerationState } from "../dom/generation-state.js";
 import { formatClipboardMarkdown, normalizeResponseFormat } from "../dom/message-format.js";
 import { resultError, resultOk } from "../errors.js";
 import { readLatestMessage, readMessages } from "../dom/messages.js";
@@ -13,6 +14,31 @@ export async function copyResponse(env, args = {}) {
     }
     const page = env.page;
     try {
+        if (isLatestSelection(args.which)) {
+            const generation = await readAssistantGenerationState(page);
+            if (generation.active || generation.stopped) {
+                const latest = await readSelectedAssistantMessage(page, args.which, args.format ?? "markdown").catch(() => undefined);
+                const warning = generation.active
+                    ? "Response is still generating; copied content may be partial."
+                    : "Response appears to have been stopped before completion; copied content may be partial.";
+                const fallbackReason = generation.active
+                    ? "Response is still generating; returned DOM-derived partial content."
+                    : "Response appears to have been stopped before completion; returned DOM-derived partial content.";
+                const data = latest === undefined ? undefined : copiedResponseFromExtracted(latest, "dom", fallbackReason);
+                const result = {
+                    ok: false,
+                    status: "partial",
+                    warnings: [
+                        warning,
+                        ...generation.signals.map(signal => `Generation state signal: ${signal}`)
+                    ],
+                    context: await contextFromPage(page)
+                };
+                if (data !== undefined)
+                    result.data = data;
+                return withCommandOutputText(result);
+            }
+        }
         if (args.prefer !== "dom") {
             const before = await readClipboard(env);
             const buttons = copyResponseButtons(page);
@@ -73,6 +99,9 @@ export async function copyResponse(env, args = {}) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
     }
 }
+function isLatestSelection(which) {
+    return which === undefined || which === "latest";
+}
 function readClipboard(env) {
     return env.clipboard?.read() ?? readSystemClipboard();
 }
@@ -97,6 +126,8 @@ function copiedResponseFromExtracted(latest, source, fallbackReason) {
     };
     if (latest.fidelity !== undefined)
         data.fidelity = latest.fidelity;
+    if (latest.captureLimit !== undefined)
+        data.captureLimit = latest.captureLimit;
     if (latest.warnings !== undefined || fallbackReason !== undefined) {
         data.warnings = [...(latest.warnings ?? []), ...(fallbackReason === undefined ? [] : [fallbackReason])];
     }
@@ -110,6 +141,8 @@ function mergeResponseMetadata(data, latest) {
         return;
     if (latest.markdown !== undefined && data.markdown === undefined)
         data.markdown = latest.markdown;
+    if (latest.captureLimit !== undefined)
+        data.captureLimit = latest.captureLimit;
     if (latest.visibleText !== undefined)
         data.visibleText = latest.visibleText;
     if (latest.normalizedText !== undefined)

package/dist/src/commands/sequence.js

@@ -1,4 +1,6 @@
+import { downloadLatestArtifact, listLatestArtifacts, waitForArtifact } from "./artifacts.js";
 import { attachFiles, downloadLatestFile } from "./files.js";
+import { addProjectSources, buildProjectSourceAddPlan, listProjectSources } from "./project-sources.js";
 import { askMessage, composeMessage, readLatest, submitMessage, waitAndRead, waitForMessage } from "./messages.js";
 import { copyResponse } from "./response-actions.js";
 import { bootstrap } from "./session.js";
@@ -59,10 +61,22 @@ export async function executeStep(step, env, previousResults) {
             return readLatest(env, step.args);
         case "messages.waitAndRead":
             return waitAndRead(env, step.args);
+        case "artifacts.listLatest":
+            return listLatestArtifacts(env, step.args);
+        case "artifacts.wait":
+            return waitForArtifact(env, step.args);
+        case "artifacts.downloadLatest":
+            return downloadLatestArtifact(env, step.args);
         case "files.attach":
             return attachFiles(env, step.args);
         case "files.downloadLatest":
             return downloadLatestFile(env, step.args);
+        case "projects.sources.list":
+            return listProjectSources(env, step.args);
+        case "projects.sources.planAdd":
+            return buildProjectSourceAddPlan(env, step.args);
+        case "projects.sources.add":
+            return addProjectSources(env, step.args);
         case "response.copy":
             return copyResponse(env, step.args);
         case "modes.set":

package/dist/src/commands/threads.js

@@ -2,6 +2,7 @@ import { parseConversationId, readPageState } from "../browser/page-state.js";
 import { resultError, resultOk } from "../errors.js";
 import { countPageMessages, readLatestMessageText } from "../dom/messages.js";
 import { requiredLocator, searchChatsButton, searchChatsInput, newChatButton } from "../dom/selectors.js";
+import { anyLabelPattern, localeLabels } from "../dom/locale-labels.js";
 import { normalizeWhitespace, stripTags } from "../dom/visible-text.js";
 import { contextFromPage } from "./context.js";
 import { bootstrap } from "./session.js";
@@ -237,7 +238,7 @@ async function openSearchUI(page) {
 async function fillSearchQuery(page, query) {
     const attempts = [
         async () => searchChatsInput(page).fill?.(query),
-        async () => page.getByRole?.("textbox", { name: "Search chats" }).fill?.(query),
+        async () => page.getByRole?.("textbox", { name: anyLabelPattern(localeLabels.searchChatsButton) }).fill?.(query),
         async () => page.getByRole?.("textbox", { name: /Search chats/i }).fill?.(query),
         async () => requiredLocator(page, "input[placeholder*='Search'], [role='dialog'] input").fill?.(query)
     ];

package/dist/src/commands/timeouts.d.ts

@@ -0,0 +1,2 @@
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
+export declare function localGuardTimeout(timeoutMs: number | undefined, capMs: number): number;

package/dist/src/commands/timeouts.js

@@ -0,0 +1,18 @@
+export async function withTimeout(promise, timeoutMs, message) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => reject(new Error(message)), Math.max(0, timeoutMs));
+            })
+        ]);
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+}
+export function localGuardTimeout(timeoutMs, capMs) {
+    return Math.max(1, Math.min(timeoutMs ?? capMs, capMs));
+}

package/dist/src/diagnostics/blockers.d.ts

@@ -0,0 +1,54 @@
+import type { CommandContext, CommandResult, ExistingTabDiagnostics } from "../types.js";
+type RemediationStep = NonNullable<NonNullable<CommandResult["blocker"]>["remediation"]>[number];
+type VisibleCandidate = NonNullable<NonNullable<CommandResult["blocker"]>["candidates"]>[number];
+export type BlockerSeverity = "info" | "warning" | "action_required" | "blocked";
+export type BlockerCategory = "environment" | "auth" | "permission" | "ui_drift" | "user_confirmation" | "targeting" | "runtime" | "not_found" | "artifact" | "download" | "upload" | "unknown";
+export type BlockerRetryGuidance = {
+    safe: true;
+    when: string;
+    command?: string;
+} | {
+    safe: false;
+    reason: string;
+};
+export type BlockerResumeGuidance = {
+    supported: true;
+    stateId?: string;
+    command?: string;
+} | {
+    supported: false;
+    reason: string;
+};
+export type BlockerExplanation = {
+    kind: string;
+    code?: string;
+    title: string;
+    summary: string;
+    severity: BlockerSeverity;
+    category: BlockerCategory;
+    userActionRequired: boolean;
+    retry: BlockerRetryGuidance;
+    resume: BlockerResumeGuidance;
+    remediation: RemediationStep[];
+    candidates?: VisibleCandidate[];
+    context?: {
+        command?: string;
+        url?: string;
+        conversationId?: string;
+        tabId?: string;
+    };
+    diagnostics?: {
+        existingTab?: ExistingTabDiagnostics;
+    };
+    nextCommands: string[];
+    markdown: string;
+};
+export type ExplainBlockerOptions = {
+    command?: string;
+    context?: Partial<CommandContext>;
+    stateId?: string;
+    nextCommands?: string[];
+};
+type Blocker = NonNullable<CommandResult["blocker"]>;
+export declare function explainCommandBlocker(resultOrBlocker: CommandResult<unknown> | Blocker | undefined, options?: ExplainBlockerOptions): BlockerExplanation;
+export {};