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

package/dist/src/operations/recovery.d.ts

@@ -0,0 +1,80 @@
+import type { OperationActionRecordV1, OperationReceiptV1, OperationStateV1 } from "./types.js";
+import { OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, OPERATION_RECOVERY_OBSERVATION_SCHEMA_VERSION } from "./types.js";
+export type OperationTargetObservation = {
+    status: "matches";
+} | {
+    status: "mismatch";
+    evidenceDigest?: string;
+} | {
+    status: "unavailable";
+    evidenceDigest?: string;
+};
+export type OperationTurnObservation = {
+    status: "not_observed";
+} | {
+    status: "owned_user_turn";
+    userTurnId: string;
+    evidenceDigest: string;
+} | {
+    status: "owned_assistant_generating";
+    userTurnId: string;
+    assistantTurnId: string;
+    evidenceDigest: string;
+} | {
+    status: "owned_assistant_terminal";
+    userTurnId: string;
+    assistantTurnId: string;
+    evidenceDigest: string;
+} | {
+    status: "ambiguous";
+    evidenceDigest?: string;
+};
+export type OperationRecoveryObservationV1 = {
+    schemaVersion: typeof OPERATION_RECOVERY_OBSERVATION_SCHEMA_VERSION;
+    target: OperationTargetObservation;
+    turn: OperationTurnObservation;
+};
+export type OperationRecoveryDecisionV1 = {
+    kind: "return_completed_receipt";
+    schemaVersion: typeof OPERATION_RECOVERY_DECISION_SCHEMA_VERSION;
+    receipt: OperationReceiptV1;
+} | {
+    kind: "continue_preparation";
+    schemaVersion: typeof OPERATION_RECOVERY_DECISION_SCHEMA_VERSION;
+    phase: "prepared" | "ready";
+    nonRepeatableActionMayStart: true;
+} | {
+    kind: "observe_action_postcondition";
+    schemaVersion: typeof OPERATION_RECOVERY_DECISION_SCHEMA_VERSION;
+    actionId: string;
+    actionKind: OperationActionRecordV1["kind"];
+    mayRepeatAction: false;
+} | {
+    kind: "continue_owned_turn_observation";
+    schemaVersion: typeof OPERATION_RECOVERY_DECISION_SCHEMA_VERSION;
+    phase: "submitted" | "generating";
+    userTurnId?: string;
+    assistantTurnId?: string;
+    evidenceDigest?: string;
+} | {
+    kind: "capture_owned_turn";
+    schemaVersion: typeof OPERATION_RECOVERY_DECISION_SCHEMA_VERSION;
+    assistantTurnId: string;
+    evidenceDigest: string;
+} | {
+    kind: "enter_uncertain";
+    schemaVersion: typeof OPERATION_RECOVERY_DECISION_SCHEMA_VERSION;
+    code: "target_evidence_unavailable" | "turn_ownership_ambiguous" | "capture_ownership_lost";
+    mayRepeatAction: false;
+} | {
+    kind: "block";
+    schemaVersion: typeof OPERATION_RECOVERY_DECISION_SCHEMA_VERSION;
+    code: "target_binding_mismatch" | "target_evidence_unavailable" | "operation_state_inconsistent";
+    mayRepeatAction: false;
+};
+/**
+ * Decide what a restarted caller may do from durable state and a fresh,
+ * operation-bound observation. This function never authorizes replay of an
+ * action whose intent is already durable.
+ */
+export declare function decideOperationRecovery(state: OperationStateV1, observation: OperationRecoveryObservationV1): OperationRecoveryDecisionV1;

package/dist/src/operations/recovery.js

@@ -0,0 +1,174 @@
+import { OPERATION_RECOVERY_DECISION_SCHEMA_VERSION } from "./types.js";
+/**
+ * Decide what a restarted caller may do from durable state and a fresh,
+ * operation-bound observation. This function never authorizes replay of an
+ * action whose intent is already durable.
+ */
+export function decideOperationRecovery(state, observation) {
+    if (state.phase === "completed") {
+        if (state.receipt === undefined) {
+            return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "block", code: "operation_state_inconsistent", mayRepeatAction: false };
+        }
+        return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "return_completed_receipt", receipt: state.receipt };
+    }
+    if (observation.target.status === "mismatch") {
+        return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "block", code: "target_binding_mismatch", mayRepeatAction: false };
+    }
+    if (observation.target.status === "unavailable") {
+        if (state.mutationBoundary === "none") {
+            return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "block", code: "target_evidence_unavailable", mayRepeatAction: false };
+        }
+        return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "enter_uncertain", code: "target_evidence_unavailable", mayRepeatAction: false };
+    }
+    // The process can stop after fsyncing an intent (or its receipt) but before
+    // appending the corresponding phase event. Phase alone therefore never
+    // authorizes a second non-repeatable browser action.
+    const pendingIntent = pendingNonRepeatableAction(state);
+    if (pendingIntent !== undefined) {
+        return decisionForPendingAction(state, pendingIntent, observation.turn);
+    }
+    if (state.phase === "prepared" || state.phase === "ready") {
+        return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "continue_preparation", phase: state.phase, nonRepeatableActionMayStart: true };
+    }
+    if (state.phase === "handoff_pending" || state.phase === "send_pending") {
+        const expectedKind = state.phase === "handoff_pending" ? "file_handoff" : "send";
+        const action = latestAction(state, candidate => candidate.kind === expectedKind);
+        if (action === undefined) {
+            return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "block", code: "operation_state_inconsistent", mayRepeatAction: false };
+        }
+        return {
+            schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION,
+            kind: "observe_action_postcondition",
+            actionId: action.actionId,
+            actionKind: action.kind,
+            mayRepeatAction: false
+        };
+    }
+    if (state.phase === "capturing") {
+        if (observation.turn.status === "owned_assistant_terminal") {
+            return {
+                schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION,
+                kind: "capture_owned_turn",
+                assistantTurnId: observation.turn.assistantTurnId,
+                evidenceDigest: observation.turn.evidenceDigest
+            };
+        }
+        return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "enter_uncertain", code: "capture_ownership_lost", mayRepeatAction: false };
+    }
+    if (state.phase === "submitted" || state.phase === "generating") {
+        return ownedTurnDecision(state.phase, observation.turn);
+    }
+    // An uncertain operation can only observe the most advanced durable
+    // boundary. It cannot return to a mutation path merely because the page
+    // looks plausible.
+    if (state.phase === "uncertain") {
+        if (state.mutationBoundary === "handoff_may_have_occurred") {
+            const action = latestAction(state, candidate => candidate.kind === "file_handoff");
+            if (action === undefined) {
+                return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "block", code: "operation_state_inconsistent", mayRepeatAction: false };
+            }
+            return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "observe_action_postcondition", actionId: action.actionId, actionKind: action.kind, mayRepeatAction: false };
+        }
+        if (state.mutationBoundary === "send_may_have_occurred" || state.mutationBoundary === "control_may_have_occurred") {
+            if (observation.turn.status === "not_observed") {
+                const action = latestAction(state, candidate => candidate.kind === "send" || candidate.kind === "work_steer" || candidate.kind === "stop");
+                if (action !== undefined) {
+                    return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "observe_action_postcondition", actionId: action.actionId, actionKind: action.kind, mayRepeatAction: false };
+                }
+            }
+            const turnDecision = ownedTurnDecision("generating", observation.turn);
+            if (turnDecision.kind === "enter_uncertain") {
+                const action = latestAction(state, candidate => candidate.kind === "send" || candidate.kind === "work_steer" || candidate.kind === "stop");
+                if (action !== undefined) {
+                    return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "observe_action_postcondition", actionId: action.actionId, actionKind: action.kind, mayRepeatAction: false };
+                }
+            }
+            return turnDecision;
+        }
+        return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "block", code: "operation_state_inconsistent", mayRepeatAction: false };
+    }
+    return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "block", code: "operation_state_inconsistent", mayRepeatAction: false };
+}
+function decisionForPendingAction(state, action, turn) {
+    // Attachment ownership is established by the exact manifest
+    // postcondition, not by turn state.  A durable handoff intent therefore
+    // always remains observation-only until that postcondition is reconciled.
+    if (action.kind === "file_handoff")
+        return observeAction(action);
+    // Send/steer/stop can be reconciled directly when an operation-owned turn
+    // is already proven.  This matters for the crash gap after the browser
+    // acted but before the action receipt or phase event was appended.  Merely
+    // having a durable intent still never authorizes a second mutation.
+    if (turn.status === "not_observed")
+        return observeAction(action);
+    if (turn.status === "ambiguous") {
+        return {
+            schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION,
+            kind: "enter_uncertain",
+            code: "turn_ownership_ambiguous",
+            mayRepeatAction: false
+        };
+    }
+    const phase = action.kind === "stop"
+        ? "generating"
+        : state.phase === "generating"
+            ? "generating"
+            : "submitted";
+    return ownedTurnDecision(phase, turn);
+}
+function observeAction(action) {
+    return {
+        schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION,
+        kind: "observe_action_postcondition",
+        actionId: action.actionId,
+        actionKind: action.kind,
+        mayRepeatAction: false
+    };
+}
+function ownedTurnDecision(phase, turn) {
+    if (turn.status === "ambiguous") {
+        return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "enter_uncertain", code: "turn_ownership_ambiguous", mayRepeatAction: false };
+    }
+    if (turn.status === "owned_assistant_terminal") {
+        return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "capture_owned_turn", assistantTurnId: turn.assistantTurnId, evidenceDigest: turn.evidenceDigest };
+    }
+    if (turn.status === "owned_assistant_generating") {
+        return {
+            schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION,
+            kind: "continue_owned_turn_observation",
+            phase: "generating",
+            userTurnId: turn.userTurnId,
+            assistantTurnId: turn.assistantTurnId,
+            evidenceDigest: turn.evidenceDigest
+        };
+    }
+    if (turn.status === "owned_user_turn") {
+        return {
+            schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION,
+            kind: "continue_owned_turn_observation",
+            phase,
+            userTurnId: turn.userTurnId,
+            evidenceDigest: turn.evidenceDigest
+        };
+    }
+    return { schemaVersion: OPERATION_RECOVERY_DECISION_SCHEMA_VERSION, kind: "continue_owned_turn_observation", phase };
+}
+function latestAction(state, predicate) {
+    return Object.values(state.actions)
+        .filter(predicate)
+        .sort((left, right) => right.intentRevision - left.intentRevision)[0];
+}
+function pendingNonRepeatableAction(state) {
+    return latestAction(state, action => {
+        if (action.kind === "file_handoff") {
+            return state.phase === "prepared" || state.phase === "handoff_pending" || state.phase === "uncertain";
+        }
+        if (action.kind === "send") {
+            return state.phase === "ready" || state.phase === "send_pending" || state.phase === "uncertain";
+        }
+        if (action.kind === "work_steer" || action.kind === "stop") {
+            return state.phase === "generating" || state.phase === "uncertain";
+        }
+        return false;
+    });
+}

package/dist/src/operations/runtime-adapter.d.ts

@@ -0,0 +1,118 @@
+import type { PageLike } from "../types.js";
+import type { CoordinatorOwner, ProcessTabCoordinator } from "../runtime/tab-coordinator.js";
+import { OperationRuntimeContext, type OperationRuntimeCapabilities } from "../runtime/operation-context.js";
+import { type ComposedOperationBrowserAdapter, type OperationBrowserAdapterOptions, type OperationBrowserCollectorPrimitive, type OperationBrowserControlPrimitive, type OperationBrowserArtifactPrimitive, type OperationBrowserCurrentTargetResult, type OperationBrowserStagingPrimitive, type OperationBrowserSubmissionPrimitive, type OperationBrowserTargetProbe, type OperationBrowserTargetProbeRequest } from "./browser-adapter.js";
+import type { BrowserTargetClaim, BrowserTargetEvidenceDigest } from "./browser-target.js";
+import type { OwnershipTargetEvidence } from "./turn-ownership.js";
+import type { OperationFileIdentity } from "./file-identity.js";
+import type { OperationSurface, OperationTargetBindingV1, OperationTargetRequestV1 } from "./types.js";
+/**
+ * Browser primitives that are safe to pass into an operation adapter.
+ *
+ * The callbacks receive the captured page explicitly.  They must perform one
+ * bounded DOM transaction and return an already-redacted observation.  In
+ * particular, a callback must not poll for generation, wait for attachment
+ * processing, read a mutable RuntimeEnv, or retry a non-repeatable browser
+ * action.  Those waits belong to the operation collector and are deliberately
+ * outside the tab actor.
+ */
+export type OperationRuntimeBrowserPrimitives = Readonly<{
+    submission?: OperationBrowserSubmissionPrimitive;
+    staging?: OperationBrowserStagingPrimitive;
+    collector?: OperationBrowserCollectorPrimitive;
+    control?: OperationBrowserControlPrimitive;
+    artifacts?: OperationBrowserArtifactPrimitive;
+}>;
+/**
+ * One request-scoped capture.  The capture factory is invoked lazily from
+ * `resolveTarget`, after OperationService has created the durable operation
+ * record.  It is the only place that may attach/claim/create a browser page.
+ *
+ * `targetEvidence` is required when no resolver is supplied.  A resolver is
+ * useful for an explicit target policy (for example a selected tab versus a
+ * caller-provided tab id), but it must remain read-only and return the same
+ * captured page object.
+ */
+export type OperationRuntimeBrowserCapture = Readonly<{
+    page: Readonly<PageLike>;
+    /** Optional immutable context captured by the provider bridge. */
+    runtimeContext?: OperationRuntimeContext<PageLike>;
+    targetEvidence?: OwnershipTargetEvidence;
+    authoritativeClaim?: BrowserTargetClaim;
+    capabilities?: Partial<OperationRuntimeCapabilities>;
+    /** Provider-proofed anchor evidence for a target whose ID is allocated by Send. */
+    newTargetAnchorDigest?: string;
+    blankTaskEvidenceDigest?: string;
+    resolveTargetEvidence?: (request: OperationBrowserTargetProbeRequest) => Promise<OperationBrowserTargetProbe> | OperationBrowserTargetProbe;
+    observeCurrentTarget?: (request: Parameters<NonNullable<OperationBrowserAdapterOptions["observeCurrentTarget"]>>[0]) => Promise<OperationBrowserCurrentTargetResult> | OperationBrowserCurrentTargetResult;
+    /** Request-local output destination; intentionally absent on recovery. */
+    outputDirectory?: string;
+    primitives?: OperationRuntimeBrowserPrimitives;
+}>;
+export type OperationRuntimeBrowserCaptureRequest = Readonly<{
+    operationId: string;
+    requestDigest: string;
+    surface: OperationSurface;
+    target: OperationTargetRequestV1;
+    signal: AbortSignal;
+}>;
+/**
+ * Frozen locator and complete durable target supplied by an authenticated
+ * post-restart handle factory.  `targetRequest` is explicit because a durable
+ * binding must never be reconstructed by guessing a selected/replacement tab.
+ */
+export type OperationRuntimeBrowserRecoveryContext = Readonly<{
+    operationId: string;
+    requestDigest: string;
+    surface: OperationSurface;
+    target: OperationTargetBindingV1;
+    targetRequest: OperationTargetRequestV1;
+}>;
+export type OperationRuntimeAdapterOptions = Readonly<{
+    /** Backend process owner used by the process/tab coordinator. */
+    owner: CoordinatorOwner;
+    /** Journal-keyed evidence digest. It must never be a bare public hash. */
+    evidenceDigest: BrowserTargetEvidenceDigest;
+    /** Lazy, request-scoped page/context capture. */
+    capture: (request: OperationRuntimeBrowserCaptureRequest) => Promise<OperationRuntimeBrowserCapture> | OperationRuntimeBrowserCapture;
+    /** Static operation closures may safely retain request-local private input. */
+    primitives?: OperationRuntimeBrowserPrimitives;
+    /** Set when the lazy capture will return the corresponding optional port.
+     * Leaving this false keeps OperationService on its read-only submission
+     * precondition path; exposing an absent staging port would otherwise turn a
+     * safe pre-populated composer into an artificial mutation blocker. */
+    exposeStaging?: boolean;
+    /** Set when callers want structured unavailable control results. */
+    exposeControl?: boolean;
+    /** Set only for a request-local submit capture with an absolute destination. */
+    exposeArtifacts?: boolean;
+    coordinator?: ProcessTabCoordinator;
+    transactionTimeoutMs?: number;
+    files?: readonly OperationFileIdentity[];
+    fileManifestDigest?: OperationBrowserAdapterOptions["fileManifestDigest"];
+    /** Explicit lazy recovery path; submit adapters do not use this option. */
+    recovery?: OperationRuntimeBrowserRecoveryContext;
+}>;
+export type OperationRuntimeAdapterErrorCode = "adapter_incomplete" | "capture_failed" | "capture_incomplete" | "target_evidence_unavailable" | "target_binding_mismatch" | "page_affinity_mismatch" | "unsupported_browser_primitive" | "not_initialized" | "backend_unavailable" | "browser_bridge_unavailable" | "login_required" | "captcha" | "rate_limited" | "permission_required" | "needs_confirmation" | "runtime_incompatible";
+/** Stable, redacted error boundary for a request-scoped runtime adapter. */
+export declare class OperationRuntimeAdapterError extends Error {
+    readonly code: OperationRuntimeAdapterErrorCode;
+    constructor(code: OperationRuntimeAdapterErrorCode);
+}
+/**
+ * This is the generic adapter's injection inventory, retained for compatibility
+ * with integrations that assemble their own provider runtime. It does not
+ * describe the default ChatGPT composite: `chatgpt-runtime.ts` injects the
+ * proven production modules for these seams. The generic adapter itself never
+ * guesses selectors or routes legacy polling helpers through a tab actor.
+ */
+export declare const UNWIRED_OPERATION_RUNTIME_PRIMITIVES: readonly ["new_thread_creation", "configuration_set", "tool_selection", "composer_population", "file_chooser_handoff", "send_activation", "stop_activation", "work_steer_activation"];
+/**
+ * Compose one lazy runtime capture over the existing operation browser
+ * adapter.  The returned object is intentionally request-scoped: a caller
+ * should construct it in `OperationClient.adapterFactory` and retain it only
+ * for the resulting operation handle.
+ */
+export declare function createRuntimeOperationBrowserAdapter(options: OperationRuntimeAdapterOptions): ComposedOperationBrowserAdapter;
+/** Alias for callers that put the runtime qualifier first. */
+export declare const createOperationRuntimeAdapter: typeof createRuntimeOperationBrowserAdapter;