@opengeni/worker-bundle 2.0.1 → 2.0.3-canary.36199476632001

package/dist/workflows/session.d.ts

@@ -1,5 +1,34 @@
 import type * as activities from "../activities.js";
 import { type EscapedMcpTimeoutRecoveryDetail, type PostClaimDatabaseRecoveryDetail, type PreClaimFailureDetail, type PreClaimFailureDisposition } from "../activities/types.js";
+/**
+ * Provider capacity waits are shared: every waiter of one exhausted pool learns
+ * the same authoritative reset time, and one capacity mutation (for example the
+ * bounded refresh that verifies a quota reset) wakes every waiter at once, both
+ * as the typed capacity signal and as the generic durable workflow wake. Without
+ * spread, a reset resumes the whole backlog in the same few seconds and its
+ * turns stampede sandbox creation and the provider. Each workflow therefore
+ * delays its reconciliation by a bounded, replay-deterministic (Temporal-seeded
+ * `Math.random`) jitter: up to one minute past a scheduled reset timer and up to
+ * 30 seconds after a capacity or queue wake or an already-due waiter. A wake
+ * that lands inside a waiter's timer spread does not shorten it. The Postgres
+ * waiter stays authoritative; jitter only delays the same reconciliation
+ * activity and never creates queue rows, input, or inference. Interruptions are
+ * never delayed.
+ *
+ * The patch marker is not understood by workers built before it: rolling the
+ * worker image back past this change while a session has recorded the marker
+ * (it waited on capacity in its current run) fails that workflow's tasks as
+ * nondeterministic until a patched worker returns.
+ */
+export declare const CAPACITY_WAKE_JITTER_PATCH = "session-capacity-wake-jitter-v1";
+export declare const CAPACITY_TIMER_WAKE_JITTER_MAX_MS = 60000;
+export declare const CAPACITY_WAKE_JITTER_MAX_MS = 30000;
+/**
+ * Pure + exported so the bound is unit-testable without a workflow environment.
+ * `overrideMaxMs` is the test-only SessionWorkflowInput ceiling; it can only
+ * narrow the production bound.
+ */
+export declare function capacityWakeJitterMs(kind: "timer" | "wake", sample: number, overrideMaxMs?: number): number;
 /**
  * How long the continuation loop must hold before re-admitting the next turn. 0 ⇒ no
  * hold (re-dispatch immediately — a rotation candidate is ready, or no idle delay was
@@ -76,5 +105,6 @@ export type SessionWorkflowInput = {
     initialEventId?: string;
     maxTurnsPerRun?: number;
     maxCapacityChecksPerRun?: number;
+    capacityWakeJitterMaxMs?: number;
 };
 export declare function sessionWorkflow(input: SessionWorkflowInput): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/worker-bundle",
-  "version": "2.0.1",
+  "version": "2.0.3-canary.36199476632001",
   "description": "OpenGeni worker entry and reusable embedded lifecycle, shipped with a release-coherent pre-bundled Temporal workflow artifact.",
   "license": "Apache-2.0",
   "repository": {
@@ -54,24 +54,25 @@
   },
   "dependencies": {
     "@llamaindex/liteparse": "2.14.2",
-    "@opengeni/agent-proto": "^0.6.0",
-    "@opengeni/capabilities": "^0.3.4",
-    "@opengeni/codemode": "^0.6.1",
-    "@opengeni/codex": "^0.2.25",
-    "@opengeni/config": "^2.1.0",
-    "@opengeni/contracts": "^5.1.0",
-    "@opengeni/core": "^4.0.1",
-    "@opengeni/db": "^6.0.1",
-    "@opengeni/documents": "^0.8.32",
-    "@opengeni/events": "^0.4.30",
-    "@opengeni/github": "^0.7.15",
-    "@opengeni/network": "^0.3.1",
-    "@opengeni/observability": "^0.8.31",
-    "@opengeni/runtime": "^4.0.1",
-    "@opengeni/sdk": "^7.1.0",
-    "@opengeni/storage": "^0.2.132",
-    "@opengeni/tool-gateway": "^0.1.12",
-    "@opengeni/xai-subscription": "^0.1.4",
+    "@opengeni/agent-proto": "^0.6.0-canary.36199476632001",
+    "@opengeni/capabilities": "^0.3.4-canary.36199476632001",
+    "@opengeni/codemode": "^0.6.2-canary.36199476632001",
+    "@opengeni/codex": "^0.2.26-canary.36199476632001",
+    "@opengeni/config": "^2.1.1-canary.36199476632001",
+    "@opengeni/contracts": "^5.1.1-canary.36199476632001",
+    "@opengeni/core": "^4.0.3-canary.36199476632001",
+    "@opengeni/db": "^6.0.3-canary.36199476632001",
+    "@opengeni/documents": "^0.8.34-canary.36199476632001",
+    "@opengeni/events": "^0.4.32-canary.36199476632001",
+    "@opengeni/github": "^0.7.16-canary.36199476632001",
+    "@opengeni/jev": "^0.1.0-canary.36199476632001",
+    "@opengeni/network": "^0.3.1-canary.36199476632001",
+    "@opengeni/observability": "^0.8.32-canary.36199476632001",
+    "@opengeni/runtime": "^4.0.3-canary.36199476632001",
+    "@opengeni/sdk": "^7.1.1-canary.36199476632001",
+    "@opengeni/storage": "^0.2.133-canary.36199476632001",
+    "@opengeni/tool-gateway": "^0.1.13-canary.36199476632001",
+    "@opengeni/xai-subscription": "^0.1.4-canary.36199476632001",
     "@temporalio/activity": "^1.17.0",
     "@temporalio/client": "^1.17.0",
     "@temporalio/worker": "^1.17.0",

package/src/activities/agent-turn/agent-build.ts

@@ -131,6 +131,8 @@ export type BuildTurnAgentDeps = {
   connectorActionPolicy: ConnectorActionPolicyHooks;
   trigger: ClaimTurnOk["trigger"];
   preparationIndependentToolNames: readonly string[];
+  /** The attempt's tool catalog includes the Jev-backed code_search tool. */
+  codeSearchAvailable: boolean;
   videoGenerationAcceptancesByCallId: Map<string, { operationId: string; requestDigest: string }>;
   activeSandboxBackend: Settings["sandboxBackend"] | undefined;
   groupBoxBackend: Settings["sandboxBackend"];
@@ -189,6 +191,7 @@ export async function buildTurnAgent(deps: BuildTurnAgentDeps) {
     connectorActionPolicy,
     trigger,
     preparationIndependentToolNames,
+    codeSearchAvailable,
     videoGenerationAcceptancesByCallId,
     activeSandboxBackend,
     groupBoxBackend,
@@ -676,6 +679,7 @@ export async function buildTurnAgent(deps: BuildTurnAgentDeps) {
           ? { gitTokenSeed: sandboxGitToken }
           : {}),
         ...(sandboxCodemodeToken ? { codemodeAvailable: true } : {}),
+        ...(codeSearchAvailable ? { codeSearchAvailable: true } : {}),
         // Managed boxes receive the bearer through their protected per-session
         // token file. Connected Machines use transient per-exec delivery above,
         // so they must not run the file-seeding lifecycle hook.

package/src/activities/agent-turn/code-search.ts

@@ -0,0 +1,275 @@
+import type { AttemptToolDefinition } from "@opengeni/codemode";
+import { usableJevApiKey, type Settings } from "@opengeni/config";
+import {
+  CODE_SEARCH_TOOL_DESCRIPTION,
+  CODE_SEARCH_TOOL_NAME,
+  CodeSearchArgumentError,
+  CodeSearchRipgrepMissingError,
+  CodeSearchWorkspaceError,
+  JevCircuitBreaker,
+  JevClient,
+  JevRequestError,
+  JevUnavailableError,
+  codeSearchInputSchema,
+  parseCodeSearchArguments,
+  renderCodeSearchError,
+  runCodeSearch,
+  type CodeSearchWorkspace,
+  type JevCircuitLease,
+} from "@opengeni/jev";
+import type { Observability } from "@opengeni/observability";
+import {
+  ChannelANotFoundError,
+  ChannelAUnavailableError,
+  ChannelAUnsupportedError,
+  ChannelAValidationError,
+  isWindowsConnectedMachinePath,
+  type SandboxChannelAService,
+} from "@opengeni/runtime/sandbox";
+import { recordCodeSearchCall, type CodeSearchCallOutcome } from "../../observability-metrics";
+
+/**
+ * One breaker per worker process. Repeated Jev outages (including an exhausted
+ * account) make `code_search` calls on this worker fail at once for a cooldown
+ * instead of each running a full retry cycle. The breaker never changes which
+ * tools a turn is offered: the tool list and instructions are the start of the
+ * model's cached prompt, and sessions move between workers whose breakers
+ * disagree.
+ */
+export const codeSearchCircuitBreaker = new JevCircuitBreaker();
+
+/** Ripgrep output kept on the box per call before framing. */
+const CODE_SEARCH_RIPGREP_MAX_BYTES = 32 * 1024 * 1024;
+
+type CodeSearchChannel = Pick<
+  SandboxChannelAService,
+  "codeSearchRipgrep" | "codeSearchPathKinds" | "fsRead"
+>;
+
+/** Adapt the turn's sandbox or Connected Machine to the code search engine. */
+export function codeSearchWorkspaceFromChannel(channel: CodeSearchChannel): CodeSearchWorkspace {
+  return {
+    ripgrep: async (args, options) => {
+      options.signal?.throwIfAborted();
+      const outcome = await channel.codeSearchRipgrep(args, {
+        timeoutMs: options.timeoutMs,
+        maxBytes: CODE_SEARCH_RIPGREP_MAX_BYTES,
+      });
+      if (!outcome.available) throw new CodeSearchRipgrepMissingError();
+      return {
+        stdout: outcome.stdout,
+        exitCode: outcome.exitCode,
+        truncated: outcome.truncated,
+        timedOut: outcome.timedOut,
+      };
+    },
+    readText: async (path, options) => {
+      options.signal?.throwIfAborted();
+      try {
+        const read = await channel.fsRead({ path, encoding: "utf8", maxBytes: options.maxBytes });
+        return { text: read.content, truncated: read.truncated, binary: read.isBinary };
+      } catch (error) {
+        if (error instanceof ChannelANotFoundError) return null;
+        throw error;
+      }
+    },
+    pathKinds: async (paths, options) => {
+      options.signal?.throwIfAborted();
+      return await channel.codeSearchPathKinds(paths);
+    },
+  };
+}
+
+/** Jev work done by one completed `code_search` call, for per-workspace usage records. */
+export type CodeSearchUsage = {
+  operationId: string;
+  jevRequests: number;
+  jevInputTokens: number;
+  jevCostUsd: number;
+};
+
+function textResult(text: string, isError: boolean) {
+  return { isError, content: [{ type: "text" as const, text }] };
+}
+
+/**
+ * The model-facing `code_search` tool. Jev scores candidates inside the worker;
+ * the sandbox only runs read-only ripgrep and file reads, so the Jev key never
+ * leaves this process. A Jev failure is reported to the model instead of
+ * degrading to keyword-only ranking, which lowered answer quality in testing.
+ */
+export function createCodeSearchAttemptToolDefinition(input: {
+  settings: Pick<Settings, "jevApiKey" | "jevBaseUrl" | "jevModel" | "jevRequestTimeoutMs">;
+  apiKey: string;
+  workspace: () => Promise<CodeSearchWorkspace>;
+  observability: Observability;
+  /** Records Jev usage against the workspace. Failures are logged, never surfaced. */
+  recordUsage?: (usage: CodeSearchUsage) => Promise<void>;
+  breaker?: JevCircuitBreaker;
+  fetch?: typeof fetch;
+}): AttemptToolDefinition {
+  const breaker = input.breaker ?? codeSearchCircuitBreaker;
+  const jev = new JevClient({
+    apiKey: input.apiKey,
+    baseUrl: input.settings.jevBaseUrl,
+    model: input.settings.jevModel,
+    timeoutMs: input.settings.jevRequestTimeoutMs,
+    ...(input.fetch ? { fetch: input.fetch } : {}),
+  });
+  return {
+    identity: { serverId: "opengeni", toolName: CODE_SEARCH_TOOL_NAME },
+    modelName: CODE_SEARCH_TOOL_NAME,
+    codemodePath: ["opengeni", CODE_SEARCH_TOOL_NAME],
+    title: "Search code",
+    description: CODE_SEARCH_TOOL_DESCRIPTION,
+    inputSchema: codeSearchInputSchema,
+    annotations: {
+      title: "Search code",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    source: "opengeni",
+    approval: "none",
+    execute: async (args, context) => {
+      const startedAt = performance.now();
+      let outcome: CodeSearchCallOutcome = "failed";
+      let jevRequests = 0;
+      let jevCostUsd = 0;
+      // The breaker lease (the single trial while half-open) is settled exactly
+      // once: by what Jev did, or released when Jev was never judged. Settling
+      // takes it, so the finally block releases only a lease still held.
+      let lease: JevCircuitLease | null = null;
+      try {
+        const request = parseCodeSearchArguments(args);
+        lease = breaker.tryAcquire(Date.now());
+        if (!lease) {
+          outcome = "breaker_open";
+          return textResult(
+            renderCodeSearchError(
+              new JevUnavailableError("Jev is not responding; calls are paused for a few minutes"),
+            ),
+            true,
+          );
+        }
+        const workspace = await input.workspace();
+        const result = await runCodeSearch({
+          ...request,
+          workspace,
+          jev,
+          ...(context.signal ? { signal: context.signal } : {}),
+        });
+        const held = lease;
+        lease = null;
+        // A pack whose final status check hit an outage still counts against Jev.
+        if (result.statusCheckError instanceof JevUnavailableError) {
+          breaker.recordFailure(result.statusCheckError, Date.now(), held);
+        } else if (result.stats.jev.requests > 0) {
+          breaker.recordSuccess(held);
+        } else {
+          breaker.release(held);
+        }
+        outcome = "completed";
+        jevRequests = result.stats.jev.requests;
+        jevCostUsd = result.stats.jev.costUsd;
+        if (input.recordUsage && jevRequests > 0) {
+          await input
+            .recordUsage({
+              operationId: context.operationId,
+              jevRequests,
+              jevInputTokens: result.stats.jev.inputTokens,
+              jevCostUsd,
+            })
+            .catch((error: unknown) => {
+              input.observability.warn("code_search usage record failed", {
+                error: error instanceof Error ? error.message : String(error),
+              });
+            });
+        }
+        return textResult(result.text, false);
+      } catch (error) {
+        if (context.signal?.aborted) {
+          outcome = "cancelled";
+          throw error;
+        }
+        if (error instanceof CodeSearchArgumentError) {
+          outcome = "invalid_arguments";
+          return textResult(error.message, true);
+        }
+        if (error instanceof JevUnavailableError) {
+          const held = lease;
+          lease = null;
+          breaker.recordFailure(error, Date.now(), held);
+          outcome = "jev_unavailable";
+          return textResult(renderCodeSearchError(error), true);
+        }
+        if (error instanceof JevRequestError) {
+          outcome = "jev_rejected";
+          return textResult(renderCodeSearchError(error), true);
+        }
+        if (error instanceof CodeSearchWorkspaceError) {
+          outcome = "workspace_unavailable";
+          return textResult(renderCodeSearchError(error), true);
+        }
+        if (
+          error instanceof ChannelAUnavailableError ||
+          error instanceof ChannelAUnsupportedError ||
+          error instanceof ChannelAValidationError
+        ) {
+          outcome = "workspace_unavailable";
+          return textResult(
+            renderCodeSearchError(new CodeSearchWorkspaceError(error.message)),
+            true,
+          );
+        }
+        throw error;
+      } finally {
+        if (lease) breaker.release(lease);
+        recordCodeSearchCall(input.observability, {
+          outcome,
+          durationSeconds: (performance.now() - startedAt) / 1_000,
+          jevRequests,
+          jevCostUsd,
+        });
+      }
+    },
+  };
+}
+
+/**
+ * The `code_search` definition for one turn, or none. It is offered only when
+ * the session's frozen decision and the deployment enable it, a usable Jev key
+ * exists, and the turn has compute that can run its POSIX shell commands (not
+ * a Windows Connected Machine). Every input is durable, so the tool list stays
+ * the same from turn to turn and on every worker. Transient Jev health never
+ * hides the tool; the breaker only refuses calls.
+ */
+export function codeSearchToolDefinitions(input: {
+  enabled: boolean;
+  settings: Pick<Settings, "jevApiKey" | "jevBaseUrl" | "jevModel" | "jevRequestTimeoutMs">;
+  backend: Settings["sandboxBackend"];
+  /** The turn's Connected Machine workspace root, when a machine is primary. */
+  machineWorkspaceRoot?: string | null;
+  observability: Observability;
+  workspace: () => Promise<CodeSearchWorkspace>;
+  recordUsage?: (usage: CodeSearchUsage) => Promise<void>;
+  breaker?: JevCircuitBreaker;
+}): AttemptToolDefinition[] {
+  const apiKey = usableJevApiKey(input.settings);
+  const breaker = input.breaker ?? codeSearchCircuitBreaker;
+  if (!input.enabled || !apiKey || input.backend === "none") return [];
+  if (input.machineWorkspaceRoot && isWindowsConnectedMachinePath(input.machineWorkspaceRoot)) {
+    return [];
+  }
+  return [
+    createCodeSearchAttemptToolDefinition({
+      settings: input.settings,
+      apiKey,
+      workspace: input.workspace,
+      observability: input.observability,
+      ...(input.recordUsage ? { recordUsage: input.recordUsage } : {}),
+      breaker,
+    }),
+  ];
+}

package/src/activities/agent-turn/codex-capacity.ts

@@ -43,6 +43,7 @@ import { recordTurnStartupPhase } from "../../observability-metrics";
 import { createTurnCredentialLeases } from "./credential-leases";
 import { deliverFailedChildTurnToParent } from "../parent-wake";
 import { randomUUID } from "node:crypto";
+import { createLogThrottle, type LogThrottle } from "@opengeni/observability";
 
 import { refreshCappedCodexUsageRows } from "./codex";
 import { codexUsageLimitFailurePayload, CODEX_USAGE_LIMIT_MAX_RESUME_MS } from "./errors";
@@ -56,6 +57,39 @@ import type {
   TurnControlState,
 } from "./turn-context";
 
+/** The eligible-pool gauge and `opengeni_codex_pool_low_total` stay per turn;
+ * the warning line is the first observation per workspace pool depth, then at
+ * most one per interval with the count it hid. The public log projection drops
+ * the identifiers and counts, so the closed `reason` keeps the depth visible. */
+export const CODEX_POOL_LOW_WARNING_INTERVAL_MS = 10 * 60_000;
+const codexPoolLowWarningThrottle = createLogThrottle({
+  intervalMs: CODEX_POOL_LOW_WARNING_INTERVAL_MS,
+  maxKeys: 1_024,
+});
+
+export function warnCodexPoolLow(
+  observability: Pick<ActivityServices["observability"], "warn">,
+  input: {
+    workspaceKey: string;
+    workspaceId: string;
+    eligibleCount: number;
+    connectedCount: number;
+    depth: "zero" | "one";
+  },
+  throttle: LogThrottle = codexPoolLowWarningThrottle,
+): void {
+  const admission = throttle.admit(`${input.workspaceKey}:${input.depth}`);
+  if (!admission) return;
+  observability.warn("Codex eligible credential pool is low", {
+    workspaceId: input.workspaceId,
+    eligibleCount: input.eligibleCount,
+    connectedCount: input.connectedCount,
+    depth: input.depth,
+    reason: input.depth === "zero" ? "eligible_pool_zero" : "eligible_pool_one",
+    ...(admission.suppressedCount > 0 ? { suppressedCount: admission.suppressedCount } : {}),
+  });
+}
+
 export type CapacityPhaseDeps = {
   input: RunAgentTurnInput;
   settings: Settings;
@@ -402,11 +436,12 @@ export async function selectCodexTurnCapacity(
           help: "Alert signal emitted when the eligible Codex pool is zero or one.",
           labels: { workspace_key: codexWorkspaceKey, depth: poolDepth },
         });
-        observability.warn("Codex eligible credential pool is low", {
+        warnCodexPoolLow(observability, {
+          workspaceKey: codexWorkspaceKey,
           workspaceId: input.workspaceId,
           eligibleCount,
           connectedCount: leased.accounts.length,
-          depth: poolDepth,
+          depth: poolDepth === "zero" ? "zero" : "one",
         });
       }
 

package/src/activities/agent-turn/compaction-prep.ts

@@ -11,7 +11,8 @@ import {
   compactionThresholdTokens,
   CompactionNeededError,
   compactionProviderRejection,
-  SUMMARY_BUFFER_TOKENS,
+  estimateSerializedValueTokens,
+  compactionSummaryOutputTokens,
   type ModelResponseUsage,
 } from "@opengeni/runtime";
 import { type Settings } from "@opengeni/config";
@@ -168,6 +169,13 @@ export async function prepareCompaction(deps: CompactionPrepDeps): Promise<Compa
   const remotePrefix: RemoteCompactionPrefix = {
     agent: null,
   };
+  const portableResponsesNeedsAgentPrefix =
+    resolvedModel?.provider.api === "responses" &&
+    !(billingState.isCodexTurn && session.codexCompactionMode === "remote_v2");
+  const preparedPortableRequest = () => {
+    if (!remotePrefix.agent) throw new Error("Compaction agent is unavailable");
+    return preparedCompactionRequest(remotePrefix.agent);
+  };
 
   const promptCacheKey = acceptsPromptCacheKeyForTurn(resolvedModel) ? input.sessionId : undefined;
   const compactionUsageState = createCompactionModelUsageEventState(claimedModelUsageSourceKeys);
@@ -200,8 +208,8 @@ export async function prepareCompaction(deps: CompactionPrepDeps): Promise<Compa
       contextContributions: eventing.companyBrainContextContributions,
     });
   };
-  const compactionSummarizerFor = (systemInstructions?: string) =>
-    resolvedModel
+  const compactionSummarizerFor = (systemInstructions?: string): CompactionSummarizer => {
+    const summarize: CompactionSummarizer = resolvedModel
       ? (s: Settings, m: Array<Record<string, unknown>>) =>
           withProviderRequestContext(() =>
             summarizeContextForCompaction(s, m, {
@@ -209,20 +217,37 @@ export async function prepareCompaction(deps: CompactionPrepDeps): Promise<Compa
               provider: resolvedModel.provider,
               api: resolvedModel.provider.api,
               model: turnExecutionPolicy.upstreamModelId,
-              maxOutputTokens: SUMMARY_BUFFER_TOKENS,
+              maxOutputTokens: compactionSummaryOutputTokens(s.contextWindowTokens),
+              ...(cancellationSignal ? { signal: cancellationSignal } : {}),
               onUsage: recordCompactionUsage,
               ...(systemInstructions ? { systemInstructions } : {}),
               ...(promptCacheKey ? { promptCacheKey } : {}),
+              ...(portableResponsesNeedsAgentPrefix
+                ? { preparedRequest: preparedPortableRequest() }
+                : {}),
             }),
           )
       : (s: Settings, m: Array<Record<string, unknown>>) =>
           summarizeContextForCompaction(s, m, {
             model: turnExecutionPolicy.upstreamModelId,
-            maxOutputTokens: SUMMARY_BUFFER_TOKENS,
+            maxOutputTokens: compactionSummaryOutputTokens(s.contextWindowTokens),
+            ...(cancellationSignal ? { signal: cancellationSignal } : {}),
             onUsage: recordCompactionUsage,
             ...(systemInstructions ? { systemInstructions } : {}),
             ...(promptCacheKey ? { promptCacheKey } : {}),
           });
+    summarize.estimatePrefixTokens = () => {
+      if (resolvedModel?.provider.api === "chat") {
+        return estimateSerializedValueTokens(systemInstructions ?? "");
+      }
+      const prepared = portableResponsesNeedsAgentPrefix ? preparedPortableRequest() : null;
+      return (
+        estimateSerializedValueTokens(prepared?.systemInstructions ?? systemInstructions ?? "") +
+        (prepared ? estimateSerializedValueTokens(prepared.tools) : 0)
+      );
+    };
+    return summarize;
+  };
   // Prompt-cache prefix for remote_v2 MUST match ordinary turns:
   // tools → instructions → history. Filled after buildAgent for every
   // compact path (including operator /compact, which now builds the agent
@@ -265,13 +290,9 @@ export async function prepareCompaction(deps: CompactionPrepDeps): Promise<Compa
     ...(remoteCompactionRequester ? { requestRemoteCompactionV2: remoteCompactionRequester } : {}),
   } as const;
 
-  // Operator /compact:
-  // - portable (incl. Codex portable): early maintenance path — no
-  //   prepareTools/sandbox; summarizer only needs composed instructions.
-  // - remote_v2: fall through to prepareTools/buildAgent so the compact
-  //   request reuses the ordinary tools→instructions cache prefix, then
-  //   settle without inference. (Requester is also wired for Codex portable
-  //   turns but unused there — gate on the frozen session mode.)
+  // Responses compaction, portable or remote, prepares the ordinary agent
+  // request first so tool schemas and instructions match the warm cache prefix.
+  // Chat providers keep the standalone portable maintenance path.
   const compactionOnlyTurn = turn.source === "compaction";
   const remoteV2CompactionNeedsAgentPrefix =
     Boolean(remoteCompactionRequester) && session.codexCompactionMode === "remote_v2";
@@ -308,7 +329,11 @@ export async function prepareCompaction(deps: CompactionPrepDeps): Promise<Compa
     control.activityStatus = "idle";
     return claimedResult({ status: "idle" });
   };
-  if (compactionOnlyTurn && !remoteV2CompactionNeedsAgentPrefix) {
+  if (
+    compactionOnlyTurn &&
+    !remoteV2CompactionNeedsAgentPrefix &&
+    !portableResponsesNeedsAgentPrefix
+  ) {
     const compactionInstructions = appendWorkspaceMemory(
       appendSessionInstructions(
         appendWorkspaceGovernance(
@@ -466,6 +491,7 @@ export async function runPostAgentCompaction(
     claimedResult,
     turn,
     session,
+    resolvedModel,
     remotePrefix,
     remoteCompactionRequester,
     publishCompactionLiveEvents,
@@ -480,10 +506,13 @@ export async function runPostAgentCompaction(
   } = deps;
 
   const agentInstructions = typeof agent.instructions === "string" ? agent.instructions : "";
+  const preparedPortable =
+    resolvedModel?.provider.api === "responses" &&
+    !(remoteCompactionRequester && session.codexCompactionMode === "remote_v2");
   const compactSummarizer = compactionSummarizerFor(
     agentInstructions.trim() ? agentInstructions : undefined,
   );
-  if (remoteCompactionRequester) {
+  if (remoteCompactionRequester || preparedPortable) {
     // The prefix is captured only after this agent passes normal SDK preparation.
     remotePrefix.agent = agent;
   }
@@ -491,7 +520,11 @@ export async function runPostAgentCompaction(
   if (compactionOnlyTurn) {
     const requested = await isSessionCompactionRequested(db, input.workspaceId, input.sessionId);
     let outcome: Awaited<ReturnType<typeof maybeCompactContext>> | null = null;
-    if (requested && remoteCompactionRequester && session.codexCompactionMode === "remote_v2") {
+    if (
+      requested &&
+      (preparedPortable ||
+        (remoteCompactionRequester && session.codexCompactionMode === "remote_v2"))
+    ) {
       queuePreparedCompaction(
         agent,
         new CompactionNeededError({
@@ -610,7 +643,10 @@ export async function runPostAgentCompaction(
     return { exit: claimedResult({ status: "idle" }) };
   }
 
-  if (remoteCompactionRequester && session.codexCompactionMode === "remote_v2") {
+  if (
+    preparedPortable ||
+    (remoteCompactionRequester && session.codexCompactionMode === "remote_v2")
+  ) {
     const forced = await isSessionCompactionRequested(db, input.workspaceId, input.sessionId);
     const thresholdTokens = compactionThresholdTokens(eventing.modelRunSettings);
     if (