@opengeni/runtime 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,912 @@
+import * as _openai_agents from '@openai/agents';
+import { Tool, Computer, AgentInputItem, Model, MCPServer, ModelProvider, Agent, RunState, CallModelInputFilter, RunStreamEvent } from '@openai/agents';
+export { MaxTurnsExceededError, OpenAIChatCompletionsModel, OpenAIResponsesModel } from '@openai/agents';
+import { ContextCompactionMode, Settings, ResolvedModelProvider, ConfiguredModel, ModelProviderApi } from '@opengeni/config';
+export { collectSandboxEnvironment, parseExposedPorts } from '@opengeni/config';
+import { ReasoningEffort, SessionEventType, ResourceRef, ToolRef, Permission } from '@opengeni/contracts';
+export { CAPABILITY_DESCRIPTORS, CapabilityDescriptor, DESKTOP_STREAM_PORT, StreamTokenPayload, StreamTokenPayload as StreamTokenPayloadType, TERMINAL_STREAM_PORT } from '@opengeni/contracts';
+import { Capability, SandboxSessionLike, SandboxSessionState, Manifest, Capabilities, LocalDirLazySkillSource, SandboxClient } from '@openai/agents/sandbox';
+import OpenAI from 'openai';
+export { ActiveBackendResolverDeps, ActiveBackendUnresolvableError, ActivePointer, ChannelAConflictError, ChannelAEmitter, ChannelAExecArgs, ChannelAExecResult, ChannelANotFoundError, ChannelASession, ChannelAUnsupportedError, ChannelAValidationError, ControlRpc, DEFAULT_DESKTOP_GEOMETRY, DISPLAY_STACK_TIMEOUT_MS, DesktopGeometry, DisplayStackError, DisplayStackUnsupportedError, EnsureDisplayStackOptions, EnsureDisplayStackResult, EnsureTerminalServerOptions, EnsureTerminalServerResult, EstablishedSandboxSession, ExposeStreamPortInput, ExposeStreamPortResult, ExposedPortEndpoint, FinalizeRecordingResult, MintStreamTokenInput, MockAgentResponder, MockAgentResponderOptions, MockExecHandler, NatsControlRpc, NatsRequestConnection, NegotiationContext, NumstatEntry, PROVIDER_REGISTRY, ProviderConstructionContext, ProviderRegistration, RecordingCodec, RecordingContentType, RecordingError, RecordingProcess, RecordingUnavailableError, ResolvedActiveBackend, RoutableBackendSession, RoutableSandbox, RoutingSandboxSession, RoutingSandboxSessionDeps, RoutingTransitionEvent, RoutingUnsupportedError, SELFHOSTED_DEFAULT_TIMEOUT_MS, SELFHOSTED_RECONNECT_WINDOW_MS, SELFHOSTED_RELAY_STREAM_PATH, STREAM_PORT, STREAM_TOKEN_DEFAULT_TTL_SECONDS, SandboxChannelAService, SandboxChannelAServiceOptions, SandboxConfigError, SandboxProviderUnavailableError, SelfhostedApplyDiff, SelfhostedControlError, SelfhostedEditor, SelfhostedEnrollment, SelfhostedExecArgs, SelfhostedExecResult, SelfhostedImageOutput, SelfhostedLivenessState, SelfhostedNegotiationInput, SelfhostedRelayConfig, SelfhostedSandboxClient, SelfhostedSession, SelfhostedSessionBuild, SelfhostedSessionDeps, SelfhostedSessionState, SelfhostedUnavailableReason, StartRecordingInput, StreamPortUnavailableError, TERMINAL_SERVER_TIMEOUT_MS, TerminalServerError, TerminalServerUnsupportedError, agentErrorToControlError, assertDescriptorRegistryInvariants, assertProviderRegistryInvariants, assertSafeRelPath, backendSupportsOs, buildDisplayStackScript, buildSelfhostedBackendSession, buildStreamUrl, buildTerminalServerScript, contentTypeForCodec, createSandboxClient, createSandboxClientForBackend, decodeModalSnapshotId, deletePriorPersistedSnapshot, deleteRecordingArtifacts, deserializeSandboxSessionStateEnvelope, desktopCapableBackend, ensureDisplayStack, ensureTerminalServer, establishSandboxSessionFromEnvelope, exposeStreamPort, extForCodec, isExecSessionLostBanner, isProviderSandboxNotFoundError, isSelfhostedProviderNotFoundError, isWorkspaceEscapeError, makeActiveBackendResolver, mintStreamToken, negotiateCapabilities, negotiateSelfhostedCapabilities, offlineAgentError, offlineControlResponse, parseExecBannerSessionId, parseNumstatZ, parsePorcelainV2, parseUnifiedPatch, readRecordingBytes, readWorkspaceArchiveFromEnvelopeSessionState, recordingStorageKey, restoredSandboxSessionStateFromEntry, sandboxStateEntryFromRunState, selectBackend, selfhostedLiveness, serializeEstablishedSandboxEnvelope, setSelfhostedApplyDiff, startRecording, stopRecording, stripExecBanner, subjectFor, tearDownDisplayStack, tearDownTerminalServer, timeoutAgentError, timeoutControlResponse, verifyStreamToken } from './sandbox/index.js';
+import '@opengeni/agent-proto';
+
+type ComputerButton = "left" | "right" | "wheel" | "back" | "forward";
+type SandboxComputerOptions = {
+    display?: string;
+    dimensions?: [number, number];
+    runAs?: string;
+    typeDelayMs?: number;
+    readOnly?: boolean;
+    screenshotTmpDir?: string;
+};
+/** No exec/execCommand on the session, or the display is not up. */
+declare class ComputerUnavailableError extends Error {
+    constructor(message: string);
+}
+/** A write action attempted while readOnly. */
+declare class ComputerReadOnlyError extends Error {
+    constructor();
+}
+/** A nonzero xdotool/scrot exit, OR a command that did not finish before the
+ *  yield window (F3 — "still running" is a failure, not a silent success). */
+declare class ComputerActionError extends Error {
+    cmd: string;
+    exitCode: number;
+    stderr: string;
+    constructor(cmd: string, exitCode: number, stderr: string);
+}
+/**
+ * The Computer the agent drives. Every action issues ONE shell line through the
+ * externally-owned session (exec ?? execCommand, F1), prefixed with the display.
+ * screenshot() scrots to a /tmp file and reads the RAW bytes by running
+ * `base64 <path>` over the SAME command primitive and stripping the banner — NOT
+ * `session.readFile` (Modal's readFile path-validates against /workspace and rejects
+ * /tmp with "escapes the workspace root", which would yield an empty frame and 400
+ * the model). The base64-over-exec path is /tmp-readable and binary-safe.
+ */
+declare class SandboxComputer implements Computer {
+    readonly environment: "ubuntu";
+    readonly dimensions: [number, number];
+    private session;
+    private readonly display;
+    private readonly runAs?;
+    private readonly typeDelayMs;
+    private readonly readOnly;
+    private readonly tmp;
+    constructor(session: SandboxSessionLike, opts?: SandboxComputerOptions);
+    /** Rebind to a freshly resumed-by-id session after a box rollover / re-establish. */
+    rebind(session: SandboxSessionLike): void;
+    private x;
+    private guardWrite;
+    private shq;
+    screenshot(): Promise<string>;
+    private readScreenshotBytes;
+    click(xp: number, yp: number, button: ComputerButton): Promise<void>;
+    doubleClick(xp: number, yp: number): Promise<void>;
+    move(xp: number, yp: number): Promise<void>;
+    scroll(xp: number, yp: number, sx: number, sy: number): Promise<void>;
+    type(text: string): Promise<void>;
+    keypress(keys: string[]): Promise<void>;
+    drag(path: [number, number][]): Promise<void>;
+    wait(): Promise<void>;
+}
+type ComputerUseArgs = {
+    dimensions?: [number, number];
+    readOnly?: boolean;
+    display?: string;
+    needsApproval?: boolean | ((ctx: unknown, action: unknown) => boolean | Promise<boolean>);
+    imageFunctionResults?: boolean;
+};
+declare function computerUse(args?: ComputerUseArgs): ComputerUseCapability;
+/**
+ * A `Capability` subclass merged into the agent's tool set by SandboxAgent
+ * (`tools = [...agent.tools, ...capability.tools()]`). `bind(session)` hands it
+ * the LIVE externally-owned session, so the agent's actions and the viewers'
+ * pixels are one display.
+ *
+ * `tools()` is TRANSPORT-AWARE, mirroring the SDK's `filesystem()` capability
+ * (which branches its `view_image` / `apply_patch` on
+ * `supportsStructuredToolOutputTransport(this._modelInstance)`):
+ *   • structured transport (the Responses/OpenAI backend) → the single HOSTED
+ *     `computer_use_preview` tool over a Computer bound to the session (unchanged).
+ *   • text transport (codex / ChatGPT backend — or an unbound model) → a set of
+ *     FUNCTION tools ({@link computerFunctionTools}) that route to the SAME Computer,
+ *     because the codex backend rejects the hosted computer tool type.
+ * The bound model instance is captured by the SDK's `bind().bindRunAs().bindModel()`
+ * chain (base `Capability._modelInstance`); the codex path in index.ts neutralizes
+ * `bindModel` so `_modelInstance` stays undefined here → the function tools win.
+ */
+declare class ComputerUseCapability extends Capability {
+    private args;
+    readonly type = "computer-use";
+    constructor(args?: ComputerUseArgs);
+    tools(): Tool<unknown>[];
+}
+
+/**
+ * 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. */
+type HistoryItem = Record<string, unknown>;
+/**
+ * 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.
+ */
+declare function sanitizeHistoryItemsForModel<T extends HistoryItem>(items: readonly 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.
+ */
+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 — the run-state REPLAY paths). The approval-decision resume and the
+ * items-mode run-state fallback replay the serialized RunState blob verbatim. 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.
+ */
+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.
+ */
+declare function neutralizeToolSearchItemsInSerializedRunState(serialized: string): string;
+
+/**
+ * Client-side conversation context compaction (the Azure path).
+ *
+ * OpenGeni runs long-lived agent sessions whose conversation truth
+ * (`session_history_items`) grows unbounded. On the OpenAI platform the
+ * Responses API compacts server-side (the SDK's `compaction()` capability). On
+ * Azure that capability 400s (`unsupported_parameter`), so the session
+ * eventually overflows the model context window and hard-fails every turn.
+ *
+ * This module is the Azure-safe replacement. It is built from two pure pieces
+ * plus one impure step the caller wires in:
+ *
+ *  1. `planCompaction` — given the active history items, the last turn's actual
+ *     input-token count, and the token budget, decide WHETHER to compact and,
+ *     if so, WHERE the orphan-safe cut boundary is (the prefix to summarize vs
+ *     the recent tail to keep verbatim). Pure, exhaustively testable.
+ *  2. (caller) summarize the prefix into ONE plain user `message` item via a
+ *     model call — see `buildCompactionMessages` / `SUMMARY_PREFIX`.
+ *  3. `applyCompaction` shape — the storage write the caller performs:
+ *     supersede the prefix rows, insert the summary at the boundary position.
+ *
+ * Design constraints (non-negotiable):
+ *  - The summary is a PLAIN user message, NOT the SDK `compaction` item type
+ *    (that requires server-minted `encrypted_content`; a hand-rolled one risks
+ *    an Azure 400).
+ *  - ORPHAN SAFETY: the cut lands only at a clean turn boundary (start of a
+ *    user message). No tool call_id may straddle the cut — for every
+ *    `function_call` dropped, its `function_call_result` is also dropped, and
+ *    vice versa. Reasoning items drop/keep with their whole turn.
+ *  - SINGLE LIVE SUMMARY: each compaction folds the prior summary forward
+ *    (summarize [prior summary] + [items since]); prior summaries are excluded
+ *    from re-collection so drift stays bounded.
+ */
+type CompactionItem = Record<string, unknown>;
+/**
+ * Marker stored on the synthetic summary item so it can be recognized on the
+ * next compaction (to fold it forward) and excluded from re-summarization. It
+ * lives in the item JSON, not a DB column, so it survives verbatim replay.
+ */
+declare const COMPACTION_SUMMARY_MARKER = "opengeni_context_summary";
+/**
+ * Bridge text prepended to the summary body in the synthetic user message. It
+ * tells the model the preceding conversation was compacted and that durable
+ * facts live in the notebook — so it treats the summary as a working-memory
+ * pointer, not the whole truth.
+ */
+declare const SUMMARY_PREFIX: string;
+/** A user-authored `message` item is the only legal turn boundary. */
+declare function isUserMessage(item: unknown): boolean;
+/** True for our synthetic compaction summary item. */
+declare function isCompactionSummary(item: unknown): boolean;
+/**
+ * Rough token estimate for an item: char/4 over its serialized text. Used only
+ * for the tail-budget walk; the trigger decision uses the real last-turn input
+ * token count, falling back to this when that is unavailable.
+ */
+declare function estimateItemTokens(item: CompactionItem): number;
+declare function estimateTokens(items: readonly CompactionItem[]): number;
+/**
+ * Walk backwards from the end of `items` keeping whole turns until the kept
+ * tail would exceed `keepRecentTokens`, and return the index of the first kept
+ * item. The returned index is always the start of a user message (a clean turn
+ * boundary), so the prefix [0, index) never splits a tool-call pair.
+ *
+ * Returns `items.length` when nothing fits within the budget yet a boundary is
+ * required (degenerate); callers treat an index of 0 or length as "no useful
+ * cut".
+ */
+declare function findKeepBoundary(items: readonly CompactionItem[], keepRecentTokens: number): number;
+/**
+ * READ-PATH BUDGET GUARD (last-resort backstop).
+ *
+ * Pre-turn compaction is best-effort: it can no-op (summarizer model call
+ * fails, "client" mode off, a fresh user message arrives after a turn already
+ * ballooned the history) and STILL leave an assembled input that exceeds the
+ * model context window. The #61 orphan sanitizer is purely structural — it has
+ * NO size awareness — so without this guard an over-budget input is sent and
+ * 400s every turn, re-bricking the session.
+ *
+ * `enforceInputBudget` drops the OLDEST history at a clean turn boundary until
+ * the estimated input fits `maxTokens`, ALWAYS keeping the most recent turn(s).
+ * It is orphan-safe by construction: it only ever cuts at the start of a user
+ * message (via `findKeepBoundary`), so no tool-call pair is split. It is a
+ * crude data-loss fallback (no summary is generated) that exists solely so a
+ * single over-budget assembled input is never put on the wire — real context
+ * preservation is the summarizing pre-turn path; this is the airbag.
+ *
+ * Pure: returns a new array (same item references, in order) with an oldest
+ * prefix omitted, or the input unchanged when it already fits. The provided
+ * `trailingTokens` accounts for the un-stored part of the assembled input (the
+ * new user/continuation message + fixed system/tool overhead) so the cap is
+ * measured against the WHOLE request, not just the stored history.
+ */
+declare function enforceInputBudget<T extends CompactionItem>(items: readonly T[], maxTokens: number, trailingTokens?: number): {
+    items: T[];
+    trimmed: boolean;
+    droppedCount: number;
+    estimatedTokens: number;
+};
+type CompactionPlan = {
+    /** Whether a compaction should run this turn. */
+    shouldCompact: boolean;
+    /** Why not, when shouldCompact is false (for logs/tests). */
+    reason: "below_threshold" | "no_boundary" | "nothing_to_summarize" | "compact";
+    /**
+     * The signal-token count the trigger decision was made on:
+     * max(actual last-turn input tokens, char/4 estimate of the active items).
+     * Recorded for logging / metrics and so a caller can reason about pressure.
+     */
+    signalTokens: number;
+    /**
+     * True when the signal reached hardFraction*B — the session is at/over the
+     * hard ceiling and compaction was forced even if the recorded last-turn count
+     * was stale-low. The boundary walk is run with a SHRUNK keep-recent budget in
+     * this case so an over-budget history always yields a non-empty prefix to
+     * summarize (the everything-is-"recent" deadlock can't strand it un-compacted).
+     */
+    hardForced: boolean;
+    /** Index (into the active items) where the kept tail begins. */
+    boundaryIndex: number;
+    /**
+     * The prefix items to summarize: active[0, boundaryIndex), EXCLUDING any
+     * prior compaction summary (which is folded forward via `priorSummaryItem`).
+     */
+    prefixItems: CompactionItem[];
+    /** The prior live summary item folded into this compaction, if any. */
+    priorSummaryItem: CompactionItem | null;
+    /** Items kept verbatim: active[boundaryIndex, end). */
+    tailItems: CompactionItem[];
+};
+type PlanCompactionInput = {
+    /** Active history items in position order (already excludes superseded rows). */
+    items: readonly CompactionItem[];
+    /**
+     * Actual input tokens reported for the last model call of the previous turn.
+     * Null/undefined falls back to a char/4 estimate over `items`.
+     */
+    lastInputTokens?: number | null;
+    /** Usable input budget B = window - reserved output. */
+    inputBudgetTokens: number;
+    softFraction: number;
+    hardFraction: number;
+    keepRecentTokens: number;
+    /**
+     * Operator-forced compaction (the /compact command): bypass the soft-limit
+     * token trigger and compact now if there is anything to summarize. The
+     * boundary / nothing-to-summarize guards still apply — force never invents a
+     * cut that would orphan a tool-call pair or summarize an empty prefix.
+     */
+    force?: boolean;
+};
+/**
+ * Decide whether and where to compact. Pure.
+ *
+ * Trigger: signal tokens >= softFraction*B (soft) or hardFraction*B (hard).
+ * Signal = MAX(actual last-turn input tokens, char/4 estimate of the active
+ * items). The max — not "trust the recorded count, estimate only when it's
+ * null" — is the self-heal fix: `sessions.last_input_tokens` is written ONLY
+ * when a model response reports usage, so a turn that OVERFLOWS on its first
+ * model call records NOTHING and the column keeps a STALE-POSITIVE value from
+ * the last good turn (e.g. ~600k). Trusting that stale-low number let an
+ * actually-over-budget history (>1.05M) slip under the soft limit and overflow
+ * again, re-bricking with no self-heal. Taking the max means a bloated history
+ * triggers compaction regardless of a stale recorded count.
+ *
+ * Hard force (hardFraction*B): at/over the hard ceiling we compact even if the
+ * recorded count was stale-low, AND we run the boundary walk with a shrunk
+ * keep-recent budget so an over-budget history always yields a non-empty prefix
+ * — otherwise a history where the whole thing reads as "recent" (tail within
+ * keepRecentTokens) would find no prefix and strand the session over budget.
+ *
+ * Boundary: the earliest user-message boundary whose kept tail fits the
+ * (possibly shrunk) keep-recent budget. The prefix before it (minus any prior
+ * summary, which is folded forward) is what gets summarized.
+ */
+declare function planCompaction(input: PlanCompactionInput): CompactionPlan;
+/** Extract the plain-text body of the prior summary item, if any. */
+declare function compactionSummaryText(item: CompactionItem | null): string;
+/**
+ * Build the synthetic summary item (a plain user message) to insert at the
+ * boundary. `summaryBody` is the model-generated working-memory bridge.
+ */
+declare function buildSummaryItem(summaryBody: string): CompactionItem;
+/**
+ * Instruction prompt for the summarizer model call. Leans on OpenGeni's durable
+ * structured memory (the notebook) so the summary stays a light working-memory
+ * bridge, never a place secret values get copied.
+ */
+declare const SUMMARY_INSTRUCTIONS: string;
+/**
+ * Render the prefix items into a transcript the summarizer reads. Keeps it
+ * bounded by truncating individual items; the model call itself is what
+ * produces the compact result.
+ */
+declare function renderPrefixTranscript(items: readonly CompactionItem[], priorSummaryText: string): string;
+/**
+ * The summarizer model call payload: a system instruction plus the rendered
+ * prefix transcript. The caller turns this into a single model request (no
+ * tools, no streaming) and feeds the text result into `buildSummaryItem`.
+ */
+declare function buildCompactionMessages(plan: CompactionPlan): {
+    system: string;
+    user: string;
+};
+
+type NormalizedRuntimeEvent = {
+    type: SessionEventType;
+    payload: unknown;
+};
+type ModelResponseUsage = {
+    responseId?: string;
+    usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        inputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
+    };
+};
+declare function ensureReadableStreamFrom(): void;
+type AgentSegmentInput = {
+    kind: "message";
+    text: string;
+    serializedRunState?: string | null;
+    historyItems?: AgentInputItem[] | null;
+    sandboxEnvelope?: Record<string, unknown> | null;
+} | {
+    kind: "approval";
+    serializedRunState: string;
+    approvalId: string;
+    decision: "approve" | "reject";
+    message?: string;
+};
+type PreparedAgentInput = {
+    input: string | AgentInputItem[] | RunState<any, any>;
+    sandboxSessionState?: SandboxSessionState;
+    serializedRunStateForSandbox?: string;
+};
+type SandboxFileDownload = {
+    fileId: string;
+    mountPath: string;
+    filename: string;
+    url?: string;
+    content?: Uint8Array;
+    expiresAt?: Date | string;
+    sizeBytes?: number;
+};
+type OpenGeniRuntime = {
+    configure: (settings: Settings) => void;
+    resolveTurnModel: (settings: Settings, modelId: string) => ReturnType<typeof resolveTurnModel>;
+    buildAgent: (settings: Settings, resources: ResourceRef[], options?: BuildAgentOptions) => Agent<any, any>;
+    prepareTools: (settings: Settings, tools: ToolRef[], options?: PrepareToolsOptions) => Promise<PreparedAgentTools>;
+    prepareInput: (agent: Agent<any, any>, input: AgentSegmentInput, options?: PrepareInputOptions) => Promise<PreparedAgentInput>;
+    runStream: (agent: Agent<any, any>, input: PreparedAgentInput, settings: Settings, options?: RunAgentStreamOptions) => Promise<Awaited<ReturnType<typeof runAgentStream>>>;
+    serializeApprovals: (interruptions: unknown[]) => unknown[];
+};
+type ProductionRuntimeOverrides = {
+    model?: Model;
+    sandboxClient?: unknown;
+};
+declare function createProductionAgentRuntime(overrides?: ProductionRuntimeOverrides): OpenGeniRuntime;
+/**
+ * Build an OpenAI client from settings for the configured provider. Mirrors the
+ * client construction in configureOpenAI so a direct API call (the compaction
+ * summarizer) uses the same Azure/OpenAI auth and base URL. Returns null when
+ * the OpenAI-platform path has only a key (the SDK default client is used via
+ * setDefaultOpenAIKey there); the caller then constructs a key-only client.
+ */
+declare function buildOpenAIClientFromSettings(settings: Settings): OpenAI;
+declare function buildProviderClient(provider: ResolvedModelProvider, settings: Settings): OpenAI;
+/**
+ * Bind a model id to a provider's OpenAI client as an @openai/agents `Model`
+ * instance, choosing the wire API by the provider's declared `api`: the "chat"
+ * providers (e.g. Fireworks) get an OpenAIChatCompletionsModel that speaks
+ * /v1/chat/completions, the "responses" providers (built-in OpenAI/Azure) get
+ * an OpenAIResponsesModel that speaks /v1/responses. Passing this Model into
+ * the agent is what routes a turn to its provider without mutating the global
+ * default client.
+ */
+declare function buildModelInstance(provider: ResolvedModelProvider, client: OpenAI, modelId: string): Model;
+/**
+ * Resolved per-turn model routing: the provider that serves `modelId`, its
+ * (cached) OpenAI client, the provider-bound `Model` instance, and the
+ * configured-model shape (label/api/contextWindow/reasoningEffort/hostedWebSearch).
+ * Returns null when the model is not in the registry — the caller then falls
+ * back to the legacy global-client path (settings.openaiModel + the default
+ * client configured by configureOpenAI), preserved byte-for-byte.
+ */
+declare function resolveTurnModel(settings: Settings, modelId: string): {
+    provider: ResolvedModelProvider;
+    client: OpenAI;
+    model: Model;
+    configured: ConfiguredModel;
+} | null;
+/**
+ * Routes a model *name* to its provider-bound Model (Fireworks chat model for a
+ * registry model id, the built-in OpenAI/Azure responses model otherwise) via
+ * `resolveTurnModel`. This is the load-bearing piece for the sandbox path:
+ * passing a Model *instance* as `agent.model` only survives the in-process
+ * (`sandboxBackend: "none"`) run — on the SandboxAgent/Modal path the instance
+ * is dropped and the model *name* is re-resolved through the run's
+ * `modelProvider` (or the global default). Without this router that re-resolution
+ * hits the default client (e.g. Azure) and a registry model 404s
+ * ("deployment does not exist"); with it the name resolves back to the right
+ * provider. Installed both as the run-scoped `Runner.config.modelProvider` (every
+ * run in runAgentStream goes through `runScopedRunner(settings)`, built from the
+ * per-turn settings) and as the process default (see configureOpenAI). The
+ * run-scoped instance is the load-bearing one: a `Runner` resolves string model
+ * names against ITS OWN modelProvider, not the lazy global default, so each
+ * concurrent turn routes codex/registry names against its own settings and a
+ * foreign turn's setDefaultModelProvider can never clobber this turn's routing.
+ * The process default remains only as a boot-time fallback. Falls back to the
+ * SDK default provider for a model that is in no provider's allow-list.
+ */
+declare class MultiProviderModelProvider implements ModelProvider {
+    private readonly settings;
+    private fallback;
+    constructor(settings: Settings);
+    getModel(modelName?: string): Promise<Model>;
+}
+/**
+ * A `codex/<slug>` turn reached the model router but the workspace has no active
+ * Codex subscription connected (the worker overlay never injected the synthetic
+ * provider, so resolveTurnModel returned nothing). Thrown instead of silently
+ * routing the id to the built-in Azure/OpenAI client — that produced an opaque
+ * "DeploymentNotFound" 404. The message is user-actionable (connect/reconnect)
+ * and carries no status/code, so agentRunFailurePayload surfaces it verbatim as
+ * a non-retryable turn.failed the session UI shows.
+ */
+declare class CodexSubscriptionUnavailableError extends Error {
+    constructor(modelName: string);
+}
+declare function configureOpenAI(settings: Settings): void;
+/**
+ * Run the compaction summarizer as one plain, tool-less, non-streaming model
+ * call against the resolved provider. `system`/`user` come from
+ * buildCompactionMessages. Returns the trimmed summary text, or null on any
+ * failure (the caller treats a failed summarize as "skip compaction this turn"
+ * — never fatal). The call deliberately does NOT request reasoning encryption,
+ * tools, or server-side compaction; it is a self-contained summarize.
+ *
+ * Provider-aware: the summary always runs on the SAME provider that serves the
+ * turn (registry providers can't summarize through OpenAI/Azure, and vice
+ * versa). `api: "chat"` providers (Fireworks) speak /v1/chat/completions, where
+ * the summary is choices[0].message.content; `api: "responses"` (the default,
+ * built-in OpenAI/Azure) speaks /v1/responses as before. When no client/api is
+ * supplied it falls back to the built-in OpenAI/Azure Responses path so the
+ * legacy global-client callers are byte-for-byte unchanged. store:false is set
+ * only on the OpenAI-platform Responses path (Azure rejects it; chat ignores it).
+ */
+declare function summarizeForCompaction(settings: Settings, messages: {
+    system: string;
+    user: string;
+}, options?: {
+    client?: OpenAI;
+    api?: ModelProviderApi;
+    maxOutputTokens?: number;
+    model?: string;
+}): Promise<string | null>;
+/**
+ * Pull the assistant text out of a Responses API result, shape-tolerant. Only
+ * `role === "assistant"` message items contribute: a provider whose Responses
+ * endpoint echoes the user input back as an output `message` item (Fireworks'
+ * beta /v1/responses does exactly this — see docs/model-providers.md) would
+ * otherwise corrupt the summary with the prompt it was given. The OpenAI/Azure
+ * Responses API only emits assistant messages, so this guard is a no-op there.
+ */
+declare function extractResponseOutputText(response: unknown): string;
+type BuildAgentOptions = {
+    model?: Model;
+    reasoningEffort?: ReasoningEffort;
+    compactionMode?: ContextCompactionMode;
+    hostedWebSearch?: boolean;
+    encryptedReasoning?: boolean;
+    contextWindowTokens?: number;
+    structuredToolTransport?: boolean;
+    codexConnectorNamespaces?: ReadonlySet<string>;
+    sandboxEnvironment?: Record<string, string>;
+    activeSandboxBackend?: Settings["sandboxBackend"];
+    fileResourceDownloads?: SandboxFileDownload[];
+    mcpServers?: MCPServer[];
+    workspaceEnvironment?: WorkspaceEnvironmentContext;
+    gitTokenSeed?: string;
+    genesisTitleHint?: boolean;
+    instructionsTemplate?: string;
+    packSkills?: PackSkill[];
+};
+type PackSkillFile = {
+    path: string;
+    content: string;
+};
+type PackSkill = {
+    name: string;
+    description?: string | null;
+    files: PackSkillFile[];
+};
+/**
+ * Operator-facing metadata for the workspace environment attached to a run.
+ * Surfaced verbatim in the agent instructions: the description is where
+ * operators document how the exported credentials are meant to be used
+ * (e.g. which variable holds a deploy key and how to clone with it), so an
+ * agent must not have to rediscover that by enumerating `env` and guessing.
+ * Only metadata belongs here — never variable values.
+ */
+type WorkspaceEnvironmentContext = {
+    name: string;
+    description?: string | null;
+    variableNames?: string[];
+};
+declare function workspaceEnvironmentInstructions(environment: WorkspaceEnvironmentContext): string[];
+/**
+ * The non-bypassable CORE of the agent instructions: the goal-loop ownership
+ * line (which names the opengeni__goal_* tools and is what keeps a long-running
+ * session driving itself) followed by the dynamic workspace-environment block.
+ * Returned as ordered lines so the caller joins them with the rest of the
+ * instructions by " ", exactly as the historical preamble did.
+ *
+ * This is the slice a white-labelled persona template must never be able to
+ * drop: composeAgentInstructions() substitutes it at the persona template's
+ * {{core}} marker, and appends it when the marker is absent.
+ */
+declare function coreInstructions(workspaceEnvironment?: WorkspaceEnvironmentContext): string[];
+/**
+ * Composes the final agent instructions from a (possibly white-labelled)
+ * persona template and the non-bypassable CORE. The CORE is substituted at the
+ * template's {{core}} marker; if the template omits the marker, the CORE is
+ * appended after it instead (the non-bypassable fail-safe). The substitution
+ * and the append both join by " ", so the DEFAULT_AGENT_INSTRUCTIONS template
+ * with an empty environment reproduces the historical preamble byte-for-byte.
+ */
+declare function composeAgentInstructions(template: string, workspaceEnvironment?: WorkspaceEnvironmentContext): string;
+declare function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[], options?: BuildAgentOptions): Agent<any, any>;
+/**
+ * Build the SandboxAgent capability set provider-aware.
+ *
+ * The SDK's `Capabilities.default()` force-includes `compaction()`, whose
+ * sampling params emit `context_management:[{type:'compaction', …}]` to the
+ * Responses transport. The OpenAI platform honors that (server-side compaction);
+ * AZURE rejects it with `400 unsupported_parameter` — which is exactly the live
+ * production failure on Azure today. So we MUST NOT attach the compaction
+ * capability on the Azure / client / off paths.
+ *
+ * We rebuild the base set explicitly (`filesystem()`, `shell()`, the same
+ * factories the SDK default uses) and add `compaction()` ONLY on the server
+ * path, with an explicit `StaticCompactionPolicy(threshold)` so gpt-5.5 — which
+ * is absent from the SDK's hardcoded context-window map and would otherwise hit
+ * the wrong 240k fallback — gets the correct threshold. The SDK has no
+ * window-registration API, so an explicit threshold is the only way to fix it.
+ *
+ * The resolved compaction mode and the effective context window are now passed
+ * IN (the multi-provider caller resolves them per provider/model) rather than
+ * re-derived from settings here. Both default to the settings-derived value so
+ * callers that don't route per-model (and the existing tests) keep today's exact
+ * behaviour; the effective window only changes the server-path threshold when a
+ * resolved model declares its own contextWindowTokens.
+ */
+declare function buildAgentCapabilities(settings: Settings, packSkills: PackSkill[], options?: {
+    compactionMode?: ContextCompactionMode;
+    contextWindowTokens?: number;
+    structuredToolTransport?: boolean;
+}): ReturnType<typeof Capabilities.default>;
+declare function sandboxRunAs(_settings: Settings): string | undefined;
+type PreparedAgentTools = {
+    mcpServers: MCPServer[];
+    close: () => Promise<void>;
+    codexConnectorNamespaces: Set<string>;
+};
+type PrepareToolsOptions = {
+    accountId?: string;
+    workspaceId?: string;
+    sessionId?: string;
+    subjectId?: string;
+    subjectLabel?: string;
+    firstPartyPermissions?: Permission[];
+};
+declare function prepareAgentTools(settings: Settings, tools: ToolRef[], options?: PrepareToolsOptions): Promise<PreparedAgentTools>;
+declare function prefixedMcpToolName(registryId: string, toolName: string): string;
+type PrepareInputOptions = {
+    sandboxClient?: unknown;
+    /**
+     * Usable input-token budget B (window - reserved output). When set, the
+     * assembled history is passed through `enforceInputBudget` so a single
+     * over-budget input can never be sent — the last-resort backstop behind the
+     * best-effort pre-turn compaction. Omitted (undefined) disables the guard
+     * (no behaviour change for callers that don't opt in).
+     */
+    inputBudgetTokens?: number;
+};
+declare function prepareRunInput(agent: Agent<any, any>, input: AgentSegmentInput, options?: PrepareInputOptions): Promise<PreparedAgentInput>;
+type RunAgentStreamOptions = {
+    sandboxClient?: unknown;
+    sandboxEnvironment?: Record<string, string>;
+    onRuntimeEvent?: (event: NormalizedRuntimeEvent) => Promise<void> | void;
+    ownedSandbox?: {
+        client: unknown;
+        session: unknown;
+        sessionState?: unknown;
+        setupSession?: unknown;
+    };
+    callModelInputFilter?: CallModelInputFilter;
+};
+declare const GENESIS_TITLE_DIRECTIVE = "This is the first turn of a new session. Before responding to the user, call the opengeni__set_session_title tool with a concise 3-7 word title that summarizes what this session is about, then address the user's request normally.";
+/**
+ * callModelInputFilter that removes provider-assigned item ids (rs_/msg_/fc_…)
+ * from every input item immediately before each model call. Responses-API
+ * requests that carry item ids are resolved against the provider's stored
+ * responses, and that store is not durable enough to anchor long runs on: a
+ * response that streamed successfully can be missing from the store on the
+ * very next call, which then fails with 400 "Item with id ... not found"
+ * (observed live on Azure OpenAI mid-turn). All item content — including the
+ * encrypted reasoning payload carried in providerData when
+ * `openaiReasoningEncryptedContent` is on — is sent inline, so the ids add
+ * fragility without adding information. Pairing fields (`call_id`/`callId`)
+ * are separate properties and stay untouched; items are cloned, never mutated.
+ */
+declare const stripProviderItemIdsFilter: CallModelInputFilter;
+/**
+ * callModelInputFilter that normalizes every `computer_call` carrying BOTH
+ * `action` and `actions` down to EXACTLY ONE (keeps `actions`, drops `action`).
+ * The Azure computer-use endpoint rejects a request whose computer_call has
+ * both with `400 Computer call input must include exactly one of `action` or
+ * `actions``; and (live-proven against gpt-5.5's GA computer tool) it also
+ * rejects the `action`-only form, accepting ONLY the batched plural `actions`.
+ * The SDK 0.11.6 schema allows both, so a freshly-emitted
+ * screenshot call carries the redundant pair. This filter runs before EVERY
+ * model call — the turn-start history replay AND every mid-turn follow-up — so
+ * it covers the just-emitted (non-replayed) computer_call on the same turn,
+ * which the turn-start `prepareRunInput` sanitizer never sees. Items are cloned,
+ * never mutated.
+ */
+declare const normalizeComputerCallsFilter: CallModelInputFilter;
+/**
+ * The model-input filter applied before every model call. The computer_call
+ * action/actions normalizer is ALWAYS on (the Azure endpoint 400s without it);
+ * the provider-item-id strip is layered on top when the configured policy
+ * selects it.
+ */
+declare function callModelInputFilterForSettings(settings: Settings): CallModelInputFilter | undefined;
+declare function runAgentStream(agent: Agent<any, any>, input: PreparedAgentInput | string | RunState<any, any>, settings: Settings, overrides?: RunAgentStreamOptions): Promise<_openai_agents.StreamedRunResult<any, Agent<any, any>>>;
+
+/**
+ * Detects the agents SDK per-segment turn cap. The cap is a pacing valve, not
+ * a session failure: callers should end the segment gracefully (idle) so an
+ * active goal's continuation loop -- or a follow-up user message -- resumes
+ * the work. When the SDK attached the run state at the moment the cap hit,
+ * the serialized form is returned so the resumed turn keeps full context.
+ */
+declare function maxTurnsExceededRunState(error: unknown): {
+    serializedRunState: string | null;
+} | null;
+/**
+ * Serialized run state attached to any agents SDK error, when present.
+ * Provider failures usually surface as raw API errors without state; callers
+ * must treat a null here as "resume from the previous snapshot" rather than
+ * an error.
+ */
+declare function agentsErrorRunState(error: unknown): string | null;
+declare function withManifestRefreshOnResume(client: SandboxClient, targetManifest: Manifest | undefined): SandboxClient;
+declare function applyMissingManifestEntries(session: SandboxSessionLike, targetManifest: Manifest): Promise<void>;
+declare function withSandboxFileDownloads(client: SandboxClient, downloads: SandboxFileDownload[], context?: Pick<SandboxLifecycleHookContext, "onRuntimeEvent" | "runAs">): SandboxClient;
+declare function materializeSandboxFileDownloads(session: SandboxSessionLike, downloads: SandboxFileDownload[], context?: Pick<SandboxLifecycleHookContext, "onRuntimeEvent" | "runAs">): Promise<void>;
+declare function sandboxFileDownloadsForAgent(agent: unknown): SandboxFileDownload[];
+/**
+ * Compact a tool-call output for the `agent.toolCall.output` SESSION EVENT so it
+ * never carries a raw binary payload. The codex-path `computer_screenshot` function
+ * tool returns a structured `{type:'image', image:{data: Uint8Array, mediaType}}`;
+ * captured verbatim its `Uint8Array` JSON-serializes as an object-of-numbers (~12.7MB
+ * per screenshot in session_events — ~10x the base64 form). This mirrors the desktop
+ * screenshot to the SAME compact `data:<mediaType>;base64,…` STRING the HOSTED
+ * `computer_call` event already carries (agents-core sets its output to that data-URL),
+ * so both computer-use transports emit one representation. The full data-URL is kept
+ * (not truncated) because the web timeline RENDERS the screenshot from this event
+ * payload — packages/react/src/timeline/tool-renderers.tsx ComputerCallRenderer
+ * (`out.startsWith("data:image")` → <ScreenshotFigure src={out}/>) and ViewImageRenderer.
+ * Non-image outputs (text strings, MCP `{isError,content}` objects, hosted computer_call
+ * data-URL strings) pass through unchanged.
+ */
+declare function normalizeToolOutputForEvent(output: unknown): unknown;
+declare function normalizeSdkEvent(event: RunStreamEvent): NormalizedRuntimeEvent[];
+declare function modelResponseUsageFromSdkEvent(event: RunStreamEvent): ModelResponseUsage | null;
+declare function serializeApprovals(interruptions: unknown[]): unknown[];
+declare function buildManifest(settings: Settings, resources: ResourceRef[], environment?: Record<string, string>, fileResourceDownloads?: SandboxFileDownload[]): Manifest;
+type SandboxLifecycleHookPhase = "beforeAgentStart";
+type SandboxLifecycleHookContext = {
+    environment: Record<string, string>;
+    onRuntimeEvent?: (event: NormalizedRuntimeEvent) => Promise<void> | void;
+    runAs?: string;
+    gitTokenSeed?: string;
+};
+type SandboxLifecycleHook = {
+    id: string;
+    phase: SandboxLifecycleHookPhase;
+    shouldRun?: (context: SandboxLifecycleHookContext) => boolean;
+    run: (session: SandboxSessionLike, context: SandboxLifecycleHookContext) => Promise<void>;
+};
+declare function sandboxLifecycleHooksForIds(ids: string[]): SandboxLifecycleHook[];
+/**
+ * Run the beforeAgentStart lifecycle hooks directly against an already-live box.
+ *
+ * The create/resume decoration (withSandboxLifecycleHooks) is structurally blind to
+ * the PROVIDED-session path: when runStream hands the SDK a live `session`
+ * (runOptions.sandbox.session — the lease-owned box resolved by the turn activity),
+ * SandboxRuntimeManager uses it as-is and never calls client.create/resume, so a
+ * wrapper around those methods never fires. Callers on that path invoke this
+ * before starting the run so the box still gets its beforeAgentStart preparation
+ * (repository clone + B1 askpass/token-file seed, azure-cli-login).
+ */
+declare function runBeforeAgentStartHooks(session: SandboxSessionLike, hooks: SandboxLifecycleHook[], context: SandboxLifecycleHookContext): Promise<void>;
+declare function withSandboxLifecycleHooks(client: SandboxClient, hooks: SandboxLifecycleHook[], context: SandboxLifecycleHookContext): SandboxClient;
+/**
+ * Whether the platform should seed a repository resource by `git clone` inside
+ * the sandbox before the agent starts.
+ *
+ * SAFETY GATE (selfhosted/bring-your-own machine): the clone hook writes into
+ * `posixPath.join("/workspace", mountPath)`, which a selfhosted agent rewrites
+ * to a path under its REAL launch directory — so a platform-initiated clone
+ * lands on the user's actual disk. A connected machine already owns its
+ * filesystem; the platform must NEVER clone onto it. We therefore key the
+ * decision off the EFFECTIVE/active backend, not just the session's HOME backend
+ * (`settings.sandboxBackend`): a session can run on the cloud default while its
+ * active sandbox has been swapped to a connected machine (active_sandbox_id → a
+ * selfhosted lease), in which case the agent actually executes on the user's
+ * machine even though the home backend is e.g. "modal". `activeSandboxBackend`
+ * defaults to the home backend, so a session whose HOME backend is "selfhosted"
+ * is gated with no caller change, and every cloud path is byte-for-byte
+ * unchanged.
+ */
+declare function repositoryUsesSandboxClone(settings: Settings, resource: Extract<ResourceRef, {
+    kind: "repository";
+}>, activeSandboxBackend?: Settings["sandboxBackend"]): boolean;
+declare function repositoryCloneCommand(resources: Extract<ResourceRef, {
+    kind: "repository";
+}>[]): string;
+declare function runRepositoryCloneHook(session: SandboxSessionLike, resources: Extract<ResourceRef, {
+    kind: "repository";
+}>[], context?: SandboxLifecycleHookContext): Promise<void>;
+declare function azureCliLoginCommand(): string;
+declare function sandboxCommandExitCode(result: unknown): number | null;
+declare function sandboxCommandOutput(result: unknown): string;
+declare function sandboxCommandStillRunning(result: unknown): boolean;
+declare function runAzureCliLoginHook(session: SandboxSessionLike, context?: SandboxLifecycleHookContext): Promise<void>;
+declare function azureOpenAIDefaultQuery(settings: Pick<Settings, "azureOpenaiApiVersion">, baseURL: string): Record<string, string> | undefined;
+/**
+ * The skill source fed to the SDK Skills capability. Without pack skills this
+ * is the plain bundled local-dir source, byte-for-byte the pre-pack behavior.
+ * With pack skills it becomes a single in-memory dir source combining bundled
+ * skill directories (as local_dir entries the SDK materializes lazily) with
+ * pack skill directories built from manifest-carried file content — one skill
+ * index, one `## Skills` instruction section, lazy `load_skill` for all of
+ * them. A pack skill shadows a bundled skill with the same directory name.
+ */
+declare function lazySkillSourceWithPackSkills(packSkills: PackSkill[]): LocalDirLazySkillSource;
+
+export { type AgentSegmentInput, type BuildAgentOptions, COMPACTION_SUMMARY_MARKER, CodexSubscriptionUnavailableError, type CompactionItem, type CompactionPlan, ComputerActionError, ComputerReadOnlyError, ComputerUnavailableError, type ComputerUseArgs, ComputerUseCapability, GENESIS_TITLE_DIRECTIVE, type HistoryItem, type ModelResponseUsage, MultiProviderModelProvider, type NormalizedRuntimeEvent, type OpenGeniRuntime, type PackSkill, type PackSkillFile, type PlanCompactionInput, type PrepareInputOptions, type PrepareToolsOptions, type PreparedAgentInput, type PreparedAgentTools, type ProductionRuntimeOverrides, type RunAgentStreamOptions, SUMMARY_INSTRUCTIONS, SUMMARY_PREFIX, SandboxComputer, type SandboxComputerOptions, type SandboxFileDownload, type SandboxLifecycleHook, type SandboxLifecycleHookContext, type SandboxLifecycleHookPhase, type WorkspaceEnvironmentContext, agentsErrorRunState, applyMissingManifestEntries, azureCliLoginCommand, azureOpenAIDefaultQuery, buildAgentCapabilities, buildCompactionMessages, buildManifest, buildModelInstance, buildOpenAIClientFromSettings, buildOpenGeniAgent, buildProviderClient, buildSummaryItem, callModelInputFilterForSettings, compactionSummaryText, composeAgentInstructions, computerUse, configureOpenAI, coreInstructions, createProductionAgentRuntime, enforceInputBudget, ensureReadableStreamFrom, estimateItemTokens, estimateTokens, extractResponseOutputText, findKeepBoundary, isCompactionSummary, isUserMessage, lazySkillSourceWithPackSkills, materializeSandboxFileDownloads, maxTurnsExceededRunState, modelResponseUsageFromSdkEvent, neutralizeToolSearchItemsInSerializedRunState, normalizeComputerCallsFilter, normalizeSdkEvent, normalizeToolOutputForEvent, planCompaction, prefixedMcpToolName, prepareAgentTools, prepareRunInput, renderPrefixTranscript, repositoryCloneCommand, repositoryUsesSandboxClone, resolveTurnModel, runAgentStream, runAzureCliLoginHook, runBeforeAgentStartHooks, runRepositoryCloneHook, sandboxCommandExitCode, sandboxCommandOutput, sandboxCommandStillRunning, sandboxFileDownloadsForAgent, sandboxLifecycleHooksForIds, sandboxRunAs, sanitizeHistoryItemsForModel, serializeApprovals, stripProviderItemIdsFilter, stripReasoningEncryptedContent, stripReasoningIdentityFromSerializedRunState, summarizeForCompaction, withManifestRefreshOnResume, withSandboxFileDownloads, withSandboxLifecycleHooks, workspaceEnvironmentInstructions };