@opengeni/runtime 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 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';
+import { Settings, ResolvedModelProvider, ConfiguredModel, ModelProviderApi } from '@opengeni/config';
 export { collectSandboxEnvironment, parseExposedPorts } from '@opengeni/config';
-import { ReasoningEffort, SessionEventType, ResourceRef, ToolRef, Permission, McpServerConnectionRef, ToolAuthNeededPayload } from '@opengeni/contracts';
+import { ReasoningEffort, GitCredentialProvider, SessionEventType, ResourceRef, ToolRef, Permission, McpServerConnectionRef, ToolAuthNeededPayload } 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 { SandboxSessionLike, Capability, SandboxSessionState, Manifest, Capabilities, LocalDirLazySkillSource, SandboxClient } from '@openai/agents/sandbox';
 import OpenAI from 'openai';
-import { R as RuntimeMetricsHooks } from './index-otZkoLYq.js';
-export { A as ActiveBackendResolverDeps, a as ActiveBackendUnresolvableError, b as ActivePointer, C as ChannelAConflictError, c as ChannelAEmitter, d as ChannelAExecArgs, e as ChannelAExecResult, f as ChannelANotFoundError, g as ChannelASession, h as ChannelAUnsupportedError, i as ChannelAValidationError, j as ControlRpc, D as DEFAULT_DESKTOP_GEOMETRY, k as DISPLAY_STACK_TIMEOUT_MS, l as DesktopGeometry, m as DisplayStackError, n as DisplayStackUnsupportedError, E as EnsureDisplayStackOptions, o as EnsureDisplayStackResult, p as EnsureTerminalServerOptions, q as EnsureTerminalServerResult, r as EstablishedSandboxSession, s as ExposeStreamPortInput, t as ExposeStreamPortResult, u as ExposedPortEndpoint, F as FinalizeRecordingResult, L as LiveModalSandboxLeaseAttribution, M as MintStreamTokenInput, v as MockAgentResponder, w as MockAgentResponderOptions, x as MockExecHandler, y as ModalModuleLoader, z as ModalOrphanSweepResult, B as ModalSandboxAttribution, N as NatsControlRpc, G as NatsRequestConnection, H as NegotiationContext, I as NumstatEntry, P as PROVIDER_REGISTRY, J as ProviderConstructionContext, K as ProviderRegistration, O as RecordingCodec, Q as RecordingContentType, S as RecordingError, T as RecordingProcess, U as RecordingUnavailableError, V as ResolvedActiveBackend, W as RoutableBackendSession, X as RoutableSandbox, Y as RoutingSandboxSession, Z as RoutingSandboxSessionDeps, _ as RoutingTransitionEvent, $ as RoutingUnsupportedError, a0 as SELFHOSTED_DEFAULT_TIMEOUT_MS, a1 as SELFHOSTED_RECONNECT_WINDOW_MS, a2 as SELFHOSTED_RELAY_STREAM_PATH, a3 as STREAM_PORT, a4 as STREAM_TOKEN_DEFAULT_TTL_SECONDS, a5 as SandboxChannelAService, a6 as SandboxChannelAServiceOptions, a7 as SandboxConfigError, a8 as SandboxCreatedCallback, a9 as SandboxProviderUnavailableError, aa as SelfhostedApplyDiff, ab as SelfhostedControlError, ac as SelfhostedEditor, ad as SelfhostedEnrollment, ae as SelfhostedExecArgs, af as SelfhostedExecResult, ag as SelfhostedImageOutput, ah as SelfhostedLivenessState, ai as SelfhostedNegotiationInput, aj as SelfhostedRelayConfig, ak as SelfhostedSandboxClient, al as SelfhostedSession, am as SelfhostedSessionBuild, an as SelfhostedSessionDeps, ao as SelfhostedSessionState, ap as SelfhostedUnavailableReason, aq as StartRecordingInput, ar as StreamPortUnavailableError, as as TERMINAL_SERVER_TIMEOUT_MS, at as TerminalServerError, au as TerminalServerUnsupportedError, av as agentErrorToControlError, aw as assertDescriptorRegistryInvariants, ax as assertProviderRegistryInvariants, ay as assertSafeRelPath, az as backendSupportsOs, aA as buildDisplayStackScript, aB as buildSelfhostedBackendSession, aC as buildStreamUrl, aD as buildTerminalServerScript, aE as contentTypeForCodec, aF as createSandboxClient, aG as createSandboxClientForBackend, aH as decodeModalSnapshotId, aI as deletePriorPersistedSnapshot, aJ as deleteRecordingArtifacts, aK as deserializeSandboxSessionStateEnvelope, aL as desktopCapableBackend, aM as ensureDisplayStack, aN as ensureModalRegistryImage, aO as ensureTerminalServer, aP as establishSandboxSessionFromEnvelope, aQ as exposeStreamPort, aR as extForCodec, aS as isExecSessionLostBanner, aT as isProviderSandboxNotFoundError, aU as isSelfhostedProviderNotFoundError, aV as isWorkspaceEscapeError, aW as makeActiveBackendResolver, aX as mintStreamToken, aY as modalSandboxAttributionEnvironment, aZ as modalSandboxAttributionTags, a_ as negotiateCapabilities, a$ as negotiateSelfhostedCapabilities, b0 as offlineAgentError, b1 as offlineControlResponse, b2 as parseExecBannerSessionId, b3 as parseNumstatZ, b4 as parsePorcelainV2, b5 as parseUnifiedPatch, b6 as readRecordingBytes, b7 as readWorkspaceArchiveFromEnvelopeSessionState, b8 as recordingStorageKey, b9 as restoredSandboxSessionStateFromEntry, ba as sandboxStateEntryFromRunState, bb as selectBackend, bc as selfhostedLiveness, bd as serializeEstablishedSandboxEnvelope, be as setSelfhostedApplyDiff, bf as startRecording, bg as stopRecording, bh as stripExecBanner, bi as subjectFor, bj as sweepModalOrphanSandboxes, bk as tagModalSandbox, bl as tearDownDisplayStack, bm as tearDownTerminalServer, bn as terminateModalSandboxById, bo as timeoutAgentError, bp as timeoutControlResponse, bq as verifyStreamToken } from './index-otZkoLYq.js';
+import { R as RuntimeMetricsHooks } from './index-DIiiwQY2.js';
+export { A as ActiveBackendResolverDeps, a as ActiveBackendUnresolvableError, b as ActivePointer, B as BackendUnresolvableCode, C as ChannelAConflictError, c as ChannelAEmitter, d as ChannelAExecArgs, e as ChannelAExecResult, f as ChannelANotFoundError, g as ChannelASession, h as ChannelAUnsupportedError, i as ChannelAValidationError, j as ControlRpc, D as DEFAULT_DESKTOP_GEOMETRY, k as DISPLAY_STACK_TIMEOUT_MS, l as DesktopGeometry, m as DisplayStackError, n as DisplayStackUnsupportedError, E as EnsureDisplayStackOptions, o as EnsureDisplayStackResult, p as EnsureTerminalServerOptions, q as EnsureTerminalServerResult, r as EstablishedSandboxSession, s as ExposeStreamPortInput, t as ExposeStreamPortResult, u as ExposedPortEndpoint, F as FAULT_FIELD_WHAT_HAPPENED, v as FAULT_FIELD_WHAT_PRESERVED, w as FAULT_FIELD_WHAT_TO_TRY, x as FAULT_FIELD_WHICH_LAYER, L as LiveModalSandboxLeaseAttribution, M as MintStreamTokenInput, y as MockAgentResponder, z as MockAgentResponderOptions, G as MockExecHandler, H as ModalModuleLoader, I as ModalOrphanSweepResult, J as ModalSandboxAttribution, N as NEVER_SENT_DETAIL_KEY, K as NatsControlRpc, O as NatsOpStreamConnection, P as NatsOpStreamTransport, Q as NatsRequestConnection, S as NegotiationContext, T as NumstatEntry, U as OP_STREAM_ACK_INTERVAL_MS, V as OP_STREAM_DEFAULT_WINDOW_BYTES, W as OP_STREAM_RECONNECT_HOLD_MS, X as OP_STREAM_SILENCE_TIMEOUT_MS, Y as OpStreamExecOutcome, Z as OpStreamJournal, _ as OpStreamSubscription, $ as OpStreamTransport, a0 as OpStreamUnavailableError, a1 as PROVIDER_REGISTRY, a2 as ProviderConstructionContext, a3 as ProviderRegistration, a4 as REPOSITORY_DISCOVERY_LIMIT, a5 as RecordingArtifactMetadata, a6 as RecordingCodec, a7 as RecordingContentType, a8 as RecordingError, a9 as RecordingProcess, aa as RecordingUnavailableError, ab as RepositoryDiscoveryDegradedReason, ac as RepositoryDiscoveryResult, ad as ResolvedActiveBackend, ae as RoutableBackendSession, af as RoutableSandbox, ag as RoutingSandboxSession, ah as RoutingSandboxSessionDeps, ai as RoutingTransitionEvent, aj as RoutingUnsupportedError, ak as SELFHOSTED_DEFAULT_TIMEOUT_MS, al as SELFHOSTED_DRAINING_MAX_RETRIES, am as SELFHOSTED_EXEC_DRAINING_MAX_RETRIES, an as SELFHOSTED_IDEMPOTENT_READONLY_OPS, ao as SELFHOSTED_INFRASTRUCTURE_FAULT_CLASSES, ap as SELFHOSTED_NEVER_SENT_MAX_RETRIES, aq as SELFHOSTED_RECONNECT_WINDOW_MS, ar as SELFHOSTED_RELAY_STREAM_PATH, as as SELFHOSTED_RETRY_BACKOFF_BASE_MS, at as SELFHOSTED_RETRY_BACKOFF_CAP_MS, au as SELFHOSTED_RETRY_BACKOFF_FACTOR, av as SELFHOSTED_TIMEOUT_MAX_RETRIES, aw as STREAM_PORT, ax as STREAM_TOKEN_DEFAULT_TTL_SECONDS, ay as SandboxChannelAService, az as SandboxChannelAServiceOptions, aA as SandboxConfigError, aB as SandboxCreatedCallback, aC as SandboxProviderUnavailableError, aD as SandboxResumeStateUnavailableError, aE as SelfhostedApplyDiff, aF as SelfhostedControlError, aG as SelfhostedEditor, aH as SelfhostedEnrollment, aI as SelfhostedExecArgs, aJ as SelfhostedExecResult, aK as SelfhostedImageOutput, aL as SelfhostedLivenessState, aM as SelfhostedNegotiationInput, aN as SelfhostedOpObservation, aO as SelfhostedOpObserver, aP as SelfhostedOpStreamDeps, aQ as SelfhostedRelayConfig, aR as SelfhostedRetryClock, aS as SelfhostedRetryDecision, aT as SelfhostedSandboxClient, aU as SelfhostedSession, aV as SelfhostedSessionBuild, aW as SelfhostedSessionDeps, aX as SelfhostedSessionState, aY as SelfhostedUnavailableReason, aZ as StartRecordingInput, a_ as StreamPortUnavailableError, a$ as SwapTargetEstablishability, b0 as TERMINAL_SERVER_TIMEOUT_MS, b1 as TerminalServerError, b2 as TerminalServerUnsupportedError, b3 as agentErrorToControlError, b4 as assertDescriptorRegistryInvariants, b5 as assertProviderRegistryInvariants, b6 as assertSafeRelPath, b7 as backendSupportsOs, b8 as buildDisplayStackScript, b9 as buildSelfhostedBackendSession, ba as buildStreamUrl, bb as buildTerminalServerScript, bc as contentTypeForCodec, bd as createSandboxClient, be as createSandboxClientForBackend, bf as decideSelfhostedRetry, bg as decodeModalSnapshotId, bh as defaultSelfhostedRetryClock, bi as deletePriorPersistedSnapshot, bj as deleteRecordingArtifacts, bk as deserializeSandboxSessionStateEnvelope, bl as desktopCapableBackend, bm as drainingExhaustedError, bn as drainingMessage, bo as ensureDisplayStack, bp as ensureModalRegistryImage, bq as ensureTerminalServer, br as establishSandboxSessionFromEnvelope, bs as execDeadlineHint, bt as exposeStreamPort, bu as extForCodec, bv as inspectRecordingArtifact, bw as isExecSessionLostBanner, bx as isProviderSandboxNotFoundError, by as isSelfhostedProviderNotFoundError, bz as isWorkspaceEscapeError, bA as makeActiveBackendResolver, bB as mintStreamToken, bC as modalSandboxAttributionEnvironment, bD as modalSandboxAttributionTags, bE as negotiateCapabilities, bF as negotiateSelfhostedCapabilities, bG as nextDurableOpId, bH as offlineAgentError, bI as offlineControlResponse, bJ as opAckSubject, bK as opFrameSubject, bL as parseExecBannerSessionId, bM as parseNumstatZ, bN as parsePorcelainV2, bO as parseUnifiedPatch, bP as payloadTooLargeMessage, bQ as readWorkspaceArchiveFromEnvelopeSessionState, bR as recordingStorageKey, bS as renderSelfhostedFault, bT as restoredSandboxSessionStateFromEntry, bU as runWithToolCallCorrelation, bV as sandboxStateEntryFromRunState, bW as sanitizeOpIdToken, bX as selectBackend, bY as selfhostedFaultClass, bZ as selfhostedLiveness, b_ as selfhostedRetryBackoffMs, b$ as serializeEstablishedSandboxEnvelope, c0 as setSelfhostedApplyDiff, c1 as startRecording, c2 as stopRecording, c3 as stripExecBanner, c4 as subjectFor, c5 as swapTargetEstablishability, c6 as sweepModalOrphanSandboxes, c7 as tagModalSandbox, c8 as tearDownDisplayStack, c9 as tearDownTerminalServer, ca as terminateModalSandboxById, cb as timeoutAgentError, cc as timeoutControlResponse, cd as uploadRecordingArtifact, ce as verifyStreamToken } from './index-DIiiwQY2.js';
 import 'modal';
 import '@opengeni/agent-proto';
 
@@ -22,6 +22,14 @@ type SandboxComputerOptions = {
     screenshotTmpDir?: string;
     screenshotWarmupBudgetMs?: number;
     screenshotRetryDelayMs?: number;
+    /**
+     * One turn-scoped preparation hook, invoked by the first real computer action.
+     * The agent may advertise computer-use on every turn, but merely advertising the
+     * tool must not boot Xvfb/XFCE or start a recording. The runtime capability owns
+     * this hook and uses it to bring up :0 (and optionally notify the worker) only
+     * after the model actually chooses a computer tool.
+     */
+    prepare?: (session: SandboxSessionLike) => Promise<void>;
 };
 /** No exec/execCommand on the session, or the display is not up. */
 declare class ComputerUnavailableError extends Error {
@@ -59,9 +67,13 @@ declare class SandboxComputer implements Computer {
     private readonly tmp;
     private readonly screenshotWarmupBudgetMs;
     private readonly screenshotRetryDelayMs;
+    private readonly prepare;
+    private prepared;
+    private preparation;
     constructor(session: SandboxSessionLike, opts?: SandboxComputerOptions);
     /** Rebind to a freshly resumed-by-id session after a box rollover / re-establish. */
     rebind(session: SandboxSessionLike): void;
+    private prepareOnce;
     private x;
     private guardWrite;
     private shq;
@@ -102,6 +114,8 @@ type ComputerUseArgs = {
     needsApproval?: boolean | ((ctx: unknown, action: unknown) => boolean | Promise<boolean>);
     imageFunctionResults?: boolean;
     toolMode?: ComputerToolMode;
+    /** Called after the display is ready on the first actual computer action. */
+    onReady?: (session: SandboxSessionLike) => Promise<void>;
 };
 declare function computerUse(args?: ComputerUseArgs): ComputerUseCapability;
 /**
@@ -162,6 +176,19 @@ declare class ComputerUseCapability extends Capability {
  */
 /** A history item is any JSON object; we only inspect a few discriminator fields. */
 type HistoryItem = Record<string, unknown>;
+/**
+ * Remove superseded `view_image` call/result pairs for the SAME local path,
+ * retaining the newest fully-paired observation. A `view_image` result can be
+ * hundreds of kilobytes of base64. When a model re-opens the same attachment,
+ * replaying every older copy on each subsequent model call grows input
+ * quadratically and can trap a turn in context-compaction/requeue recovery.
+ *
+ * This is state-based rather than count-based: every distinct path is kept,
+ * and an older observation is removed only after a newer successful pair for
+ * that exact path exists. The reasoning items immediately attached to a
+ * removed call are removed with it, preserving Responses API item validity.
+ */
+declare function elideSupersededViewImagePairs<T extends HistoryItem>(items: readonly T[]): T[];
 /**
  * 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,
@@ -234,9 +261,8 @@ declare function stripReasoningEncryptedContent<T extends HistoryItem>(item: T):
  * 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
+ * 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
@@ -287,11 +313,11 @@ declare function stripReasoningIdentityFromSerializedRunState(serialized: string
 declare function neutralizeToolSearchItemsInSerializedRunState(serialized: string): string;
 
 /**
- * Client-side conversation context compaction (the Azure/client path).
+ * Portable conversation context compaction, following Codex CLI's local path.
  *
- * This mirrors Codex CLI's compaction model: the checkpoint model sees the
- * current active history plus one fixed checkpoint prompt, then the active
- * history is rebuilt as all real user messages plus one summary message.
+ * 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.
  */
@@ -303,7 +329,7 @@ type CompactionItem = Record<string, unknown>;
 declare const COMPACTION_SUMMARY_MARKER = "opengeni_context_summary";
 declare const SUMMARY_BUFFER_TOKENS = 20000;
 declare const COMPACT_USER_MESSAGE_MAX_TOKENS = 20000;
-declare const DEFAULT_COMPACTION_THRESHOLD_RATIO = 0.6;
+declare const DEFAULT_COMPACTION_THRESHOLD_RATIO = 0.9;
 declare const MIN_COMPACTION_THRESHOLD_RATIO = 0.3;
 declare const MAX_COMPACTION_THRESHOLD_RATIO = 0.9;
 declare const COMPACTION_PROMPT: string;
@@ -313,63 +339,49 @@ declare const USER_MESSAGE_TRUNCATION_MARKER = "\n[... middle truncated for cont
 declare function isUserMessage(item: unknown): boolean;
 /** True for our synthetic compaction summary item. */
 declare function isCompactionSummary(item: unknown): boolean;
+/** Platform-authored system context exists for one inference and is never persisted. */
+declare function isEphemeralInternalContext(item: unknown): boolean;
 /**
  * Rough token estimate for an item: char/4 over its serialized text. Used for
- * the pre-first-call fallback, per-user-message cap, and read-path airbag.
+ * the pre-first-call signal and the retained user-message budget.
  */
 declare function estimateItemTokens(item: CompactionItem): number;
 declare function estimateTokens(items: readonly CompactionItem[]): number;
 declare function clampCompactionThresholdRatio(value: number | undefined | null): number;
-declare function clientCompactionThresholdTokens(input: {
+declare function compactionThresholdTokens(input: {
     contextWindowTokens: number;
     contextReservedOutputTokens: number;
-    contextCompactionThresholdRatio?: number | null;
+    contextAutoCompactThresholdTokens?: number | null | undefined;
+    contextCompactionThresholdRatio?: number | null | undefined;
 }): number;
-type ClientCompactionDecision = {
+type CompactionDecision = {
     shouldCompact: boolean;
     reason: "force" | "above_threshold" | "below_threshold" | "no_history";
     signalTokens: number;
     thresholdTokens: number;
 };
-declare function decideClientCompaction(input: {
+declare function decideCompaction(input: {
     items: readonly CompactionItem[];
     lastInputTokens?: number | null;
     contextWindowTokens: number;
     contextReservedOutputTokens: number;
-    contextCompactionThresholdRatio?: number | null;
+    contextAutoCompactThresholdTokens?: number | null | undefined;
+    contextCompactionThresholdRatio?: number | null | undefined;
     force?: boolean;
-}): ClientCompactionDecision;
+}): CompactionDecision;
 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";
     });
 }
 declare function findCompactionNeededError(error: unknown, seen?: WeakSet<object>): CompactionNeededError | null;
-/**
- * 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. Retained for the read-path budget guard only; the client compaction
- * rebuild no longer uses a keep-recent tail.
- */
-declare function findKeepBoundary(items: readonly CompactionItem[], keepRecentTokens: number): number;
-/**
- * READ-PATH BUDGET GUARD (last-resort backstop).
- *
- * Drops the oldest history at a clean user-message boundary until an assembled
- * input fits the request budget. This remains a request-local safety rail; it
- * is not the compaction strategy.
- */
-declare function enforceInputBudget<T extends CompactionItem>(items: readonly T[], maxTokens: number, trailingTokens?: number): {
-    items: T[];
-    trimmed: boolean;
-    droppedCount: number;
-    estimatedTokens: number;
-};
 /**
  * The exact checkpoint input shape: current active history followed by Codex's
  * checkpoint prompt as a synthesized user message.
@@ -377,42 +389,30 @@ declare function enforceInputBudget<T extends CompactionItem>(items: readonly T[
 declare function buildCompactionPromptInput(items: readonly CompactionItem[]): CompactionItem[];
 /**
  * Build the active history after compaction:
- * all real user messages (prior summaries excluded, images removed, each
- * message capped) plus one marked summary item.
+ * the newest real user messages that fit one cumulative 20k-token budget
+ * (prior summaries excluded, images removed) plus one marked summary item.
  */
 declare function buildCompactionReplacementHistory(items: readonly CompactionItem[], summaryBody: string): CompactionItem[];
-type DeterministicFallbackCompactionInput = {
-    items: readonly CompactionItem[];
-    cause?: string;
-    targetTokens?: number;
-};
-declare function buildDeterministicFallbackCompactionHistory(input: DeterministicFallbackCompactionInput): CompactionItem[];
 /**
  * Build the synthetic summary item (a plain user message) appended to the
  * rebuilt active history.
  */
 declare function buildSummaryItem(summaryBody: string): CompactionItem;
-type RenderCompactionTranscriptOptions = {
-    /**
-     * Hard cap for a rendered transcript. When set, oldest rendered items are
-     * dropped first while preserving the final checkpoint prompt; if the retained
-     * item itself is too large, it is middle-truncated instead of looping.
-     */
-    maxEstimatedTokens?: number;
-};
-declare function renderCompactionPromptInputForChat(input: readonly CompactionItem[], options?: RenderCompactionTranscriptOptions): string;
+declare function renderCompactionPromptInputForChat(input: readonly CompactionItem[]): string;
 
-declare const SCREENSHOT_OMITTED_PLACEHOLDER = "[screenshot omitted: an older desktop frame \u2014 the full image remains in the session event log]";
-type ElideStaleScreenshotsResult<T> = {
-    items: T[];
-    imageCount: number;
-    elidedCount: number;
-};
-type ElideStaleScreenshotsOptions = {
-    keepLast?: number;
-    placeholder?: string;
+type UsageDetails = Record<string, unknown> | Array<Record<string, unknown>>;
+type ModelCallUsageTelemetry = {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cachedTokens: number | null;
+    reasoningTokens: number | null;
 };
-declare function elideStaleScreenshotImages<T extends AgentInputItem>(items: readonly T[], options?: ElideStaleScreenshotsOptions): ElideStaleScreenshotsResult<T>;
+declare function modelCallUsageTelemetry(usage: {
+    inputTokens?: unknown;
+    outputTokens?: unknown;
+    inputTokensDetails?: UsageDetails | undefined;
+    outputTokensDetails?: UsageDetails | undefined;
+} | null | undefined): ModelCallUsageTelemetry;
 
 type NormalizedRuntimeEvent = {
     type: SessionEventType;
@@ -425,6 +425,7 @@ type ModelResponseUsage = {
         outputTokens?: number;
         totalTokens?: number;
         inputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
+        outputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
     };
 };
 type ResolveConnectionCredentialInput = {
@@ -452,8 +453,10 @@ type ResolveConnectionCredentialResult = {
 declare function ensureReadableStreamFrom(): void;
 type AgentSegmentInput = {
     kind: "message";
-    text: string;
-    serializedRunState?: string | null;
+    /** A real human/API prompt. Omitted when resuming the same inference. */
+    text?: string;
+    /** Ephemeral platform context: system role, never conversation history. */
+    internalContext?: string;
     historyItems?: AgentInputItem[] | null;
     sandboxEnvelope?: Record<string, unknown> | null;
 } | {
@@ -466,7 +469,6 @@ type AgentSegmentInput = {
 type PreparedAgentInput = {
     input: string | AgentInputItem[] | RunState<any, any>;
     sandboxSessionState?: SandboxSessionState;
-    serializedRunStateForSandbox?: string;
 };
 type SandboxFileDownload = {
     fileId: string;
@@ -477,6 +479,17 @@ type SandboxFileDownload = {
     expiresAt?: Date | string;
     sizeBytes?: number;
 };
+type SandboxFileDownloadFailure = {
+    fileId: string;
+    filename: string;
+    path: string;
+    reason: string;
+    exitCode?: number;
+    output?: string;
+};
+type SandboxFileDownloadMaterializationResult = {
+    failures: SandboxFileDownloadFailure[];
+};
 declare function configureRuntimeMetricsHooks(hooks: RuntimeMetricsHooks | null | undefined): void;
 type OpenGeniRuntime = {
     configure: (settings: Settings) => void;
@@ -564,14 +577,25 @@ declare class MultiProviderModelProvider implements ModelProvider {
 declare class CodexSubscriptionUnavailableError extends Error {
     constructor(modelName: string);
 }
+/**
+ * The workspace's model policy blocks the provider/model this turn resolved
+ * to. Thrown at the worker's post-resolution gate INSTEAD of running the turn
+ * on the blocked provider — a policy-restricted workspace (e.g. fail-closed to
+ * the Codex subscription) must never silently remap to, or fall through to,
+ * the paid built-in client. Like CodexSubscriptionUnavailableError the message
+ * is user-actionable and surfaces verbatim as a non-retryable turn.failed.
+ */
+declare class WorkspaceModelPolicyBlockedError extends Error {
+    constructor(modelName: string, providerId: string, reason: "provider" | "model");
+}
 declare function configureOpenAI(settings: Settings): void;
 /**
  * Run the compaction summarizer as one plain, tool-less, non-streaming model
  * call against the resolved provider. `input` is the active history plus
- * Codex's checkpoint prompt. Returns the trimmed summary text, or null on any
- * failure (the caller can retry with a harder-trimmed transcript, then fall
- * back to deterministic non-LLM compaction). The call deliberately does NOT
- * request reasoning encryption, tools, or server-side compaction; it is a
+ * Codex's checkpoint prompt. Provider failures propagate to the compaction
+ * lifecycle; there is no non-model fallback that silently discards history.
+ * The call deliberately does NOT
+ * request reasoning encryption, tools, or inline provider compaction; it is a
  * self-contained summarize.
  *
  * Provider-aware: the summary always runs on the SAME provider that serves the
@@ -579,8 +603,7 @@ declare function configureOpenAI(settings: Settings): void;
  * 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
+ * supplied it uses the built-in OpenAI/Azure Responses path. store:false is set
  * only on the OpenAI-platform Responses path (Azure rejects it; chat ignores it).
  */
 declare function summarizeForCompaction(settings: Settings, input: Array<Record<string, unknown>>, options?: {
@@ -588,8 +611,10 @@ declare function summarizeForCompaction(settings: Settings, input: Array<Record<
     api?: ModelProviderApi;
     maxOutputTokens?: number;
     model?: string;
-    maxTranscriptTokens?: number;
-}): Promise<string | null>;
+    promptCacheKey?: string;
+    systemInstructions?: string;
+    onUsage?: (usage: ModelResponseUsage) => void | Promise<void>;
+}): Promise<string>;
 /**
  * Pull the assistant text out of a Responses API result, shape-tolerant. Only
  * `role === "assistant"` message items contribute: a provider whose Responses
@@ -599,24 +624,38 @@ declare function summarizeForCompaction(settings: Settings, input: Array<Record<
  * Responses API only emits assistant messages, so this guard is a no-op there.
  */
 declare function extractResponseOutputText(response: unknown): string;
+type GitTokenSeeds = Partial<Record<GitCredentialProvider, string>>;
+type GitCredentialTokenWriterSession = SandboxSessionLike;
 type BuildAgentOptions = {
     model?: Model;
     reasoningEffort?: ReasoningEffort;
-    compactionMode?: ContextCompactionMode;
     hostedWebSearch?: boolean;
     encryptedReasoning?: boolean;
-    contextWindowTokens?: number;
     structuredToolTransport?: boolean;
     computerToolMode?: ComputerToolMode;
+    /**
+     * Invoked once, immediately before the first real computer action and after
+     * the display is ready. Merely advertising computer-use does not call it.
+     * The worker uses this seam for computer-use-only recording; ordinary
+     * shell/filesystem turns never pay that cost.
+     */
+    onComputerUseReady?: (session: SandboxSessionLike) => Promise<void>;
     codexConnectorNamespaces?: ReadonlySet<string>;
+    promptCacheKey?: string;
     sandboxEnvironment?: Record<string, string>;
     activeSandboxBackend?: Settings["sandboxBackend"];
     fileResourceDownloads?: SandboxFileDownload[];
     mcpServers?: MCPServer[];
+    workspaceMemory?: string;
     workspaceEnvironment?: WorkspaceEnvironmentContext;
+    rig?: RigInstructionsContext;
+    rigSetup?: RigSetupDescriptor;
+    rigCredentialHookIds?: string[];
     gitTokenSeed?: string;
+    gitTokenSeeds?: GitTokenSeeds;
     toolspaceTokenSeed?: string;
     genesisTitleHint?: boolean;
+    persistentSessionSettings?: PersistentSessionSettings;
     instructionsTemplate?: string;
     sessionInstructions?: string;
     packSkills?: PackSkill[];
@@ -643,6 +682,22 @@ type WorkspaceEnvironmentContext = {
     description?: string | null;
     variableNames?: string[];
 };
+type PersistentSessionSettings = {
+    titleIsSet: boolean;
+    childNotificationsMode?: "digest" | "passive";
+};
+/**
+ * The rig a session rides (M3): its name + the active version pinned onto the
+ * session. Surfaced verbatim in the non-bypassable CORE instructions so the
+ * agent understands its sandbox is a disposable fork of a shared, versioned
+ * machine definition and how to promote a durable change. Absent for rig-less
+ * sessions (the block never renders).
+ */
+type RigInstructionsContext = {
+    name: string;
+    version: number;
+};
+declare function rigInstructions(rig: RigInstructionsContext): string[];
 declare function workspaceEnvironmentInstructions(environment: WorkspaceEnvironmentContext): string[];
 /**
  * The non-bypassable CORE of the agent instructions: the goal-loop ownership
@@ -655,7 +710,7 @@ declare function workspaceEnvironmentInstructions(environment: WorkspaceEnvironm
  * 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[];
+declare function coreInstructions(workspaceEnvironment?: WorkspaceEnvironmentContext, rig?: RigInstructionsContext): string[];
 /**
  * Composes the final agent instructions from a (possibly white-labelled)
  * persona template and the non-bypassable CORE. The CORE is substituted at the
@@ -664,7 +719,7 @@ declare function coreInstructions(workspaceEnvironment?: WorkspaceEnvironmentCon
  * 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 composeAgentInstructions(template: string, workspaceEnvironment?: WorkspaceEnvironmentContext, rig?: RigInstructionsContext): string;
 /**
  * Appends the per-session persona instructions to the already-composed
  * (workspace + CORE) instructions, joined by " " — exactly the join used
@@ -673,6 +728,22 @@ declare function composeAgentInstructions(template: string, workspaceEnvironment
  * is a no-op that returns the composed string byte-for-byte.
  */
 declare function appendSessionInstructions(composed: string, sessionInstructions?: string): string;
+/**
+ * Append the durable session metadata the model otherwise cannot observe.
+ * This is deliberately declarative and excludes the title text: the title is
+ * user-controlled display metadata, while the agent only needs to know whether
+ * initialization has already happened. The block is present on every turn when
+ * supplied so compaction cannot erase knowledge that these settings persist.
+ */
+declare function appendPersistentSessionSettings(composed: string, settings?: PersistentSessionSettings): string;
+/**
+ * Appends the workspace memory working-set block to the already-composed
+ * (workspace + CORE + generic substrate) instructions, joined by " ". The
+ * memory slice is workspace-ground and intentionally lands before
+ * per-session instructions. An absent/blank value is a no-op that returns the
+ * composed string byte-for-byte.
+ */
+declare function appendWorkspaceMemory(composed: string, workspaceMemory?: string): string;
 /**
  * Appends the generic programmatic-tool-calling (toolspace) directive to the
  * composed workspace + CORE instructions, joined by " ". This is GENERIC
@@ -728,34 +799,19 @@ declare function mcpToolErrorOutput(error: unknown): {
 };
 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.
+ * Codex accepts ordinary FUNCTION tools but also accepts `input_image` content
+ * inside a function_call_output (the same transport used by codex-rs
+ * view_image). The SDK filesystem capability unnecessarily couples this choice
+ * to hosted apply_patch support; when hosted tools are disabled it degrades
+ * view_image to a giant text data URL, charging roughly one token per four
+ * base64 characters. Re-wrap only successful data-URL results as a structured
+ * image. Text errors remain text, and the tool itself remains a normal function.
  */
+declare function withStructuredViewImageFunctionResults(tools: Tool<unknown>[]): Tool<unknown>[];
 declare function buildAgentCapabilities(settings: Settings, packSkills: PackSkill[], options?: {
-    compactionMode?: ContextCompactionMode;
-    contextWindowTokens?: number;
     structuredToolTransport?: boolean;
     computerToolMode?: ComputerToolMode;
+    onComputerUseReady?: (session: SandboxSessionLike) => Promise<void>;
 }): ReturnType<typeof Capabilities.default>;
 declare function sandboxRunAs(_settings: Settings): string | undefined;
 type PreparedAgentTools = {
@@ -767,6 +823,7 @@ type PrepareToolsOptions = {
     accountId?: string;
     workspaceId?: string;
     sessionId?: string;
+    turnId?: string;
     subjectId?: string;
     subjectLabel?: string;
     firstPartyPermissions?: Permission[];
@@ -777,14 +834,6 @@ declare function prepareAgentTools(settings: Settings, tools: ToolRef[], options
 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 = {
@@ -792,19 +841,32 @@ type RunAgentStreamOptions = {
     sandboxEnvironment?: Record<string, string>;
     onRuntimeEvent?: (event: NormalizedRuntimeEvent) => Promise<void> | void;
     contextCompactionSignalTokens?: () => number | null | undefined;
+    contextCompactionRequested?: () => boolean | Promise<boolean>;
+    onGitCredentialSessionReady?: (session: GitCredentialTokenWriterSession) => Promise<void> | void;
     ownedSandbox?: {
         client: unknown;
         session: unknown;
         sessionState?: unknown;
         setupSession?: unknown;
+        fileDownloadsMaterialized?: boolean;
+        deferredSetup?: boolean;
     };
     callModelInputFilter?: CallModelInputFilter;
 };
 type ContextRobustnessFilterOptions = {
     contextCompactionSignalTokens?: () => number | null | undefined;
+    contextCompactionRequested?: () => boolean | Promise<boolean>;
     throwOnCompactionNeeded?: boolean;
 };
 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.";
+/**
+ * Inject the genesis-title directive into exactly one model request. Agent
+ * instructions are reused for every model call in a tool loop, so placing this
+ * directive there turned a nominally one-shot setup action into repeated title
+ * calls. The closure is intentionally consumed even when the first request
+ * fails: a retry/recovery must continue the task, not restart setup.
+ */
+declare function oneShotGenesisTitleInputFilter(): CallModelInputFilter;
 declare const TOOLSPACE_PROGRAMMATIC_DIRECTIVE = "Every tool on your MCP surface is also callable programmatically from the sandbox shell, so scripts can invoke tools without a model round trip per call. Run `ogtool list` to see the available tools and their input schemas (from tools/list), then `ogtool call <tool-name> '<json-args>'`; equivalently, POST MCP JSON-RPC to $OPENGENI_TOOLSPACE_URL with the bearer token read from $OPENGENI_TOOLSPACE_TOKEN_FILE. Prefer programmatic calls for loops, polling, and bulk filtering: their results stay in the sandbox and do not consume your context window. Tools that require human approval must still be invoked normally \u2014 called programmatically they return a typed error.";
 /**
  * callModelInputFilter that removes provider-assigned item ids (rs_/msg_/fc_…)
@@ -825,7 +887,7 @@ declare const stripProviderItemIdsFilter: CallModelInputFilter;
  * `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
+ * `actions``; and (live-proven against gpt-5.6-sol'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
@@ -835,13 +897,20 @@ declare const stripProviderItemIdsFilter: CallModelInputFilter;
  * never mutated.
  */
 declare const normalizeComputerCallsFilter: CallModelInputFilter;
+/**
+ * Per-call state compaction for local image inspection. Re-opening the same
+ * path supersedes its prior base64 result; carrying both provides no newer
+ * information and can otherwise balloon every following model request.
+ */
+declare const elideSupersededViewImagesFilter: CallModelInputFilter;
 declare function contextRobustnessFilterForSettings(settings: Settings, options?: ContextRobustnessFilterOptions): 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; the context-robustness guard then elides stale screenshots on
- * every mode and applies hard budget trimming only on the client-compaction path.
+ * selects it; the context-robustness guard then raises the proactive durable
+ * compaction signal on the client-compaction path. It never trims history from
+ * an individual request.
  */
 declare function callModelInputFilterForSettings(settings: Settings, options?: ContextRobustnessFilterOptions): 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>>>;
@@ -863,10 +932,63 @@ declare function maxTurnsExceededRunState(error: unknown): {
  * 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 withManifestRefreshOnResume(client: SandboxClient, targetManifest: Manifest | undefined, context?: Pick<SandboxLifecycleHookContext, "onRuntimeEvent">): SandboxClient;
+declare function applyMissingManifestEntries(session: SandboxSessionLike, targetManifest: Manifest, context?: Pick<SandboxLifecycleHookContext, "onRuntimeEvent">): Promise<void>;
+/**
+ * Key-level diff of the live box's baked manifest env vs the freshly recomputed
+ * target env. Returns null when identical. Key NAMES only — values are secrets
+ * and must never leave this function's comparison.
+ */
+declare function manifestEnvironmentDrift(current: Manifest, target: Manifest): {
+    added: string[];
+    removed: string[];
+    changed: string[];
+} | null;
+/**
+ * ENV PIN for provided sessions (the ownership-inversion turn path). The SDK
+ * validates the FULL target manifest environment against a live provided
+ * session's baked env BEFORE reducing to its entry-only delta
+ * (validateNoEnvironmentDelta -> session-fatal UserError on ANY difference).
+ * So a turn resuming an existing box must declare the box's OWN env,
+ * byte-identical — never the fresh recompute. This replaces the agent's
+ * defaultManifest environment with the baked one and reports the drift (key
+ * names only) instead of letting it kill the session. Fresh env lands at the
+ * next cold-create; rotating values ride OFF-manifest (TOKEN-BROKER B1/B2).
+ */
+declare function pinProvidedSessionManifestEnvironment(agent: Agent<any, any>, session: SandboxSessionLike, context?: Pick<SandboxLifecycleHookContext, "onRuntimeEvent">): Promise<void>;
+/**
+ * The one-truth owned-path platform setup: the manifest-env pin (align the turn's
+ * manifest to the live box's baked env + report drift, NEVER die on it) plus the
+ * beforeAgentStart hooks (repository clone with B1 token/askpass seed, toolspace
+ * token seed, azure-cli-login) and signed-URL file materialization — all executed
+ * DIRECTLY against the pinned, UN-proxied established box (the SDK never calls
+ * client.create/resume for a provided session, so these decorations would never
+ * fire on their own).
+ *
+ * Extracted verbatim from `runStream`'s owned branch so both the EAGER path
+ * (runStream, before the run starts) and the LAZY path (the worker's first-op
+ * provisioner, after the box is established) run the IDENTICAL setup. A pure
+ * refactor for the eager path: same order, same gates, same idempotency
+ * (clone skips a materialized tree, token seed overwrites — the desired per-turn
+ * refresh, az login is idempotent). The connected-machine (selfhosted) branch
+ * keeps platform setup OFF the user's real box and seeds ONLY the toolspace token.
+ *
+ * `gitTokenSeedsOverride` lets the lazy provisioner pass its own freshly-minted
+ * run-scoped provider tokens (minted at establish time, not turn start);
+ * unset ⇒ read the seeds off the agent exactly as the eager path does.
+ */
+declare function runOwnedSandboxSetup(agent: Agent<any, any>, session: SandboxSessionLike, setupSession: SandboxSessionLike, opts: {
+    settings: Settings;
+    environment: Record<string, string>;
+    preparedInput?: PreparedAgentInput;
+    fileDownloadsMaterialized?: boolean;
+    onRuntimeEvent?: SandboxLifecycleHookContext["onRuntimeEvent"];
+    gitTokenSeedsOverride?: GitTokenSeeds;
+    gitTokenSeedOverride?: string;
+}): 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 materializeSandboxFileDownloads(session: SandboxSessionLike, downloads: SandboxFileDownload[], context?: Pick<SandboxLifecycleHookContext, "onRuntimeEvent" | "runAs">): Promise<SandboxFileDownloadMaterializationResult>;
+declare function sandboxFileDownloadFailureNote(failures: SandboxFileDownloadFailure[]): string;
 declare function sandboxFileDownloadsForAgent(agent: unknown): SandboxFileDownload[];
 /**
  * Compact a tool-call output for the `agent.toolCall.output` SESSION EVENT so it
@@ -886,6 +1008,8 @@ declare function sandboxFileDownloadsForAgent(agent: unknown): SandboxFileDownlo
 declare function normalizeToolOutputForEvent(output: unknown): unknown;
 declare function normalizeSdkEvent(event: RunStreamEvent): NormalizedRuntimeEvent[];
 declare function modelResponseUsageFromSdkEvent(event: RunStreamEvent): ModelResponseUsage | null;
+/** Normalize usage from either a Responses or Chat Completions result. */
+declare function modelResponseUsageFromResponse(response: unknown): 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";
@@ -894,7 +1018,16 @@ type SandboxLifecycleHookContext = {
     onRuntimeEvent?: (event: NormalizedRuntimeEvent) => Promise<void> | void;
     runAs?: string;
     gitTokenSeed?: string;
+    gitTokenSeeds?: GitTokenSeeds;
     toolspaceTokenSeed?: string;
+    rigSetup?: RigSetupDescriptor;
+};
+type RigSetupDescriptor = {
+    rigId: string;
+    versionId: string;
+    rigName: string;
+    script: string;
+    timeoutMs: number;
 };
 type SandboxLifecycleHook = {
     id: string;
@@ -937,11 +1070,50 @@ declare function withSandboxLifecycleHooks(client: SandboxClient, hooks: Sandbox
 declare function repositoryUsesSandboxClone(settings: Settings, resource: Extract<ResourceRef, {
     kind: "repository";
 }>, activeSandboxBackend?: Settings["sandboxBackend"]): boolean;
+/**
+ * Build the off-manifest command used to atomically replace provider token files.
+ *
+ * Token values exist only in this one sandbox exec command. The stable askpass
+ * and provider-CLI wrappers always read the files at invocation time, so an
+ * in-flight multi-day turn observes the replacement without changing its
+ * manifest environment or rebuilding the sandbox.
+ */
+declare function gitProviderTokenRefreshCommand(seeds: GitTokenSeeds): string;
+declare function refreshGitProviderTokenFiles(session: GitCredentialTokenWriterSession, seeds: GitTokenSeeds, options?: {
+    runAs?: string;
+}): Promise<void>;
 declare function repositoryCloneCommand(resources: Extract<ResourceRef, {
     kind: "repository";
 }>[]): string;
 declare function toolspaceTokenSeedCommand(): string;
 declare function runToolspaceTokenSeedHook(session: SandboxSessionLike, context: SandboxLifecycleHookContext): Promise<void>;
+/**
+ * The rig-setup command (M3). One idempotent bash program:
+ *   1. `mkdir -p /var/opengeni` and, if the per-version marker already exists,
+ *      print the SKIP sentinel and exit 0 (a warm box re-running the hook).
+ *   2. otherwise atomically claim a per-version lock directory. A loser waits
+ *      for the winner's marker, then skips; if the winner fails and releases the
+ *      lock, the loser retries the claim.
+ *   3. the winner writes the rig's setup script to a temp file and runs it under
+ *      coreutils `timeout` (NOT `bash -e` — the script opts into `set -e`
+ *      itself if it wants), then captures the exit code and `touch`es the marker
+ *      ONLY on success (exit 0) so a failed/timed-out setup re-runs next turn.
+ * The heredoc delimiter is quoted, so the script content is executed verbatim
+ * with no host-side expansion.
+ */
+declare function rigSetupScriptCommand(script: string, versionId: string, timeoutMs?: number, markerRoot?: string): string;
+/**
+ * The rig-setup beforeAgentStart hook (M3). Runs the frozen rig version's setup
+ * script exactly once per box (marker-guarded), under the RIG's own timeout
+ * (context.rigSetup.timeoutMs, NOT the 120s lifecycle default). Emits
+ * rig.setup.started, then one terminal event:
+ *   - rig.setup.skipped   — marker already present,
+ *   - rig.setup.completed — script ran and exited 0,
+ *   - rig.setup.failed    — nonzero exit / timeout,
+ * and on failure THROWS (fail the turn closed) with a message naming the
+ * rig/version and a bounded tail of the setup output.
+ */
+declare function runRigSetupHook(session: SandboxSessionLike, context?: SandboxLifecycleHookContext): Promise<void>;
 declare function runRepositoryCloneHook(session: SandboxSessionLike, resources: Extract<ResourceRef, {
     kind: "repository";
 }>[], context?: SandboxLifecycleHookContext): Promise<void>;
@@ -962,4 +1134,4 @@ declare function azureOpenAIDefaultQuery(settings: Pick<Settings, "azureOpenaiAp
  */
 declare function lazySkillSourceWithPackSkills(packSkills: PackSkill[]): LocalDirLazySkillSource;
 
-export { type AgentSegmentInput, type BuildAgentOptions, COMPACTION_PROMPT, COMPACTION_SUMMARY_MARKER, COMPACT_USER_MESSAGE_MAX_TOKENS, type ClientCompactionDecision, CodexSubscriptionUnavailableError, type CompactionItem, CompactionNeededError, ComputerActionError, ComputerReadOnlyError, type ComputerToolMode, ComputerUnavailableError, type ComputerUseArgs, ComputerUseCapability, type ContextRobustnessFilterOptions, DEFAULT_COMPACTION_THRESHOLD_RATIO, type ElideStaleScreenshotsOptions, type ElideStaleScreenshotsResult, GENESIS_TITLE_DIRECTIVE, type HistoryItem, MAX_COMPACTION_THRESHOLD_RATIO, MIN_COMPACTION_THRESHOLD_RATIO, type ModelResponseUsage, MultiProviderModelProvider, type NormalizedRuntimeEvent, type OpenGeniRuntime, type PackSkill, type PackSkillFile, type PrepareInputOptions, type PrepareToolsOptions, type PreparedAgentInput, type PreparedAgentTools, type ProductionRuntimeOverrides, type ResolveConnectionCredentialInput, type ResolveConnectionCredentialResult, type RunAgentStreamOptions, RuntimeMetricsHooks, SCREENSHOT_OMITTED_PLACEHOLDER, SUMMARY_BUFFER_TOKENS, SUMMARY_PREFIX, SandboxComputer, type SandboxComputerOptions, type SandboxFileDownload, type SandboxLifecycleHook, type SandboxLifecycleHookContext, type SandboxLifecycleHookPhase, TOOLSPACE_PROGRAMMATIC_DIRECTIVE, USER_MESSAGE_TRUNCATION_MARKER, type WorkspaceEnvironmentContext, agentsErrorRunState, appendGenesisTitleDirective, appendSessionInstructions, appendToolspaceInstructions, applyMissingManifestEntries, azureCliLoginCommand, azureOpenAIDefaultQuery, buildAgentCapabilities, buildCompactionPromptInput, buildCompactionReplacementHistory, buildDeterministicFallbackCompactionHistory, buildManifest, buildModelInstance, buildOpenAIClientFromSettings, buildOpenGeniAgent, buildProviderClient, buildSummaryItem, callModelInputFilterForSettings, clampCompactionThresholdRatio, clientCompactionThresholdTokens, composeAgentInstructions, computerUse, configureOpenAI, configureRuntimeMetricsHooks, contextRobustnessFilterForSettings, coreInstructions, createProductionAgentRuntime, decideClientCompaction, elideStaleScreenshotImages, enforceInputBudget, ensureReadableStreamFrom, estimateItemTokens, estimateTokens, extractResponseOutputText, findCompactionNeededError, findKeepBoundary, isCompactionSummary, isUserMessage, lazySkillSourceWithPackSkills, materializeSandboxFileDownloads, maxTurnsExceededRunState, mcpToolErrorOutput, modelResponseUsageFromSdkEvent, neutralizeToolSearchItemsInSerializedRunState, normalizeComputerCallsFilter, normalizeSdkEvent, normalizeToolOutputForEvent, prefixedMcpToolName, prepareAgentTools, prepareRunInput, renderCompactionPromptInputForChat, repositoryCloneCommand, repositoryUsesSandboxClone, resolveTurnModel, runAgentStream, runAzureCliLoginHook, runBeforeAgentStartHooks, runRepositoryCloneHook, runToolspaceTokenSeedHook, sandboxCommandExitCode, sandboxCommandOutput, sandboxCommandStillRunning, sandboxFileDownloadsForAgent, sandboxLifecycleHooksForIds, sandboxRunAs, sanitizeHistoryItemsForModel, serializeApprovals, stripProviderItemIdsFilter, stripReasoningEncryptedContent, stripReasoningIdentityFromSerializedRunState, summarizeForCompaction, toolspaceTokenSeedCommand, withManifestRefreshOnResume, withSandboxFileDownloads, withSandboxLifecycleHooks, workspaceEnvironmentInstructions };
+export { type AgentSegmentInput, type BuildAgentOptions, COMPACTION_PROMPT, COMPACTION_SUMMARY_MARKER, COMPACT_USER_MESSAGE_MAX_TOKENS, CodexSubscriptionUnavailableError, type CompactionDecision, type CompactionItem, CompactionNeededError, ComputerActionError, ComputerReadOnlyError, type ComputerToolMode, ComputerUnavailableError, type ComputerUseArgs, ComputerUseCapability, type ContextRobustnessFilterOptions, DEFAULT_COMPACTION_THRESHOLD_RATIO, GENESIS_TITLE_DIRECTIVE, type GitCredentialTokenWriterSession, type GitTokenSeeds, type HistoryItem, MAX_COMPACTION_THRESHOLD_RATIO, MIN_COMPACTION_THRESHOLD_RATIO, type ModelCallUsageTelemetry, type ModelResponseUsage, MultiProviderModelProvider, type NormalizedRuntimeEvent, type OpenGeniRuntime, type PackSkill, type PackSkillFile, type PersistentSessionSettings, type PrepareInputOptions, type PrepareToolsOptions, type PreparedAgentInput, type PreparedAgentTools, type ProductionRuntimeOverrides, type ResolveConnectionCredentialInput, type ResolveConnectionCredentialResult, type RigInstructionsContext, type RigSetupDescriptor, type RunAgentStreamOptions, RuntimeMetricsHooks, SUMMARY_BUFFER_TOKENS, SUMMARY_PREFIX, SandboxComputer, type SandboxComputerOptions, type SandboxFileDownload, type SandboxFileDownloadFailure, type SandboxFileDownloadMaterializationResult, type SandboxLifecycleHook, type SandboxLifecycleHookContext, type SandboxLifecycleHookPhase, TOOLSPACE_PROGRAMMATIC_DIRECTIVE, USER_MESSAGE_TRUNCATION_MARKER, type WorkspaceEnvironmentContext, WorkspaceModelPolicyBlockedError, agentsErrorRunState, appendGenesisTitleDirective, appendPersistentSessionSettings, appendSessionInstructions, appendToolspaceInstructions, appendWorkspaceMemory, applyMissingManifestEntries, azureCliLoginCommand, azureOpenAIDefaultQuery, buildAgentCapabilities, buildCompactionPromptInput, buildCompactionReplacementHistory, buildManifest, buildModelInstance, buildOpenAIClientFromSettings, buildOpenGeniAgent, buildProviderClient, buildSummaryItem, callModelInputFilterForSettings, clampCompactionThresholdRatio, compactionThresholdTokens, composeAgentInstructions, computerUse, configureOpenAI, configureRuntimeMetricsHooks, contextRobustnessFilterForSettings, coreInstructions, createProductionAgentRuntime, decideCompaction, elideSupersededViewImagePairs, elideSupersededViewImagesFilter, ensureReadableStreamFrom, estimateItemTokens, estimateTokens, extractResponseOutputText, findCompactionNeededError, gitProviderTokenRefreshCommand, isCompactionSummary, isEphemeralInternalContext, isUserMessage, lazySkillSourceWithPackSkills, manifestEnvironmentDrift, materializeSandboxFileDownloads, maxTurnsExceededRunState, mcpToolErrorOutput, modelCallUsageTelemetry, modelResponseUsageFromResponse, modelResponseUsageFromSdkEvent, neutralizeToolSearchItemsInSerializedRunState, normalizeComputerCallsFilter, normalizeSdkEvent, normalizeToolOutputForEvent, oneShotGenesisTitleInputFilter, pinProvidedSessionManifestEnvironment, prefixedMcpToolName, prepareAgentTools, prepareRunInput, refreshGitProviderTokenFiles, renderCompactionPromptInputForChat, repositoryCloneCommand, repositoryUsesSandboxClone, resolveTurnModel, rigInstructions, rigSetupScriptCommand, runAgentStream, runAzureCliLoginHook, runBeforeAgentStartHooks, runOwnedSandboxSetup, runRepositoryCloneHook, runRigSetupHook, runToolspaceTokenSeedHook, sandboxCommandExitCode, sandboxCommandOutput, sandboxCommandStillRunning, sandboxFileDownloadFailureNote, sandboxFileDownloadsForAgent, sandboxLifecycleHooksForIds, sandboxRunAs, sanitizeHistoryItemsForModel, serializeApprovals, stripProviderItemIdsFilter, stripReasoningEncryptedContent, stripReasoningIdentityFromSerializedRunState, summarizeForCompaction, toolspaceTokenSeedCommand, withManifestRefreshOnResume, withSandboxFileDownloads, withSandboxLifecycleHooks, withStructuredViewImageFunctionResults, workspaceEnvironmentInstructions };