@opengeni/runtime 0.14.3 → 0.14.15

package/dist/codex-tool-search.d.ts

@@ -0,0 +1,100 @@
+import { type Tool } from "@openai/agents";
+/** The prefix OpenGeni's PrefixedMcpServer stamps on codex_apps connector tools. */
+export declare const CODEX_APPS_TOOL_PREFIX = "codex_apps__";
+/** True for a materialized codex_apps connector function tool. */
+export declare function isCodexAppsFunctionTool(tool: unknown): tool is Tool & {
+    name: string;
+    deferLoading?: boolean;
+};
+/**
+ * True for non-mandatory MCP function tools on the effective agent surface.
+ * The prefix is the same runtime namespace used by PrefixedMcpServer; this
+ * intentionally does not inspect the global registry, connection metadata, or
+ * credentials, so search cannot widen the already-authorized tool set.
+ */
+export declare function isSearchableMcpFunctionTool(tool: unknown, mcpServerIds?: ReadonlySet<string>): tool is Tool & {
+    name: string;
+    deferLoading?: boolean;
+};
+/**
+ * Rank connector tools against a plain-language query with BM25 (Okapi, k1=1.5,
+ * b=0.75) over tokenized name+description+params. Returns the top `limit` tools
+ * with a positive score, most-relevant first. An empty or no-match query returns
+ * [] — matching codex-rs, whose search returns empty rather than arbitrary tools;
+ * disclosing unrelated (and thereby CALLABLE) tools on a miss feeds the model
+ * noise. The SDK normalizes an empty executor result into an empty
+ * tool_search_output, which the model reads as "nothing matched — rephrase".
+ */
+export declare function bm25RankTools(tools: Tool[], query: string, limit: number): Tool[];
+/**
+ * Render the search tool's description from the account's ACTUALLY-connected
+ * sources — codex-rs parity (its create_tool_search_tool builds "You have access
+ * to tools from the following sources:\n- <name>" from the live enabled-source
+ * list). With defer_loading stripping every connector schema (and name) from
+ * model context, this description is the model's ONLY signal of which apps
+ * exist, so a hardcoded list would both advertise absent connectors and hide
+ * present ones.
+ */
+export declare function renderSearchToolDescription(connectorNamespaces: ReadonlySet<string>): string;
+/**
+ * A per-TURN freeze cell for the tool_search description (AM-8). The connector Set
+ * `installCodexToolSearch` reads is LIVE and by-reference — it fills as the turn's
+ * codex_apps tools/list resolves and can change between a turn's model calls.
+ * Re-rendering the description per call from a changed Set flips the tools block,
+ * and because tools precede the history in the request prefix, ANY change misses the
+ * ENTIRE conversation prefix from that point on — a proven prompt-cache breaker.
+ *
+ * We therefore freeze the description ONCE, at the first model call whose Set has
+ * been populated (connectors discovered), and reuse that frozen string for the rest
+ * of the turn — trading a slightly staler connector list for a byte-stable prefix.
+ * The freeze is created per {@link installCodexToolSearch} (once per turn) and shared
+ * by reference into every clone re-install, so all of a turn's clones agree.
+ */
+export type CodexToolSearchDescriptionFreeze = {
+    value: string | null;
+};
+/** Build the client-executed tool_search tool that discloses deferred MCP tools on demand. */
+export declare function buildCodexToolSearchTool(connectorNamespaces?: ReadonlySet<string>, mcpServerIds?: ReadonlySet<string>): Tool;
+/**
+ * The transform applied to a turn's resolved tool list: tag every searchable
+ * non-mandatory MCP function tool `deferLoading = true`, and — unless one is already
+ * present — append the client tool_search tool. Pure (mutates the passed tools +
+ * returns the possibly-extended array); the SDK's `getTools` gate requires a
+ * tool_search whenever a deferred tool is present, which appending here satisfies
+ * in the same request.
+ *
+ * The search tool is appended UNCONDITIONALLY (even when the turn has no
+ * searchable MCP tools, e.g. a best-effort connector was dropped this
+ * turn): a prior turn's history may carry tool_search_call/output items, and
+ * replaying those without a tool_search tool in the request risks a backend
+ * reject; a search over an empty pool simply discloses nothing. The description
+ * reflects the LIVE connector namespaces, so an empty turn reads
+ * "none currently available".
+ */
+export declare function applyCodexToolSearch(tools: Tool[], connectorNamespaces?: ReadonlySet<string>, descriptionFreeze?: CodexToolSearchDescriptionFreeze, mcpServerIds?: ReadonlySet<string>): Tool[];
+type CloneCapableAgent = {
+    getAllTools: (runContext: unknown) => Promise<Tool[]>;
+    clone?: (config: unknown) => CloneCapableAgent;
+};
+/**
+ * Install progressive MCP disclosure on a Codex-path agent by wrapping
+ * `getAllTools` so every per-model-call tool resolution runs
+ * {@link applyCodexToolSearch}. Idempotent-per-call (re-tags each
+ * freshly-materialized MCP tool under cacheToolsList:false). Gated by the caller
+ * (flag + Codex path).
+ *
+ * CLONE SURVIVAL (the part that makes this work on the REAL sandbox path): the
+ * SDK's sandbox runtime routes EVERY model call through
+ * `prepareSandboxAgent → agent.clone(...)` (agentPreparation.js), and
+ * `SandboxAgent.clone` constructs a FRESH agent from a fixed field list — an
+ * instance-own `getAllTools` override is NOT copied, so patching only this
+ * instance would silently no-op the whole feature on sandbox turns (the run
+ * loop resolves tools on the CLONE). We therefore also wrap `clone` to
+ * RE-INSTALL onto every clone, recursively — covering clone-of-clone and the
+ * RunState resume paths. `connectorNamespaces` is the LIVE, by-reference Set the
+ * codex_apps sanitizing transport fills during each turn's tools/list
+ * (prepareAgentTools), so by the time the wrapper post-processes getAllTools the
+ * current turn's connector sources are known.
+ */
+export declare function installCodexToolSearch(agent: CloneCapableAgent, connectorNamespaces?: ReadonlySet<string>, mcpServerIds?: ReadonlySet<string>): void;
+export {};

package/dist/context-compaction.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Portable conversation context compaction, following Codex CLI's local path.
+ *
+ * The checkpoint model sees the current active history plus one fixed
+ * checkpoint prompt, then the active history is rebuilt from the newest real
+ * user messages within one cumulative 20k-token budget plus one summary.
+ * Assistant messages, tool calls/results, reasoning, and images are removed
+ * from the active model-facing history; the database audit rows remain.
+ */
+export type CompactionItem = Record<string, unknown>;
+/**
+ * Marker stored on the synthetic summary item so the UI can render it and the
+ * next rebuild can exclude old summaries from the retained user-message set.
+ */
+export declare const COMPACTION_SUMMARY_MARKER = "opengeni_context_summary";
+export declare const SUMMARY_BUFFER_TOKENS = 20000;
+export declare const COMPACT_USER_MESSAGE_MAX_TOKENS = 20000;
+/** Codex CLI remote compaction v2 retained-message budget (codex-rs). */
+export declare const REMOTE_V2_RETAINED_MESSAGE_TOKEN_BUDGET = 64000;
+export declare const REMOTE_COMPACTION_V2_IMPLEMENTATION: "responses_compaction_v2";
+export declare const REMOTE_COMPACTION_V2_BETA_FEATURE: "remote_compaction_v2";
+export declare const DEFAULT_COMPACTION_THRESHOLD_RATIO = 0.9;
+export declare const MIN_COMPACTION_THRESHOLD_RATIO = 0.3;
+export declare const MAX_COMPACTION_THRESHOLD_RATIO = 0.9;
+export declare const COMPACTION_PROMPT: string;
+export declare const SUMMARY_PREFIX = "Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. Use this to build on the work that has already been done and avoid duplicating work. Here is the summary produced by the other language model, use the information in this summary to assist with your own analysis:";
+export declare const USER_MESSAGE_TRUNCATION_MARKER = "\n[... middle truncated for context compaction ...]\n";
+/** A user-authored `message` item is the only legal turn boundary. */
+export declare function isUserMessage(item: unknown): boolean;
+/** True for our synthetic compaction summary item. */
+export declare function isCompactionSummary(item: unknown): boolean;
+/**
+ * Conservative tokenizer-independent text estimate used for every local input
+ * budget. Preserve the stable ASCII `chars / 4` heuristic, but never discount
+ * Unicode as UTF-16 length/4: each non-ASCII code unit costs at least one token
+ * (CJK ≈ 1/code point; an astral emoji's surrogate pair ≈ 2). This intentionally
+ * errs toward compaction rather than letting multilingual current input exceed
+ * a provider context window before an authoritative usage anchor exists.
+ */
+export declare function estimateTextTokens(text: string): number;
+export declare const UNKNOWN_IMAGE_TOKENS = 4096;
+export declare const MAX_NATIVE_IMAGE_TOKENS = 8192;
+export type NativeImageEstimateReason = "dimensions" | "bounded_fallback";
+export type NativeImageTokenEstimate = {
+    tokens: number;
+    width: number | null;
+    height: number | null;
+    detail: string;
+    reason: NativeImageEstimateReason;
+};
+export type ModelInputTokenBreakdown = {
+    totalTokens: number;
+    textTokens: number;
+    imageTokens: number;
+    imageCount: number;
+    imageFallbackCount: number;
+};
+/**
+ * Provider-neutral local estimate for one native image. Inline bytes are used
+ * only to recover dimensions; their base64 length never becomes text tokens.
+ */
+export declare function estimateNativeImageTokens(input: {
+    source?: unknown;
+    width?: number | null;
+    height?: number | null;
+    detail?: unknown;
+}): NativeImageTokenEstimate;
+/**
+ * Codex CLI `estimate_reasoning_length`: opaque encrypted payloads are not
+ * model-visible as raw JSON/base64. Visible bytes ≈ `len * 3/4 - 650`.
+ */
+export declare function estimateOpaqueEncryptedModelVisibleBytes(encodedLen: number): number;
+/** Codex CLI bytes→tokens for opaque encrypted content (`ceil(bytes / 4)`). */
+export declare function estimateOpaqueEncryptedTokens(encodedLen: number): number;
+/**
+ * Length of opaque encrypted content that must use the Codex encrypted
+ * estimator instead of JSON.stringify (compaction blobs and reasoning).
+ */
+export declare function opaqueEncryptedContentLength(item: unknown): number | null;
+/** Native-image-aware item estimate for pre-call accounting and retained budgets. */
+export declare function estimateItemTokenBreakdown(item: CompactionItem): ModelInputTokenBreakdown;
+export declare function estimateItemTokens(item: CompactionItem): number;
+export declare function estimateTokens(items: readonly CompactionItem[]): number;
+export declare function estimateTokensBreakdown(items: readonly CompactionItem[]): ModelInputTokenBreakdown;
+export declare function estimateSerializedValueTokens(value: unknown): number;
+export type CompleteModelInputFootprint = {
+    input: readonly CompactionItem[];
+    instructionsTokens: number;
+    toolSchemaTokens: number;
+};
+export type ProviderContextTokenSignal = {
+    /** Monotonic within one sampled run; advances after every model response. */
+    revision: number;
+    /** Provider total tokens after that response (input + generated output). */
+    totalTokens: number;
+};
+export type CompleteModelInputEstimate = {
+    tokens: number;
+    source: "complete_estimate" | "provider_plus_local";
+    inputTokens: number;
+    inputTextTokens: number;
+    inputImageTokens: number;
+    inputImageCount: number;
+    inputImageFallbackCount: number;
+    instructionsTokens: number;
+    toolSchemaTokens: number;
+    appendedAfterModelTokens: number;
+};
+/**
+ * Match Codex history accounting: after one provider response, start from its
+ * authoritative TOTAL token count and add only local items placed after the
+ * newest model-generated item. System instructions and tool schemas are
+ * compared with the exact request footprint that produced the provider count;
+ * positive growth is added. Without a bound anchor, estimate the entire
+ * outgoing request rather than trusting stale usage from an earlier turn.
+ */
+export declare function estimateCompleteModelInput(input: {
+    current: CompleteModelInputFootprint;
+    provider?: ProviderContextTokenSignal | null;
+    providerRequestFootprint?: CompleteModelInputFootprint | null;
+}): CompleteModelInputEstimate;
+export declare function itemsAfterLastModelGeneratedItem(items: readonly CompactionItem[]): CompactionItem[];
+export declare function hasModelGeneratedItem(items: readonly CompactionItem[]): boolean;
+export declare function clampCompactionThresholdRatio(value: number | undefined | null): number;
+export declare function compactionThresholdTokens(input: {
+    contextWindowTokens: number;
+    contextReservedOutputTokens: number;
+    contextAutoCompactThresholdTokens?: number | null | undefined;
+    contextCompactionThresholdRatio?: number | null | undefined;
+}): number;
+export type CompactionDecision = {
+    shouldCompact: boolean;
+    reason: "force" | "above_threshold" | "below_threshold" | "no_history";
+    signalTokens: number;
+    thresholdTokens: number;
+};
+export declare function decideCompaction(input: {
+    items: readonly CompactionItem[];
+    lastInputTokens?: number | null;
+    contextWindowTokens: number;
+    contextReservedOutputTokens: number;
+    contextAutoCompactThresholdTokens?: number | null | undefined;
+    contextCompactionThresholdRatio?: number | null | undefined;
+    force?: boolean;
+}): CompactionDecision;
+export declare class CompactionNeededError extends Error {
+    readonly signalTokens: number;
+    readonly thresholdTokens: number;
+    readonly signalSource: "provider" | "estimate";
+    readonly trigger: "threshold" | "operator";
+    constructor(input: {
+        signalTokens: number;
+        thresholdTokens: number;
+        signalSource: "provider" | "estimate";
+        trigger?: "threshold" | "operator";
+    });
+}
+export declare class EmptyCompactionSummaryError extends Error {
+    readonly diagnostics: Record<string, unknown>;
+    constructor(diagnostics?: Record<string, unknown>);
+}
+/**
+ * The checkpoint model request ended in a provider/transport failure rather
+ * than a successful response with an empty assistant message. Diagnostics are
+ * deliberately bounded and content-free so this error can be persisted on a
+ * turn without copying provider messages or conversation input into events.
+ */
+export declare class CompactionProviderResponseError extends Error {
+    readonly diagnostics: Record<string, unknown>;
+    readonly status?: number;
+    readonly code?: string;
+    readonly type?: string;
+    readonly cause?: unknown;
+    constructor(diagnostics?: Record<string, unknown>, cause?: unknown);
+}
+export declare function findCompactionNeededError(error: unknown, seen?: WeakSet<object>): CompactionNeededError | null;
+/**
+ * The exact checkpoint input shape: current active history followed by Codex's
+ * checkpoint prompt as a synthesized user message.
+ */
+export declare function buildCompactionPromptInput(items: readonly CompactionItem[]): CompactionItem[];
+export type PreparedCompactionPromptInput = {
+    input: CompactionItem[];
+    estimatedInputTokens: number;
+    rewrittenToolOutputs: number;
+    droppedHistoryItems: number;
+};
+/**
+ * Fit the explicit checkpoint request without mutating canonical history.
+ *
+ * Codex first replaces oversized tool outputs in its temporary remote-
+ * compaction input. OpenGeni does the same oldest-first, preserving the most
+ * recent tool detail for the plaintext summary. If that is still insufficient,
+ * whole oldest user-delimited work units are removed and the remaining suffix
+ * is protocol-sanitized so no call/result/reasoning fragment is orphaned.
+ * The raw active history is still the source for the eventual replacement and
+ * remains unchanged if the provider call fails.
+ */
+export declare function prepareCompactionPromptInput(items: readonly CompactionItem[], maxInputTokens: number): PreparedCompactionPromptInput;
+/**
+ * Build the active history after compaction:
+ * the newest real user messages that fit one cumulative 20k-token budget
+ * (prior summaries excluded, images removed) plus one marked summary item.
+ */
+export declare function buildCompactionReplacementHistory(items: readonly CompactionItem[], summaryBody: string): CompactionItem[];
+/** True for a Codex remote-compaction output item with opaque encrypted content. */
+export declare function isRemoteCompactionItem(item: unknown): item is CompactionItem;
+/** Messages retained beside a remote v2 compaction blob (user + developer). */
+export declare function isRetainedRemoteV2Message(item: unknown): boolean;
+/**
+ * Build the active history after Codex remote compaction v2:
+ * newest retained user/developer messages within the CLI 64k budget plus the
+ * opaque `{ type: "compaction", encrypted_content }` item.
+ */
+export declare function buildRemoteV2ReplacementHistory(items: readonly CompactionItem[], compactionItem: CompactionItem): CompactionItem[];
+/**
+ * Append the transient compaction_trigger used only for the remote v2 request.
+ *
+ * The OpenAI Agents SDK's Responses converter rejects a bare
+ * `{ type: "compaction_trigger" }` (`UserError: Unsupported item`). It does
+ * accept `type: "unknown"` and forwards `providerData` onto the wire, which is
+ * how we deliver the Codex-only trigger through CompactionResponsesModel into
+ * the Codex fetch normalizer (which allowlists top-level `compaction_trigger`).
+ */
+export declare function buildRemoteCompactionV2PromptInput(items: readonly CompactionItem[]): CompactionItem[];
+/** Extract exactly one compaction output item from a Responses payload. */
+export declare function extractRemoteCompactionV2OutputItem(response: unknown): CompactionItem;
+export declare function compactionReplacementFingerprint(items: readonly CompactionItem[]): string;
+/** Fingerprint the latest durable replacement prefix in active history. */
+export declare function latestCompactionReplacementFingerprint(items: readonly CompactionItem[]): string | null;
+/**
+ * Build the synthetic summary item (a plain user message) appended to the
+ * rebuilt active history.
+ */
+export declare function buildSummaryItem(summaryBody: string): CompactionItem;
+export declare function renderCompactionPromptInputForChat(input: readonly CompactionItem[]): string;

package/dist/history-sanitizer.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Read-path sanitizer for replayed conversation history (issue: orphaned
+ * tool outputs brick a session).
+ *
+ * Conversation truth is persisted as a flat list of SDK history items in
+ * `session_history_items` and replayed verbatim into the model on every turn.
+ * The OpenAI Responses API rejects the whole request (HTTP 400) when that list
+ * violates its tool-call pairing rules — most destructively:
+ *
+ *   `400 No tool call found for function call output with call_id <X>`
+ *
+ * when a `function_call_result` (a.k.a. function_call_output) has no matching
+ * `function_call` earlier in the list. Because the corrupt item is replayed on
+ * every subsequent turn, one orphaned output permanently bricks the session
+ * across revival — it stays dead until the row is hand-deleted.
+ *
+ * This module is the reliability net: before history items are sent to the
+ * model they pass through `sanitizeHistoryItemsForModel`, which removes any
+ * item that would make the request invalid. It mirrors the SDK's own
+ * `dropOrphanToolCalls` continuation logic (which only runs over the SDK's
+ * in-memory `state.history`, not over rows we reload from the database) so a
+ * reloaded history is shaped exactly like a freshly-generated one.
+ *
+ * It is a pure function over plain JSON item shapes (no SDK import, no I/O) so
+ * it is cheap to unit-test exhaustively. It NEVER mutates its input items and
+ * NEVER touches the stored rows — only the in-memory copy sent to the model is
+ * filtered, keeping the persisted audit trail intact.
+ */
+/** A history item is any JSON object; we only inspect a few discriminator fields. */
+export type HistoryItem = Record<string, unknown>;
+/**
+ * @deprecated Model-visible history is append-only outside the explicit
+ * durable compaction transition. This compatibility identity function performs
+ * no elision and returns the exact input array with every item untouched and in
+ * its original order.
+ */
+export declare function elideSupersededViewImagePairs<T extends HistoryItem>(items: readonly T[]): T[];
+/**
+ * Tool-call item types and the result-item type that settles them. Kept in
+ * sync with the SDK's `TOOL_CALL_RESULT_TYPE_BY_CALL_TYPE`; `function_call` is
+ * the one observed live, the rest are included so the same pairing logic holds
+ * for every tool-call kind the SDK can emit.
+ */
+export declare const TOOL_CALL_RESULT_TYPE_BY_CALL_TYPE: Record<string, string>;
+/**
+ * Sanitize a replayed history item list into a sequence the Responses API
+ * accepts. Pure: returns a new array of the same item references in order,
+ * with invalid items omitted. Valid histories come back byte-identical
+ * (same references, same order).
+ *
+ * Rules, each motivated by a concrete 400 the API raises:
+ *
+ *  1. Drop every tool-call RESULT whose matching tool CALL does not appear
+ *     earlier in the list. This is the session-bricking orphan: a
+ *     `function_call_result` with no preceding `function_call` of the same
+ *     `call_id`. ("No tool call found for function call output…")
+ *
+ *  2. Drop every tool CALL that has no matching RESULT anywhere after it.
+ *     The Responses API requires each tool call to be settled by its output
+ *     before the conversation can continue; a dangling call left in replayed
+ *     history 400s with "No tool output found for function call…". Dropping
+ *     the dangling call (rather than synthesizing a fake output) is what the
+ *     SDK itself does for in-memory continuation, so a reloaded history is
+ *     shaped identically. The matching result, if it later exists, is kept;
+ *     only genuinely unpaired calls are removed.
+ *
+ *  3. Drop any `reasoning` item that immediately precedes (across a run of
+ *     reasoning items) a dropped tool call. The Responses API ties an
+ *     encrypted reasoning item to the tool call it produced; a reasoning item
+ *     orphaned by rule 2 trips "Item 'rs_…' of type 'reasoning' was provided
+ *     without its required following item". Mirrors the SDK's
+ *     `dropReasoningItemsPrecedingDroppedCalls`.
+ *
+ * A `call_id` is paired only when BOTH a call and a result of the matching
+ * types exist with that id, the call appearing before the result. Calls and
+ * results that satisfy that survive untouched.
+ */
+export declare function sanitizeHistoryItemsForModel<T extends HistoryItem>(items: readonly T[], toolOutputTruncationTokens?: number): T[];
+/**
+ * Internal marker stamping machine-generated resume/continuation messages
+ * (turn-resumed notices, goal continuations) so compaction housekeeping can
+ * recognize them in STORED history. Lives here (not context-compaction, which
+ * imports from this module) so the wire sanitizer below can strip it without
+ * an import cycle; context-compaction re-exports it.
+ */
+export declare const INTERNAL_RESUME_MESSAGE_MARKER = "opengeni_internal_resume";
+/**
+ * Remove the {@link INTERNAL_RESUME_MESSAGE_MARKER} providerData key from a
+ * single item before it reaches ANY model wire. Pure + non-mutating; returns
+ * the SAME reference when there is nothing to strip (keeping the common path
+ * byte-identical, mirroring {@link stripReasoningEncryptedContent}).
+ *
+ * WHY. The @openai/agents SDK serializes providerData keys verbatim into the
+ * request item, and strict Responses backends reject unknown per-item fields —
+ * observed in production as `400 Unknown parameter:
+ * 'input[N].opengeni_internal_resume'`, which deterministically failed every
+ * turn whose replayed history contained a marked resume message (the marker is
+ * durable in conversation truth, so retries could never succeed). Detection
+ * (isInternalResumeMessage) reads STORED items and also keeps a text-prefix
+ * fallback, so stripping at the wire degrades housekeeping gracefully and
+ * never the turn.
+ */
+export declare function stripInternalResumeMarker<T extends HistoryItem>(item: T): T;
+/**
+ * Drop the account/org-bound `reasoning.encrypted_content` blob from a single
+ * history item, preserving everything else (the visible chain-of-thought text in
+ * `summary`/`content`, and every non-reasoning field). Pure + non-mutating: when
+ * there is nothing to strip the SAME reference is returned (so the common,
+ * same-account path stays byte-identical); otherwise a shallow clone is returned.
+ *
+ * WHY. A codex-subscription turn round-trips `reasoning.encrypted_content` — an
+ * opaque blob minted by the ChatGPT/Codex backend that is bound to the account
+ * (org) that produced it. After a manual switch from codex account A to B, the
+ * carried history items still hold A-minted blobs; replaying them into a turn
+ * running on B is rejected (400). The blob is purely a chain-of-thought
+ * continuity optimization — dropping it costs at most one turn of lost CoT
+ * continuity and never any message content.
+ *
+ * USED FOR `compaction` items only on the history-items read path: a foreign
+ * `compaction` summary carries account-bound `encrypted_content` but its summary
+ * is real conversation content that must be preserved, so we strip only the blob
+ * (we do NOT drop the whole item). Foreign `reasoning` items are instead dropped
+ * WHOLESALE by the caller (id + blob), because the Responses backend validates
+ * the foreign `rs_…` id and rejects a reasoning item that has a foreign id and no
+ * encrypted_content (so blanking the blob alone is not enough — see
+ * {@link applyCodexHistoryStrip}).
+ *
+ * The SDK's Responses converter reads the blob via `providerData.encryptedContent`
+ * (camel) or `providerData.encrypted_content` (snake); persisted rows use the
+ * snake form, but we delete both casings defensively. We also clear a top-level
+ * `encrypted_content` (the `compaction`-item shape) belt-and-braces — that blob
+ * is likewise source-bound. Only `reasoning` and `compaction` items are touched;
+ * messages, tool calls, and tool outputs pass through untouched by reference.
+ */
+export declare function stripReasoningEncryptedContent<T extends HistoryItem>(item: T): T;
+/**
+ * Neutralize the account/org-bound identity of EVERY `reasoning` item embedded
+ * in a serialized RunState JSON string, returning the re-serialized string. Pure:
+ * a parse failure or a no-op returns the SAME string reference (so an unchanged
+ * or non-codex run-state replays byte-for-byte).
+ *
+ * WHY (HOLE C — approval replay). An approval decision resumes the serialized
+ * RunState blob. That blob round-trips `reasoning.encrypted_content` minted by the ChatGPT/Codex
+ * backend (bound to the freezing account/org — a foreign account 400s it) AND the
+ * foreign `rs_…` reasoning ids the Responses backend validates (rejected once the
+ * blob is gone). Unlike `session_history_items`, the blob carries NO per-item
+ * producer tag, so foreign-ness cannot be decided per item; the worker instead
+ * records the FREEZING codex account on the run-state row and calls this only when
+ * the resuming turn's codex account DIFFERS from it. When the accounts differ we
+ * conservatively neutralize every reasoning item: delete its provider id and its
+ * `encrypted_content` (both casings, in `providerData`). The visible reasoning
+ * `content`/`summary` and every message / tool-call / tool-output item are left
+ * intact (message and tool content are never account-bound).
+ *
+ * A reasoning item with no id and no encrypted_content is exactly the shape the
+ * production Azure path already sends (see `stripProviderItemIdsFilter`), so it
+ * deserializes and replays cleanly. Reasoning items live in several places in the
+ * blob — `originalInput` (when an array), each `modelResponses[].output`,
+ * `lastModelResponse.output`, and the `generatedItems` wrappers (`reasoning_item`
+ * → `rawItem`) — and we scrub all of them. `compaction` items are deliberately
+ * left untouched: their `encrypted_content` is a protocol-REQUIRED field whose
+ * removal would fail the SDK's run-state schema validation on deserialize.
+ */
+export declare function stripReasoningIdentityFromSerializedRunState(serialized: string): string;
+/**
+ * Neutralize tool_search items IN PLACE in a serialized RunState blob for a
+ * cross-account codex resume — the run-state sibling of
+ * `applyCodexHistoryStrip`'s tool_search rule, but COUNT-PRESERVING (HOLE E: the
+ * blob path's reconcile watermark counts the blob's history length, so items
+ * must never be removed — only mutated, exactly like the reasoning
+ * neutralization above).
+ *
+ * The hazard: on deserialize, the SDK re-runs the registered CLIENT tool_search
+ * execute callback per frozen pair (`rehydrateToolSearchRuntimeTools`) and
+ * THROWS a UserError when the re-run's runtime-tool keys mismatch the serialized
+ * expectation — which is exactly what happens when the RESUMING account's
+ * connector pool differs from the FREEZING account's. The SDK skips that
+ * rehydration entirely for `execution === 'server'` calls, so flipping the
+ * frozen pairs' `execution` to `"server"` in place defuses the throw without
+ * touching counts, ids, pairing, or content. The flipped shape is wire-safe:
+ * LIVE-VERIFIED against /codex/responses — a replayed server-execution pair is
+ * accepted (200) and its disclosure still holds. The account-bound `tsc_…` id is
+ * separately stripped by the codex transport normalizer (all input item ids).
+ *
+ * Walks the same blob locations as {@link stripReasoningIdentityFromSerializedRunState}:
+ * `originalInput` (array form), `generatedItems` (SDK run-item wrappers — the
+ * raw shape under `rawItem`), every `modelResponses[].output`, and
+ * `lastModelResponse.output`. Returns the input string unchanged when nothing
+ * matched.
+ */
+export declare function neutralizeToolSearchItemsInSerializedRunState(serialized: string): string;
+/**
+ * Normalize `computer_call` items so each carries EXACTLY ONE of the two
+ * mutually-exclusive action fields the provider accepts.
+ *
+ * The OpenAI Agents SDK 0.11.6 `computer_call` schema (protocol.mjs) carries
+ * BOTH the legacy singular `action` and the GA batched `actions`, each
+ * `.optional()`, and only requires "at least one" (its superRefine errors only
+ * when both are absent). The Azure computer-use endpoint is stricter: it
+ * requires EXACTLY one and rejects the whole request with
+ *
+ *   `400 Computer call input must include exactly one of `action` or `actions`.`
+ *
+ * when an emitted `computer_call` carries both (observed live: a screenshot
+ * call carrying `action:{type:"screenshot"}` AND `actions:[{type:"screenshot"}]`).
+ *
+ * Which singular do we keep? LIVE-PROVEN against the deployed Azure deployment
+ * (gpt-5.6-sol-2026-04-24): for gpt-5.6-sol the SDK serializes the GA computer tool as
+ * `{type:"computer"}` (not the legacy `computer_use_preview`), and that GA tool
+ * accepts ONLY the batched plural `actions`. Probing all three shapes:
+ *   - `action`-only  -> 400 "exactly one of action or actions" (STILL rejected)
+ *   - `actions`-only -> passes the action/actions structural validation
+ *   - both           -> 400 "exactly one …"
+ * The "exactly one" wording is misleading: only the `actions`-only form is
+ * accepted by the GA tool. So when both are present we KEEP `actions` (the GA
+ * batched plural) and DROP `action`. Calls that already carry exactly one field
+ * — or the legacy `action`-only form — pass through untouched (this transform's
+ * sole job is to resolve the both-present conflict, not to rewrite singulars).
+ *
+ * Pure and non-mutating: only the conflicting item(s) are cloned; every other
+ * item passes through by reference (byte-identical). Unlike
+ * {@link sanitizeHistoryItemsForModel} (which only *filters* items), this is a
+ * read-path *transform* of a single item's shape.
+ */
+export declare function normalizeComputerCallActions<T extends HistoryItem>(items: readonly T[]): T[];
+/**
+ * Rewrite EVERY `computer_call` item in a serialized Responses request body to
+ * the ACTIONS-ONLY shape the GA Azure computer tool accepts, mutating the parsed
+ * JSON object in place and returning whether anything changed.
+ *
+ * WHY THIS LIVES AT THE WIRE LEVEL (not the input-item filter). The input-item
+ * normalizer above ({@link normalizeComputerCallActions}, wired as a
+ * callModelInputFilter) runs BEFORE the SDK's responses converter
+ * (`convertAgentItemToResponsesInput`). That converter then re-derives the wire
+ * payload from the item: when `actions` is present it emits BOTH
+ * `{action: ..., actions: [...]}`, and when only `action` is present it emits
+ * `action`-only. It can NEVER emit actions-only. Probed live against the
+ * deployed Azure gpt-5.6-sol-2026-04-24 GA computer tool (`{type:"computer"}`):
+ *   - `action`-only  -> 400 "Computer call input must include exactly one of
+ *                       `action` or `actions`." (rejected)
+ *   - both           -> 400 same message (rejected)
+ *   - `actions`-only -> passes the action/actions structural validation
+ * So neither the input-filter nor the converter can produce an accepted body.
+ * The ONLY seam that sees — and can rewrite — the final serialized JSON is a
+ * custom `fetch` on the OpenAI client (it runs after the converter and after
+ * `responses.create` serialization). This function is that rewriter's core.
+ *
+ * It collapses each computer_call to actions-only: it prefers an existing
+ * non-empty `actions` array, else wraps the singular `action` into
+ * `actions:[action]`, then deletes `action`. A computer_call with neither field
+ * is left untouched (nothing to derive; let the provider report it).
+ *
+ * Mutates `body` in place (the caller has already JSON.parsed a private copy of
+ * the request body). Returns `true` iff at least one computer_call was changed.
+ */
+export declare function rewriteComputerCallsToActionsOnly(body: unknown): boolean;
+/**
+ * Backstop for the empty `computer_call_output` image_url: walk the `input` array of
+ * a serialized Responses request body and replace any `computer_call_output` item
+ * whose `output.image_url` is empty/missing with a LEGIBLE "screen capture failed"
+ * error card ({@link SCREENSHOT_FAILURE_CARD_IMAGE_URL}).
+ *
+ * WHY A CARD, NOT A BLANK. An empty `image_url` reaches this seam ONLY when the
+ * computer op genuinely FAILED to produce a screen: agents-core's `toolExecution.mjs`
+ * catch sets `output = ''` when the action OR the follow-up `computer.screenshot()`
+ * throws, building `{type:"computer_call_output",output:{type:"computer_screenshot",
+ * image_url:""}}`. Azure then rejects the whole request with
+ * `400 Invalid 'input[N].output.image_url'`. The previous fix substituted a 1×1
+ * TRANSPARENT placeholder to dodge the 400 — but that reaches the model as a
+ * plausible BLANK DESKTOP it confidently reports ("the screen appears blank/empty"),
+ * turning a hard capture FAILURE into a silent, wrong observation. That is the worst
+ * failure mode for computer use, and it is exactly what the 0.1.3 TCC-denied incident
+ * produced. Substituting a legible error card instead makes the failure REACH THE
+ * MODEL as an error (the only channel the hosted `computer_use_preview` protocol has
+ * is the image), so the model stops and tells the user rather than hallucinating.
+ *
+ * WHY THIS IS SAFE (empty = failure, never an intentional blank). Post-af289e3 the
+ * intentional-blank cases carry a NON-empty data URI already: agents-core's
+ * tool-approval-rejection screenshot is its own non-empty 1×1 placeholder, and the
+ * SandboxComputer action-timeout now warn+returns to a REAL screenshot rather than an
+ * empty output. So an EMPTY image_url at this seam is unambiguously a capture/interact
+ * FAILURE — the error card is the correct substitution for every empty case, and this
+ * function never touches a non-empty (real screenshot OR intentional blank) output.
+ *
+ * The failure REASON (permission denied / null image / timeout / display down) is not
+ * on the card; it is logged worker-side by `NativeDesktopComputer.screenshot()`.
+ *
+ * Mutates `body` in place (the caller has already JSON.parsed a private copy).
+ * Returns `true` iff at least one image_url was replaced.
+ */
+export declare function rewriteEmptyComputerCallOutputImageUrls(body: unknown): boolean;
+/**
+ * Wrap a `fetch` so every outbound OpenAI Responses request body that contains a
+ * `computer_call` is rewritten to the ACTIONS-ONLY shape (see
+ * {@link rewriteComputerCallsToActionsOnly}) before it reaches the network, AND
+ * any `computer_call_output` item with an empty/missing `output.image_url` is
+ * patched with the 1×1 transparent PNG placeholder (see
+ * {@link rewriteEmptyComputerCallOutputImageUrls}).
+ *
+ * Installed as the `fetch:` option on the Azure OpenAI client, this is the
+ * lowest reachable seam — below the agents-core input filter and below the SDK's
+ * responses converter — so it neutralizes the converter's both-fields synthesis
+ * regardless of what the input item carried, and backstops the action-timeout
+ * empty image_url regardless of how it was produced.
+ *
+ * Surgical and cheap: it only parses the body when it is a string that contains
+ * the prefix `"computer_call` (matching both `"computer_call"` action items and
+ * `"computer_call_output"` result items). Every other request — non-computer-use
+ * turns, streaming SSE responses, non-string bodies — forwards untouched, the
+ * SAME `init` reference, so streaming and other providers are unaffected. A JSON
+ * parse failure or a no-op rewrite also forwards the original `init` unchanged.
+ *
+ * Typed structurally (the `(input, init) => Promise<Response>` call signature)
+ * rather than as the DOM `typeof fetch` so it omits the `preconnect` static the
+ * global type carries; this matches the OpenAI SDK's `Fetch` option, which only
+ * needs the call signature. The wiring site passes it as the client `fetch:`.
+ */
+type FetchLike = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => Promise<Response>;
+export declare function computerCallNormalizingFetch(base: FetchLike): FetchLike;
+export {};