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

package/dist/src/backend/compatibility.d.ts

@@ -0,0 +1,12 @@
+import { type BackendCompatibilityReport, type BackendRuntimeIdentity } from "./protocol.js";
+export type BackendCompatibilityExpectedIdentity = Partial<Pick<BackendRuntimeIdentity, "backendSessionId" | "packageName" | "packageVersion" | "runtime" | "runtimeVersion" | "buildDigest">>;
+/**
+ * Compare only explicitly supplied, bounded provenance. Package/runtime
+ * differences are diagnostic warnings; protocol/capability rejection is
+ * handled by the handshake before browser commands are admitted.
+ */
+export declare function compatibilityReportFromHello(value: Record<string, unknown>, expected: BackendCompatibilityExpectedIdentity | undefined, mode: "multiplexed" | "single-flight" | "legacy"): BackendCompatibilityReport;
+export declare function compatibilityReportFromLegacy(version: Record<string, unknown>, expected: BackendCompatibilityExpectedIdentity | undefined): BackendCompatibilityReport;
+export declare function blockedCompatibilityReport(message?: string): BackendCompatibilityReport;
+/** Validate transport-owned diagnostics before exposing them through a facade. */
+export declare function validateBackendCompatibilityReport(value: unknown): BackendCompatibilityReport;

package/dist/src/backend/compatibility.js

@@ -0,0 +1,208 @@
+import { BACKEND_COMPATIBILITY_SCHEMA_VERSION } from "./protocol.js";
+const MAX_WARNINGS = 16;
+const MAX_TEXT_LENGTH = 512;
+const UNKNOWN_PROVENANCE = "unknown";
+/**
+ * Compare only explicitly supplied, bounded provenance. Package/runtime
+ * differences are diagnostic warnings; protocol/capability rejection is
+ * handled by the handshake before browser commands are admitted.
+ */
+export function compatibilityReportFromHello(value, expected, mode) {
+    const warnings = [];
+    const fields = [
+        ["backendSessionId", "backend session identity"],
+        ["packageName", "package name"],
+        ["packageVersion", "package version"],
+        ["runtime", "runtime"],
+        ["runtimeVersion", "runtime version"],
+        ["buildDigest", "build digest"]
+    ];
+    for (const [field, label] of fields) {
+        const received = boundedString(value[field]);
+        const expectedValue = boundedString(expected?.[field]);
+        if (received === undefined || received === UNKNOWN_PROVENANCE) {
+            warnings.push({
+                code: "provenance_unknown",
+                ...(field === "backendSessionId" ? {} : { field }),
+                ...(received === undefined ? {} : { received }),
+                message: `Backend ${label} provenance is unknown.`
+            });
+            continue;
+        }
+        if (expectedValue !== undefined && expectedValue !== UNKNOWN_PROVENANCE && expectedValue !== received) {
+            const code = mismatchCode(field);
+            warnings.push({
+                code,
+                ...(field === "backendSessionId" ? {} : { field }),
+                expected: expectedValue,
+                received,
+                message: `Backend ${label} differs from the expected runtime (${expectedValue} versus ${received}).`
+            });
+        }
+    }
+    const boundedWarnings = warnings.slice(0, MAX_WARNINGS);
+    const hasUnknown = boundedWarnings.some(warning => warning.code === "provenance_unknown");
+    const protocolVersion = boundedString(value.protocolVersion);
+    return snapshot({
+        schemaVersion: BACKEND_COMPATIBILITY_SCHEMA_VERSION,
+        status: boundedWarnings.some(warning => warning.code !== "provenance_unknown")
+            ? "warning"
+            : hasUnknown
+                ? "unknown"
+                : "compatible",
+        mode,
+        ...(protocolVersion === undefined ? {} : { protocolVersion }),
+        ...optionalIdentity(value, "backendSessionId"),
+        ...optionalIdentity(value, "packageName"),
+        ...optionalIdentity(value, "packageVersion"),
+        ...optionalIdentity(value, "runtime"),
+        ...optionalIdentity(value, "runtimeVersion"),
+        ...optionalIdentity(value, "buildDigest"),
+        warnings: boundedWarnings
+    });
+}
+export function compatibilityReportFromLegacy(version, expected) {
+    const base = compatibilityReportFromHello({
+        protocolVersion: version.protocolVersion,
+        backendSessionId: version.backendSessionId,
+        packageName: version.packageName,
+        packageVersion: version.packageVersion,
+        runtime: version.runtime,
+        runtimeVersion: version.runtimeVersion,
+        buildDigest: version.buildDigest
+    }, expected, "legacy");
+    const warnings = [
+        {
+            code: "legacy_backend",
+            message: "Backend negotiated legacy single-flight compatibility; multiplexing was not advertised."
+        },
+        ...base.warnings
+    ].slice(0, MAX_WARNINGS);
+    return snapshot({
+        ...base,
+        status: "warning",
+        warnings
+    });
+}
+export function blockedCompatibilityReport(message = "Backend compatibility negotiation was rejected.") {
+    return snapshot({
+        schemaVersion: BACKEND_COMPATIBILITY_SCHEMA_VERSION,
+        status: "blocked",
+        mode: "unknown",
+        warnings: [{ code: "negotiation_rejected", message: boundedMessage(message) }]
+    });
+}
+/** Validate transport-owned diagnostics before exposing them through a facade. */
+export function validateBackendCompatibilityReport(value) {
+    if (!isRecord(value)
+        || value.schemaVersion !== BACKEND_COMPATIBILITY_SCHEMA_VERSION
+        || !isStatus(value.status)
+        || !isMode(value.mode)
+        || !Array.isArray(value.warnings)
+        || value.warnings.length > MAX_WARNINGS) {
+        throw new TypeError("Backend compatibility report is malformed.");
+    }
+    for (const field of ["protocolVersion", "backendSessionId", "packageName", "packageVersion", "runtime", "runtimeVersion", "buildDigest"]) {
+        if (value[field] !== undefined && boundedString(value[field]) === undefined) {
+            throw new TypeError("Backend compatibility report contains an invalid identity field.");
+        }
+    }
+    const warnings = [];
+    for (const warning of value.warnings) {
+        const message = isRecord(warning) ? boundedString(warning.message) : undefined;
+        if (!isRecord(warning)
+            || !isWarningCode(warning.code)
+            || (warning.field !== undefined && !isField(warning.field))
+            || (warning.expected !== undefined && boundedString(warning.expected) === undefined)
+            || (warning.received !== undefined && boundedString(warning.received) === undefined)
+            || message === undefined) {
+            throw new TypeError("Backend compatibility report contains an invalid warning.");
+        }
+        const expected = boundedString(warning.expected);
+        const received = boundedString(warning.received);
+        warnings.push({
+            code: warning.code,
+            ...(warning.field === undefined ? {} : { field: warning.field }),
+            ...(expected === undefined ? {} : { expected }),
+            ...(received === undefined ? {} : { received }),
+            message
+        });
+    }
+    const protocolVersion = boundedString(value.protocolVersion);
+    return snapshot({
+        schemaVersion: BACKEND_COMPATIBILITY_SCHEMA_VERSION,
+        status: value.status,
+        mode: value.mode,
+        ...(protocolVersion === undefined ? {} : { protocolVersion }),
+        ...copyOptionalIdentity(value, "backendSessionId"),
+        ...copyOptionalIdentity(value, "packageName"),
+        ...copyOptionalIdentity(value, "packageVersion"),
+        ...copyOptionalIdentity(value, "runtime"),
+        ...copyOptionalIdentity(value, "runtimeVersion"),
+        ...copyOptionalIdentity(value, "buildDigest"),
+        warnings
+    });
+}
+function snapshot(report) {
+    const warnings = Object.freeze(report.warnings.map(warning => Object.freeze({ ...warning })));
+    return Object.freeze({ ...report, warnings });
+}
+function mismatchCode(field) {
+    switch (field) {
+        case "packageName": return "package_name_mismatch";
+        case "packageVersion": return "package_version_mismatch";
+        case "runtime": return "runtime_mismatch";
+        case "runtimeVersion": return "runtime_version_mismatch";
+        case "buildDigest": return "build_digest_mismatch";
+        default: return "provenance_unknown";
+    }
+}
+function optionalIdentity(value, field) {
+    const result = boundedString(value[field]);
+    return result === undefined ? {} : { [field]: result };
+}
+function copyOptionalIdentity(value, field) {
+    const result = boundedString(value[field]);
+    return result === undefined ? {} : { [field]: result };
+}
+function boundedString(value) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= MAX_TEXT_LENGTH
+        && value.trim() === value
+        && !/[\u0000-\u001f\u007f]/u.test(value)
+        ? value
+        : undefined;
+}
+function boundedMessage(value) {
+    return value.length <= MAX_TEXT_LENGTH ? value : "Backend compatibility negotiation was rejected.";
+}
+function isStatus(value) {
+    return value === "compatible" || value === "warning" || value === "unknown" || value === "blocked";
+}
+function isMode(value) {
+    return value === "multiplexed" || value === "single-flight" || value === "legacy" || value === "unknown";
+}
+function isField(value) {
+    return value === "packageName"
+        || value === "packageVersion"
+        || value === "runtime"
+        || value === "runtimeVersion"
+        || value === "buildDigest";
+}
+function isWarningCode(value) {
+    return value === "package_name_mismatch"
+        || value === "package_version_mismatch"
+        || value === "runtime_mismatch"
+        || value === "runtime_version_mismatch"
+        || value === "build_digest_mismatch"
+        || value === "provenance_unknown"
+        || value === "legacy_backend"
+        || value === "negotiation_rejected";
+}
+function isRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/src/backend/protocol.d.ts

@@ -1,7 +1,39 @@
 export declare const BACKEND_REQUEST_SCHEMA_VERSION: "chatgpt.browser_control.backend_request.v1";
 export declare const BACKEND_RESPONSE_SCHEMA_VERSION: "chatgpt.browser_control.backend_response.v1";
 export declare const BACKEND_EVENT_SCHEMA_VERSION: "chatgpt.browser_control.backend_event.v1";
-export declare const backendCommands: readonly ["backend.version", "backend.health", "backend.capabilities", "runner.run", "runner.plan", "runner.stream", "responses.create", "ask", "askInThread", "askWithFiles", "askAndDownload", "runMessages", "openThread", "readLatest", "copyLatest", "downloadLatest", "runPlan", "doctor", "createReport", "reports.create", "reports.redact", "reports.summarize", "commands", "describe", "help", "session.bootstrap", "experience.detect", "experience.open", "configuration.inspect", "configuration.apply", "work.start", "work.status", "work.wait", "work.steer", "work.readLatest", "threads.new", "threads.search", "threads.open", "messages.compose", "messages.submit", "messages.ask", "messages.wait", "messages.readLatest", "messages.status", "messages.stop", "messages.waitAndRead", "artifacts.listLatest", "artifacts.wait", "artifacts.downloadLatest", "files.preflight", "files.attach", "files.downloadLatest", "projects.sources.list", "projects.sources.planAdd", "projects.sources.add", "modes.set", "modes.get", "tools.select", "response.copy"];
+export declare const BACKEND_HELLO_COMMAND: "backend.hello";
+export declare const BACKEND_UNKNOWN_ID_QUARANTINE_LIMIT = 256;
+export declare const BACKEND_UNKNOWN_ID_QUARANTINE_TTL_MS = 60000;
+/** Maximum encoded NDJSON frame size, excluding the trailing newline. */
+export declare const BACKEND_NDJSON_FRAME_LIMIT_BYTES: number;
+/** Maximum requestId length accepted on any backend protocol message. */
+export declare const BACKEND_REQUEST_ID_MAX_LENGTH = 4096;
+/** Reserved for transport-owned hello/legacy control probes. */
+export declare const BACKEND_CONTROL_REQUEST_ID_PREFIX = "__backend_control__";
+export declare const BACKEND_COMPATIBILITY_SCHEMA_VERSION: "chatgpt.browser_control.backend_compatibility.v1";
+/** A bounded, redacted comparison retained by a lifecycle-owned backend transport. */
+export type BackendCompatibilityWarningCode = "package_name_mismatch" | "package_version_mismatch" | "runtime_mismatch" | "runtime_version_mismatch" | "build_digest_mismatch" | "provenance_unknown" | "legacy_backend" | "negotiation_rejected";
+export type BackendCompatibilityWarning = Readonly<{
+    code: BackendCompatibilityWarningCode;
+    field?: "packageName" | "packageVersion" | "runtime" | "runtimeVersion" | "buildDigest";
+    expected?: string;
+    received?: string;
+    message: string;
+}>;
+export type BackendCompatibilityReport = Readonly<{
+    schemaVersion: typeof BACKEND_COMPATIBILITY_SCHEMA_VERSION;
+    status: "compatible" | "warning" | "unknown" | "blocked";
+    mode: "multiplexed" | "single-flight" | "legacy" | "unknown";
+    protocolVersion?: string;
+    backendSessionId?: string;
+    packageName?: string;
+    packageVersion?: string;
+    runtime?: string;
+    runtimeVersion?: string;
+    buildDigest?: string;
+    warnings: readonly BackendCompatibilityWarning[];
+}>;
+export declare const backendCommands: readonly ["backend.version", "backend.health", "backend.capabilities", "backend.hello", "runner.run", "runner.plan", "runner.stream", "responses.create", "ask", "askInThread", "askWithFiles", "askAndDownload", "runMessages", "openThread", "readLatest", "copyLatest", "downloadLatest", "runPlan", "doctor", "createReport", "reports.create", "reports.redact", "reports.summarize", "commands", "describe", "help", "session.bootstrap", "experience.detect", "experience.open", "configuration.inspect", "configuration.apply", "work.start", "work.status", "work.wait", "work.steer", "work.readLatest", "threads.new", "threads.search", "threads.open", "messages.compose", "messages.submit", "messages.ask", "messages.wait", "messages.readLatest", "messages.status", "messages.stop", "messages.waitAndRead", "artifacts.listLatest", "artifacts.wait", "artifacts.downloadLatest", "files.preflight", "files.attach", "files.downloadLatest", "projects.sources.list", "projects.sources.planAdd", "projects.sources.add", "modes.set", "modes.get", "tools.select", "response.copy", "operations.submit", "operations.collect", "operations.inspect", "operations.control"];
 export type BackendCommand = typeof backendCommands[number];
 export type BackendRequest = {
     schemaVersion: typeof BACKEND_REQUEST_SCHEMA_VERSION;
@@ -34,12 +66,62 @@ export type BackendResponseError = {
 export type BackendResponse<TResult = unknown> = BackendResponseOk<TResult> | BackendResponseError;
 export type BackendCapabilities = {
     protocolVersion: typeof BACKEND_REQUEST_SCHEMA_VERSION;
+    backendSessionId: string;
+    packageName: string;
+    packageVersion: string;
+    runtime: "node";
+    runtimeVersion: string;
+    buildDigest: string;
+    supportedProtocolVersions: string[];
     commands: BackendCommand[];
     transports: Array<"stdio" | "http">;
     streaming: {
         modes: Array<"ndjson" | "sse">;
         tokenDeltas: false;
     };
+    requestIds: {
+        required: boolean;
+        scope: "connection" | "process" | "none";
+    };
+    multiplexing: {
+        unary: boolean;
+        streams: boolean;
+    };
+    cancellation: {
+        supported: boolean;
+        requests: boolean;
+        streams: boolean;
+    };
+    tabs: {
+        stableProviderIdentity: boolean;
+        stableBrowserIdentity: boolean;
+        stableTabIdentity: boolean;
+        coordinationScope: "none" | "process" | "provider";
+        authoritativeClaim: boolean;
+        fencing: boolean;
+        concurrentTabs: boolean;
+        /** Deprecated aliases retained for older capability consumers. */
+        stableIdentity?: boolean;
+        coordination?: boolean;
+        concurrent?: boolean;
+    };
+};
+export type BackendRuntimeIdentity = {
+    backendSessionId: string;
+    packageName: string;
+    packageVersion: string;
+    runtime: "node";
+    runtimeVersion: string;
+    buildDigest: string;
+    protocolVersion: typeof BACKEND_REQUEST_SCHEMA_VERSION;
+};
+export type BackendHelloPayload = {
+    protocolVersion?: string;
+    capabilities?: Partial<BackendCapabilities>;
+};
+export type BackendHelloResult = BackendRuntimeIdentity & {
+    accepted: boolean;
+    capabilities: BackendCapabilities;
 };
 export type BackendRunItemStreamEvent = {
     type: "run_item_stream_event";
@@ -68,6 +150,7 @@ export type BackendEvent = BackendEventPayload & {
     requestId?: string;
 };
 export declare function parseBackendRequest(raw: unknown): BackendRequest;
+export declare function isValidBackendRequestId(value: unknown): value is string;
 export declare function backendResponseOk<TResult>(requestId: string | undefined, result: TResult): BackendResponseOk<TResult>;
 export declare function backendResponseError(requestId: string | undefined, error: ProtocolError | Error): BackendResponseError;
 export declare function backendEvent(requestId: string | undefined, payload: BackendEventPayload): BackendEvent;

package/dist/src/backend/protocol.js

@@ -1,10 +1,21 @@
 export const BACKEND_REQUEST_SCHEMA_VERSION = "chatgpt.browser_control.backend_request.v1";
 export const BACKEND_RESPONSE_SCHEMA_VERSION = "chatgpt.browser_control.backend_response.v1";
 export const BACKEND_EVENT_SCHEMA_VERSION = "chatgpt.browser_control.backend_event.v1";
+export const BACKEND_HELLO_COMMAND = "backend.hello";
+export const BACKEND_UNKNOWN_ID_QUARANTINE_LIMIT = 256;
+export const BACKEND_UNKNOWN_ID_QUARANTINE_TTL_MS = 60_000;
+/** Maximum encoded NDJSON frame size, excluding the trailing newline. */
+export const BACKEND_NDJSON_FRAME_LIMIT_BYTES = 16 * 1024 * 1024;
+/** Maximum requestId length accepted on any backend protocol message. */
+export const BACKEND_REQUEST_ID_MAX_LENGTH = 4096;
+/** Reserved for transport-owned hello/legacy control probes. */
+export const BACKEND_CONTROL_REQUEST_ID_PREFIX = "__backend_control__";
+export const BACKEND_COMPATIBILITY_SCHEMA_VERSION = "chatgpt.browser_control.backend_compatibility.v1";
 export const backendCommands = [
     "backend.version",
     "backend.health",
     "backend.capabilities",
+    "backend.hello",
     "runner.run",
     "runner.plan",
     "runner.stream",
@@ -60,7 +71,11 @@ export const backendCommands = [
     "modes.set",
     "modes.get",
     "tools.select",
-    "response.copy"
+    "response.copy",
+    "operations.submit",
+    "operations.collect",
+    "operations.inspect",
+    "operations.control"
 ];
 export class ProtocolError extends Error {
     code;
@@ -91,13 +106,20 @@ export function parseBackendRequest(raw) {
         payload: normalizePayload(raw.payload)
     };
     if (raw.requestId !== undefined) {
-        if (typeof raw.requestId !== "string" || raw.requestId.length === 0) {
+        if (!isValidBackendRequestId(raw.requestId)) {
             throw new ProtocolError("invalid_request", "Backend request requestId must be a non-empty string when provided.", false);
         }
         request.requestId = raw.requestId;
     }
     return request;
 }
+export function isValidBackendRequestId(value) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= BACKEND_REQUEST_ID_MAX_LENGTH
+        && value.trim() === value
+        && !/[\u0000-\u001f\u007f]/u.test(value);
+}
 export function backendResponseOk(requestId, result) {
     const response = {
         schemaVersion: BACKEND_RESPONSE_SCHEMA_VERSION,
@@ -109,13 +131,17 @@ export function backendResponseOk(requestId, result) {
     return response;
 }
 export function backendResponseError(requestId, error) {
+    // Arbitrary command/provider errors can contain prompts, local paths, page
+    // text, or bridge diagnostics. Only deliberately constructed ProtocolError
+    // messages are safe to cross the backend boundary.
+    const protocolError = error instanceof ProtocolError;
     const response = {
         schemaVersion: BACKEND_RESPONSE_SCHEMA_VERSION,
         ok: false,
         error: {
-            code: error instanceof ProtocolError ? error.code : "invalid_request",
-            message: error.message,
-            recoverable: error instanceof ProtocolError ? error.recoverable : false
+            code: protocolError ? error.code : "invalid_request",
+            message: protocolError ? error.message : "Backend command failed safely.",
+            recoverable: protocolError ? error.recoverable : false
         }
     };
     if (requestId !== undefined)

package/dist/src/backend/runtime-identity.d.ts

@@ -0,0 +1,10 @@
+import type { BackendSessionOptions } from "./session.js";
+/**
+ * Resolve truthful provenance for the exact backend entry artifact.
+ *
+ * The digest is computed from the loaded file, so copied/sanitized plugin
+ * bundles do not accidentally inherit the source bundle's identity. Package
+ * metadata is discovered from a bounded ancestor walk and is optional:
+ * unknown is preferable to guessing when a custom embedding has no manifest.
+ */
+export declare function detectPackagedBackendIdentity(moduleUrl: string | URL): Promise<BackendSessionOptions["backendIdentity"]>;

package/dist/src/backend/runtime-identity.js

@@ -0,0 +1,141 @@
+import { constants as fsConstants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const MAX_METADATA_BYTES = 1024 * 1024;
+const MAX_BACKEND_ARTIFACT_BYTES = 128 * 1024 * 1024;
+const MAX_ANCESTORS = 8;
+const MAX_IDENTITY_FIELD_LENGTH = 512;
+/**
+ * Resolve truthful provenance for the exact backend entry artifact.
+ *
+ * The digest is computed from the loaded file, so copied/sanitized plugin
+ * bundles do not accidentally inherit the source bundle's identity. Package
+ * metadata is discovered from a bounded ancestor walk and is optional:
+ * unknown is preferable to guessing when a custom embedding has no manifest.
+ */
+export async function detectPackagedBackendIdentity(moduleUrl) {
+    const artifactPath = modulePath(moduleUrl);
+    const [metadata, buildDigest] = await Promise.all([
+        findPackageMetadata(dirname(artifactPath)),
+        digestArtifact(artifactPath)
+    ]);
+    return {
+        ...(metadata.packageName === undefined ? {} : { packageName: metadata.packageName }),
+        ...(metadata.packageVersion === undefined ? {} : { packageVersion: metadata.packageVersion }),
+        ...(buildDigest === undefined ? {} : { buildDigest })
+    };
+}
+function modulePath(moduleUrl) {
+    try {
+        const url = moduleUrl instanceof URL ? moduleUrl : new URL(moduleUrl);
+        if (url.protocol !== "file:")
+            throw new TypeError("Backend module URL must use file protocol.");
+        return resolve(fileURLToPath(url));
+    }
+    catch (error) {
+        throw new TypeError(`Backend module URL is invalid: ${error instanceof Error ? error.message : "unknown URL error"}`);
+    }
+}
+async function digestArtifact(path) {
+    const bytes = await readStableRegularFile(path, MAX_BACKEND_ARTIFACT_BYTES);
+    return bytes === undefined
+        ? undefined
+        : `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+async function findPackageMetadata(start) {
+    let current = resolve(start);
+    for (let depth = 0; depth < MAX_ANCESTORS; depth += 1) {
+        for (const candidate of [join(current, "package.json"), join(current, ".codex-plugin", "plugin.json")]) {
+            const parsed = await readBoundedJson(candidate);
+            if (parsed === undefined)
+                continue;
+            const packageName = identityField(parsed.name);
+            const packageVersion = identityField(parsed.version);
+            if (packageName !== undefined || packageVersion !== undefined) {
+                return {
+                    ...(packageName === undefined ? {} : { packageName }),
+                    ...(packageVersion === undefined ? {} : { packageVersion })
+                };
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return {};
+}
+async function readBoundedJson(path) {
+    const bytes = await readStableRegularFile(path, MAX_METADATA_BYTES);
+    if (bytes === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(bytes.toString("utf8"));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read one bounded regular file without trusting pathname-only checks.
+ * Windows does not expose O_NOFOLLOW, so lstat must reject links explicitly;
+ * the handle/path identity comparisons also fail closed if the entry is
+ * replaced between the checks and the read.
+ */
+async function readStableRegularFile(path, maxBytes) {
+    let handle;
+    try {
+        const before = await lstat(path);
+        if (!isBoundedRegularFile(before, maxBytes))
+            return undefined;
+        handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+        const opened = await handle.stat();
+        if (!isBoundedRegularFile(opened, maxBytes) || !sameFileIdentity(before, opened))
+            return undefined;
+        const bytes = await handle.readFile();
+        const finalHandle = await handle.stat();
+        const finalPath = await lstat(path);
+        if (!isBoundedRegularFile(finalHandle, maxBytes)
+            || !isBoundedRegularFile(finalPath, maxBytes)
+            || !sameFileIdentity(opened, finalHandle)
+            || !sameFileIdentity(finalHandle, finalPath)
+            || bytes.byteLength !== finalHandle.size) {
+            return undefined;
+        }
+        return bytes;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function isBoundedRegularFile(metadata, maxBytes) {
+    return !metadata.isSymbolicLink()
+        && metadata.isFile()
+        && Number.isSafeInteger(metadata.size)
+        && metadata.size >= 0
+        && metadata.size <= maxBytes;
+}
+function sameFileIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function identityField(value) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= MAX_IDENTITY_FIELD_LENGTH
+        && value.trim() === value
+        && !/[\u0000-\u001f\u007f]/u.test(value)
+        ? value
+        : undefined;
+}
+function isRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/src/backend/session.d.ts

@@ -1,11 +1,19 @@
 import { type ChatGPTClientOptions } from "../client.js";
-import { type BackendEvent, type BackendRequest, type BackendResponse } from "./protocol.js";
-export type BackendSessionOptions = ChatGPTClientOptions;
+import { type BackendEvent, type BackendRuntimeIdentity, type BackendRequest, type BackendResponse } from "./protocol.js";
+export type BackendSessionOptions = ChatGPTClientOptions & {
+    /**
+     * Optional build metadata injected by a packaged backend. Unknown values are
+     * deliberately retained as "unknown" instead of being guessed.
+     */
+    backendIdentity?: Partial<Omit<BackendRuntimeIdentity, "protocolVersion" | "runtime">>;
+};
 export declare class BackendSession {
     private readonly options;
     private clientInstance;
+    private readonly identity;
     constructor(options?: BackendSessionOptions);
     dispatch(request: BackendRequest): Promise<BackendResponse>;
     stream(request: BackendRequest): AsyncIterable<BackendEvent>;
+    private hello;
     private client;
 }