codex-chatgpt-control 0.5.1-alpha.2 → 0.5.1-alpha.3

package/dist/src/runner/responses.d.ts

@@ -3,6 +3,8 @@ import type { BootstrapArgs, ChatGPTExperience, ConfigurationSelection, Response
 import type { ChatGPTAttachmentInput, ChatGPTInputItem, ChatGPTResponse, ChatGPTRunInput, ChatGPTRunResult, ChatGPTThreadSelector, ChatGPTVisibleModePreference, ChatGPTVisibleToolPreference, UnsupportedField } from "./types.js";
 export type ChatGPTResponsesCreateArgs = {
     input: string | ChatGPTInputItem[];
+    /** Caller-owned durable identity; opts this invocation into operations.run. */
+    operationId?: string;
     thread?: ChatGPTThreadSelector;
     existingTab?: BootstrapArgs["existingTab"];
     preferExistingTab?: boolean;
@@ -29,4 +31,4 @@ export type ResponsesValidationResult = {
 export declare function validateResponsesCreateArgs(args: Record<string, unknown>): ResponsesValidationResult;
 export declare function responsesCreateArgsToRunInput(args: ChatGPTResponsesCreateArgs): ChatGPTRunInput;
 export declare function responseFromRunResult<TOutput>(result: ChatGPTRunResult<TOutput>, now?: Date): ChatGPTResponse;
-export declare function unsupportedResponse(unsupported: UnsupportedField[], now?: Date): ChatGPTResponse;
+export declare function unsupportedResponse(unsupported: UnsupportedField[], now?: Date, operationId?: string): ChatGPTResponse;

package/dist/src/runner/responses.js

@@ -1,6 +1,7 @@
 import { renderUntrustedOutputReturnEnvelope } from "../safety/untrusted-output.js";
 const acceptedTopLevelFields = new Set([
     "input",
+    "operationId",
     "thread",
     "existingTab",
     "preferExistingTab",
@@ -38,6 +39,7 @@ const responseFormats = new Set([
     "blocks",
     "all"
 ]);
+const operationIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
 export function validateResponsesCreateArgs(args) {
     const unsupported = [];
     for (const [path, alternative] of Object.entries(unsupportedAlternatives)) {
@@ -61,6 +63,13 @@ export function validateResponsesCreateArgs(args) {
             alternative: "Provide input: \"your visible prompt\"."
         });
     }
+    if (args.operationId !== undefined && (typeof args.operationId !== "string" || !operationIdPattern.test(args.operationId))) {
+        unsupported.push({
+            path: "operationId",
+            reason: "operationId must be a canonical UUID when provided.",
+            alternative: "Provide a caller-owned UUID, or omit operationId to retain the legacy runner path."
+        });
+    }
     if (args.stream !== undefined && args.stream !== false) {
         unsupported.push({
             path: "stream",
@@ -108,6 +117,8 @@ export function responsesCreateArgsToRunInput(args) {
         input: args.input,
         response: { format: args.text?.format ?? "markdown" }
     };
+    if (args.operationId !== undefined)
+        runInput.operationId = args.operationId;
     if (args.thread !== undefined)
         runInput.thread = args.thread;
     if (args.existingTab !== undefined)
@@ -148,6 +159,12 @@ export function responseFromRunResult(result, now = new Date()) {
         browserControl.completionState = completionState;
     if (generationActive !== undefined)
         browserControl.generationActive = generationActive;
+    const operationId = result.data?.operationId;
+    if (operationId !== undefined)
+        browserControl.operationId = operationId;
+    const handle = result.data?.handle;
+    if (handle !== undefined)
+        browserControl.handle = handle;
     if (result.output_text.length > 0) {
         const envelopeArgs = {
             outputText: result.output_text,
@@ -173,7 +190,7 @@ export function responseFromRunResult(result, now = new Date()) {
         browser_control: browserControl
     };
 }
-export function unsupportedResponse(unsupported, now = new Date()) {
+export function unsupportedResponse(unsupported, now = new Date(), operationId) {
     return {
         id: responseId(now),
         object: "chatgpt.browser.response",
@@ -184,6 +201,7 @@ export function unsupportedResponse(unsupported, now = new Date()) {
         browser_control: {
             visibleUi: true,
             resultStatus: "unsupported",
+            ...(operationId === undefined ? {} : { operationId }),
             unsupported
         }
     };

package/dist/src/runner/result.js

@@ -1,14 +1,26 @@
 import { renderUntrustedOutputReturnEnvelope } from "../safety/untrusted-output.js";
 import { interruptionFromCommandResult } from "./interruptions.js";
 import { augmentCommandBlocker } from "./resume.js";
+const MAX_RESULT_TRAVERSAL_DEPTH = 16;
+const MAX_RESULT_TRAVERSAL_NODES = 2_048;
 export function toRunResult(agent, result) {
-    const outputText = extractOutputText(result.data);
+    const extractedOutput = extractOutput(result.data);
+    const outputText = extractedOutput?.text ?? "";
     const finalOutput = parseFinalOutput(agent, outputText);
     const interruption = interruptionFromCommandResult(result, failedCommand(result));
     const interruptions = interruption === undefined ? [] : [interruption];
-    const output = runItemsFromResult(result, outputText);
+    const output = runItemsFromResult(result, outputText, extractedOutput?.source);
     const state = runStateFromResult(result, interruptions);
     const data = { outputText };
+    const operationId = readOperationId(result.data);
+    const handle = readOperationHandle(result.data);
+    const requestDigest = readRequestDigest(result.data);
+    if (operationId !== undefined)
+        data.operationId = operationId;
+    if (handle !== undefined)
+        data.handle = handle;
+    if (requestDigest !== undefined)
+        data.requestDigest = requestDigest;
     const submissionState = readSubmissionState(result.data);
     const completionState = readCompletionState(result.data);
     const generationActive = readGenerationActive(result.data);
@@ -54,19 +66,25 @@ export function toRunResult(agent, result) {
         mapped.finalOutput = finalOutput;
     return mapped;
 }
-function extractOutputText(data) {
-    if (!isRecord(data))
-        return "";
-    if (typeof data.responseText === "string")
-        return data.responseText;
-    if (typeof data.text === "string")
-        return data.text;
-    for (const value of Object.values(data)) {
-        const nested = extractOutputText(value);
-        if (nested.length > 0)
+function extractOutput(data, seen = new WeakSet(), depth = 0, budget = { remaining: MAX_RESULT_TRAVERSAL_NODES }) {
+    if (!enterResultRecord(data, seen, depth, budget))
+        return undefined;
+    const responseText = ownDataProperty(data, "responseText");
+    if (typeof responseText === "string") {
+        return { text: responseText, source: data };
+    }
+    const text = ownDataProperty(data, "text");
+    if (typeof text === "string") {
+        return { text, source: data };
+    }
+    for (const value of ownDataValues(data)) {
+        const nested = extractOutput(value, seen, depth + 1, budget);
+        // Keep the pre-existing extractor's behavior: an empty nested record is
+        // not a usable result, so continue searching siblings for real output.
+        if (nested !== undefined && nested.text.length > 0)
             return nested;
     }
-    return "";
+    return undefined;
 }
 function parseFinalOutput(agent, outputText) {
     if (outputText.length === 0)
@@ -81,16 +99,16 @@ function parseFinalOutput(agent, outputText) {
     }
     return outputText;
 }
-function runItemsFromResult(result, outputText) {
+function runItemsFromResult(result, outputText, outputSource) {
+    const responseFormat = responseFormatForOutput(result.data, outputSource);
     const items = lifecycleItemsFromSteps(result.steps);
+    // Prompt provenance is independent from assistant-output provenance: a
+    // submitted prompt may be recorded in a sibling branch of the result.
     items.push(...messageItemsFromData(result.data));
     if (!items.some(item => item.type === "message.completed" || item.type === "message.in_progress") && outputText.length > 0) {
-        if (result.status === "partial" && readCompletionState(result.data) !== "complete") {
-            items.push(inProgressItem(outputText, readCompletionState(result.data), readGenerationActive(result.data)));
-        }
-        else {
-            items.push({ type: "message.completed", role: "assistant", output_text: outputText, format: "markdown" });
-        }
+        const assistant = assistantItemFromOutput(outputSource, outputText, responseFormat, result.status);
+        if (assistant !== undefined)
+            items.push(assistant);
     }
     if (result.blocker !== undefined) {
         items.push({ type: "run.blocked", blocker: augmentCommandBlocker(result.blocker) });
@@ -132,34 +150,55 @@ function lifecycleItemsFromSteps(steps) {
     }
     return items;
 }
-function messageItemsFromData(data) {
-    if (!isRecord(data))
+function messageItemsFromData(data, seen = new WeakSet(), depth = 0, budget = { remaining: MAX_RESULT_TRAVERSAL_NODES }) {
+    if (!enterResultRecord(data, seen, depth, budget))
         return [];
     const items = [];
-    if (typeof data.prompt === "string" && data.prompt.length > 0) {
+    const prompt = ownDataProperty(data, "prompt");
+    if (typeof prompt === "string" && prompt.length > 0) {
         items.push({
             type: "message.submitted",
             role: "user",
-            preview: data.prompt.length > 160 ? `${data.prompt.slice(0, 159)}...` : data.prompt,
+            preview: prompt.length > 160 ? `${prompt.slice(0, 159)}...` : prompt,
             redacted: true
         });
-    }
-    if (typeof data.responseText === "string" && data.responseText.length > 0) {
-        if (readCompletionState(data) === "complete" || data.complete === true) {
-            items.push({ type: "message.completed", role: "assistant", output_text: data.responseText, format: "markdown" });
-        }
-        else {
-            items.push(inProgressItem(data.responseText, readCompletionState(data), readGenerationActive(data)));
-        }
-    }
-    if (items.length > 0)
         return items;
-    for (const value of Object.values(data)) {
-        const nested = messageItemsFromData(value);
+    }
+    for (const value of ownDataValues(data)) {
+        const nested = messageItemsFromData(value, seen, depth + 1, budget);
         if (nested.length > 0)
             return nested;
     }
-    return [];
+    return items;
+}
+function assistantItemFromOutput(outputSource, outputText, responseFormat, resultStatus) {
+    if (outputSource === undefined || outputText.length === 0)
+        return undefined;
+    // The selected output record is the sole authority for assistant text and
+    // lifecycle metadata. In particular, do not recursively borrow completion
+    // state from a later sibling branch.
+    const completionState = completionStateFromRecord(outputSource);
+    const complete = ownDataProperty(outputSource, "complete");
+    if (completionState === "complete" || complete === true) {
+        return { type: "message.completed", role: "assistant", output_text: outputText, format: responseFormat };
+    }
+    const incomplete = complete === false
+        || completionState !== undefined
+        || resultStatus === "partial";
+    if (incomplete) {
+        return inProgressItem(outputText, completionState, generationActiveFromRecord(outputSource), responseFormat);
+    }
+    return { type: "message.completed", role: "assistant", output_text: outputText, format: responseFormat };
+}
+function completionStateFromRecord(data) {
+    const value = ownDataProperty(data, "completionState");
+    return value === "complete" || value === "generating" || value === "stopped" || value === "partial" || value === "unknown"
+        ? value
+        : undefined;
+}
+function generationActiveFromRecord(data) {
+    const value = ownDataProperty(data, "generationActive");
+    return typeof value === "boolean" ? value : undefined;
 }
 function runStateFromResult(result, interruptions) {
     const resumable = interruptions.some(interruption => interruption.resume.supported);
@@ -168,6 +207,17 @@ function runStateFromResult(result, interruptions) {
         id: firstResume?.supported === true && firstResume.stateId !== undefined ? firstResume.stateId : `run_${Date.now().toString(36)}`,
         resumable
     };
+    const operationId = readOperationId(result.data);
+    const handle = readOperationHandle(result.data);
+    if (operationId !== undefined) {
+        state.operationId = operationId;
+        // Use the durable identity for correlation without changing the runner's
+        // resume-policy bit: recovery is collect-only through the operation
+        // handle, not permission to replay the high-level workflow.
+        state.id = operationId;
+    }
+    if (handle !== undefined)
+        state.handle = handle;
     const thread = threadRefFromContext(result.context);
     if (thread !== undefined)
         state.thread = thread;
@@ -179,13 +229,13 @@ function runStateFromResult(result, interruptions) {
         state.completionState = completionState;
     return state;
 }
-function inProgressItem(outputText, completionState, generationActive) {
+function inProgressItem(outputText, completionState, generationActive, responseFormat) {
     const item = {
         type: "message.in_progress",
         role: "assistant",
         output_text: outputText,
         preview: outputText.length > 160 ? `${outputText.slice(0, 159)}...` : outputText,
-        format: "markdown",
+        format: responseFormat,
         textLength: outputText.length,
         textHash: hashText(outputText)
     };
@@ -195,46 +245,168 @@ function inProgressItem(outputText, completionState, generationActive) {
         item.generationActive = generationActive;
     return item;
 }
-function readCompletionState(data) {
-    if (!isRecord(data))
+function responseFormatForOutput(data, outputSource) {
+    // A top-level responseFormat is an explicit result contract and therefore
+    // remains authoritative even when the output text is nested below it.
+    const topLevel = ownDataProperty(data, "responseFormat");
+    if (isResponseFormat(topLevel))
+        return topLevel;
+    // Legacy format fields are only meaningful when co-located with the record
+    // whose text won the bounded output traversal. Never borrow one from an
+    // unrelated metadata/configuration branch.
+    const local = responseFormatFromRecord(outputSource);
+    return local ?? "markdown";
+}
+function responseFormatFromRecord(data) {
+    if (data === undefined)
         return undefined;
-    const value = data.completionState;
+    const explicit = ownDataProperty(data, "responseFormat");
+    if (isResponseFormat(explicit))
+        return explicit;
+    const local = ownDataProperty(data, "format");
+    return isResponseFormat(local) ? local : undefined;
+}
+function isResponseFormat(value) {
+    return value === "markdown"
+        || value === "text"
+        || value === "normalized_text"
+        || value === "visible_text"
+        || value === "html"
+        || value === "blocks"
+        || value === "all";
+}
+function readCompletionState(data, seen = new WeakSet(), depth = 0, budget = { remaining: MAX_RESULT_TRAVERSAL_NODES }) {
+    if (!enterResultRecord(data, seen, depth, budget))
+        return undefined;
+    const value = ownDataProperty(data, "completionState");
     if (value === "complete" || value === "generating" || value === "stopped" || value === "partial" || value === "unknown") {
         return value;
     }
-    for (const nested of Object.values(data)) {
-        const nestedState = readCompletionState(nested);
+    for (const nested of ownDataValues(data)) {
+        const nestedState = readCompletionState(nested, seen, depth + 1, budget);
         if (nestedState !== undefined)
             return nestedState;
     }
     return undefined;
 }
-function readSubmissionState(data) {
-    if (!isRecord(data))
+function readSubmissionState(data, seen = new WeakSet(), depth = 0, budget = { remaining: MAX_RESULT_TRAVERSAL_NODES }) {
+    if (!enterResultRecord(data, seen, depth, budget))
         return undefined;
-    const value = data.submissionState;
+    const value = ownDataProperty(data, "submissionState");
     if (value === "not_submitted" || value === "submitted" || value === "submitted_unconfirmed" || value === "submitted_generating") {
         return value;
     }
-    for (const nested of Object.values(data)) {
-        const nestedState = readSubmissionState(nested);
+    for (const nested of ownDataValues(data)) {
+        const nestedState = readSubmissionState(nested, seen, depth + 1, budget);
         if (nestedState !== undefined)
             return nestedState;
     }
     return undefined;
 }
-function readGenerationActive(data) {
-    if (!isRecord(data))
+function readGenerationActive(data, seen = new WeakSet(), depth = 0, budget = { remaining: MAX_RESULT_TRAVERSAL_NODES }) {
+    if (!enterResultRecord(data, seen, depth, budget))
         return undefined;
-    if (typeof data.generationActive === "boolean")
-        return data.generationActive;
-    for (const nested of Object.values(data)) {
-        const value = readGenerationActive(nested);
+    const generationActive = ownDataProperty(data, "generationActive");
+    if (typeof generationActive === "boolean")
+        return generationActive;
+    for (const nested of ownDataValues(data)) {
+        const value = readGenerationActive(nested, seen, depth + 1, budget);
         if (value !== undefined)
             return value;
     }
     return undefined;
 }
+function readOperationId(data) {
+    const value = ownDataProperty(data, "operationId");
+    return typeof value === "string"
+        && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value)
+        ? value
+        : undefined;
+}
+function readRequestDigest(data) {
+    const value = ownDataProperty(data, "requestDigest");
+    return typeof value === "string" && /^hmac-sha256:[0-9a-f]{64}$/u.test(value)
+        ? value
+        : undefined;
+}
+function readOperationHandle(data) {
+    const value = ownDataProperty(data, "handle");
+    if (!isRecord(value))
+        return undefined;
+    const operationId = ownDataProperty(value, "operationId");
+    const requestDigest = ownDataProperty(value, "requestDigest");
+    const schemaVersion = ownDataProperty(value, "schemaVersion");
+    const surface = ownDataProperty(value, "surface");
+    const revision = ownDataProperty(value, "revision");
+    const phase = ownDataProperty(value, "phase");
+    const mutationBoundary = ownDataProperty(value, "mutationBoundary");
+    const targetBindingDigest = ownDataProperty(value, "targetBindingDigest");
+    if (schemaVersion !== "chatgpt.browser_control.operation_handle.v1"
+        || typeof operationId !== "string"
+        || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(operationId)
+        || typeof requestDigest !== "string"
+        || !/^hmac-sha256:[0-9a-f]{64}$/u.test(requestDigest)
+        || (surface !== "chat" && surface !== "work")
+        || !Number.isSafeInteger(revision)
+        || revision < 1
+        || !["prepared", "handoff_pending", "ready", "send_pending", "submitted", "generating", "capturing", "completed", "uncertain"].includes(String(phase))
+        || !["none", "handoff_may_have_occurred", "send_may_have_occurred", "control_may_have_occurred"].includes(String(mutationBoundary))
+        || (targetBindingDigest !== undefined
+            && (typeof targetBindingDigest !== "string" || !/^hmac-sha256:[0-9a-f]{64}$/u.test(targetBindingDigest)))) {
+        return undefined;
+    }
+    return Object.freeze({
+        schemaVersion,
+        operationId,
+        requestDigest,
+        surface,
+        revision: revision,
+        phase: phase,
+        mutationBoundary: mutationBoundary,
+        ...(targetBindingDigest === undefined ? {} : { targetBindingDigest })
+    });
+}
+/** Never invoke a getter while extracting operation metadata from result data. */
+function ownDataProperty(value, key) {
+    if (!isRecord(value))
+        return undefined;
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Enumerate data values without invoking getters or trusting proxy traps. */
+function ownDataValues(value) {
+    if (!isRecord(value))
+        return [];
+    try {
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const values = [];
+        for (const key of Reflect.ownKeys(descriptors)) {
+            if (typeof key !== "string")
+                continue;
+            const descriptor = descriptors[key];
+            if (descriptor !== undefined && "value" in descriptor)
+                values.push(descriptor.value);
+        }
+        return values;
+    }
+    catch {
+        return [];
+    }
+}
+function enterResultRecord(value, seen, depth, budget) {
+    if (!isRecord(value) || depth > MAX_RESULT_TRAVERSAL_DEPTH || budget.remaining <= 0)
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    budget.remaining -= 1;
+    return true;
+}
 function hashText(value) {
     let hash = 2166136261;
     for (let index = 0; index < value.length; index += 1) {

package/dist/src/runner/types.d.ts

@@ -2,6 +2,7 @@ import type { AttachedFile, ChatGPTExperience, CommandResult, CommandStatus, Com
 import type { RunReportOptions } from "../commands/reports.js";
 import type { UntrustedOutputReturnEnvelope } from "../safety/untrusted-output.js";
 import type { ChatGPTRunStream } from "./stream.js";
+import type { OperationHandleV1 } from "../operations/types.js";
 export type ChatGPTThreadSelector = {
     type: "new";
 } | {
@@ -106,6 +107,8 @@ export type ChatGPTInputItem = {
 };
 export type ChatGPTRunInput = string | {
     input: string | ChatGPTInputItem[];
+    /** Caller-owned durable identity; opts this invocation into operations.run. */
+    operationId?: string;
     thread?: ChatGPTThreadSelector;
     existingTab?: BootstrapArgs["existingTab"];
     preferExistingTab?: boolean;
@@ -240,6 +243,8 @@ export type ChatGPTConfirmation = {
 export type ChatGPTRunState = {
     id: string;
     resumable: boolean;
+    operationId?: string;
+    handle?: OperationHandleV1;
     thread?: ChatGPTThreadRef;
     nextStepId?: string;
     submissionState?: SubmissionState;
@@ -248,6 +253,11 @@ export type ChatGPTRunState = {
 export type ChatGPTRunData<TOutput = string> = {
     finalOutput?: TOutput;
     outputText: string;
+    /** Effective caller-owned operation identity when the transactional path was selected. */
+    operationId?: string;
+    /** Durable locator returned by the transactional operation path. */
+    handle?: OperationHandleV1;
+    requestDigest?: string;
     untrustedOutput?: UntrustedOutputReturnEnvelope;
     thread?: ChatGPTThreadRef;
     downloads?: DownloadedFileSummary[];
@@ -290,6 +300,8 @@ export type ChatGPTResponse = {
         submissionState?: SubmissionState;
         completionState?: CompletionState;
         generationActive?: boolean;
+        operationId?: string;
+        handle?: OperationHandleV1;
         untrustedOutput?: UntrustedOutputReturnEnvelope;
         unsupported?: UnsupportedField[];
     };

package/dist/src/runtime/command-routing.d.ts

@@ -0,0 +1,149 @@
+import { ProcessTabCoordinator, type CoordinatorAcquisitionContext, type CoordinatorPriority } from "./tab-coordinator.js";
+import type { OperationRuntimeContext } from "./operation-context.js";
+import { type CoordinatedBrowserOptions } from "./coordinated-browser.js";
+import type { RuntimeEnv } from "../types.js";
+/**
+ * Routing keeps the implementation classes visible while also exposing a
+ * binary browser-free/coordinator-routed disposition for the acceptance
+ * contract. Legacy command implementations still run directly, but their
+ * page and browser method calls use the bounded coordinated runtime facade.
+ * That does not make the whole command or its polling loop one coordinator
+ * transaction.
+ *
+ * `operation_opt_in` means that an explicit caller-owned operation identity is
+ * handled by an operation-aware public facade. It does not authorize wrapping
+ * the whole public command in a coordinator callback.
+ */
+export type CommandRoutingClass = "browser_free" | "operation_opt_in" | "legacy_page_facade" | "legacy_browser_unrouted" | "coordinator_entrypoint";
+/** The complete routing inventory is intentionally explicit and reviewable. */
+export declare const COMMAND_ROUTING_INVENTORY: Readonly<{
+    browserFree: readonly ["backend.version", "backend.health", "backend.capabilities", "backend.hello", "runner.plan", "createReport", "reports.create", "reports.redact", "reports.summarize", "commands", "describe", "help", "redacted-run-report", "files.preflight", "projects.sources.planAdd", "operations.inspect"];
+    /**
+     * These commands opt into the operation facade only when an operation
+     * identity is present. With no identity they retain their legacy path.
+     */
+    operationOptIn: readonly ["runner.run", "runner.stream", "responses.create", "ask", "askInThread", "askWithFiles", "askAndDownload", "work.start", "work.steer", "operations.submit", "operations.collect", "operations.control"];
+    /**
+     * Legacy commands retain their public workflow and now receive a
+     * coordinator-backed PageLike/BrowserLike facade. This is a method-level
+     * guarantee: it does not turn the whole command or its polling loop into a
+     * single actor callback.
+     */
+    legacyPageFacade: readonly ["runMessages", "openThread", "copyLatest", "readLatest", "downloadLatest", "runPlan", "new-ask-read", "find-open-ask-read", "find-open-copy-latest", "attach-ask-read", "ask-and-download", "two-turn", "doctor-upload", "doctor", "session.bootstrap", "experience.detect", "experience.open", "configuration.inspect", "configuration.apply", "work.status", "work.wait", "work.readLatest", "threads.new", "threads.search", "threads.open", "messages.compose", "messages.submit", "messages.ask", "messages.wait", "messages.readLatest", "messages.status", "messages.stop", "messages.waitAndRead", "artifacts.listLatest", "artifacts.wait", "artifacts.downloadLatest", "files.attach", "files.downloadLatest", "projects.sources.list", "projects.sources.add", "response.copy", "modes.set", "modes.get", "tools.select"];
+    /**
+     * Browser acquisition seams not covered by the facade remain explicit
+     * migration gaps. The current command surface has none; discovery is
+     * coordinated in browser/attach.ts.
+     */
+    legacyBrowserUnrouted: readonly [];
+    /**
+     * No backend or sequence command currently invokes
+     * routeCommandBrowserTransaction. Keep this category explicit so a future
+     * migration cannot silently turn a classification into an enforcement
+     * claim. A command may enter this list only after its own bounded DOM seam
+     * is implemented and tested.
+     */
+    coordinatorEntrypoint: readonly [];
+}>;
+type InventoryCommand = typeof COMMAND_ROUTING_INVENTORY.browserFree[number] | typeof COMMAND_ROUTING_INVENTORY.operationOptIn[number] | typeof COMMAND_ROUTING_INVENTORY.legacyPageFacade[number] | typeof COMMAND_ROUTING_INVENTORY.legacyBrowserUnrouted[number] | typeof COMMAND_ROUTING_INVENTORY.coordinatorEntrypoint[number];
+type LegacyBrowserCommand = typeof COMMAND_ROUTING_INVENTORY.legacyBrowserUnrouted[number];
+/**
+ * The operation-aware public dispatch seams currently implemented by the
+ * client/backend path. This is separate from the coordinator entrypoint
+ * inventory: these commands route into the operation facade, whose adapter
+ * owns its own short tab transactions, rather than calling the generic helper
+ * below around the whole command.
+ */
+export declare const OPERATION_AWARE_DISPATCH_COMMANDS: readonly ["runner.run", "runner.stream", "responses.create", "ask", "askInThread", "askWithFiles", "askAndDownload", "work.start", "work.steer", "operations.submit", "operations.collect", "operations.control"];
+export type CommandRoutingGap = Readonly<{
+    command: LegacyBrowserCommand;
+    status: "legacy_browser_unrouted";
+    owner: string;
+    requiredSeam: "bounded_tab_transaction";
+    reason: "legacy_command_dispatch_has_no_operation_aware_tab_seam";
+}>;
+export declare const COMMAND_ROUTING_GAPS: readonly CommandRoutingGap[];
+/** Return undefined for a command that has not been explicitly classified. */
+export declare function classifyCommandRouting(command: string): CommandRoutingClass | undefined;
+export declare function isBrowserFreeCommand(command: string): boolean;
+export declare function isOperationOptInCommand(command: string): boolean;
+export declare function isLegacyBrowserUnroutedCommand(command: string): boolean;
+export declare function isLegacyPageFacadeCommand(command: string): boolean;
+export declare function isCoordinatorEntrypointCommand(command: string): boolean;
+/**
+ * The public acceptance contract intentionally collapses the implementation
+ * classes into the two meaningful routing dispositions.  `operation_opt_in`
+ * is coordinator-routed by its operation adapter; the legacy page facade is
+ * coordinator-routed by the bounded environment adapter below.  An explicit
+ * `legacy_browser_unrouted` entry is a migration gap and therefore has no
+ * safe disposition.
+ */
+export type CommandRoutingDisposition = "browser_free" | "coordinator_routed";
+export declare function commandRoutingDisposition(command: string): CommandRoutingDisposition | undefined;
+export declare function isCoordinatorRoutedCommand(command: string): boolean;
+/** Options for the bounded legacy command adapter. */
+export type CommandRoutingAdapterOptions = Readonly<Pick<CoordinatedBrowserOptions, "coordinator" | "owner">>;
+/**
+ * Prepare the environment for one command invocation.
+ *
+ * This is deliberately an adapter rather than a whole-command coordinator
+ * transaction.  `coordinateRuntimeEnv` returns PageLike/BrowserLike facades
+ * whose individual browser calls acquire the process-scoped actor for a
+ * bounded operation and release it before the next await.  Consequently a
+ * command may wait for generation, poll, write a journal, or invoke caller
+ * code without retaining a tab actor.  The coordinated browser/page values
+ * are copied back into the supplied invocation environment so legacy command
+ * mutations (notably `session.bootstrap`) remain visible to later sequence
+ * steps. Calling this on an already-coordinated environment is idempotent
+ * through the wrapper caches.
+ */
+export declare function routeCommandRuntimeEnv(command: string, env: RuntimeEnv, options?: CommandRoutingAdapterOptions): RuntimeEnv;
+/**
+ * Run one command with the bounded legacy environment adapter.
+ *
+ * The callback is invoked outside any coordinator callback.  The returned
+ * PageLike/BrowserLike values enforce short method-level transactions, so a
+ * caller callback or a generation/poll sleep cannot deadlock a nested actor.
+ */
+export declare function routeCommandExecution<T>(command: string, env: RuntimeEnv, callback: (routedEnv: RuntimeEnv) => T | PromiseLike<T>, options?: CommandRoutingAdapterOptions): Promise<T>;
+export type CommandRoutingContext<Page extends object = object> = Readonly<{
+    coordinator: ProcessTabCoordinator;
+    runtimeContext: OperationRuntimeContext<Page>;
+    priority?: CoordinatorPriority;
+    signal?: AbortSignal;
+    deadlineAt?: number;
+    timeoutMs?: number;
+    label?: string;
+}>;
+export type CommandRoutingErrorCode = "unclassified_command" | "coordinator_context_required" | "exact_ownership_unavailable" | "legacy_command_unrouted" | "legacy_page_facade" | "operation_facade_managed" | "operation_routing_unavailable";
+/** Stable error for callers that try to route without enough ownership proof. */
+export declare class CommandRoutingError extends Error {
+    readonly code: CommandRoutingErrorCode;
+    constructor(code: CommandRoutingErrorCode);
+}
+/**
+ * Execute one already-bounded browser transaction for an explicit coordinator
+ * entrypoint. The callback is intentionally the transaction boundary, not
+ * the command or request boundary. Callers must keep generation waits,
+ * polling sleeps, file hashing/transfers, journal writes, and report/caller
+ * callbacks outside this helper.
+ */
+export declare function routeCommandBrowserTransaction<T, Page extends object = object>(command: string, context: CommandRoutingContext<Page> | undefined, callback: (acquisition: CoordinatorAcquisitionContext | undefined) => T | PromiseLike<T>): Promise<T>;
+/** Return a readonly snapshot useful for diagnostics and inventory tests. */
+export declare function commandRoutingInventory(): Readonly<Record<string, CommandRoutingClass>>;
+/**
+ * Return true when a request carries one of the reserved caller-owned
+ * operation identity fields. This is intentionally structural and never
+ * reads or serializes prompt/instruction values.
+ */
+export declare function hasOperationIdentity(value: unknown): boolean;
+/**
+ * Backend and sequence dispatchers call this before direct command dispatch.
+ * Legacy callers without an operation identity remain byte-for-byte on the
+ * existing path. An operation-aware request is allowed only for explicitly
+ * migrated facade commands (or browser-free diagnostics); all other browser
+ * commands fail before their handler can touch the browser.
+ */
+export declare function assertOperationAwareDispatchAllowed(command: string, payload: unknown): void;
+export type ClassifiedCommand = InventoryCommand;
+export {};