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

package/dist/src/operations/wire-requests.js

@@ -0,0 +1,396 @@
+import { OPERATION_COLLECT_REQUEST_SCHEMA_VERSION, OPERATION_CONTROL_REQUEST_SCHEMA_VERSION, OPERATION_HANDLE_SCHEMA_VERSION, OPERATION_INSPECT_REQUEST_SCHEMA_VERSION, OPERATION_REQUEST_SCHEMA_VERSION } from "./types.js";
+/**
+ * Raised by the closed runtime validators in this module.
+ *
+ * The message intentionally contains no field name or value. Operation
+ * requests can contain prompts and local paths, and validation failures must
+ * be safe to send across a backend boundary.
+ */
+export class OperationWireRequestError extends Error {
+    code = "invalid_operation_request";
+    recoverable = false;
+    constructor() {
+        super("Transactional operation request is invalid.");
+        this.name = "OperationWireRequestError";
+    }
+}
+/** Validate the canonical direct v1 submit payload. */
+export function validateOperationSubmitRequest(value) {
+    const request = operationRecord(value);
+    operationExactKeys(request, [
+        "schemaVersion", "operationId", "surface", "prompt", "target", "configuration", "files", "capture", "timeoutMs"
+    ]);
+    operationConst(propertyValue(request, "schemaVersion"), OPERATION_REQUEST_SCHEMA_VERSION);
+    operationId(propertyValue(request, "operationId"));
+    operationSurface(propertyValue(request, "surface"));
+    operationText(propertyValue(request, "prompt"), 8 * 1024 * 1024, false);
+    validateOperationTarget(propertyValue(request, "target"));
+    const configuration = propertyValue(request, "configuration");
+    if (configuration !== undefined)
+        validateOperationConfiguration(configuration);
+    const files = propertyValue(request, "files");
+    if (files !== undefined) {
+        const entries = arrayValues(files, 256);
+        for (const file of entries) {
+            const entry = operationRecord(file);
+            operationExactKeys(entry, ["path", "displayName"]);
+            operationText(propertyValue(entry, "path"), 4096, true);
+            const displayName = propertyValue(entry, "displayName");
+            if (displayName !== undefined)
+                operationText(displayName, 512, true);
+        }
+    }
+    const capture = propertyValue(request, "capture");
+    if (capture !== undefined)
+        validateOperationCapture(capture);
+    validateOperationTimeout(propertyValue(request, "timeoutMs"));
+}
+/** Validate the canonical direct v1 collect payload. */
+export function validateOperationCollectRequest(value) {
+    const request = operationRecord(value);
+    operationExactKeys(request, ["schemaVersion", "handle", "wait", "timeoutMs", "pollIntervalMs", "responseContent"]);
+    operationConst(propertyValue(request, "schemaVersion"), OPERATION_COLLECT_REQUEST_SCHEMA_VERSION);
+    validateOperationHandlePayload(propertyValue(request, "handle"));
+    const wait = propertyValue(request, "wait");
+    if (wait !== undefined && typeof wait !== "boolean")
+        throw invalidOperationRequest();
+    validateOperationTimeout(propertyValue(request, "timeoutMs"));
+    const pollIntervalMs = propertyValue(request, "pollIntervalMs");
+    if (pollIntervalMs !== undefined
+        && (typeof pollIntervalMs !== "number" || !Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 0 || pollIntervalMs > 60_000)) {
+        throw invalidOperationRequest();
+    }
+    const responseContent = propertyValue(request, "responseContent");
+    if (responseContent !== undefined && responseContent !== "include" && responseContent !== "metadata") {
+        throw invalidOperationRequest();
+    }
+}
+/** Validate the canonical direct v1 inspect payload. */
+export function validateOperationInspectRequest(value) {
+    const request = operationRecord(value);
+    operationExactKeys(request, ["schemaVersion", "handle"]);
+    operationConst(propertyValue(request, "schemaVersion"), OPERATION_INSPECT_REQUEST_SCHEMA_VERSION);
+    validateOperationHandlePayload(propertyValue(request, "handle"));
+}
+/** Validate the canonical direct v1 control payload. */
+export function validateOperationControlRequest(value) {
+    const request = operationRecord(value);
+    operationExactKeys(request, [
+        "schemaVersion", "controlActionId", "parent", "action", "expectedAssistantTurnId", "steerPrompt", "timeoutMs"
+    ]);
+    operationConst(propertyValue(request, "schemaVersion"), OPERATION_CONTROL_REQUEST_SCHEMA_VERSION);
+    operationId(propertyValue(request, "controlActionId"));
+    const parent = validateOperationHandlePayload(propertyValue(request, "parent"));
+    if (propertyValue(parent, "phase") !== "generating" || propertyValue(parent, "targetBindingDigest") === undefined) {
+        throw invalidOperationRequest();
+    }
+    const action = propertyValue(request, "action");
+    if (action !== "stop" && action !== "steer")
+        throw invalidOperationRequest();
+    operationOpaqueId(propertyValue(request, "expectedAssistantTurnId"), 512);
+    const steerPrompt = propertyValue(request, "steerPrompt");
+    if (action === "steer") {
+        if (steerPrompt === undefined)
+            throw invalidOperationRequest();
+        operationText(steerPrompt, 8 * 1024 * 1024, true);
+    }
+    else if (steerPrompt !== undefined) {
+        throw invalidOperationRequest();
+    }
+    validateOperationTimeout(propertyValue(request, "timeoutMs"));
+}
+function validateOperationTarget(value) {
+    const target = operationRecord(value);
+    const type = propertyValue(target, "type");
+    if (typeof type !== "string")
+        throw invalidOperationRequest();
+    switch (type) {
+        case "new":
+        case "selected_tab":
+            operationExactKeys(target, ["type"]);
+            return;
+        case "tab_id":
+            operationExactKeys(target, ["type", "tabId"]);
+            operationOpaqueId(propertyValue(target, "tabId"), 512);
+            return;
+        case "conversation_id":
+            operationExactKeys(target, ["type", "conversationId"]);
+            operationOpaqueId(propertyValue(target, "conversationId"), 512);
+            return;
+        case "url": {
+            operationExactKeys(target, ["type", "url"]);
+            const url = propertyValue(target, "url");
+            operationText(url, 4096, true);
+            if (typeof url !== "string" || /[\u0000-\u001f\u007f]/u.test(url)) {
+                throw invalidOperationRequest();
+            }
+            try {
+                const parsed = new URL(url);
+                if ((parsed.protocol !== "https:" && parsed.protocol !== "http:") || parsed.username || parsed.password) {
+                    throw new Error("invalid");
+                }
+            }
+            catch {
+                throw invalidOperationRequest();
+            }
+            return;
+        }
+        default:
+            throw invalidOperationRequest();
+    }
+}
+function validateOperationConfiguration(value) {
+    const configuration = operationRecord(value);
+    operationExactKeys(configuration, ["experience", "model", "modelVersion", "reasoning", "mode", "tools", "additional"]);
+    const experience = propertyValue(configuration, "experience");
+    if (experience !== undefined && experience !== "chat" && experience !== "work")
+        throw invalidOperationRequest();
+    for (const field of ["model", "modelVersion", "reasoning", "mode"]) {
+        const requested = propertyValue(configuration, field);
+        if (requested !== undefined)
+            operationText(requested, 256, true);
+    }
+    const tools = propertyValue(configuration, "tools");
+    if (tools !== undefined) {
+        for (const tool of arrayValues(tools, 256))
+            operationText(tool, 256, true);
+    }
+    const additional = propertyValue(configuration, "additional");
+    if (additional !== undefined) {
+        if (!isPlainRecord(additional))
+            throw invalidOperationRequest();
+        validateOperationJson(additional);
+    }
+}
+function validateOperationCapture(value) {
+    const capture = operationRecord(value);
+    operationExactKeys(capture, ["responseContent", "responseFormat", "artifacts", "outputDirectory"]);
+    const responseContent = propertyValue(capture, "responseContent");
+    const responseFormat = propertyValue(capture, "responseFormat");
+    const artifacts = propertyValue(capture, "artifacts");
+    const outputDirectory = propertyValue(capture, "outputDirectory");
+    if (responseContent !== "include" && responseContent !== "metadata")
+        throw invalidOperationRequest();
+    if (responseFormat !== undefined && responseFormat !== "markdown" && responseFormat !== "text")
+        throw invalidOperationRequest();
+    if (artifacts !== "receipt_only" && artifacts !== "transfer")
+        throw invalidOperationRequest();
+    if (outputDirectory !== undefined)
+        operationText(outputDirectory, 4096, true);
+    if (artifacts === "transfer" && outputDirectory === undefined)
+        throw invalidOperationRequest();
+    if (artifacts === "receipt_only" && outputDirectory !== undefined)
+        throw invalidOperationRequest();
+}
+function validateOperationHandlePayload(value) {
+    const handle = operationRecord(value);
+    operationExactKeys(handle, [
+        "schemaVersion", "operationId", "requestDigest", "surface", "revision", "phase", "mutationBoundary", "targetBindingDigest"
+    ]);
+    operationConst(propertyValue(handle, "schemaVersion"), OPERATION_HANDLE_SCHEMA_VERSION);
+    operationId(propertyValue(handle, "operationId"));
+    operationDigest(propertyValue(handle, "requestDigest"));
+    operationSurface(propertyValue(handle, "surface"));
+    const revision = propertyValue(handle, "revision");
+    if (!Number.isSafeInteger(revision) || revision < 1)
+        throw invalidOperationRequest();
+    if (!OPERATION_PHASES.has(propertyValue(handle, "phase"))
+        || !OPERATION_BOUNDARIES.has(propertyValue(handle, "mutationBoundary"))) {
+        throw invalidOperationRequest();
+    }
+    const targetBindingDigest = propertyValue(handle, "targetBindingDigest");
+    if (targetBindingDigest !== undefined)
+        operationDigest(targetBindingDigest);
+    return handle;
+}
+function validateOperationTimeout(value) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+        throw invalidOperationRequest();
+}
+function validateOperationJson(value, depth = 0, budget = { nodes: 0, utf8Bytes: 0 }) {
+    budget.nodes += 1;
+    if (budget.nodes > MAX_OPERATION_JSON_NODES || depth > MAX_OPERATION_JSON_DEPTH)
+        throw invalidOperationRequest();
+    if (value === null || typeof value === "boolean")
+        return;
+    if (typeof value === "string") {
+        addOperationJsonBytes(budget, value);
+        return;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw invalidOperationRequest();
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of arrayValues(value, MAX_OPERATION_JSON_NODES))
+            validateOperationJson(entry, depth + 1, budget);
+        return;
+    }
+    if (!isPlainRecord(value))
+        throw invalidOperationRequest();
+    const record = operationRecord(value);
+    for (const key of ownStringKeys(record)) {
+        operationText(key, 256, false);
+        if (/[\u0000-\u001f\u007f]/u.test(key))
+            throw invalidOperationRequest();
+        addOperationJsonBytes(budget, key);
+        validateOperationJson(propertyValue(record, key), depth + 1, budget);
+    }
+}
+function addOperationJsonBytes(budget, value) {
+    if (!isWellFormedUnicode(value))
+        throw invalidOperationRequest();
+    budget.utf8Bytes += Buffer.byteLength(value, "utf8");
+    if (!Number.isSafeInteger(budget.utf8Bytes) || budget.utf8Bytes > MAX_OPERATION_JSON_UTF8_BYTES) {
+        throw invalidOperationRequest();
+    }
+}
+function operationRecord(value) {
+    if (!isPlainRecord(value))
+        throw invalidOperationRequest();
+    try {
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== "string")
+                throw invalidOperationRequest();
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor === undefined || !("value" in descriptor) || descriptor.enumerable !== true) {
+                throw invalidOperationRequest();
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof OperationWireRequestError)
+            throw error;
+        throw invalidOperationRequest();
+    }
+    return value;
+}
+function operationExactKeys(value, allowed) {
+    const allowedSet = new Set(allowed);
+    if (ownStringKeys(value).some(key => !allowedSet.has(key)))
+        throw invalidOperationRequest();
+}
+function ownStringKeys(value) {
+    try {
+        const keys = Reflect.ownKeys(value);
+        if (keys.some(key => typeof key !== "string"))
+            throw invalidOperationRequest();
+        return keys;
+    }
+    catch (error) {
+        if (error instanceof OperationWireRequestError)
+            throw error;
+        throw invalidOperationRequest();
+    }
+}
+function propertyValue(value, key) {
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined)
+            return undefined;
+        if (!("value" in descriptor) || descriptor.enumerable !== true)
+            throw invalidOperationRequest();
+        return descriptor.value;
+    }
+    catch (error) {
+        if (error instanceof OperationWireRequestError)
+            throw error;
+        throw invalidOperationRequest();
+    }
+}
+function arrayValues(value, maxLength) {
+    if (!Array.isArray(value))
+        throw invalidOperationRequest();
+    try {
+        const length = value.length;
+        if (length > maxLength)
+            throw invalidOperationRequest();
+        const keys = Reflect.ownKeys(value);
+        const allowed = new Set(["length", ...Array.from({ length }, (_, index) => String(index))]);
+        if (keys.some(key => typeof key !== "string" || !allowed.has(key)))
+            throw invalidOperationRequest();
+        const values = [];
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (descriptor === undefined || !("value" in descriptor) || descriptor.enumerable !== true) {
+                throw invalidOperationRequest();
+            }
+            values.push(descriptor.value);
+        }
+        return values;
+    }
+    catch (error) {
+        if (error instanceof OperationWireRequestError)
+            throw error;
+        throw invalidOperationRequest();
+    }
+}
+function operationConst(value, expected) {
+    if (value !== expected)
+        throw invalidOperationRequest();
+}
+function operationSurface(value) {
+    if (value !== "chat" && value !== "work")
+        throw invalidOperationRequest();
+}
+function operationId(value) {
+    if (typeof value !== "string" || !OPERATION_UUID_PATTERN.test(value))
+        throw invalidOperationRequest();
+}
+function operationDigest(value) {
+    if (typeof value !== "string" || !OPERATION_DIGEST_PATTERN.test(value))
+        throw invalidOperationRequest();
+}
+function operationText(value, maxBytes, nonEmpty) {
+    if (typeof value !== "string"
+        || (nonEmpty && value.length === 0)
+        || !isWellFormedUnicode(value)
+        || Buffer.byteLength(value, "utf8") > maxBytes)
+        throw invalidOperationRequest();
+}
+function isWellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return false;
+        }
+    }
+    return true;
+}
+function operationOpaqueId(value, maxBytes) {
+    operationText(value, maxBytes, true);
+    if (typeof value !== "string"
+        || value.trim().length === 0
+        || /[\u0000-\u001f\u007f]/u.test(value))
+        throw invalidOperationRequest();
+}
+function invalidOperationRequest() {
+    return new OperationWireRequestError();
+}
+function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        return prototype === Object.prototype || prototype === null;
+    }
+    catch {
+        return false;
+    }
+}
+const OPERATION_UUID_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;
+const OPERATION_DIGEST_PATTERN = /^hmac-sha256:[0-9a-f]{64}$/u;
+const OPERATION_PHASES = new Set([
+    "prepared", "handoff_pending", "ready", "send_pending", "submitted", "generating", "capturing", "completed", "uncertain"
+]);
+const OPERATION_BOUNDARIES = new Set(["none", "handoff_may_have_occurred", "send_may_have_occurred", "control_may_have_occurred"]);
+const MAX_OPERATION_JSON_DEPTH = 16;
+const MAX_OPERATION_JSON_NODES = 10_000;
+const MAX_OPERATION_JSON_UTF8_BYTES = 1024 * 1024;

package/dist/src/operations/wire-results.d.ts

@@ -0,0 +1,97 @@
+import type { CollectorResult } from "./collector.js";
+import type { ControlResult } from "./control.js";
+import type { OperationBlockerV1, OperationControlReceiptV1, OperationHandleV1, OperationResponseFormatV1, OperationReceiptV1, OperationStateV1 } from "./types.js";
+import type { OperationInspectResult, OperationSubmitResult } from "./service.js";
+import type { BackendCompatibilityReport } from "../backend/protocol.js";
+/** Versioned result envelopes used at backend/SDK boundaries. */
+export declare const OPERATION_SUBMIT_RESULT_SCHEMA_VERSION: "chatgpt.browser_control.operation_submit_result.v1";
+export declare const OPERATION_COLLECT_RESULT_SCHEMA_VERSION: "chatgpt.browser_control.operation_collect_result.v1";
+export declare const OPERATION_INSPECT_RESULT_SCHEMA_VERSION: "chatgpt.browser_control.operation_inspect_result.v1";
+export declare const OPERATION_CONTROL_RESULT_SCHEMA_VERSION: "chatgpt.browser_control.operation_control_result.v1";
+export declare const OPERATION_LIVE_RESPONSE_SCHEMA_VERSION: "chatgpt.browser_control.operation_live_response.v1";
+export declare const MAX_WIRE_RESPONSE_BYTES: number;
+export declare const MAX_WIRE_RESPONSE_CHARS: number;
+export declare const MAX_WIRE_BLOCKER_MESSAGE_LENGTH = 512;
+export declare const MAX_WIRE_ARTIFACTS = 32;
+export type OperationWireStatus = "accepted" | "completed" | "pending" | "blocked" | "uncertain";
+/**
+ * Raw response content is deliberately a separate, explicitly ephemeral
+ * value. It is never accepted by a receipt or durable state validator.
+ */
+export type OperationLiveResponseV1 = Readonly<{
+    schemaVersion: typeof OPERATION_LIVE_RESPONSE_SCHEMA_VERSION;
+    durability: "ephemeral";
+    durable: false;
+    content: string;
+    responseFormat?: OperationResponseFormatV1;
+    bytes: number;
+    chars: number;
+}>;
+type OperationWireBase = Readonly<{
+    operationId: string;
+    requestDigest: string;
+    handle: OperationHandleV1;
+}>;
+export type OperationSubmitWireResult = (OperationWireBase & Readonly<{
+    schemaVersion: typeof OPERATION_SUBMIT_RESULT_SCHEMA_VERSION;
+    status: "accepted";
+}>) | (OperationWireBase & Readonly<{
+    schemaVersion: typeof OPERATION_SUBMIT_RESULT_SCHEMA_VERSION;
+    status: "completed";
+    receipt: OperationReceiptV1;
+}>) | (OperationWireBase & Readonly<{
+    schemaVersion: typeof OPERATION_SUBMIT_RESULT_SCHEMA_VERSION;
+    status: "blocked" | "uncertain";
+    blocker: OperationBlockerV1;
+}>);
+export type OperationCollectWireResult = (OperationWireBase & Readonly<{
+    schemaVersion: typeof OPERATION_COLLECT_RESULT_SCHEMA_VERSION;
+    status: "completed";
+    receipt: OperationReceiptV1;
+    liveResponse?: OperationLiveResponseV1;
+}>) | (OperationWireBase & Readonly<{
+    schemaVersion: typeof OPERATION_COLLECT_RESULT_SCHEMA_VERSION;
+    status: "pending";
+}>) | (OperationWireBase & Readonly<{
+    schemaVersion: typeof OPERATION_COLLECT_RESULT_SCHEMA_VERSION;
+    status: "blocked" | "uncertain";
+    blocker: OperationBlockerV1;
+}>);
+export type OperationInspectWireResult = OperationWireBase & Readonly<{
+    schemaVersion: typeof OPERATION_INSPECT_RESULT_SCHEMA_VERSION;
+    status: "completed" | "pending" | "uncertain";
+    state: OperationStateV1;
+    /** Additive transport provenance; absent for direct in-process backends. */
+    compatibility?: BackendCompatibilityReport;
+}>;
+export type OperationControlWireResult = OperationWireBase & Readonly<{
+    schemaVersion: typeof OPERATION_CONTROL_RESULT_SCHEMA_VERSION;
+    status: "completed" | "blocked" | "uncertain";
+    parentRequestDigest: string;
+    parentTargetBindingDigest: string;
+    controlActionId: string;
+    action: "stop" | "steer";
+    expectedAssistantTurnId: string;
+    receipt?: OperationControlReceiptV1;
+    blocker?: OperationBlockerV1;
+}>;
+export declare class OperationWireResultError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Convert the internal submission result into a strict, versioned envelope. */
+export declare function toOperationSubmitWireResult(result: OperationSubmitResult, receipt?: OperationReceiptV1): OperationSubmitWireResult;
+/** Convert the collector result using the freshly reloaded handle and receipt. */
+export declare function toOperationCollectWireResult(
+/** The handle freshly reloaded after the collector attempt (including pending). */
+handle: OperationHandleV1, result: CollectorResult, receipt?: OperationReceiptV1): OperationCollectWireResult;
+/** Inspect is a durable read, so its status is derived from the fresh state. */
+export declare function toOperationInspectWireResult(result: OperationInspectResult): OperationInspectWireResult;
+/** Convert a control result with the current parent handle reloaded by the service. */
+export declare function toOperationControlWireResult(result: ControlResult, handle: OperationHandleV1): OperationControlWireResult;
+export declare function liveResponseFromText(content: string, responseFormat?: OperationResponseFormatV1): OperationLiveResponseV1;
+export declare function validateOperationSubmitWireResult(value: unknown): OperationSubmitWireResult;
+export declare function validateOperationCollectWireResult(value: unknown): OperationCollectWireResult;
+export declare function validateOperationInspectWireResult(value: unknown): OperationInspectWireResult;
+export declare function validateOperationControlWireResult(value: unknown): OperationControlWireResult;
+export {};