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

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

@@ -16,11 +16,17 @@ import {
   type CompactionProviderRejection,
   isMcpRequestTimeoutError,
   isMcpTransportConnectivityError,
-  isModalTaskExecStartDnsResolutionError,
+  isModalTaskExecStartPreDispatchUnavailableError,
+  isRoutingMutationOutcomeUnknownError,
   RoutingWorkspaceRootChangedError,
   SandboxMaterializationVerificationError,
   materializationVerificationDiagnostic,
   type MaterializationVerificationDiagnostic,
+  PROVIDER_QUOTA_EXHAUSTED_CODE,
+  type ProviderQuotaExhaustion,
+  type ProviderQuotaScope,
+  classifyProviderQuotaError,
+  providerQuotaExhaustedMessage,
   SelfhostedWorkspaceRootChangedError,
   UNKNOWN_MODEL_FINISH_REASON_CODE,
 } from "@opengeni/runtime";
@@ -33,6 +39,7 @@ import { CODEX_USAGE_EXHAUSTED_PCT } from "../codex-rotation";
 import { RetainedAttachmentTransportLimitError } from "../run-input";
 import type { CodexAccountStatus } from "@opengeni/db";
 import {
+  CODEX_USAGE_LIMIT_ERROR_TYPE,
   CodexReloginRequired,
   classifyCodexEncryptedArtifactRejection,
   classifyCodexResponseTimeoutError,
@@ -119,6 +126,7 @@ export function providerRecoveryResult(input: {
           input.failureCode === "sandbox_command_start_unavailable" ||
           input.failureCode === "mcp_transport_timeout" ||
           input.failureCode === "mcp_transport_unavailable" ||
+          input.failureCode === "turn_execution_policy_definition_mismatch" ||
           input.failureCode === POST_COMPACTION_CONTINUATION_EMPTY_CODE
         ? Math.max(
             providerDelay ?? 0,
@@ -612,6 +620,14 @@ export function compactionFailureReasonFromError(error: unknown): string {
       `the model provider rejected the compaction request (${describeCompactionProviderRejection(rejection)}). Active history was preserved. ${COMPACTION_PROVIDER_REJECTION_GUIDANCE}`,
     );
   }
+  // An exhausted provider quota is not retried (see agentRunFailurePayload),
+  // so name the refusal plainly instead of the raw diagnostic envelope.
+  const quota = classifyProviderQuotaExhaustionError(error);
+  if (quota) {
+    return compactionFailureReason(
+      `${providerQuotaExhaustedMessage(quota.scope)} Active history was preserved.`,
+    );
+  }
   if (
     error instanceof CompactionProviderResponseError ||
     error instanceof EmptyCompactionSummaryError
@@ -638,8 +654,12 @@ export function compactionFailureTurnEventPayload(
   recovery: "user_message";
   compacted: false;
   providerRejection?: CompactionProviderRejection;
+  quotaScope?: ProviderQuotaScope;
 } {
   const rejection = compactionProviderRejection(error);
+  // The same closed marker as a `provider_quota_exhausted` turn failure, so
+  // clients can name the exhausted limit and offer another model here too.
+  const quota = rejection ? null : classifyProviderQuotaExhaustionError(error);
   return {
     error: overrides.error ?? compactionFailureReasonFromError(error),
     code: "context_compaction_failed",
@@ -647,6 +667,7 @@ export function compactionFailureTurnEventPayload(
     recovery: "user_message",
     compacted: false,
     ...(rejection ? { providerRejection: rejection } : {}),
+    ...(quota ? { quotaScope: quota.scope } : {}),
   };
 }
 
@@ -844,6 +865,27 @@ export function isTransientProviderError(error: unknown): boolean {
   );
 }
 
+/** An explicit `usage_limit_reached` type or code string anywhere on the error chain. */
+function hasCodexUsageLimitType(error: unknown): boolean {
+  return collectErrorStrings(error).some((value) => value.includes(CODEX_USAGE_LIMIT_ERROR_TYPE));
+}
+
+/**
+ * Recognize an exhausted API-key provider quota (a daily or monthly allowance,
+ * a free-tier day cap, or an account out of credits) as distinct from an
+ * ordinary per-minute rate limit. Retrying within the bounded same-turn budget
+ * cannot succeed, so the turn fails promptly instead. Subscription transports
+ * own their quota semantics through credential rotation and durable capacity
+ * waits, so a Codex or SuperGrok transport error never classifies here.
+ */
+export function classifyProviderQuotaExhaustionError(
+  error: unknown,
+): ProviderQuotaExhaustion | null {
+  if (isCodexTransportError(error) || isXaiSubscriptionTransportError(error)) return null;
+  // The same reader the OpenAI SDK retry veto uses, so the two never disagree.
+  return classifyProviderQuotaError(error);
+}
+
 export type XaiCredentialFailure = {
   kind: "auth" | "forbidden" | "rate_limit";
   cooldownMs: number | null;
@@ -950,6 +992,7 @@ function baseAgentRunFailurePayload(
   historyPersistenceStage?: MandatoryHistoryPersistenceStage;
   mcpTransportDiagnostic?: McpTransportRequestFailureDiagnostic;
   materializationDiagnostic?: MaterializationVerificationDiagnostic;
+  quotaScope?: ProviderQuotaScope;
 } {
   if (error instanceof SandboxMaterializationVerificationError) {
     return {
@@ -1021,10 +1064,13 @@ function baseAgentRunFailurePayload(
       retryable: true,
     };
   }
-  if (isModalTaskExecStartDnsResolutionError(error)) {
+  if (
+    !isRoutingMutationOutcomeUnknownError(error) &&
+    isModalTaskExecStartPreDispatchUnavailableError(error)
+  ) {
     return {
       error:
-        "The managed sandbox command transport was temporarily unreachable before the command started. The same turn will retry after a short delay.",
+        "The managed sandbox command router was not ready before the command was sent. The same turn will retry after a short delay.",
       code: "sandbox_command_start_unavailable",
       retryable: true,
     };
@@ -1099,8 +1145,11 @@ function baseAgentRunFailurePayload(
   // `usage_limit_reached` shape must still outrank generic 429 retryability.
   // Credential quarantine/failover remains separately provenance-gated by
   // `isCodexTransportError`; this branch only chooses the truthful user payload.
+  // The looser "429 ... usage limit" wording counts only on a Codex transport
+  // error: an API-key provider's 429 that says "usage limit" is provider quota
+  // evidence, not a ChatGPT/Codex subscription cap.
   const usageLimit = classifyCodexUsageLimitError(error);
-  if (usageLimit) {
+  if (usageLimit && (isCodexTransportError(error) || hasCodexUsageLimitType(error))) {
     return codexUsageLimitFailurePayload(usageLimit, message);
   }
   const codexTimeout = classifyCodexResponseTimeoutError(error, {
@@ -1152,6 +1201,20 @@ function baseAgentRunFailurePayload(
       retryable: true,
     };
   }
+  // An exhausted quota also arrives as HTTP 429 (or 402), but no retry within
+  // the finite same-turn budget can succeed. Fail the turn promptly with a
+  // distinct code so the client can offer another model; ordinary short rate
+  // limits fall through to the retryable branch below.
+  const quota = classifyProviderQuotaExhaustionError(error);
+  if (quota) {
+    return {
+      error: providerQuotaExhaustedMessage(quota.scope),
+      code: PROVIDER_QUOTA_EXHAUSTED_CODE,
+      retryable: false,
+      quotaScope: quota.scope,
+      ...(message ? { detail: message } : {}),
+    };
+  }
   if (
     status === 429 ||
     code === "rate_limit_exceeded" ||

package/src/activities/agent-turn/failure-settlement.ts

@@ -16,14 +16,14 @@ import {
 } from "@opengeni/db";
 import { publishDurableSessionEvents } from "@opengeni/events";
 import { maxTurnsExceededRunState } from "@opengeni/runtime";
-import { CancelledFailure } from "@temporalio/activity";
+import { ApplicationFailure, CancelledFailure } from "@temporalio/activity";
 import {
   authoritativeCodexCapacityResetAt,
   classifyCodexPin,
   selectCodexCredentialLeaseForTurn,
   type CodexRotationStrategy,
 } from "../codex-rotation";
-import type { Settings } from "@opengeni/config";
+import { TurnExecutionPolicyDefinitionMismatchError, type Settings } from "@opengeni/config";
 import {
   classifyCodexEncryptedArtifactRejection,
   classifyCodexUsageLimitError,
@@ -1499,10 +1499,28 @@ export async function settleTurnFailure(deps: TurnFailureDeps): Promise<RunAgent
   // truth, recover this SAME accepted turn, then let the workflow re-claim
   // it after a pacing delay. This is independent of goal state and never
   // relies on a synthetic continuation prompt.
-  let failure = agentRunFailurePayload(error, {
-    isCodexTurn: billingState.isCodexTurn,
-  }) as ReturnType<typeof agentRunFailurePayload>;
-  if (failure.retryable && eventing.publish && attempt.turnId && eventing.turnStartedPublished) {
+  // A rolling-deployment definition mismatch is a separate configuration
+  // class: only the exact typed setup error can use this checkpoint before
+  // eventing exists. No generic setup/credential failure gains retry authority.
+  const earlyDefinitionMismatch =
+    error instanceof TurnExecutionPolicyDefinitionMismatchError &&
+    !attempt.modelRequestStarted &&
+    !eventing.turnStartedPublished &&
+    !!attempt.turnId &&
+    !!attempt.triggerEventId &&
+    attempt.executionGeneration > 0;
+  let failure = (
+    earlyDefinitionMismatch
+      ? { error: error.message, code: error.code, retryable: true }
+      : agentRunFailurePayload(error, {
+          isCodexTurn: billingState.isCodexTurn,
+        })
+  ) as ReturnType<typeof agentRunFailurePayload>;
+  if (
+    attempt.turnId &&
+    (earlyDefinitionMismatch ||
+      (failure.retryable && eventing.publish && eventing.turnStartedPublished))
+  ) {
     const nextProviderRecoveryCount = attempt.providerRecoveryCount + 1;
     const recoveryResult = providerRecoveryResult({
       failureCode: failure.code,
@@ -1511,8 +1529,10 @@ export async function settleTurnFailure(deps: TurnFailureDeps): Promise<RunAgent
     });
     try {
       if (recoveryResult.status === "recovering") {
-        await flushRuntimeBatcher();
-        await historySink.reconcileConversationTruth({ requireDurable: true });
+        if (!earlyDefinitionMismatch) {
+          await flushRuntimeBatcher();
+          await historySink.reconcileConversationTruth({ requireDurable: true });
+        }
         const recovery = await requestSessionTurnRecovery(db, input.workspaceId, {
           sessionId: input.sessionId,
           turnId: attempt.turnId,
@@ -1540,6 +1560,18 @@ export async function settleTurnFailure(deps: TurnFailureDeps): Promise<RunAgent
         return claimedResult(recoveryResult);
       }
       failure = providerRecoveryExhaustedFailure(failure, recoveryResult);
+      if (earlyDefinitionMismatch) {
+        // Setup has no eventing sink yet. Carry only the fixed, safe diagnostic
+        // through Temporal into exact-attempt workflow failure settlement.
+        control.activityStatus = "failed";
+        control.turnMetricOutcome = "failed";
+        control.activityError = error;
+        throw ApplicationFailure.create({
+          message: `${error.message}. Automatic same-turn configuration recovery exhausted after ${recoveryResult.providerRecoveryCount} retries.`,
+          type: "TurnExecutionPolicyDefinitionMismatchError",
+          nonRetryable: true,
+        });
+      }
     } catch (recoveryError) {
       const escaped =
         recoveryResult.status === "recovering"

package/src/activities/agent-turn/governance-model.ts

@@ -20,7 +20,11 @@ import {
   renderWorkspaceGovernanceContext,
   type OpenGeniRuntime,
 } from "@opengeni/runtime";
-import { settingsWithResolvedModelContext, type Settings } from "@opengeni/config";
+import {
+  codeSearchDeploymentPolicy,
+  settingsWithResolvedModelContext,
+  type Settings,
+} from "@opengeni/config";
 import { projectReasoningConfigurations, supportsReasoningConfiguration } from "@opengeni/codex";
 import { settingsWithSessionMcpServersForRun } from "../capabilities";
 import { resolveRigProviderImageForRun } from "@opengeni/core";
@@ -46,6 +50,7 @@ import {
   resolveWorkspaceAgentHumanInputEnabled,
   type MediaGenerationResult,
 } from "@opengeni/contracts";
+import { codeSearchEnabledForTurn } from "@opengeni/contracts/code-search";
 
 import { assertWorkspaceHumanInputAllowed } from "./admission";
 import {
@@ -89,6 +94,8 @@ export type GovernanceModelOk = {
     | null;
   rigName: string | null;
   agentHumanInputEnabled: boolean;
+  /** Deployment and workspace allow the Jev-backed code_search tool. */
+  codeSearchEnabled: boolean;
   workspaceAgentInstructions: string | null | undefined;
   workspaceGovernance: ReturnType<typeof renderWorkspaceGovernanceContext>;
   structuredWorkspacePolicyActive: boolean;
@@ -230,6 +237,14 @@ export async function prepareGovernanceAndModel(
   workspaceRefs.rigVersionId = session.rigVersionId ?? "";
   if (!workspace) throw new Error(`Workspace not found: ${input.workspaceId}`);
   const agentHumanInputEnabled = resolveWorkspaceAgentHumanInputEnabled(workspace.settings);
+  // The session's decision was frozen when it was created, so only a
+  // deliberate switch-off (deployment or workspace Off), or undoing one,
+  // changes its tool list.
+  const codeSearchEnabled = codeSearchEnabledForTurn(
+    session.codeSearchEnabled,
+    workspace.settings,
+    codeSearchDeploymentPolicy(capabilitySettings),
+  );
   const contextSelection = await resolveCompanyBrainContextSelection(db, governanceClaims);
   const workspaceAgentInstructions = contextSelection.legacyWorkspaceInstructions;
   const memoryPromptMode = contextSelection.receipt.memoryPromptMode;
@@ -460,6 +475,7 @@ export async function prepareGovernanceAndModel(
       rigVersion,
       rigName,
       agentHumanInputEnabled,
+      codeSearchEnabled,
       workspaceAgentInstructions,
       workspaceGovernance,
       structuredWorkspacePolicyActive,

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

@@ -186,7 +186,20 @@ export function toolCallProducesRetainableSessionImage(name: string | null): boo
   return (
     name === "computer_screenshot" ||
     name === "view_image" ||
-    name === "interaction__computer_observe"
+    name === "interaction__computer_observe" ||
+    retainableBrowserScreenshotToolCall(name)
+  );
+}
+
+/** Browser interactions can carry an image block, including opt-in observe frames. */
+export function retainableBrowserScreenshotToolCall(name: string | null): boolean {
+  return (
+    name === "browser_screenshot" ||
+    name === "interaction__browser_screenshot" ||
+    name === "browser_observe" ||
+    name === "interaction__browser_observe" ||
+    name === "browser_act" ||
+    name === "interaction__browser_act"
   );
 }
 

package/src/activities/agent-turn/media-artifacts.ts

@@ -12,7 +12,7 @@ import {
   type TurnToolCancellationFence,
 } from "@opengeni/runtime";
 import type { Settings } from "@opengeni/config";
-import type { RetainedArtifactMetadata } from "@opengeni/contracts";
+import type { RetainedArtifactMetadata, RetainedSessionScreenshotKind } from "@opengeni/contracts";
 import type { ResumedTurnSandbox } from "../../sandbox-resume";
 import type { SharedActivityServices } from "../types";
 import {
@@ -79,6 +79,7 @@ export class TurnMediaArtifacts {
   sandboxFileDownloadBackend: Settings["sandboxBackend"];
   nativeImageGenerationRetention: NativeImageGenerationRetention | null = null;
   readonly retainedSessionImageCallIds = new Set<string>();
+  readonly retainedSessionImageKindsByCallId = new Map<string, RetainedSessionScreenshotKind>();
 
   constructor(private readonly deps: TurnMediaArtifactDeps) {
     this.sandboxFileDownloadBackend = deps.getModelRunSettings().sandboxBackend;

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

@@ -535,6 +535,7 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
             rigVersion,
             rigName,
             agentHumanInputEnabled,
+            codeSearchEnabled,
             workspaceAgentInstructions,
             workspaceGovernance,
             structuredWorkspacePolicyActive,
@@ -1278,6 +1279,7 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
             turnExecutionPolicy,
             trigger,
             runSettings,
+            resolvedModel,
             lazyToolTransport,
             turnTools,
             connectionScope,
@@ -1289,6 +1291,7 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
             credentialSubjectId,
             interactionInterventionResume,
             runWorkspaceMutationForSandbox,
+            codeSearchEnabled,
             throwIfWorkerShuttingDown,
             throwIfTurnCancelled,
           });
@@ -1352,6 +1355,7 @@ export function createRunAgentTurnActivity(services: () => Promise<ActivityServi
             connectorActionPolicy,
             trigger,
             preparationIndependentToolNames,
+            codeSearchAvailable: toolRuntime.codeSearchAvailable,
             videoGenerationAcceptancesByCallId,
             activeSandboxBackend,
             groupBoxBackend,

package/src/activities/agent-turn/sandbox-establish.ts

@@ -35,7 +35,11 @@ import {
 import { rigProviderImageSourceImage } from "../sandbox-images";
 import type { TurnActivityServices as ActivityServices, RunAgentTurnInput } from "../types";
 import type { currentActivityContext } from "../streaming";
-import { resumeBoxForTurn, type ResumedTurnSandbox } from "../../sandbox-resume";
+import {
+  createFreshSandboxReadinessReplacementBudget,
+  resumeBoxForTurn,
+  type ResumedTurnSandbox,
+} from "../../sandbox-resume";
 import {
   wrapTurnBoxWithRouting,
   wrapLazyTurnBoxWithRouting,
@@ -298,6 +302,9 @@ export async function resolveSandboxRoute(deps: SandboxRouteDeps): Promise<Sandb
 }
 
 export async function establishTurnSandbox(deps: EstablishTurnSandboxDeps): Promise<void> {
+  // One fresh-box readiness replacement per turn attempt, shared by the eager
+  // establish and every lazy provisioner retry of this attempt.
+  const freshSandboxReadinessReplacementBudget = createFreshSandboxReadinessReplacementBudget();
   const {
     input,
     settings,
@@ -592,6 +599,8 @@ export async function establishTurnSandbox(deps: EstablishTurnSandboxDeps): Prom
                 logicalFallbackSettings: logicalSandboxSettings,
                 cancellationSignal: sandboxResumeSignal,
                 sandboxMetrics: runtimeMetricsHooksForObservability(observability),
+                observability,
+                freshSandboxReadinessReplacementBudget,
                 onSandboxLost: publishSandboxLost,
                 objectStorage,
               },
@@ -667,6 +676,8 @@ export async function establishTurnSandbox(deps: EstablishTurnSandboxDeps): Prom
                 logicalFallbackSettings: logicalSandboxSettings,
                 cancellationSignal: sandboxResumeSignal,
                 sandboxMetrics: runtimeMetricsHooksForObservability(observability),
+                observability,
+                freshSandboxReadinessReplacementBudget,
                 onSandboxLost: publishSandboxLost,
                 objectStorage,
               },

package/src/activities/agent-turn/sandbox-runtime.ts

@@ -1,7 +1,7 @@
 import {
   advanceWorkspaceGeneration,
   verifyWorkspaceMutationSettlement,
-  heartbeatLeaseHolder,
+  heartbeatLeaseHolderStatus,
   readLease,
   accrueWarmSeconds,
   SandboxWorkspaceMutationFencedError,
@@ -526,12 +526,15 @@ export function createSandboxTurnRuntime(deps: SandboxTurnRuntimeDeps) {
     // home turn that degraded to the cloud group box (swap-away / flag-off), that
     // is the deployment default (modal), so the fallback box is warm-metered at
     // the cloud rate instead of selfhosted's rate-0 (which would under-bill).
-    const warmRate = sandboxWarmRateMicrosPerSecond(
-      settings,
-      warmBackend ?? (sandbox.established.backendId as Settings["sandboxBackend"]),
-    );
+    const warmRate =
+      settings.sandboxWarmBillingMode === "usage_only"
+        ? 0
+        : sandboxWarmRateMicrosPerSecond(
+            settings,
+            warmBackend ?? (sandbox.established.backendId as Settings["sandboxBackend"]),
+          );
     sandboxState.leaseHeartbeatTimer = setInterval(() => {
-      void heartbeatLeaseHolder(db, {
+      void heartbeatLeaseHolderStatus(db, {
         accountId: input.accountId,
         workspaceId: input.workspaceId,
         sandboxGroupId: heartbeatGroupId,
@@ -539,9 +542,17 @@ export function createSandboxTurnRuntime(deps: SandboxTurnRuntimeDeps) {
         holderId: heartbeatHolderId,
         leaseTtlMs: settings.sandboxLeaseTtlMs,
         expectedEpoch: heartbeatEpoch,
+        billingMode: settings.sandboxWarmBillingMode,
       })
-        .then(async (alive) => {
-          if (alive) return;
+        .then(async (status) => {
+          if (status.fence === "funding") {
+            stopLeaseHeartbeat();
+            sandboxRotationController.abort(
+              new Error("Insufficient OpenGeni credits to extend paid sandbox compute"),
+            );
+            return;
+          }
+          if (status.leaseExtended) return;
           const rotation = await beginRotationPreemption(sandbox, heartbeatEpoch, heartbeatGroupId);
           if (rotation === "not_rotating") {
             // The holder was reaped, the exact attempt closed, the epoch was
@@ -557,9 +568,14 @@ export function createSandboxTurnRuntime(deps: SandboxTurnRuntimeDeps) {
         sandboxGroupId: heartbeatGroupId,
         expectedEpoch: heartbeatEpoch,
         warmRateMicrosPerSecond: warmRate,
+        billingMode: settings.sandboxWarmBillingMode,
         subjectId: input.sessionId,
       })
-        .then((result) => recordCreditMicros(observability, "usage", result.costMicros))
+        .then((result) => {
+          if (settings.sandboxWarmBillingMode === "credits") {
+            recordCreditMicros(observability, "usage", result.costMicros);
+          }
+        })
         .catch(() => undefined);
       // MID-SESSION snapshot (sandbox-file-persistence): while the turn holds
       // the box, fold a fresh /workspace snapshot onto the lease every

package/src/activities/agent-turn/session-title.ts

@@ -1,9 +1,15 @@
 import { hasPermission } from "@opengeni/core";
 import type { AttemptToolDefinition } from "@opengeni/codemode";
-import type { GeneratedSessionTitle } from "@opengeni/runtime";
+import { isManagedOpenRouterFreeRoute, type ModelCapabilitiesV1 } from "@opengeni/config";
+import type {
+  GeneratedSessionTitle,
+  GenerateSessionTitleOptions,
+  OpenGeniRuntime,
+} from "@opengeni/runtime";
 import {
   AUTOMATIC_SESSION_TITLE_FALLBACK,
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
+  ReasoningEffort,
   type FirstPartyMcpToolName,
   type Permission,
   type ToolRef,
@@ -29,11 +35,26 @@ export function shouldRequestMissingSessionTitle(input: {
   return hasPermission([...permissions], "sessions:control");
 }
 
+/**
+ * Whether the turn's route can afford a model request spent only on a title.
+ * The managed OpenRouter free route draws on one deployment-wide per-minute
+ * and per-day request quota that users' turns need, so an untitled session on
+ * it gets no title sidecar and no title tool (whose call would cost a
+ * follow-up request). Clients keep showing the prompt preview, and a later
+ * turn on another route titles the session.
+ */
+export function routeAllowsSessionTitleRequests(
+  resolvedModel: ReturnType<OpenGeniRuntime["resolveTurnModel"]>,
+): boolean {
+  return !resolvedModel || !isManagedOpenRouterFreeRoute(resolvedModel);
+}
+
 export function sessionTitleToolPlan(input: {
   tools: readonly ToolRef[];
   selectedFirstPartyMcpTools: readonly FirstPartyMcpToolName[];
   shouldRequestTitle: boolean;
   parallelGenerationAvailable: boolean;
+  routeAllowsTitleRequests: boolean;
 }): {
   promoteTitleTool: boolean;
   generateTitleInParallel: boolean;
@@ -43,8 +64,9 @@ export function sessionTitleToolPlan(input: {
   const titleToolAvailable =
     input.shouldRequestTitle &&
     input.tools.some((tool) => tool.kind === "mcp" && tool.id === "opengeni");
-  const generateTitleInParallel = titleToolAvailable && input.parallelGenerationAvailable;
-  const promoteTitleTool = titleToolAvailable && !generateTitleInParallel;
+  const titleRequestAllowed = titleToolAvailable && input.routeAllowsTitleRequests;
+  const generateTitleInParallel = titleRequestAllowed && input.parallelGenerationAvailable;
+  const promoteTitleTool = titleRequestAllowed && !generateTitleInParallel;
   return {
     promoteTitleTool,
     generateTitleInParallel,
@@ -57,6 +79,54 @@ export function sessionTitleToolPlan(input: {
 
 export const PARALLEL_SESSION_TITLE_TIMEOUT_MS = 15_000;
 
+/**
+ * The lowest reasoning effort the resolved model can run, for the auxiliary
+ * title request only. A title needs no deliberation, and a provider default
+ * effort can use most of the output budget before any visible text. Returns
+ * undefined when the model declares no runnable reasoning control, so the
+ * request carries no reasoning parameter.
+ */
+export function sessionTitleReasoningEffort(
+  capabilities: Pick<ModelCapabilitiesV1, "reasoning"> | undefined,
+): ReasoningEffort | undefined {
+  const reasoning = capabilities?.reasoning;
+  if (!reasoning?.runnable) return undefined;
+  const order = ReasoningEffort.options;
+  let lowest: ReasoningEffort | undefined;
+  for (const effort of reasoning.efforts) {
+    if (!lowest || order.indexOf(effort) < order.indexOf(lowest)) lowest = effort;
+  }
+  return lowest;
+}
+
+/**
+ * Options for the parallel title request. It uses the turn's resolved
+ * provider and credential authority, but its own lowest runnable reasoning
+ * effort rather than the turn's effort.
+ */
+export function sessionTitleGenerationOptions(input: {
+  resolvedModel: ReturnType<OpenGeniRuntime["resolveTurnModel"]>;
+  modelName: string;
+  serviceTier: GenerateSessionTitleOptions["serviceTier"] | null | undefined;
+  signal: AbortSignal;
+}): GenerateSessionTitleOptions {
+  const { resolvedModel, serviceTier } = input;
+  const reasoningEffort = sessionTitleReasoningEffort(resolvedModel?.configured.capabilities);
+  return {
+    ...(resolvedModel
+      ? {
+          client: resolvedModel.client,
+          provider: resolvedModel.provider,
+          model: resolvedModel.model,
+        }
+      : {}),
+    modelName: input.modelName,
+    ...(serviceTier ? { serviceTier } : {}),
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+    signal: input.signal,
+  };
+}
+
 export type ParallelSessionTitleGeneration = {
   finish: () => Promise<GeneratedSessionTitle | null>;
   cancel: () => Promise<void>;