@opengeni/runtime 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -7,7 +7,8 @@ import { ReasoningEffort, SessionEventType, ResourceRef, ToolRef, Permission } f
 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';
+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, LiveModalSandboxLeaseAttribution, MintStreamTokenInput, MockAgentResponder, MockAgentResponderOptions, MockExecHandler, ModalOrphanSweepResult, ModalSandboxAttribution, 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, SandboxCreatedCallback, 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, modalSandboxAttributionEnvironment, modalSandboxAttributionTags, negotiateCapabilities, negotiateSelfhostedCapabilities, offlineAgentError, offlineControlResponse, parseExecBannerSessionId, parseNumstatZ, parsePorcelainV2, parseUnifiedPatch, readRecordingBytes, readWorkspaceArchiveFromEnvelopeSessionState, recordingStorageKey, restoredSandboxSessionStateFromEntry, sandboxStateEntryFromRunState, selectBackend, selfhostedLiveness, serializeEstablishedSandboxEnvelope, setSelfhostedApplyDiff, startRecording, stopRecording, stripExecBanner, subjectFor, sweepModalOrphanSandboxes, tagModalSandbox, tearDownDisplayStack, tearDownTerminalServer, terminateModalSandboxById, timeoutAgentError, timeoutControlResponse, verifyStreamToken } from './sandbox/index.js';
+import 'modal';
 import '@opengeni/agent-proto';
 
 type ComputerButton = "left" | "right" | "wheel" | "back" | "forward";
@@ -18,6 +19,8 @@ type SandboxComputerOptions = {
     typeDelayMs?: number;
     readOnly?: boolean;
     screenshotTmpDir?: string;
+    screenshotWarmupBudgetMs?: number;
+    screenshotRetryDelayMs?: number;
 };
 /** No exec/execCommand on the session, or the display is not up. */
 declare class ComputerUnavailableError extends Error {
@@ -53,6 +56,8 @@ declare class SandboxComputer implements Computer {
     private readonly typeDelayMs;
     private readonly readOnly;
     private readonly tmp;
+    private readonly screenshotWarmupBudgetMs;
+    private readonly screenshotRetryDelayMs;
     constructor(session: SandboxSessionLike, opts?: SandboxComputerOptions);
     /** Rebind to a freshly resumed-by-id session after a box rollover / re-establish. */
     rebind(session: SandboxSessionLike): void;
@@ -280,97 +285,77 @@ declare function stripReasoningIdentityFromSerializedRunState(serialized: string
 declare function neutralizeToolSearchItemsInSerializedRunState(serialized: string): string;
 
 /**
- * Client-side conversation context compaction (the Azure path).
+ * Client-side conversation context compaction (the Azure/client 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.
+ * 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.
+ * Assistant messages, tool calls/results, reasoning, and images are removed
+ * from the active model-facing history; the database audit rows remain.
  */
 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.
+ * Marker stored on the synthetic summary item so the UI can render it and the
+ * next rebuild can exclude old summaries from the retained user-message set.
  */
 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;
+declare const SUMMARY_BUFFER_TOKENS = 20000;
+declare const COMPACT_USER_MESSAGE_MAX_TOKENS = 20000;
+declare const CLIENT_COMPACTION_TRIGGER_FRACTION = 0.9;
+declare const COMPACTION_PROMPT: string;
+declare const SUMMARY_PREFIX = "Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. Use this to build on the work that has already been done and avoid duplicating work. Here is the summary produced by the other language model, use the information in this summary to assist with your own analysis:";
+declare const USER_MESSAGE_TRUNCATION_MARKER = "\n[... middle truncated for context compaction ...]\n";
 /** 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.
+ * 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.
  */
 declare function estimateItemTokens(item: CompactionItem): number;
 declare function estimateTokens(items: readonly CompactionItem[]): number;
+declare function clientCompactionThresholdTokens(input: {
+    contextWindowTokens: number;
+    contextReservedOutputTokens: number;
+}): number;
+type ClientCompactionDecision = {
+    shouldCompact: boolean;
+    reason: "force" | "above_threshold" | "below_threshold" | "no_history";
+    signalTokens: number;
+    thresholdTokens: number;
+};
+declare function decideClientCompaction(input: {
+    items: readonly CompactionItem[];
+    lastInputTokens?: number | null;
+    contextWindowTokens: number;
+    contextReservedOutputTokens: number;
+    force?: boolean;
+}): ClientCompactionDecision;
+declare class CompactionNeededError extends Error {
+    readonly signalTokens: number;
+    readonly thresholdTokens: number;
+    readonly signalSource: "provider" | "estimate";
+    constructor(input: {
+        signalTokens: number;
+        thresholdTokens: number;
+        signalSource: "provider" | "estimate";
+    });
+}
+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. 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".
+ * 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).
  *
- * 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.
+ * 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[];
@@ -378,111 +363,35 @@ declare function enforceInputBudget<T extends CompactionItem>(items: readonly T[
     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.
+ * The exact checkpoint input shape: current active history followed by Codex's
+ * checkpoint prompt as a synthesized user message.
  */
-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;
+declare function buildCompactionPromptInput(items: readonly CompactionItem[]): CompactionItem[];
 /**
- * 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.
+ * Build the active history after compaction:
+ * all real user messages (prior summaries excluded, images removed, each
+ * message capped) plus one marked summary item.
  */
-declare function renderPrefixTranscript(items: readonly CompactionItem[], priorSummaryText: string): string;
+declare function buildCompactionReplacementHistory(items: readonly CompactionItem[], summaryBody: string): CompactionItem[];
 /**
- * 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`.
+ * Build the synthetic summary item (a plain user message) appended to the
+ * rebuilt active history.
  */
-declare function buildCompactionMessages(plan: CompactionPlan): {
-    system: string;
-    user: string;
+declare function buildSummaryItem(summaryBody: string): CompactionItem;
+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;
+};
+declare function elideStaleScreenshotImages<T extends AgentInputItem>(items: readonly T[], options?: ElideStaleScreenshotsOptions): ElideStaleScreenshotsResult<T>;
 
 type NormalizedRuntimeEvent = {
     type: SessionEventType;
@@ -613,10 +522,10 @@ declare class CodexSubscriptionUnavailableError extends Error {
 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
+ * 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 treats a failed summarize as "skip compaction this turn"
- * — never fatal). The call deliberately does NOT request reasoning encryption,
+ * - 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
@@ -628,10 +537,7 @@ declare function configureOpenAI(settings: Settings): void;
  * 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?: {
+declare function summarizeForCompaction(settings: Settings, input: Array<Record<string, unknown>>, options?: {
     client?: OpenAI;
     api?: ModelProviderApi;
     maxOutputTokens?: number;
@@ -664,6 +570,7 @@ type BuildAgentOptions = {
     gitTokenSeed?: string;
     genesisTitleHint?: boolean;
     instructionsTemplate?: string;
+    sessionInstructions?: string;
     packSkills?: PackSkill[];
 };
 type PackSkillFile = {
@@ -710,6 +617,20 @@ declare function coreInstructions(workspaceEnvironment?: WorkspaceEnvironmentCon
  * with an empty environment reproduces the historical preamble byte-for-byte.
  */
 declare function composeAgentInstructions(template: string, workspaceEnvironment?: WorkspaceEnvironmentContext): string;
+/**
+ * Appends the per-session persona instructions to the already-composed
+ * (workspace + CORE) instructions, joined by " " — exactly the join used
+ * throughout the persona composition. The session slice is intentionally LAST
+ * (session-specific refinement of the workspace persona). An absent/blank value
+ * is a no-op that returns the composed string byte-for-byte.
+ */
+declare function appendSessionInstructions(composed: string, sessionInstructions?: string): string;
+/**
+ * Appends the one-shot genesis title directive (genesis turn only), joined by
+ * " " and always LAST so a white-label persona template or a per-session
+ * instruction can't drop it. A no-op when the hint is absent.
+ */
+declare function appendGenesisTitleDirective(instructions: string, genesisTitleHint?: boolean): string;
 declare function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[], options?: BuildAgentOptions): Agent<any, any>;
 /**
  * Build the SandboxAgent capability set provider-aware.
@@ -773,6 +694,7 @@ type RunAgentStreamOptions = {
     sandboxClient?: unknown;
     sandboxEnvironment?: Record<string, string>;
     onRuntimeEvent?: (event: NormalizedRuntimeEvent) => Promise<void> | void;
+    contextCompactionSignalTokens?: () => number | null | undefined;
     ownedSandbox?: {
         client: unknown;
         session: unknown;
@@ -781,6 +703,10 @@ type RunAgentStreamOptions = {
     };
     callModelInputFilter?: CallModelInputFilter;
 };
+type ContextRobustnessFilterOptions = {
+    contextCompactionSignalTokens?: () => number | null | undefined;
+    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.";
 /**
  * callModelInputFilter that removes provider-assigned item ids (rs_/msg_/fc_…)
@@ -811,13 +737,15 @@ declare const stripProviderItemIdsFilter: CallModelInputFilter;
  * never mutated.
  */
 declare const normalizeComputerCallsFilter: 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.
+ * selects it; the context-robustness guard then elides stale screenshots on
+ * every mode and applies hard budget trimming only on the client-compaction path.
  */
-declare function callModelInputFilterForSettings(settings: Settings): CallModelInputFilter | undefined;
+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>>>;
 
 /**
@@ -933,4 +861,4 @@ declare function azureOpenAIDefaultQuery(settings: Pick<Settings, "azureOpenaiAp
  */
 declare function lazySkillSourceWithPackSkills(packSkills: PackSkill[]): LocalDirLazySkillSource;
 
-export { type AgentSegmentInput, type BuildAgentOptions, COMPACTION_SUMMARY_MARKER, CodexSubscriptionUnavailableError, type CompactionItem, type CompactionPlan, ComputerActionError, ComputerReadOnlyError, type ComputerToolMode, 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 };
+export { type AgentSegmentInput, type BuildAgentOptions, CLIENT_COMPACTION_TRIGGER_FRACTION, 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, type ElideStaleScreenshotsOptions, type ElideStaleScreenshotsResult, GENESIS_TITLE_DIRECTIVE, type HistoryItem, type ModelResponseUsage, MultiProviderModelProvider, type NormalizedRuntimeEvent, type OpenGeniRuntime, type PackSkill, type PackSkillFile, type PrepareInputOptions, type PrepareToolsOptions, type PreparedAgentInput, type PreparedAgentTools, type ProductionRuntimeOverrides, type RunAgentStreamOptions, SCREENSHOT_OMITTED_PLACEHOLDER, SUMMARY_BUFFER_TOKENS, SUMMARY_PREFIX, SandboxComputer, type SandboxComputerOptions, type SandboxFileDownload, type SandboxLifecycleHook, type SandboxLifecycleHookContext, type SandboxLifecycleHookPhase, USER_MESSAGE_TRUNCATION_MARKER, type WorkspaceEnvironmentContext, agentsErrorRunState, appendGenesisTitleDirective, appendSessionInstructions, applyMissingManifestEntries, azureCliLoginCommand, azureOpenAIDefaultQuery, buildAgentCapabilities, buildCompactionPromptInput, buildCompactionReplacementHistory, buildManifest, buildModelInstance, buildOpenAIClientFromSettings, buildOpenGeniAgent, buildProviderClient, buildSummaryItem, callModelInputFilterForSettings, clientCompactionThresholdTokens, composeAgentInstructions, computerUse, configureOpenAI, contextRobustnessFilterForSettings, coreInstructions, createProductionAgentRuntime, decideClientCompaction, elideStaleScreenshotImages, enforceInputBudget, ensureReadableStreamFrom, estimateItemTokens, estimateTokens, extractResponseOutputText, findCompactionNeededError, findKeepBoundary, isCompactionSummary, isUserMessage, lazySkillSourceWithPackSkills, materializeSandboxFileDownloads, maxTurnsExceededRunState, modelResponseUsageFromSdkEvent, neutralizeToolSearchItemsInSerializedRunState, normalizeComputerCallsFilter, normalizeSdkEvent, normalizeToolOutputForEvent, prefixedMcpToolName, prepareAgentTools, prepareRunInput, renderCompactionPromptInputForChat, repositoryCloneCommand, repositoryUsesSandboxClone, resolveTurnModel, runAgentStream, runAzureCliLoginHook, runBeforeAgentStartHooks, runRepositoryCloneHook, sandboxCommandExitCode, sandboxCommandOutput, sandboxCommandStillRunning, sandboxFileDownloadsForAgent, sandboxLifecycleHooksForIds, sandboxRunAs, sanitizeHistoryItemsForModel, serializeApprovals, stripProviderItemIdsFilter, stripReasoningEncryptedContent, stripReasoningIdentityFromSerializedRunState, summarizeForCompaction, withManifestRefreshOnResume, withSandboxFileDownloads, withSandboxLifecycleHooks, workspaceEnvironmentInstructions };