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

package/dist/src/client.js

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { downloadLatestArtifact, listLatestArtifacts, waitForArtifact } from "./commands/artifacts.js";
 import { attachFiles, downloadLatestFile, preflightFiles } from "./commands/files.js";
 import { addProjectSources, buildProjectSourceAddPlan, listProjectSources } from "./commands/project-sources.js";
@@ -20,11 +22,56 @@ import { responseFromRunResult, responsesCreateArgsToRunInput, unsupportedRespon
 import { streamFromRunResult } from "./runner/stream.js";
 import { redactReportValue } from "./safety/report-redaction.js";
 import { explainCommandBlocker } from "./diagnostics/blockers.js";
+import { OperationClient, OperationClientError } from "./operations/client.js";
+import { OperationJournal } from "./operations/journal.js";
+import { OperationService } from "./operations/service.js";
+import { OPERATION_CONTROL_REQUEST_SCHEMA_VERSION, OPERATION_REQUEST_SCHEMA_VERSION } from "./operations/types.js";
+import { createRuntimeEnvSession } from "./runtime/runtime-session.js";
+import { coordinateRuntimeEnv } from "./runtime/coordinated-browser.js";
+import { createChatGPTOperationAdapterFactory, createChatGPTOperationControlAdapterFactory, createChatGPTOperationHandleAdapterFactory } from "./operations/chatgpt-runtime.js";
 export function createChatGPT(options = {}) {
-    const env = runtimeEnv(options);
+    // RuntimeEnv remains mutable for the legacy command implementations, but it
+    // must never be shared by two public invocations.  The session owns only the
+    // browser/page/tab snapshot; provider references are copied once and each
+    // call receives its own mutable capture for the whole workflow.
+    const runtimeEnvironment = runtimeEnv(options);
+    const runtime = createRuntimeEnvSession(runtimeEnvironment);
+    // The cached OperationClient must remain stable so request-local adapters
+    // (including file/output closures) survive a submit -> collect sequence.
+    // Its default ChatGPT factories, however, must see the invocation that is
+    // currently using them. Async-local scope keeps concurrent calls from
+    // replacing one another's browser/page snapshot.
+    const operationRuntime = new AsyncLocalStorage();
+    // A direct in-process client is one runtime lifetime. Keep its coordinator
+    // identity stable across every operation while ensuring separately created
+    // clients remain diagnostically distinguishable.
+    const operationOwner = Object.freeze({
+        backendSessionId: randomUUID()
+    });
     const limits = normalizeLimits(options.limits);
+    // Keep one promise for the lifetime of this client. Opening the journal is
+    // deliberately deferred until an operation is actually requested, while
+    // concurrent first calls still converge on one authenticated service/key.
+    let operationClientPromise;
+    const operationClient = () => {
+        operationClientPromise ??= createOperationClientForChatGPT(options, () => operationRuntime.getStore() ?? runtimeEnvironment, operationOwner);
+        return operationClientPromise;
+    };
+    const runOperationInvocation = (callback) => {
+        const active = operationRuntime.getStore();
+        if (active !== undefined)
+            return callback();
+        return runtime.run(env => operationRuntime.run(env, callback));
+    };
+    const operations = Object.freeze({
+        submit: (request, operationOptions) => runOperationInvocation(() => operationClient().then(client => client.submit(request, operationOptions))),
+        collect: (handle, operationOptions) => runOperationInvocation(() => operationClient().then(client => client.collect(handle, operationOptions))),
+        inspect: handle => runOperationInvocation(() => operationClient().then(client => client.inspect(handle))),
+        control: (request, operationOptions) => runOperationInvocation(() => operationClient().then(client => client.control(request, operationOptions))),
+        run: (request, operationOptions) => runOperationInvocation(() => operationClient().then(client => client.run(request, operationOptions)))
+    });
     const runnerRun = ((agent, input, runnerOptions) => {
-        const run = () => runAgentWorkflow(agent, input, env, limits, options.defaults, options.reporting);
+        const run = () => runtime.run(env => operationRuntime.run(env, () => runAgentWorkflow(agent, input, env, limits, options.defaults, options.reporting, options, operations)));
         return runnerOptions?.stream === true ? streamFromRunResult(run) : run();
     });
     const runner = {
@@ -35,24 +82,36 @@ export function createChatGPT(options = {}) {
         agent: config => createChatGPTAgent(config),
         run: runner.run,
         runner,
+        operations,
         responses: {
-            create: args => createResponse(args, runner, env.now)
+            // Keep the entire Responses adapter, including its runner invocation,
+            // inside one capture.  Passing a runner bound to this env avoids a
+            // nested session capture for the same public workflow.
+            create: args => runtime.run(env => operationRuntime.run(env, () => createResponse(args, (agent, input) => runAgentWorkflow(agent, input, env, limits, options.defaults, options.reporting, options, operations), env.now)))
         },
-        ask: args => runGuarded(planAskWorkflow(args, options.defaults), env, limits, reportOptions(args.report, options.reporting)),
-        askInThread: args => runGuarded(planAskWorkflow(args, options.defaults), env, limits, reportOptions(args.report, options.reporting)),
-        askWithFiles: args => runGuarded(planAskWorkflow(args, options.defaults), env, limits, reportOptions(args.report, options.reporting)),
-        askAndDownload: args => runGuarded(planAskWorkflow(args, options.defaults), env, limits, reportOptions(args.report, options.reporting)),
-        runMessages: args => runGuarded(planRunMessages(args, options.defaults), env, limits, reportOptions(args.report, options.reporting)),
-        openThread: thread => runSequence(planOpenThread(thread), env),
-        readLatest: args => readLatest(env, args),
-        copyLatest: args => copyResponse(env, args),
-        downloadLatest: args => downloadLatestFile(env, args),
-        runPlan: plan => runPlanInvocation(plan, env, limits, options.defaults, options.reporting),
-        doctor: args => doctor(env, args),
-        createReport: (result, args) => createRunReport(env, result, args ?? options.reporting ?? {}),
+        ask: args => runtime.run(env => operationRuntime.run(env, () => args.operationId === undefined
+            ? runGuarded(planAskWorkflow(args, options.defaults), env, limits, reportOptions(args.report, options.reporting))
+            : runTransactionalAsk(args, options.defaults, options, operations))),
+        askInThread: args => runtime.run(env => operationRuntime.run(env, () => args.operationId === undefined
+            ? runGuarded(planAskWorkflow(args, options.defaults), env, limits, reportOptions(args.report, options.reporting))
+            : runTransactionalAsk(args, options.defaults, options, operations))),
+        askWithFiles: args => runtime.run(env => operationRuntime.run(env, () => args.operationId === undefined
+            ? runGuarded(planAskWorkflow(args, options.defaults), env, limits, reportOptions(args.report, options.reporting))
+            : runTransactionalAsk(args, options.defaults, options, operations))),
+        askAndDownload: args => runtime.run(env => operationRuntime.run(env, () => args.operationId === undefined
+            ? runGuarded(planAskWorkflow(args, options.defaults), env, limits, reportOptions(args.report, options.reporting))
+            : runTransactionalAsk(args, options.defaults, options, operations))),
+        runMessages: args => runtime.run(env => runGuarded(planRunMessages(args, options.defaults), env, limits, reportOptions(args.report, options.reporting))),
+        openThread: thread => runtime.run(env => runSequence(planOpenThread(thread), env)),
+        readLatest: args => runtime.run(env => readLatest(env, args)),
+        copyLatest: args => runtime.run(env => copyResponse(env, args)),
+        downloadLatest: args => runtime.run(env => downloadLatestFile(env, args)),
+        runPlan: plan => runtime.run(env => runPlanInvocation(plan, env, limits, options.defaults, options.reporting)),
+        doctor: args => runtime.run(env => doctor(env, args)),
+        createReport: (result, args) => runtime.run(env => createRunReport(env, result, args ?? options.reporting ?? {})),
         explainBlocker: (resultOrBlocker, args) => explainCommandBlocker(resultOrBlocker, args),
         reports: {
-            create: (result, args) => createRunReport(env, result, args ?? options.reporting ?? {}),
+            create: (result, args) => runtime.run(env => createRunReport(env, result, args ?? options.reporting ?? {})),
             redact: async (value, args) => resultOk(redactReportValue(value, args), {}),
             summarize: async (result, args) => resultOk(redactReportValue(resultSummary(result), args), {})
         },
@@ -61,69 +120,73 @@ export function createChatGPT(options = {}) {
         describe: name => describeCommand(name),
         help: topic => helpText(topic),
         session: {
-            bootstrap: args => bootstrap(env, args)
+            bootstrap: args => runtime.run(env => bootstrap(env, args))
         },
         experience: {
-            detect: args => detectExperience(env, args),
-            open: args => openExperience(env, args)
+            detect: args => runtime.run(env => detectExperience(env, args)),
+            open: args => runtime.run(env => openExperience(env, args))
         },
         configuration: {
-            inspect: args => inspectConfiguration(env, args),
-            apply: args => applyConfiguration(env, args)
+            inspect: args => runtime.run(env => inspectConfiguration(env, args)),
+            apply: args => runtime.run(env => applyConfiguration(env, args))
         },
         work: {
-            start: args => startWork(env, args),
-            status: args => workStatus(env, args),
-            wait: args => waitForWork(env, args),
-            steer: args => steerWork(env, args),
-            readLatest: args => readLatestWork(env, args),
+            start: args => runtime.run(env => operationRuntime.run(env, () => args.operationId === undefined
+                ? startWork(env, args)
+                : runTransactionalWorkStart(args, options.defaults, operations))),
+            status: args => runtime.run(env => workStatus(env, args)),
+            wait: args => runtime.run(env => waitForWork(env, args)),
+            steer: args => runtime.run(env => operationRuntime.run(env, () => hasTransactionalWorkControl(args)
+                ? runTransactionalWorkSteer(args, operations)
+                : steerWork(env, args))),
+            readLatest: args => runtime.run(env => readLatestWork(env, args)),
             artifacts: {
-                listLatest: args => listLatestArtifacts(env, args),
-                wait: args => waitForArtifact(env, args),
-                downloadLatest: args => downloadLatestArtifact(env, args)
+                listLatest: args => runtime.run(env => listLatestArtifacts(env, args)),
+                wait: args => runtime.run(env => waitForArtifact(env, args)),
+                downloadLatest: args => runtime.run(env => downloadLatestArtifact(env, args))
             }
         },
         threads: {
-            new: args => newThread(env, args),
-            search: args => searchThreads(env, args),
-            open: args => openThread(env, args)
+            new: args => runtime.run(env => newThread(env, args)),
+            search: args => runtime.run(env => searchThreads(env, args)),
+            open: args => runtime.run(env => openThread(env, args))
         },
         messages: {
-            compose: args => composeMessage(env, args),
-            submit: args => submitMessage(env, args),
-            ask: args => askMessage(env, args),
-            wait: args => waitForMessage(env, args),
-            readLatest: args => readLatest(env, args),
-            status: args => messageStatus(env, args),
-            stop: args => stopGeneration(env, args),
-            waitAndRead: args => waitAndRead(env, args)
+            compose: args => runtime.run(env => composeMessage(env, args)),
+            submit: args => runtime.run(env => submitMessage(env, args)),
+            ask: args => runtime.run(env => askMessage(env, args)),
+            wait: args => runtime.run(env => waitForMessage(env, args)),
+            readLatest: args => runtime.run(env => readLatest(env, args)),
+            status: args => runtime.run(env => messageStatus(env, args)),
+            stop: args => runtime.run(env => stopGeneration(env, args)),
+            waitAndRead: args => runtime.run(env => waitAndRead(env, args))
         },
         files: {
-            preflight: args => preflightFiles(env, args),
-            attach: args => attachFiles(env, args),
-            downloadLatest: args => downloadLatestFile(env, args)
+            preflight: args => runtime.run(env => preflightFiles(env, args)),
+            attach: args => runtime.run(env => attachFiles(env, args)),
+            downloadLatest: args => runtime.run(env => downloadLatestFile(env, args))
         },
         projects: {
             sources: {
-                list: args => listProjectSources(env, args),
-                planAdd: args => buildProjectSourceAddPlan(env, args),
-                add: args => addProjectSources(env, args)
+                list: args => runtime.run(env => listProjectSources(env, args)),
+                planAdd: args => runtime.run(env => buildProjectSourceAddPlan(env, args)),
+                add: args => runtime.run(env => addProjectSources(env, args))
             }
         },
         artifacts: {
-            listLatest: args => listLatestArtifacts(env, args),
-            wait: args => waitForArtifact(env, args),
-            downloadLatest: args => downloadLatestArtifact(env, args)
+            listLatest: args => runtime.run(env => listLatestArtifacts(env, args)),
+            wait: args => runtime.run(env => waitForArtifact(env, args)),
+            downloadLatest: args => runtime.run(env => downloadLatestArtifact(env, args))
         },
         modes: {
-            set: args => setMode(env, args),
-            get: args => getMode(env, args)
+            set: args => runtime.run(env => setMode(env, args)),
+            get: args => runtime.run(env => getMode(env, args))
         },
         tools: {
-            select: args => selectTool(env, args)
+            select: args => runtime.run(env => selectTool(env, args))
         },
         response: {
-            copy: args => copyResponse(env, args)
+            copy: args => runtime.run(env => copyResponse(env, args))
         }
     };
 }
@@ -277,11 +340,11 @@ function capReportOptions(report, limits) {
         maxPreviewChars: Math.min(report.maxPreviewChars ?? limits.maxReportPreviewChars, limits.maxReportPreviewChars)
     };
 }
-async function createResponse(args, runner, now) {
+async function createResponse(args, run, now) {
     const validation = validateResponsesCreateArgs(args);
     const timestamp = now?.() ?? new Date();
     if (!validation.ok) {
-        return unsupportedResponse(validation.unsupported, timestamp);
+        return unsupportedResponse(validation.unsupported, timestamp, readOperationIdFromUnknown(args));
     }
     const responseArgs = args;
     const agentConfig = {
@@ -292,21 +355,74 @@ async function createResponse(args, runner, now) {
         agentConfig.instructions = responseArgs.instructions;
     }
     const agent = createChatGPTAgent(agentConfig);
-    const result = await runner.run(agent, responsesCreateArgsToRunInput(responseArgs));
+    const result = await run(agent, responsesCreateArgsToRunInput(responseArgs));
     return responseFromRunResult(result, now?.() ?? timestamp);
 }
-async function runAgentWorkflow(agent, input, env, limits, defaults, reporting) {
+async function runAgentWorkflow(agent, input, env, limits, defaults, reporting, clientOptions, operations) {
+    const requestedOperationId = runnerOperationId(input);
     try {
         const normalized = normalizeRunnerInput(agent, input);
+        if (normalized.operationId !== undefined) {
+            const result = await runTransactionalRunnerWorkflow(agent, normalized, defaults, clientOptions, operations);
+            return toRunResult(agent, result);
+        }
         const plan = planAgentWorkflowFromNormalized(agent, normalized, defaults);
         const report = reportOptions(normalized.report ?? agent.defaults.report, reporting);
         const result = await runGuarded(plan, env, limits, report);
         return toRunResult(agent, result);
     }
     catch (error) {
-        return toRunResult(agent, resultError(error instanceof Error ? error : new Error(String(error)), {}));
+        const result = requestedOperationId === undefined
+            ? resultError(error instanceof Error ? error : new Error(String(error)), {})
+            : transactionalAskError(requestedOperationId, error);
+        return toRunResult(agent, result);
     }
 }
+/**
+ * Runner opt-in adapter.  It deliberately funnels through the same
+ * transactional ask preparation/result mapping used by the high-level Chat
+ * helpers so request identity, file manifests, action journaling, and
+ * structured blocker handling cannot drift between surfaces.
+ */
+async function runTransactionalRunnerWorkflow(agent, input, defaults, clientOptions, operations) {
+    const operationId = input.operationId;
+    if (operationId === undefined) {
+        return transactionalAskError("invalid-operation", new Error("Transactional runner input is missing operationId."));
+    }
+    if (agent.instructionsMode === "visible_setup_message" && hasInstructions(agent)) {
+        const unsupported = transactionalUnsupported(operationId, "visible_setup_message requires a separate setup turn and is not supported by one transactional operation.", "agent.instructionsMode");
+        return unsupported.ok ? transactionalAskError(operationId, new Error("Invalid transactional runner input.")) : unsupported.result;
+    }
+    if (input.copy !== undefined && input.copy !== false) {
+        const unsupported = transactionalUnsupported(operationId, "copy is not supported by the transactional runner path; use operations.collect and an explicit response action.", "copy");
+        return unsupported.ok ? transactionalAskError(operationId, new Error("Invalid transactional runner input.")) : unsupported.result;
+    }
+    // Match the legacy precedence exactly: input values win, then agent
+    // defaults, then client defaults.  The transactional mapper performs the
+    // same merge for target/configuration/wait/read as the Chat ask surface.
+    const effectiveDefaults = {
+        ...(defaults ?? {}),
+        ...agent.defaults
+    };
+    const report = input.report ?? agent.defaults.report;
+    const result = await runTransactionalAsk({
+        operationId,
+        prompt: renderRunnerPrompt(agent, input.prompt),
+        ...(input.thread === undefined ? {} : { thread: input.thread }),
+        ...(input.existingTab === undefined ? {} : { existingTab: input.existingTab }),
+        ...(input.preferExistingTab === undefined ? {} : { preferExistingTab: input.preferExistingTab }),
+        ...(input.experience === undefined ? {} : { experience: input.experience }),
+        ...(input.configuration === undefined ? {} : { configuration: input.configuration }),
+        ...(input.mode === undefined ? {} : { mode: input.mode }),
+        ...(input.tools.length === 0 ? {} : { tools: input.tools }),
+        ...(input.files.length === 0 ? {} : { files: input.files }),
+        ...(input.wait === undefined ? {} : { wait: input.wait }),
+        ...(input.read === undefined ? {} : { read: input.read }),
+        ...(report === undefined ? {} : { report }),
+        ...(input.download === undefined || input.download === false ? {} : { download: input.download })
+    }, effectiveDefaults, clientOptions, operations);
+    return result;
+}
 function planAgentWorkflow(agent, input, defaults = {}) {
     return planAgentWorkflowFromNormalized(agent, normalizeRunnerInput(agent, input), defaults);
 }
@@ -382,6 +498,8 @@ function normalizeRunnerInput(agent, input) {
         tools: args.tools ?? [],
         files: [...collected.files, ...attachments]
     };
+    if (args.operationId !== undefined)
+        normalized.operationId = args.operationId;
     if (args.thread !== undefined)
         normalized.thread = args.thread;
     if (args.existingTab !== undefined)
@@ -407,6 +525,9 @@ function normalizeRunnerInput(agent, input) {
     }
     return normalized;
 }
+function runnerOperationId(input) {
+    return typeof input === "string" ? undefined : input.operationId;
+}
 function collectRunnerInput(input) {
     if (typeof input === "string") {
         return { prompt: input, files: [] };
@@ -504,7 +625,1013 @@ function runtimeEnv(options) {
         env.clipboard = options.clipboard;
     if (options.now !== undefined)
         env.now = options.now;
-    return env;
+    if (options.expectedTabId !== undefined)
+        env.expectedTabId = options.expectedTabId;
+    // Coordinate only the browser/page snapshot. The runtime session still
+    // owns invocation isolation and compatibility mutation semantics for the
+    // legacy fields; browser methods themselves use the process-wide actor.
+    return coordinateRuntimeEnv(env);
+}
+async function createOperationClientForChatGPT(options, runtimeEnvironment, owner) {
+    const operationOptions = options.operations ?? {};
+    const journal = await OperationJournal.open(operationOptions.stateRoot === undefined ? {} : { stateRoot: operationOptions.stateRoot });
+    const serviceOptions = {
+        ...(operationOptions.maxCasRetries === undefined ? {} : { maxCasRetries: operationOptions.maxCasRetries }),
+        ...(options.now === undefined ? {} : { now: () => options.now().getTime() })
+    };
+    const service = new OperationService(journal, serviceOptions);
+    const adapter = operationOptions.adapter ?? unavailableOperationAdapter();
+    // Supplying any custom adapter seam is an explicit integration choice. Do
+    // not combine one half of a custom provider with the default ChatGPT
+    // recovery path. With no customization, however, browser-touching
+    // operations work out of the box and remain lazy until target resolution.
+    const hasCustomAdapter = operationOptions.adapter !== undefined
+        || operationOptions.adapterFactory !== undefined
+        || operationOptions.handleAdapterFactory !== undefined
+        || operationOptions.controlAdapterFactory !== undefined;
+    const evidenceDigest = (domain, material) => {
+        // Provider primitives use both the journal's short labels and their own
+        // versioned slash-separated domains. Preserve short labels verbatim so
+        // service-side identities (notably file manifests) remain identical;
+        // envelope provider domains inside one bounded journal namespace rather
+        // than allowing the provider label to violate the journal API.
+        if (/^[a-z][a-z0-9-]{0,63}$/u.test(domain)) {
+            return journal.evidenceDigest(domain, material);
+        }
+        return journal.evidenceDigest("provider-evidence", { domain, material });
+    };
+    const adapterFactory = hasCustomAdapter
+        ? operationOptions.adapterFactory
+        : async (context) => createChatGPTOperationAdapterFactory({
+            env: runtimeEnvironment(),
+            owner,
+            evidenceDigest
+        })(context);
+    const handleAdapterFactory = hasCustomAdapter
+        ? operationOptions.handleAdapterFactory
+        : async (context) => createChatGPTOperationHandleAdapterFactory({
+            env: runtimeEnvironment(),
+            owner,
+            evidenceDigest
+        })(context);
+    const controlAdapterFactory = hasCustomAdapter
+        ? operationOptions.controlAdapterFactory
+        : async (context) => createChatGPTOperationControlAdapterFactory({
+            env: runtimeEnvironment(),
+            owner,
+            evidenceDigest
+        })(context);
+    return new OperationClient(service, adapter, {
+        ...(adapterFactory === undefined ? {} : { adapterFactory }),
+        ...(handleAdapterFactory === undefined ? {} : { handleAdapterFactory }),
+        ...(controlAdapterFactory === undefined ? {} : { controlAdapterFactory }),
+        ...(operationOptions.maxCachedAdapters === undefined ? {} : { maxCachedAdapters: operationOptions.maxCachedAdapters })
+    });
+}
+/**
+ * A conservative placeholder keeps the public facade constructible for
+ * browser-free inspection and for callers that provide factories later. It
+ * never probes a page, claims capabilities, or synthesizes a successful
+ * operation result; all browser-touching paths fail closed.
+ */
+function unavailableOperationAdapter() {
+    const unavailable = async () => {
+        throw new OperationClientError("adapter_unavailable", "A browser-bound operation adapter is required for this operation.");
+    };
+    return {
+        resolveTarget: unavailable,
+        submission: {
+            observeStaging: unavailable,
+            executeFileHandoffOnce: unavailable,
+            observeAttachments: unavailable,
+            // Send is deliberately exposed as explicit phases.  The placeholder
+            // has no browser capability, so every phase fails closed; retaining the
+            // legacy method below is source compatibility only and is never used by
+            // the transactional coordinator.
+            prepareSend: unavailable,
+            executePreparedSend: unavailable,
+            verifyPreparedSend: unavailable,
+            recoverSend: unavailable,
+            executeFinalTabTransaction: unavailable
+        },
+        collector: {
+            readContext: unavailable,
+            observe: unavailable,
+            sleep: unavailable
+        }
+    };
+}
+const TRANSACTIONAL_OPERATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+async function runTransactionalAsk(args, defaults, clientOptions, operations) {
+    const prepared = prepareTransactionalAsk(args, defaults, clientOptions);
+    if (!prepared.ok)
+        return prepared.result;
+    try {
+        // Route through the public, stable facade so this path has exactly the
+        // same identity/journal semantics as callers using chatgpt.operations.run.
+        const run = await operations.run(prepared.value.request, prepared.value.options);
+        const handle = await freshestOperationHandle(operations, run.submit.handle);
+        return transactionalAskCommandResult(prepared.value, run, handle);
+    }
+    catch (error) {
+        // OperationClient and adapter errors are intentionally converted to a
+        // bounded structured result.  Their native messages may include a path,
+        // URL, prompt, or provider-private text and must not cross this boundary.
+        return transactionalAskError(args.operationId, error);
+    }
+}
+/**
+ * Work's public workflow keeps its existing command implementation as the
+ * compatibility path.  An explicit operation ID opts only this client call
+ * into the durable submit/collect protocol; the low-level `startWork` command
+ * remains available to sequence callers unchanged.
+ */
+async function runTransactionalWorkStart(args, defaults, operations) {
+    const prepared = prepareTransactionalWorkStart(args, defaults);
+    if (!prepared.ok)
+        return prepared.result;
+    try {
+        const run = await operations.run(prepared.value.request, prepared.value.options);
+        const handle = await freshestOperationHandle(operations, run.submit.handle);
+        const task = await transactionalWorkTask(operations, handle);
+        return transactionalWorkStartResult(prepared.value, run, handle, task);
+    }
+    catch (error) {
+        return transactionalWorkError(args.operationId, error);
+    }
+}
+function prepareTransactionalWorkStart(args, defaults) {
+    const operationId = args.operationId;
+    if (operationId === undefined || !TRANSACTIONAL_OPERATION_ID_PATTERN.test(operationId)) {
+        return {
+            ok: false,
+            result: transactionalWorkStartUnsupported(operationId, "operationId must be a canonical UUID.", "operationId")
+        };
+    }
+    if (args.prompt.trim().length === 0) {
+        return {
+            ok: false,
+            result: transactionalWorkStartUnsupported(operationId, "prompt must be non-empty.", "prompt")
+        };
+    }
+    if (args.timeoutMs !== undefined && (!Number.isSafeInteger(args.timeoutMs) || args.timeoutMs < 1 || args.timeoutMs > 86_400_000)) {
+        return {
+            ok: false,
+            result: transactionalWorkStartUnsupported(operationId, "timeoutMs must be between 1 and 86400000.", "timeoutMs")
+        };
+    }
+    const wait = args.wait ?? false;
+    const read = args.read ?? false;
+    const waitOptions = transactionalWorkWaitOptions(wait, read);
+    if (!waitOptions.ok) {
+        return { ok: false, result: transactionalWorkStartUnsupported(operationId, waitOptions.message, waitOptions.fieldPath) };
+    }
+    const configuration = transactionalWorkConfiguration(args.configuration ?? defaults?.configuration);
+    if (!configuration.ok) {
+        return { ok: false, result: transactionalWorkStartUnsupported(operationId, configuration.message, configuration.fieldPath) };
+    }
+    const files = (args.files ?? []).map(path => ({ path }));
+    const request = {
+        schemaVersion: OPERATION_REQUEST_SCHEMA_VERSION,
+        operationId,
+        surface: "work",
+        prompt: args.prompt,
+        target: args.newTask === false ? { type: "selected_tab" } : { type: "new" },
+        ...(configuration.value === undefined ? {} : { configuration: configuration.value }),
+        ...(files.length === 0 ? {} : { files }),
+        capture: {
+            responseContent: waitOptions.responseContent,
+            responseFormat: waitOptions.responseFormat,
+            artifacts: "receipt_only"
+        }
+    };
+    return {
+        ok: true,
+        value: {
+            request,
+            options: {
+                ...waitOptions.options,
+                ...(args.timeoutMs === undefined || typeof wait !== "object" || wait.timeoutMs !== undefined
+                    ? {}
+                    : { timeoutMs: args.timeoutMs })
+            },
+            readRequested: waitOptions.readRequested,
+            responseFormat: waitOptions.responseFormat,
+            ...(waitOptions.maxResponseChars === undefined ? {} : { maxResponseChars: waitOptions.maxResponseChars })
+        }
+    };
+}
+function transactionalWorkConfiguration(selected) {
+    if (selected === undefined)
+        return { ok: true };
+    const value = { experience: "work" };
+    if (selected.model !== undefined)
+        value.model = selected.model;
+    const modelVersion = selected.modelVersion ?? selected.version;
+    if (modelVersion !== undefined)
+        value.modelVersion = modelVersion;
+    const additional = {};
+    if (selected.effort !== undefined)
+        additional.effort = selected.effort;
+    if (selected.speed !== undefined)
+        additional.speed = selected.speed;
+    if (selected.intelligence !== undefined) {
+        return {
+            ok: false,
+            message: "configuration.intelligence is not supported by the transactional Work path.",
+            fieldPath: "configuration.intelligence"
+        };
+    }
+    if (Object.keys(additional).length > 0)
+        value.additional = additional;
+    return { ok: true, value };
+}
+function transactionalWorkWaitOptions(wait, read) {
+    const readRequested = read === true || typeof read === "object";
+    const responseFormat = typeof read === "object" && read.format === "text"
+        ? "text"
+        : "markdown";
+    const maxResponseChars = typeof read === "object" ? read.maxChars : undefined;
+    if (maxResponseChars !== undefined
+        && (!Number.isSafeInteger(maxResponseChars) || maxResponseChars < 0 || maxResponseChars > 8 * 1024 * 1024)) {
+        return { ok: false, message: "read.maxChars must be between 0 and 8388608.", fieldPath: "read.maxChars" };
+    }
+    if (typeof read === "object") {
+        if (read.role !== undefined && read.role !== "assistant") {
+            return { ok: false, message: "read.role=user is not supported by the transactional Work path.", fieldPath: "read.role" };
+        }
+        if (read.format !== undefined && read.format !== "markdown" && read.format !== "text") {
+            return { ok: false, message: "read.format must be markdown or text on the transactional Work path.", fieldPath: "read.format" };
+        }
+    }
+    if (typeof wait === "object") {
+        if (wait.timeoutMs !== undefined && (!Number.isSafeInteger(wait.timeoutMs) || wait.timeoutMs < 1 || wait.timeoutMs > 86_400_000)) {
+            return { ok: false, message: "wait.timeoutMs must be between 1 and 86400000.", fieldPath: "wait.timeoutMs" };
+        }
+        if (wait.pollMs !== undefined && (!Number.isSafeInteger(wait.pollMs) || wait.pollMs < 0 || wait.pollMs > 60_000)) {
+            return { ok: false, message: "wait.pollMs must be between 0 and 60000.", fieldPath: "wait.pollMs" };
+        }
+        if (wait.responseContent !== undefined && wait.responseContent !== "include" && wait.responseContent !== "metadata") {
+            return { ok: false, message: "wait.responseContent must be include or metadata.", fieldPath: "wait.responseContent" };
+        }
+        for (const [key, value] of [
+            ["afterTurnCount", wait.afterTurnCount],
+            ["afterAssistantTurnCount", wait.afterAssistantTurnCount],
+            ["afterStep", wait.afterStep],
+            ["stableMs", wait.stableMs],
+            ["mode", wait.mode]
+        ]) {
+            if (value !== undefined) {
+                return { ok: false, message: `wait.${key} is not supported by the transactional Work path.`, fieldPath: `wait.${key}` };
+            }
+        }
+    }
+    // A Work read is collect-only.  If the caller asks to read without an
+    // explicit wait, collect still waits for the exact owned turn rather than
+    // falling back to a page-wide latest response.
+    const waitForOwnedTurn = wait !== false || readRequested;
+    const responseContent = typeof wait === "object" && wait.responseContent !== undefined
+        ? wait.responseContent
+        : readRequested ? "include" : "metadata";
+    const options = {
+        wait: waitForOwnedTurn,
+        responseContent,
+        ...(typeof wait === "object" && wait.timeoutMs === undefined ? {} : typeof wait === "object" ? { timeoutMs: wait.timeoutMs } : {}),
+        ...(typeof wait === "object" && wait.pollMs === undefined ? {} : typeof wait === "object" ? { pollIntervalMs: wait.pollMs } : {})
+    };
+    return {
+        ok: true,
+        options,
+        responseContent,
+        readRequested,
+        responseFormat,
+        ...(maxResponseChars === undefined ? {} : { maxResponseChars })
+    };
+}
+async function transactionalWorkTask(operations, handle) {
+    try {
+        const inspected = await operations.inspect(handle);
+        const target = inspected.state.target;
+        return {
+            ...(target?.canonicalThreadUrl === undefined ? {} : { url: target.canonicalThreadUrl }),
+            ...(target?.conversationId === undefined ? {} : { conversationId: target.conversationId })
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function transactionalWorkStartResult(prepared, run, handle, task) {
+    const base = {
+        task,
+        responseFormat: prepared.responseFormat,
+        operationId: handle.operationId,
+        handle,
+        requestDigest: handle.requestDigest,
+        submitted: {
+            submitted: false,
+            submissionState: transactionalSubmissionState(handle, "blocker" in run.submit.submission ? run.submit.submission.blocker.mutationBoundary : handle.mutationBoundary),
+            completionState: transactionalCompletionState(handle.phase),
+            generationActive: handle.phase === "generating"
+        }
+    };
+    const submission = run.submit.submission;
+    if (submission.kind === "blocked" || submission.kind === "uncertain" || submission.kind === "cancelled") {
+        const submitted = {
+            ...base,
+            submitted: {
+                ...base.submitted,
+                submitted: base.submitted.submissionState !== "not_submitted"
+            }
+        };
+        return transactionalWorkBlockerResult(submitted, submission.blocker.code, submission.kind === "uncertain" || submission.blocker.mutationBoundary !== "none", submission.blocker.observationRequired);
+    }
+    base.submitted = {
+        ...base.submitted,
+        submitted: true,
+        submissionState: "submitted",
+        completionState: handle.phase === "generating" ? "generating" : handle.phase === "completed" ? "complete" : "unknown",
+        generationActive: handle.phase === "generating"
+    };
+    const collected = run.collect;
+    if (collected === undefined) {
+        return {
+            ok: true,
+            status: "ok",
+            data: { ...base, pending: true, complete: handle.phase === "completed" },
+            warnings: ["Work was submitted through the transactional path; collect the returned handle to observe its exact assistant turn."],
+            context: { timestamp: new Date().toISOString(), experience: "work" }
+        };
+    }
+    if (collected.kind === "completed") {
+        const rawText = prepared.request.capture?.responseContent === "include" ? collected.response.rawText : undefined;
+        const responseText = rawText === undefined
+            ? undefined
+            : prepared.maxResponseChars === undefined
+                ? rawText
+                : rawText.slice(0, prepared.maxResponseChars);
+        const response = prepared.readRequested && responseText !== undefined
+            ? {
+                role: "assistant",
+                text: responseText,
+                format: prepared.responseFormat === "text" ? "normalized_text" : "markdown",
+                completionState: "complete",
+                generationActive: false
+            }
+            : undefined;
+        const data = {
+            ...base,
+            complete: true,
+            ...(collected.response.text?.digest === undefined ? {} : { responseDigest: collected.response.text.digest }),
+            ...(collected.response.text?.bytes === undefined ? {} : { responseBytes: collected.response.text.bytes }),
+            ...(response === undefined ? {} : { response }),
+            submitted: {
+                ...base.submitted,
+                completionState: "complete",
+                generationActive: false
+            }
+        };
+        return { ok: true, status: "ok", data, warnings: [], context: { timestamp: new Date().toISOString(), experience: "work" } };
+    }
+    if (collected.kind === "pending") {
+        return {
+            ok: false,
+            status: "partial",
+            data: {
+                ...base,
+                pending: true,
+                complete: false,
+                submitted: {
+                    ...base.submitted,
+                    completionState: collected.phase === "generating" ? "generating" : "unknown",
+                    generationActive: collected.phase === "generating"
+                }
+            },
+            warnings: ["Work was submitted exactly once, but completion was not verified."],
+            context: { timestamp: new Date().toISOString(), experience: "work" }
+        };
+    }
+    return transactionalWorkBlockerResult(base, collected.blocker.code, collected.blocker.mutationBoundary !== "none", true);
+}
+function hasTransactionalWorkControl(args) {
+    return args.operationId !== undefined
+        || args.handle !== undefined
+        || args.controlActionId !== undefined
+        || args.expectedAssistantTurnId !== undefined;
+}
+async function runTransactionalWorkSteer(args, operations) {
+    const operationId = args.operationId ?? args.handle?.operationId;
+    if (args.prompt.trim().length === 0) {
+        return transactionalWorkSteerUnsupported(operationId, "prompt must be non-empty.", "prompt");
+    }
+    if (args.handle === undefined) {
+        return transactionalWorkSteerUnsupported(operationId, "a durable parent handle is required for transactional Work steer.", "handle");
+    }
+    if (args.handle.surface !== "work") {
+        return transactionalWorkSteerUnsupported(operationId, "the parent handle must belong to the Work surface.", "handle.surface", args.handle);
+    }
+    if (args.handle.phase !== "generating") {
+        return transactionalWorkSteerUnsupported(operationId, "the parent handle must identify a generating Work operation.", "handle.phase", args.handle);
+    }
+    if (args.handle.targetBindingDigest === undefined) {
+        return transactionalWorkSteerUnsupported(operationId, "the parent handle must carry an exact target binding.", "handle.targetBindingDigest", args.handle);
+    }
+    if (operationId === undefined || !TRANSACTIONAL_OPERATION_ID_PATTERN.test(operationId)) {
+        return transactionalWorkSteerUnsupported(operationId, "operationId must be a canonical UUID.", "operationId", args.handle);
+    }
+    if (args.handle.operationId !== operationId) {
+        return transactionalWorkSteerUnsupported(operationId, "operationId must match handle.operationId.", "operationId", args.handle);
+    }
+    if (args.controlActionId === undefined || !TRANSACTIONAL_OPERATION_ID_PATTERN.test(args.controlActionId)) {
+        return transactionalWorkSteerUnsupported(operationId, "controlActionId must be a canonical UUID.", "controlActionId", args.handle);
+    }
+    if (args.expectedAssistantTurnId === undefined || !/^[A-Za-z0-9._:-]{1,512}$/u.test(args.expectedAssistantTurnId)) {
+        return transactionalWorkSteerUnsupported(operationId, "expectedAssistantTurnId must identify one exact assistant turn.", "expectedAssistantTurnId", args.handle);
+    }
+    if (args.wait !== undefined && args.wait !== false) {
+        return transactionalWorkSteerUnsupported(operationId, "wait is not supported by transactional Work steer; collect the parent operation separately.", "wait", args.handle);
+    }
+    if (args.read !== undefined && args.read !== false) {
+        return transactionalWorkSteerUnsupported(operationId, "read is not supported by transactional Work steer; collect the parent operation separately.", "read", args.handle);
+    }
+    if (args.timeoutMs !== undefined && (!Number.isSafeInteger(args.timeoutMs) || args.timeoutMs < 0 || args.timeoutMs > 86_400_000)) {
+        return transactionalWorkSteerUnsupported(operationId, "timeoutMs must be between 0 and 86400000.", "timeoutMs", args.handle);
+    }
+    const request = {
+        schemaVersion: OPERATION_CONTROL_REQUEST_SCHEMA_VERSION,
+        controlActionId: args.controlActionId,
+        parent: args.handle,
+        action: "steer",
+        expectedAssistantTurnId: args.expectedAssistantTurnId,
+        steerPrompt: args.prompt,
+        ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs })
+    };
+    try {
+        const result = await operations.control(request);
+        const data = {
+            operationId,
+            controlActionId: result.controlActionId,
+            requestDigest: result.requestDigest,
+            handle: args.handle,
+            parentHandle: args.handle,
+            ...(result.kind === "completed" || result.receipt === undefined ? {} : { control: result.receipt }),
+            ...(result.kind === "completed" ? { control: result.receipt } : {})
+        };
+        if (result.kind === "completed") {
+            return {
+                ok: true,
+                status: "ok",
+                data,
+                warnings: ["Work steer was bound to the supplied assistant turn and authorized at most one browser action."],
+                context: { timestamp: new Date().toISOString(), experience: "work" }
+            };
+        }
+        return transactionalWorkBlockerResult(data, result.blocker.code, result.kind === "uncertain" || result.blocker.mutationBoundary !== "none", result.blocker.observationRequired);
+    }
+    catch (error) {
+        return transactionalWorkError(operationId, error, args.controlActionId, args.handle);
+    }
+}
+function transactionalWorkStartUnsupported(operationId, message, fieldPath) {
+    const unsupported = transactionalUnsupported(operationId, message, fieldPath);
+    if (unsupported.ok) {
+        return {
+            ok: false,
+            status: "error",
+            data: {
+                task: {},
+                submitted: { submitted: false, submissionState: "not_submitted" },
+                ...(operationId === undefined ? {} : { operationId })
+            },
+            warnings: [],
+            error: { name: "OperationInputError", message, recoverable: false },
+            context: { timestamp: new Date().toISOString(), experience: "work" }
+        };
+    }
+    return {
+        ...unsupported.result,
+        data: {
+            task: {},
+            submitted: { submitted: false, submissionState: "not_submitted" },
+            ...(operationId === undefined ? {} : { operationId })
+        }
+    };
+}
+function transactionalWorkSteerUnsupported(operationId, message, fieldPath, handle) {
+    const unsupported = transactionalUnsupported(operationId, message, fieldPath);
+    if (unsupported.ok) {
+        return {
+            ok: false,
+            status: "error",
+            data: {
+                ...(operationId === undefined ? {} : { operationId }),
+                ...(handle === undefined ? {} : { handle, parentHandle: handle })
+            },
+            warnings: [],
+            error: { name: "OperationInputError", message, recoverable: false },
+            context: { timestamp: new Date().toISOString(), experience: "work" }
+        };
+    }
+    return {
+        ...unsupported.result,
+        data: {
+            ...(operationId === undefined ? {} : { operationId }),
+            ...(handle === undefined ? {} : { handle, parentHandle: handle })
+        }
+    };
+}
+function transactionalWorkBlockerResult(data, code, uncertain, recoverable) {
+    const message = `Transactional Work operation ${uncertain ? "is uncertain" : "was blocked"} (${code.replaceAll("_", " ")}).`;
+    return {
+        ok: false,
+        status: uncertain ? "partial" : "blocked",
+        data,
+        warnings: [],
+        blocker: {
+            kind: transactionalBlockerKind(code),
+            code,
+            message,
+            resumable: recoverable
+        },
+        context: { timestamp: new Date().toISOString(), experience: "work" }
+    };
+}
+function transactionalWorkError(operationId, error, controlActionId, parentHandle) {
+    const code = safeOwnErrorCode(error) ?? "operation_error";
+    const message = `Transactional Work operation failed (${code.replaceAll("_", " ")}).`;
+    const blocker = code === "adapter_unavailable"
+        || code === "browser_bridge_unavailable"
+        || code === "target_evidence_unavailable"
+        || code === "backend_unavailable";
+    const data = parentHandle === undefined
+        ? {
+            operationId,
+            task: {},
+            submitted: { submitted: false, submissionState: "not_submitted" }
+        }
+        : {
+            operationId,
+            controlActionId,
+            handle: parentHandle,
+            parentHandle
+        };
+    return {
+        ok: false,
+        status: blocker ? "blocked" : "error",
+        data,
+        warnings: [],
+        ...(blocker ? { blocker: { kind: transactionalBlockerKind(code), code, message, resumable: true } } : {}),
+        error: { name: "OperationError", message, recoverable: blocker },
+        context: { timestamp: new Date().toISOString(), experience: "work" }
+    };
+}
+async function freshestOperationHandle(operations, candidate) {
+    try {
+        const inspected = await operations.inspect(candidate);
+        return inspected.handle;
+    }
+    catch {
+        // The submit/collect result is still an authenticated handle and is the
+        // freshest locator available if a browser-free reload is unavailable.
+        return candidate;
+    }
+}
+function prepareTransactionalAsk(args, defaults, clientOptions) {
+    const operationId = args.operationId;
+    if (operationId === undefined || !TRANSACTIONAL_OPERATION_ID_PATTERN.test(operationId)) {
+        return transactionalUnsupported(operationId, "operationId must be a canonical UUID.", "operationId");
+    }
+    if (args.prompt.trim().length === 0) {
+        return transactionalUnsupported(operationId, "prompt must be non-empty.", "prompt");
+    }
+    if (args.download !== undefined) {
+        return transactionalUnsupported(operationId, "download is not supported by the transactional ask path; use operations.collect and an explicit artifact transfer.", "download");
+    }
+    if (args.report !== undefined && args.report !== false) {
+        return transactionalUnsupported(operationId, "report is not supported by the transactional ask path.", "report");
+    }
+    if (clientOptions.reporting?.enabled === true) {
+        return transactionalUnsupported(operationId, "client reporting must be disabled for the transactional ask path.", "reporting");
+    }
+    const target = transactionalTarget(args, defaults);
+    if (!target.ok)
+        return transactionalUnsupported(operationId, target.message, target.fieldPath);
+    const configuration = transactionalConfiguration(args, defaults);
+    if (!configuration.ok)
+        return transactionalUnsupported(operationId, configuration.message, configuration.fieldPath);
+    const wait = args.wait ?? defaults?.wait ?? true;
+    const read = args.read ?? defaults?.read ?? { format: "markdown" };
+    const waitOptions = transactionalWaitOptions(wait, read);
+    if (!waitOptions.ok)
+        return transactionalUnsupported(operationId, waitOptions.message, waitOptions.fieldPath);
+    const files = [
+        ...(args.files ?? []),
+        ...(args.attachments ?? [])
+    ].map(file => typeof file === "string" ? { path: file } : { path: file.path });
+    const request = {
+        schemaVersion: OPERATION_REQUEST_SCHEMA_VERSION,
+        operationId,
+        surface: "chat",
+        prompt: args.prompt,
+        target: target.target,
+        ...(configuration.value === undefined ? {} : { configuration: configuration.value }),
+        ...(files.length === 0 ? {} : { files }),
+        capture: {
+            responseContent: waitOptions.responseContent,
+            responseFormat: waitOptions.responseFormat,
+            artifacts: "receipt_only"
+        }
+    };
+    return {
+        ok: true,
+        value: {
+            request,
+            options: waitOptions.options,
+            responseFormat: waitOptions.responseFormat,
+            ...(waitOptions.maxResponseChars === undefined ? {} : { maxResponseChars: waitOptions.maxResponseChars })
+        }
+    };
+}
+function transactionalTarget(args, defaults) {
+    const thread = args.thread ?? defaults?.thread;
+    const existingTab = args.existingTab ?? defaults?.existingTab;
+    const preferExistingTab = args.preferExistingTab ?? defaults?.preferExistingTab;
+    if (thread !== undefined) {
+        if (existingTab !== undefined || preferExistingTab === true) {
+            return {
+                ok: false,
+                message: "thread cannot be combined with existingTab or preferExistingTab on the transactional ask path.",
+                fieldPath: "thread"
+            };
+        }
+        return targetFromWorkflowThread(thread);
+    }
+    if (preferExistingTab === true) {
+        if (existingTab !== undefined) {
+            return {
+                ok: false,
+                message: "preferExistingTab cannot be combined with existingTab on the transactional ask path.",
+                fieldPath: "preferExistingTab"
+            };
+        }
+        return { ok: true, target: { type: "selected_tab" } };
+    }
+    if (existingTab !== undefined)
+        return targetFromExistingTab(existingTab);
+    return { ok: true, target: { type: "new" } };
+}
+function targetFromWorkflowThread(thread) {
+    if (isTypedThread(thread)) {
+        switch (thread.type) {
+            case "new":
+                return { ok: true, target: { type: "new" } };
+            case "current":
+                return { ok: true, target: { type: "selected_tab" } };
+            case "url":
+                return thread.url.length > 0
+                    ? { ok: true, target: { type: "url", url: thread.url } }
+                    : { ok: false, message: "thread.url must be non-empty.", fieldPath: "thread.url" };
+            case "conversationId":
+            case "conversation_id":
+                return thread.conversationId.length > 0
+                    ? { ok: true, target: { type: "conversation_id", conversationId: thread.conversationId } }
+                    : { ok: false, message: "thread.conversationId must be non-empty.", fieldPath: "thread.conversationId" };
+            case "search":
+            case "title":
+                return {
+                    ok: false,
+                    message: "thread search/title selection is not supported by the transactional ask path; supply a URL or conversationId.",
+                    fieldPath: "thread"
+                };
+        }
+    }
+    if (thread.url !== undefined) {
+        return thread.url.length > 0
+            ? { ok: true, target: { type: "url", url: thread.url } }
+            : { ok: false, message: "thread.url must be non-empty.", fieldPath: "thread.url" };
+    }
+    if (thread.conversationId !== undefined) {
+        return thread.conversationId.length > 0
+            ? { ok: true, target: { type: "conversation_id", conversationId: thread.conversationId } }
+            : { ok: false, message: "thread.conversationId must be non-empty.", fieldPath: "thread.conversationId" };
+    }
+    if (thread.query !== undefined || thread.title !== undefined) {
+        return {
+            ok: false,
+            message: "thread search/title selection is not supported by the transactional ask path; supply a URL or conversationId.",
+            fieldPath: "thread"
+        };
+    }
+    return { ok: true, target: { type: "new" } };
+}
+function targetFromExistingTab(existingTab) {
+    if (existingTab === true)
+        return { ok: true, target: { type: "selected_tab" } };
+    if (existingTab === false)
+        return { ok: true, target: { type: "new" } };
+    if (existingTab.ifMissing !== undefined && existingTab.ifMissing !== "block") {
+        return { ok: false, message: "existingTab.ifMissing must be block on the transactional ask path.", fieldPath: "existingTab.ifMissing" };
+    }
+    if (existingTab.ifMultiple !== undefined && existingTab.ifMultiple !== "block") {
+        return { ok: false, message: "existingTab.ifMultiple must be block on the transactional ask path.", fieldPath: "existingTab.ifMultiple" };
+    }
+    if (existingTab.requireChatGPT === false) {
+        return { ok: false, message: "existingTab.requireChatGPT=false is not supported by the transactional ask path.", fieldPath: "existingTab.requireChatGPT" };
+    }
+    const target = existingTab.target;
+    if (target === undefined || target.type === "selected")
+        return { ok: true, target: { type: "selected_tab" } };
+    switch (target.type) {
+        case "tabId":
+            return target.tabId.length > 0
+                ? { ok: true, target: { type: "tab_id", tabId: target.tabId } }
+                : { ok: false, message: "existingTab.target.tabId must be non-empty.", fieldPath: "existingTab.target.tabId" };
+        case "conversationId":
+        case "conversation_id":
+            return target.conversationId.length > 0
+                ? { ok: true, target: { type: "conversation_id", conversationId: target.conversationId } }
+                : { ok: false, message: "existingTab.target.conversationId must be non-empty.", fieldPath: "existingTab.target.conversationId" };
+        case "url":
+            return target.url.length > 0
+                ? { ok: true, target: { type: "url", url: target.url } }
+                : { ok: false, message: "existingTab.target.url must be non-empty.", fieldPath: "existingTab.target.url" };
+        case "title":
+            return { ok: false, message: "existingTab title selection is not supported by the transactional ask path; supply a tabId, URL, or conversationId.", fieldPath: "existingTab.target" };
+    }
+}
+function transactionalConfiguration(args, defaults) {
+    const experience = args.experience ?? defaults?.experience;
+    if (experience === "work") {
+        return { ok: false, message: "experience=work is not supported by the transactional chat ask path.", fieldPath: "experience" };
+    }
+    const selected = args.configuration ?? defaults?.configuration;
+    const mode = args.mode ?? defaults?.mode;
+    if (mode?.timeoutMs !== undefined) {
+        return { ok: false, message: "mode.timeoutMs is not supported by the transactional ask path.", fieldPath: "mode.timeoutMs" };
+    }
+    const values = {};
+    if (experience !== undefined)
+        values.experience = experience;
+    const model = mergeConfigurationValue("model", selected?.model, mode?.model);
+    if (!model.ok)
+        return model;
+    if (model.value !== undefined)
+        values.model = model.value;
+    const modelVersion = mergeConfigurationValue("modelVersion", selected?.modelVersion ?? selected?.version, mode?.modelVersion ?? mode?.version);
+    if (!modelVersion.ok)
+        return modelVersion;
+    if (modelVersion.value !== undefined)
+        values.modelVersion = modelVersion.value;
+    const additional = {};
+    for (const [axis, first, second] of [
+        ["intelligence", selected?.intelligence, mode?.intelligence],
+        ["effort", selected?.effort, mode?.effort],
+        ["speed", selected?.speed, undefined]
+    ]) {
+        const merged = mergeConfigurationValue(axis, first, second);
+        if (!merged.ok)
+            return merged;
+        if (merged.value !== undefined)
+            additional[axis] = merged.value;
+    }
+    const tools = args.tools;
+    if (tools !== undefined) {
+        for (const [index, tool] of tools.entries()) {
+            if (tool.tool.trim().length === 0) {
+                return { ok: false, message: "tool must be non-empty.", fieldPath: `tools[${index}].tool` };
+            }
+            if (tool.timeoutMs !== undefined) {
+                return { ok: false, message: "tool timeoutMs is not supported by the transactional ask path.", fieldPath: `tools[${index}].timeoutMs` };
+            }
+        }
+        if (tools.length > 0)
+            values.tools = tools.map(tool => tool.tool);
+    }
+    if (Object.keys(additional).length > 0)
+        values.additional = additional;
+    return Object.keys(values).length === 0 ? { ok: true } : { ok: true, value: values };
+}
+function mergeConfigurationValue(axis, first, second) {
+    if (first !== undefined && second !== undefined && first !== second) {
+        return {
+            ok: false,
+            message: `configuration and mode disagree for ${axis}; provide one value.`,
+            fieldPath: axis === "modelVersion" ? "configuration.modelVersion" : `configuration.${axis}`
+        };
+    }
+    if (first === undefined && second === undefined)
+        return { ok: true };
+    const value = first ?? second;
+    return value === undefined ? { ok: true } : { ok: true, value };
+}
+function transactionalWaitOptions(wait, read) {
+    const readRequested = read === true || typeof read === "object";
+    const responseFormat = typeof read === "object" && read.format === "text"
+        ? "text"
+        : "markdown";
+    const maxResponseChars = typeof read === "object" ? read.maxChars : undefined;
+    if (maxResponseChars !== undefined && (!Number.isSafeInteger(maxResponseChars) || maxResponseChars < 0 || maxResponseChars > 8 * 1024 * 1024)) {
+        return { ok: false, message: "read.maxChars must be between 0 and 8388608.", fieldPath: "read.maxChars" };
+    }
+    if (typeof read === "object") {
+        if (read.role !== undefined && read.role !== "assistant") {
+            return { ok: false, message: "read.role=user is not supported by the transactional ask path.", fieldPath: "read.role" };
+        }
+        if (read.format !== undefined && read.format !== "markdown" && read.format !== "text") {
+            return { ok: false, message: "read.format must be markdown or text on the transactional ask path.", fieldPath: "read.format" };
+        }
+    }
+    if (typeof wait === "object") {
+        if (wait.timeoutMs !== undefined && (!Number.isSafeInteger(wait.timeoutMs) || wait.timeoutMs < 1 || wait.timeoutMs > 86_400_000)) {
+            return { ok: false, message: "wait.timeoutMs must be between 1 and 86400000.", fieldPath: "wait.timeoutMs" };
+        }
+        if (wait.pollMs !== undefined && (!Number.isSafeInteger(wait.pollMs) || wait.pollMs < 0 || wait.pollMs > 60_000)) {
+            return { ok: false, message: "wait.pollMs must be between 0 and 60000.", fieldPath: "wait.pollMs" };
+        }
+        if (wait.responseContent !== undefined && wait.responseContent !== "include" && wait.responseContent !== "metadata") {
+            return { ok: false, message: "wait.responseContent must be include or metadata.", fieldPath: "wait.responseContent" };
+        }
+        for (const [key, value] of [
+            ["afterTurnCount", wait.afterTurnCount],
+            ["afterAssistantTurnCount", wait.afterAssistantTurnCount],
+            ["afterStep", wait.afterStep],
+            ["stableMs", wait.stableMs],
+            ["mode", wait.mode]
+        ]) {
+            if (value !== undefined) {
+                return { ok: false, message: `wait.${key} is not supported by the transactional ask path.`, fieldPath: `wait.${key}` };
+            }
+        }
+    }
+    const responseContent = typeof wait === "object" && wait.responseContent !== undefined
+        ? wait.responseContent
+        : readRequested ? "include" : "metadata";
+    const options = {
+        wait: wait !== false,
+        responseContent,
+        ...(typeof wait === "object" && wait.timeoutMs === undefined ? {} : typeof wait === "object" ? { timeoutMs: wait.timeoutMs } : {}),
+        ...(typeof wait === "object" && wait.pollMs === undefined ? {} : typeof wait === "object" ? { pollIntervalMs: wait.pollMs } : {})
+    };
+    return {
+        ok: true,
+        options,
+        responseContent,
+        readRequested,
+        responseFormat,
+        ...(maxResponseChars === undefined ? {} : { maxResponseChars })
+    };
+}
+function transactionalUnsupported(operationId, message, fieldPath) {
+    const data = operationId === undefined ? {} : { operationId };
+    return {
+        ok: false,
+        result: {
+            ok: false,
+            status: "unsupported",
+            data,
+            warnings: [],
+            error: { name: "OperationInputError", message, recoverable: false },
+            blocker: { kind: "unknown", code: "unsupported_operation_input", fieldPath, message },
+            context: { timestamp: new Date().toISOString() }
+        }
+    };
+}
+function transactionalAskCommandResult(prepared, run, handle) {
+    const base = {
+        operationId: handle.operationId,
+        responseFormat: prepared.responseFormat,
+        handle,
+        requestDigest: handle.requestDigest
+    };
+    const submission = run.submit.submission;
+    if (submission.kind === "blocked" || submission.kind === "uncertain" || submission.kind === "cancelled") {
+        return transactionalBlockerResult({
+            ...base,
+            submissionState: transactionalSubmissionState(handle, submission.blocker.mutationBoundary),
+            complete: false,
+            completionState: transactionalCompletionState(handle.phase),
+            generationActive: handle.phase === "generating"
+        }, submission.blocker.code, submission.blocker.mutationBoundary !== "none", submission.blocker.observationRequired);
+    }
+    if (run.collect === undefined) {
+        if (submission.kind === "completed_receipt") {
+            return {
+                ok: true,
+                status: "ok",
+                data: { ...base, submissionState: "submitted", complete: true, completionState: "complete", generationActive: false },
+                warnings: [],
+                context: { timestamp: new Date().toISOString() }
+            };
+        }
+        return {
+            ok: false,
+            status: "partial",
+            data: { ...base, pending: true, complete: false, completionState: "generating", generationActive: true, submissionState: "submitted_generating" },
+            warnings: [],
+            context: { timestamp: new Date().toISOString() }
+        };
+    }
+    const collected = run.collect;
+    if (collected.kind === "completed") {
+        const rawText = prepared.request.capture?.responseContent === "include" ? collected.response.rawText : undefined;
+        const responseText = rawText === undefined
+            ? undefined
+            : prepared.maxResponseChars === undefined
+                ? rawText
+                : rawText.slice(0, prepared.maxResponseChars);
+        const data = {
+            ...base,
+            submissionState: "submitted",
+            complete: true,
+            completionState: "complete",
+            generationActive: false,
+            ...(responseText === undefined ? {} : { responseText }),
+            ...(collected.response.text?.digest === undefined ? {} : { responseDigest: collected.response.text.digest }),
+            ...(collected.response.text?.bytes === undefined ? {} : { responseBytes: collected.response.text.bytes }),
+            artifacts: collected.response.artifacts
+        };
+        return { ok: true, status: "ok", data, warnings: [], context: { timestamp: new Date().toISOString() } };
+    }
+    if (collected.kind === "pending") {
+        return {
+            ok: false,
+            status: "partial",
+            data: { ...base, pending: true, complete: false, completionState: collected.phase === "generating" ? "generating" : "unknown", generationActive: collected.phase === "generating", submissionState: "submitted_generating" },
+            warnings: [],
+            context: { timestamp: new Date().toISOString() }
+        };
+    }
+    return transactionalBlockerResult({
+        ...base,
+        submissionState: transactionalSubmissionState(handle, collected.blocker.mutationBoundary),
+        complete: false,
+        completionState: transactionalCompletionState(handle.phase),
+        generationActive: handle.phase === "generating"
+    }, collected.blocker.code, collected.blocker.mutationBoundary !== "none", true);
+}
+function transactionalSubmissionState(handle, boundary) {
+    if (["submitted", "generating", "capturing", "completed"].includes(handle.phase)) {
+        return handle.phase === "generating" ? "submitted_generating" : "submitted";
+    }
+    return boundary === "send_may_have_occurred" || boundary === "control_may_have_occurred"
+        ? "submitted_unconfirmed"
+        : "not_submitted";
+}
+function transactionalCompletionState(phase) {
+    if (phase === "completed")
+        return "complete";
+    if (phase === "generating")
+        return "generating";
+    if (phase === "uncertain" || phase === "capturing")
+        return "partial";
+    return "unknown";
+}
+function transactionalBlockerResult(data, code, uncertain, recoverable) {
+    const kind = transactionalBlockerKind(code);
+    const message = `Transactional operation ${uncertain ? "is uncertain" : "was blocked"} (${code.replaceAll("_", " ")}).`;
+    return {
+        ok: false,
+        status: uncertain ? "partial" : "blocked",
+        data,
+        warnings: [],
+        blocker: { kind, code, message, resumable: recoverable },
+        context: { timestamp: new Date().toISOString() }
+    };
+}
+function transactionalBlockerKind(code) {
+    if (code === "browser_bridge_unavailable")
+        return "browser_bridge_unavailable";
+    if (code === "login_required")
+        return "login_required";
+    if (code === "captcha")
+        return "captcha";
+    if (code === "rate_limited")
+        return "rate_limit";
+    if (code === "permission_required" || code === "input_file_changed")
+        return "permission";
+    if (code === "needs_confirmation")
+        return "confirmation";
+    if (code.includes("artifact"))
+        return "artifact_unavailable";
+    if (code.includes("selector") || code.includes("configuration") || code.includes("target") || code.includes("turn"))
+        return "selector_drift";
+    if (code.includes("file") || code.includes("attachment"))
+        return "upload_failed";
+    return "unknown";
+}
+function transactionalAskError(operationId, error) {
+    const code = safeOwnErrorCode(error) ?? "operation_error";
+    const blocker = code === "adapter_unavailable" || code === "browser_bridge_unavailable" || code === "target_evidence_unavailable";
+    const message = `Transactional operation failed (${code.replaceAll("_", " ")}).`;
+    return {
+        ok: false,
+        status: blocker ? "blocked" : "error",
+        data: { operationId },
+        warnings: [],
+        ...(blocker ? { blocker: { kind: transactionalBlockerKind(code), code, message, resumable: true } } : {}),
+        error: { name: "OperationError", message, recoverable: blocker },
+        context: { timestamp: new Date().toISOString() }
+    };
 }
 function planAskWorkflow(args, defaults = {}) {
     const thread = args.thread ?? { type: "new" };
@@ -786,6 +1913,42 @@ function normalizeFileInputs(files) {
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+/**
+ * Read only a bounded own data property. Provider/runtime failures are an
+ * untrusted boundary: consulting an inherited property or accessor can run
+ * arbitrary code and can surface private diagnostics while formatting a
+ * public result.
+ */
+function safeOwnErrorCode(value) {
+    if (!isRecord(value))
+        return undefined;
+    let descriptor;
+    try {
+        descriptor = Object.getOwnPropertyDescriptor(value, "code");
+    }
+    catch {
+        return undefined;
+    }
+    if (descriptor === undefined || !("value" in descriptor))
+        return undefined;
+    return typeof descriptor.value === "string" && /^[a-z][a-z0-9_]{0,63}$/u.test(descriptor.value)
+        ? descriptor.value
+        : undefined;
+}
+function readOperationIdFromUnknown(value) {
+    if (!isRecord(value))
+        return undefined;
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(value, "operationId");
+        const operationId = descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+        return typeof operationId === "string" && TRANSACTIONAL_OPERATION_ID_PATTERN.test(operationId)
+            ? operationId
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function stringInput(input, key) {
     const value = input[key];
     if (typeof value !== "string" || value.length === 0) {