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

package/dist/src/scripts/live-smoke/transactional.js

@@ -0,0 +1,254 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createChatGPT } from "../../client.js";
+import { contextEnvFlag, contextEnvText } from "./harness.js";
+const EXPECTED_RESPONSE = "ISSUE41_OK";
+const PROMPT = `Reply with exactly this token and no other text:\n\n${EXPECTED_RESPONSE}`;
+/**
+ * Explicit opt-in: one new synthetic conversation, zero attachments, and at
+ * most one Send. Uses the production runtime with an optional explicit journal service.
+ * An ambiguous submission permits one guarded, observation-only recovery.
+ * A completed receipt is required before the final same-identity replay.
+ */
+export const transactionalSubmitOnceScenario = {
+    name: "transactional-submit-once",
+    required: false,
+    enabled: context => contextEnvFlag(context, "CHATGPT_E2E_TRANSACTIONAL"),
+    run: async (context) => {
+        const startedMs = Date.now();
+        const startedAt = new Date(startedMs).toISOString();
+        const descriptorPath = contextEnvText(context, "CHATGPT_E2E_JOURNAL_DESCRIPTOR");
+        const chatgpt = createChatGPT({
+            agent: context.agent,
+            ...(descriptorPath === undefined ? {} : { operations: { journalService: { descriptorPath } } }),
+            ...(context.browser === undefined ? {} : { browser: context.browser })
+        });
+        const evidence = await qualifyTransactionalSubmitOnce(chatgpt);
+        return {
+            name: "transactional-submit-once",
+            required: false,
+            status: evidence.passed ? "pass" : "fail",
+            startedAt,
+            endedAt: new Date().toISOString(),
+            durationMs: Date.now() - startedMs,
+            details: evidence.details
+        };
+    }
+};
+/** The injected client is solely a harness test seam; the live entrypoint uses the public production facade. */
+export async function qualifyTransactionalSubmitOnce(chatgpt) {
+    const args = {
+        operationId: randomUUID(),
+        prompt: PROMPT,
+        thread: { type: "new" },
+        experience: "chat",
+        files: [],
+        wait: false,
+        read: { format: "text" },
+        report: false
+    };
+    const details = {
+        productionRuntime: true,
+        filesRequested: 0,
+        multilinePrompt: true,
+        duplicateRequestAttempted: false,
+        recoveryAttempted: false
+    };
+    let stage = "ask.submit";
+    const fail = () => ({ passed: false, details: { ...details, failedStage: stage } });
+    try {
+        let submitted = await chatgpt.ask(args);
+        details.submitStatus = submitted.status;
+        if (submitted.blocker !== undefined) {
+            details.blockerCode = safeCode(submitted.blocker.code);
+            if (submitted.blocker.code !== "ambiguous_submit")
+                return fail();
+        }
+        const handle = handleFromCommand(submitted);
+        if (handle === undefined || handle.operationId !== args.operationId
+            || (submitted.status !== "ok" && submitted.status !== "partial"))
+            return fail();
+        stage = "operations.inspect.submitted";
+        let initial = await chatgpt.operations.inspect(handle);
+        let initialSend = sendActions(initial.state);
+        details.initialPhase = initial.state.phase;
+        details.sendActionCount = initialSend.length;
+        if (submitted.blocker?.code === "ambiguous_submit") {
+            const intent = initialSend[0];
+            const target = initial.state.target;
+            details.recoveryEligible = sameOperationHandle(handle, initial.handle)
+                && matchesHandleState(initial.handle, initial.state)
+                && (initial.state.phase === "uncertain" || initial.state.phase === "submitted")
+                && initial.state.mutationBoundary === "send_may_have_occurred"
+                && initialSend.length === 1 && intent !== undefined
+                && intent.repeatPolicy === "observe_only_after_intent"
+                && intent.requestDigest === handle.requestDigest
+                && intent.targetDigest === handle.targetBindingDigest
+                && Number.isSafeInteger(intent.intentRevision) && intent.intentRevision > 0
+                && typeof intent.actionId === "string" && intent.actionId.length > 0
+                && target !== undefined
+                && [target.providerId, target.browserId, target.tabId].every(value => typeof value === "string" && value.length > 0);
+            if (details.recoveryEligible !== true || intent === undefined || target === undefined)
+                return fail();
+            // Capture immutable identity before calling recovery. New conversations
+            // may establish a conversation ID, but cannot change their tab/anchor.
+            const before = {
+                handle: { ...initial.handle }, intent: { ...intent },
+                providerId: target.providerId, browserId: target.browserId, tabId: target.tabId,
+                conversationId: target.conversationId
+            };
+            stage = "ask.recover_submission";
+            details.recoveryAttempted = true;
+            const recovered = await chatgpt.ask(args);
+            details.recoveryStatus = recovered.status;
+            if (recovered.blocker !== undefined) {
+                details.recoveryBlockerCode = safeCode(recovered.blocker.code);
+                return fail();
+            }
+            const recoveredHandle = handleFromCommand(recovered);
+            if (recoveredHandle === undefined || !sameOperationHandle(before.handle, recoveredHandle)
+                || (recovered.status !== "ok" && recovered.status !== "partial"))
+                return fail();
+            stage = "operations.inspect.recovered";
+            const recoveredState = await chatgpt.operations.inspect(recoveredHandle);
+            const recoveredSend = sendActions(recoveredState.state);
+            const afterIntent = recoveredSend[0];
+            const afterTarget = recoveredState.state.target;
+            details.recoverySameTarget = sameOperationHandle(before.handle, recoveredState.handle)
+                && matchesHandleState(recoveredState.handle, recoveredState.state)
+                && afterTarget?.providerId === before.providerId
+                && afterTarget?.browserId === before.browserId
+                && afterTarget?.tabId === before.tabId
+                && (before.conversationId === undefined || afterTarget?.conversationId === before.conversationId);
+            details.recoverySameSendAction = recoveredSend.length === 1
+                && afterIntent?.actionId === before.intent.actionId
+                && afterIntent?.intentRevision === before.intent.intentRevision
+                && afterIntent?.requestDigest === before.intent.requestDigest
+                && afterIntent?.targetDigest === before.intent.targetDigest
+                && afterIntent?.repeatPolicy === before.intent.repeatPolicy;
+            if (details.recoverySameTarget !== true || details.recoverySameSendAction !== true)
+                return fail();
+            details.recoveredPhase = recoveredState.state.phase;
+            submitted = recovered;
+            initial = recoveredState;
+            initialSend = recoveredSend;
+        }
+        if (initialSend.length !== 1 || initialSend[0]?.outcome !== "satisfied")
+            return fail();
+        stage = "operations.collect";
+        const collected = await chatgpt.operations.collect(initial.handle, {
+            wait: true,
+            timeoutMs: 60_000,
+            maxAttempts: 120,
+            pollIntervalMs: 500,
+            responseContent: "include",
+            responseFormat: "text"
+        });
+        details.collectKind = collected.kind;
+        if (collected.kind !== "completed") {
+            if (collected.kind === "blocked")
+                details.blockerCode = safeCode(collected.blocker.code);
+            return fail();
+        }
+        // A fast response may already be captured by ask's first observation.
+        // Completed receipt replay deliberately does not persist or return raw text.
+        const initialData = submitted.data;
+        const text = collected.response.rawText ?? (initial.state.phase === "completed"
+            && typeof initialData?.responseText === "string" ? initialData.responseText : undefined);
+        details.responseMatches = text?.trim() === EXPECTED_RESPONSE;
+        details.responseBytes = text === undefined ? 0 : new TextEncoder().encode(text).length;
+        if (text !== undefined)
+            details.responseHash = createHash("sha256").update(text).digest("hex");
+        if (details.responseMatches !== true)
+            return fail();
+        stage = "operations.inspect.completed";
+        const completed = await chatgpt.operations.inspect(initial.handle);
+        const receipt = completed.state.receipt;
+        if (completed.state.phase !== "completed" || receipt === undefined
+            || receipt.userTurnId !== collected.turn.userTurnId
+            || receipt.assistantTurnId !== collected.turn.assistantTurnId)
+            return fail();
+        details.ownedReceiptVerified = true;
+        stage = "messages.status.completed";
+        const before = await chatgpt.messages.status({ maxPreviewChars: 0 });
+        details.initialConversationVerified = matchesEstablishedConversation(before, completed.state);
+        if (!hasExactlyOneExchange(before) || details.initialConversationVerified !== true)
+            return fail();
+        // This is unreachable after unresolved uncertainty, a pending collect,
+        // a host blocker, or a missing receipt. Never use a new ID as a retry.
+        stage = "ask.same_identity";
+        details.duplicateRequestAttempted = true;
+        const replayed = await chatgpt.ask(args);
+        details.replayStatus = replayed.status;
+        if (!replayed.ok)
+            return fail();
+        const replayHandle = handleFromCommand(replayed);
+        details.sameOperationHandle = replayHandle !== undefined
+            && replayHandle.operationId === args.operationId
+            && sameOperationHandle(replayHandle, completed.handle);
+        if (details.sameOperationHandle !== true)
+            return fail();
+        stage = "operations.inspect.replayed";
+        const replayState = await chatgpt.operations.inspect(completed.handle);
+        const replaySend = sendActions(replayState.state);
+        const replayReceipt = replayState.state.receipt;
+        details.sameSendAction = replaySend.length === 1
+            && replaySend[0]?.actionId === initialSend[0]?.actionId
+            && replaySend[0]?.intentRevision === initialSend[0]?.intentRevision
+            && replaySend[0]?.receiptRevision === initialSend[0]?.receiptRevision;
+        details.sameOwnedTurns = replayReceipt?.userTurnId === receipt.userTurnId
+            && replayReceipt?.assistantTurnId === receipt.assistantTurnId;
+        if (details.sameSendAction !== true || details.sameOwnedTurns !== true)
+            return fail();
+        stage = "messages.status.replayed";
+        const after = await chatgpt.messages.status({ maxPreviewChars: 0 });
+        details.exactlyOneExchange = hasExactlyOneExchange(after);
+        details.sameConversation = matchesEstablishedConversation(after, completed.state);
+        if (details.exactlyOneExchange !== true || details.sameConversation !== true)
+            return fail();
+        details.finalPhase = replayState.state.phase;
+        return { passed: true, details };
+    }
+    catch {
+        // Host/provider failures can contain private paths or identifiers. Only
+        // bounded structural evidence crosses the live report boundary.
+        details.exception = true;
+        return fail();
+    }
+}
+function sendActions(state) {
+    return Object.values(state.actions).filter(action => action.kind === "send");
+}
+function sameOperationHandle(first, second) {
+    return typeof first.operationId === "string" && first.operationId.length > 0
+        && first.operationId === second.operationId
+        && typeof first.requestDigest === "string" && first.requestDigest.length > 0
+        && first.requestDigest === second.requestDigest
+        && first.surface === "chat" && first.surface === second.surface
+        && typeof first.targetBindingDigest === "string" && first.targetBindingDigest.length > 0
+        && first.targetBindingDigest === second.targetBindingDigest;
+}
+function matchesHandleState(handle, state) {
+    return state.operationId === handle.operationId && state.requestDigest === handle.requestDigest
+        && state.surface === handle.surface;
+}
+function handleFromCommand(command) {
+    if (typeof command.data !== "object" || command.data === null || !("handle" in command.data))
+        return undefined;
+    const value = command.data.handle;
+    return typeof value === "object" && value !== null && "operationId" in value
+        ? value
+        : undefined;
+}
+function hasExactlyOneExchange(command) {
+    const data = command.data;
+    return command.ok && data?.turnCount === 2 && data.assistantTurnCount === 1;
+}
+function matchesEstablishedConversation(command, state) {
+    const target = state.target;
+    return typeof target?.conversationId === "string" && target.conversationId.length > 0
+        && command.context.conversationId === target.conversationId
+        && (command.context.tabId === undefined || command.context.tabId === target.tabId);
+}
+function safeCode(value) {
+    return value !== undefined && /^[a-z0-9_]{1,100}$/u.test(value) ? value : "unavailable";
+}

package/dist/src/scripts/live-smoke/types.d.ts

@@ -3,6 +3,7 @@ export type LiveSmokeStatus = "pass" | "fail" | "skip";
 export type LiveSmokeCleanupResult = {
     attempted: boolean;
     ok: boolean;
+    closedTabCount?: number;
     reason?: string;
     error?: {
         name: string;
@@ -34,6 +35,8 @@ export type LiveSmokeBrowser = BrowserLike & {
 export type LiveSmokeContext = {
     agent: unknown;
     browser?: LiveSmokeBrowser;
+    /** Optional tool-scoped browser that owns tab finalization but is not used for behavior. */
+    cleanupBrowser?: LiveSmokeBrowser;
     env?: Record<string, string | undefined>;
     reportDir: string;
     knownThreadQuery?: string;

package/dist/src/scripts/release-canary-module.js

@@ -1,5 +1,6 @@
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { resolveChatGPTBrowser } from "../browser/attach.js";
 import { main as captureSurfaceProfile } from "./capture-surface-profile.js";
 import { filterScenarios, runLiveSmoke } from "./live-smoke/harness.js";
 import { optionalScenarios, requiredScenarios } from "./live-smoke/scenarios.js";
@@ -15,6 +16,11 @@ export async function runReleaseCanary(runtime, options) {
     if (options.tabId.trim().length === 0) {
         throw new Error("runReleaseCanary requires an exact dedicated ChatGPT tab id.");
     }
+    // Acquire through the agent once so bridge capability proxies are normalized
+    // before coordination. Passing globalThis.browser back through RuntimeEnv
+    // bypasses that acquisition boundary and can lose user-open-tab visibility
+    // or private-field receiver bindings on Chrome bridge methods.
+    const managedBrowser = await resolveChatGPTBrowser({ agent: runtime.agent });
     const reportDir = resolve(options.reportDir ?? join(process.cwd(), "reports", "release-canary"));
     const profileDir = join(reportDir, "surface-profiles");
     await mkdir(profileDir, { recursive: true });
@@ -32,7 +38,7 @@ export async function runReleaseCanary(runtime, options) {
                 "--if-missing", "block",
                 "--out", profilePaths[index],
                 "--provenance", "Sanitized release canary capture from a dedicated visible ChatGPT tab."
-            ], runtime);
+            ], { agent: runtime.agent });
             if (exitCode !== 0) {
                 return {
                     ok: false,
@@ -44,14 +50,18 @@ export async function runReleaseCanary(runtime, options) {
         }
     }
     finally {
-        await closeDedicatedProfileTab(runtime.browser, options.tabId);
+        await closeDedicatedProfileTab(managedBrowser, options.tabId);
     }
     const names = options.includeUpload === true
         ? [...CORE_SCENARIOS, "attach-one-file"]
         : CORE_SCENARIOS;
     const context = {
         agent: runtime.agent,
-        ...(runtime.browser === undefined ? {} : { browser: runtime.browser }),
+        browser: managedBrowser,
+        // The agent-acquired browser is authoritative for tab discovery and page
+        // behavior. The bridge-hosted global browser separately owns finalize(),
+        // which closes only this tool call's temporary tabs after each scenario.
+        ...(runtime.browser === undefined ? {} : { cleanupBrowser: runtime.browser }),
         reportDir: join(reportDir, "live-smoke"),
         env: {
             CHATGPT_E2E_CONFIGURATION_MUTATION: "1",
@@ -63,7 +73,10 @@ export async function runReleaseCanary(runtime, options) {
         throw new Error(`Release canary scenario registration drift: expected ${names.length}, found ${scenarios.length}.`);
     }
     const smoke = await runLiveSmoke(context, scenarios);
-    const failures = smoke.results.filter(result => result.status !== "pass").map(result => result.name);
+    const failures = smoke.results.flatMap(result => [
+        ...(result.status === "pass" ? [] : [result.name]),
+        ...(result.cleanup?.ok === true ? [] : [`${result.name}:cleanup`])
+    ]);
     return {
         ok: failures.length === 0,
         profilePaths,

package/dist/src/types.d.ts

@@ -1,3 +1,5 @@
+import type { OperationControlReceiptV1, OperationHandleV1 } from "./operations/types.js";
+import type { BackendCompatibilityReport } from "./backend/protocol.js";
 export type CommandStatus = "ok" | "partial" | "timeout" | "blocked" | "needs_confirmation" | "not_found" | "unsupported" | "error";
 export type SubmissionState = "not_submitted" | "submitted" | "submitted_unconfirmed" | "submitted_generating";
 export type CompletionState = "complete" | "generating" | "stopped" | "partial" | "unknown";
@@ -663,6 +665,8 @@ export type WorkTaskRef = {
 };
 export type StartWorkArgs = {
     prompt: string;
+    /** Caller-owned durable identity. Supplying it opts Work start into operations.run. */
+    operationId?: string;
     /** Start from a blank Work task when possible. Defaults to true. */
     newTask?: boolean;
     files?: string[];
@@ -674,6 +678,17 @@ export type StartWorkArgs = {
 export type StartWorkData = {
     task: WorkTaskRef;
     submitted: SubmitData;
+    /** Requested runner output format for the transactional Work path. */
+    responseFormat?: Extract<ResponseFormat, "markdown" | "text">;
+    /** Effective durable operation identity when the transactional path was selected. */
+    operationId?: string;
+    /** Durable locator returned by the transactional Work path. */
+    handle?: OperationHandleV1;
+    requestDigest?: string;
+    pending?: boolean;
+    responseDigest?: string;
+    responseBytes?: number;
+    complete?: boolean;
     configuration?: ApplyConfigurationData;
     wait?: WaitData;
     response?: ReadLatestData;
@@ -691,11 +706,31 @@ export type WorkWaitArgs = WaitArgs;
 export type WorkWaitData = WaitData;
 export type SteerWorkArgs = {
     prompt: string;
+    /**
+     * Caller-owned parent operation identity. A transactional steer must also
+     * provide the exact parent handle, control action ID, and assistant turn;
+     * omitting all operation fields preserves the legacy primitive path.
+     */
+    operationId?: string;
+    handle?: OperationHandleV1;
+    /** Caller-owned immutable identity for this one steer action. */
+    controlActionId?: string;
+    expectedAssistantTurnId?: string;
     wait?: boolean | WaitArgs;
     read?: boolean | ReadLatestArgs;
     timeoutMs?: number;
 };
-export type SteerWorkData = AskReadData;
+export type SteerWorkData = Omit<AskReadData, "prompt"> & {
+    /** Legacy steering returns the prompt; transactional errors never echo it. */
+    prompt?: string;
+    operationId?: string;
+    controlActionId?: string;
+    requestDigest?: string;
+    /** Exact parent locator used for a transactional steer. */
+    handle?: OperationHandleV1;
+    parentHandle?: OperationHandleV1;
+    control?: OperationControlReceiptV1;
+};
 export type ReadWorkLatestArgs = ReadLatestArgs;
 export type ReadWorkLatestData = ReadLatestData;
 export type SelectToolArgs = {
@@ -854,6 +889,8 @@ export type RuntimeEnv = {
     clipboard?: ClipboardLike;
     now?: () => Date;
     expectedTabId?: string;
+    /** Optional transport-owned compatibility diagnostics for doctor. */
+    compatibility?: BackendCompatibilityReport;
 };
 export type ClipboardLike = {
     read: () => Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-chatgpt-control",
-  "version": "0.5.1-alpha.2",
+  "version": "0.5.1-alpha.4",
   "description": "Unofficial SDK for controlling visible ChatGPT Chat and Work sessions.",
   "type": "module",
   "license": "MIT",
@@ -44,7 +44,8 @@
     "smoke:search": "tsx src/scripts/smoke-search-open-read.ts",
     "smoke:attach": "tsx src/scripts/smoke-attach-file.ts",
     "smoke:live": "tsx src/scripts/live-smoke.ts",
-    "smoke:release:build": "npm run bundle:release-canary"
+    "smoke:release:build": "npm run bundle:release-canary",
+    "bundle:journal": "esbuild src/scripts/journal-server.ts --bundle --platform=node --format=esm --outfile=dist/codex-chatgpt-control-journal.mjs"
   },
   "exports": {
     ".": {
@@ -59,13 +60,17 @@
   },
   "types": "./dist/src/index.d.ts",
   "bin": {
-    "codex-chatgpt-control-backend": "dist/src/scripts/backend-server.js"
+    "codex-chatgpt-control-backend": "dist/src/scripts/backend-server.js",
+    "codex-chatgpt-control-journal": "dist/src/scripts/journal-server.js"
   },
   "files": [
     "dist/src/**/*.js",
     "dist/src/**/*.d.ts",
     "dist/codex-chatgpt-control.bundle.mjs",
     "dist/codex-chatgpt-control-backend.mjs",
+    "dist/codex-chatgpt-control-journal.mjs",
+    "dist/codex-chatgpt-control-live-smoke.bundle.mjs",
+    "dist/codex-chatgpt-control-release-canary.bundle.mjs",
     "contracts/v1/**/*.json",
     "contracts/v1/**/*.ndjson",
     "references/**/*.md",