@opengeni/worker-bundle 1.0.0-canary.0 → 1.0.0

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

@@ -1,15 +1,29 @@
 import {
   advanceWorkspaceGeneration,
   verifyWorkspaceMutationSettlement,
-  heartbeatLeaseHolder,
+  heartbeatLeaseHolderStatus,
   readLease,
   accrueWarmSeconds,
   SandboxWorkspaceMutationFencedError,
+  retainWorkspaceMutationProcess,
+  retainedProviderCommandPersistence,
+  SandboxRetainedProcessPromotionFencedError,
 } from "@opengeni/db";
+import { createProviderCommandRetainer } from "@opengeni/db/retained-provider-commands";
 import {
   RoutingMutationOutcomeUnknownError,
+  ProviderCommandStartOutcomeUnknownError,
+  ProviderCommandObservationUnavailableError,
+  isModalCommandStartOutcomeUnknownError,
+  withModalCommandStartSignal,
+  resolveModalCheckpointProviderBindingForSession,
+  runManagedCodemodeClientHook,
   type EstablishedSandboxSession,
+  type ProviderCommandSession,
+  type RoutingRetainedProcess,
 } from "@opengeni/runtime";
+import { ModalRouterProviderCommand } from "@opengeni/contracts";
+import { isDeepStrictEqual } from "node:util";
 import {
   sandboxLifecycleTransitionWaitMs,
   sandboxWarmRateMicrosPerSecond,
@@ -18,7 +32,10 @@ import {
 import { createRuntimeBatcher, currentActivityContext } from "../streaming";
 import type { TurnActivityServices as ActivityServices, RunAgentTurnInput } from "../types";
 import { maybePersistWarmWorkspaceSnapshot, type ResumedTurnSandbox } from "../../sandbox-resume";
-import { recordCreditMicros } from "../../observability-metrics";
+import {
+  recordCreditMicros,
+  runtimeMetricsHooksForObservability,
+} from "../../observability-metrics";
 import { ChannelAPartialMutationError } from "@opengeni/runtime/sandbox";
 
 import { safeErrorDiagnostic } from "./errors";
@@ -46,6 +63,114 @@ export type SandboxTurnRuntimeDeps = {
 
 export type SandboxTurnRuntime = ReturnType<typeof createSandboxTurnRuntime>;
 
+const retainInternalProviderCommand = createProviderCommandRetainer(
+  retainWorkspaceMutationProcess,
+  (error) => (error instanceof SandboxRetainedProcessPromotionFencedError ? error.process : null),
+);
+
+/** Only the complete runtime producer boundary supplies a command descriptor.
+ * A bare SDK boundary can veto rejection, but its task/exec fields alone cannot
+ * establish its sandbox, PTY or complete original invocation. */
+function internalMutationUnknownCommand(
+  error: unknown,
+  instanceId: string,
+): { unknown: boolean; command: ModalRouterProviderCommand | null } {
+  const pending = [{ value: error, depth: 0 }];
+  const seen = new Set<object>();
+  const commands: ModalRouterProviderCommand[] = [];
+  let unknown = false;
+  let incomplete = false;
+  for (let inspected = 0; pending.length && inspected < 128; inspected++) {
+    const { value, depth } = pending.shift()!;
+    if (!value || typeof value !== "object" || seen.has(value)) continue;
+    seen.add(value);
+    try {
+      if (
+        value instanceof ProviderCommandStartOutcomeUnknownError ||
+        value instanceof ProviderCommandObservationUnavailableError
+      ) {
+        unknown = true;
+        // Zod reads ordinary properties. First make a bounded own-data-only
+        // copy so neither validation nor equality executes descriptor getters.
+        // This contract has no arrays, functions or symbol-keyed fields.
+        let remaining = 64;
+        const copyCommandData = (candidate: unknown, descriptorDepth = 0): unknown => {
+          if (--remaining < 0 || descriptorDepth > 4)
+            throw new Error("Internal command descriptor exceeded inspection bounds");
+          if (
+            candidate === null ||
+            candidate === undefined ||
+            typeof candidate === "string" ||
+            typeof candidate === "number" ||
+            typeof candidate === "boolean"
+          )
+            return candidate;
+          if (typeof candidate !== "object" || Array.isArray(candidate))
+            throw new Error("Internal command descriptor is not a data object");
+          const keys = Reflect.ownKeys(candidate);
+          if (keys.length > 16)
+            throw new Error("Internal command descriptor exceeded field bounds");
+          const copy: Record<string, unknown> = Object.create(null);
+          for (const key of keys) {
+            const property = Object.getOwnPropertyDescriptor(candidate, key);
+            if (typeof key !== "string" || !property || !("value" in property))
+              throw new Error("Internal command descriptor contains a non-data field");
+            copy[key] = copyCommandData(property.value, descriptorDepth + 1);
+          }
+          return copy;
+        };
+        const parsed = ModalRouterProviderCommand.safeParse(
+          copyCommandData(Object.getOwnPropertyDescriptor(value, "command")?.value),
+        );
+        if (!parsed.success || parsed.data.sandboxId !== instanceId) incomplete = true;
+        else commands.push(parsed.data);
+        // This complete producer boundary owns its original SDK cause. Do not
+        // reinterpret that cause's partial locator as a second command.
+        continue;
+      }
+      const sdkUnknown = isModalCommandStartOutcomeUnknownError(value);
+      if (sdkUnknown || value instanceof RoutingMutationOutcomeUnknownError) unknown = true;
+      const nested: unknown[] = [];
+      for (const key of ["cause", "error", "errors"] as const) {
+        const property = Object.getOwnPropertyDescriptor(value, key);
+        if (!property) continue;
+        if (!("value" in property)) {
+          incomplete = true;
+          continue;
+        }
+        if (key === "errors" && Array.isArray(property.value)) {
+          const length = Object.getOwnPropertyDescriptor(property.value, "length")?.value;
+          if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0) {
+            incomplete = true;
+            continue;
+          }
+          if (length > 64) incomplete = true;
+          for (let index = 0; index < Math.min(length, 64); index++) {
+            const element = Object.getOwnPropertyDescriptor(property.value, String(index));
+            if (!element || !("value" in element)) incomplete = true;
+            else nested.push(element.value);
+          }
+        } else if (property.value !== undefined) nested.push(property.value);
+      }
+      if (
+        sdkUnknown &&
+        (nested.length === 0 ||
+          Object.getOwnPropertyDescriptor(value, "taskId") ||
+          Object.getOwnPropertyDescriptor(value, "execId"))
+      )
+        incomplete = true;
+      if (depth >= 12 && nested.length) incomplete = true;
+      else for (const child of nested) pending.push({ value: child, depth: depth + 1 });
+    } catch {
+      incomplete = true;
+    }
+  }
+  if (pending.length) incomplete = true;
+  const command = commands[0] ?? null;
+  if (commands.some((candidate) => !isDeepStrictEqual(candidate, command))) incomplete = true;
+  return { unknown: unknown || incomplete, command: incomplete ? null : command };
+}
+
 /**
  * Provider-deadline rotation is a preemption boundary, not a cooperative
  * snapshot boundary. Snapshotting while this attempt still owns active tools
@@ -81,12 +206,62 @@ export function createSandboxTurnRuntime(deps: SandboxTurnRuntimeDeps) {
     eventing,
     attempt,
   } = deps;
+  const commandStartSignal = cancellationSignal
+    ? AbortSignal.any([cancellationSignal, sandboxRotationController.signal])
+    : sandboxRotationController.signal;
+
+  // The exact existing private release closure is the holder authority. Keep
+  // its ordinary eager release, but never pass a false writer-drain proof that
+  // would let releaseLeaseHolder settle an ambiguous null-outcome admission.
+  const releaseGuards = new WeakMap<
+    ResumedTurnSandbox["release"],
+    {
+      pending: Map<string, { operation: string; cause?: unknown }>;
+      release: ResumedTurnSandbox["release"];
+    }
+  >();
+  const guardSandboxRelease = (sandbox: ResumedTurnSandbox) => {
+    if (typeof sandbox.release !== "function") return null;
+    const original = sandbox.release;
+    let guard = releaseGuards.get(original);
+    if (!guard) {
+      const pending = new Map<string, { operation: string; cause?: unknown }>();
+      const release: ResumedTurnSandbox["release"] = async (options) => {
+        if (options?.workspaceWritersQuiesced && pending.size) {
+          await original();
+          throw new RoutingMutationOutcomeUnknownError(
+            "internalWorkspaceMutationDrain",
+            "Internal workspace command is still outcome-unknown; its admission remains fenced until exact retention or physical settlement",
+            { cause: new AggregateError([...pending.values()].map((entry) => entry.cause)) },
+          );
+        }
+        await original(options);
+      };
+      guard = { pending, release };
+      releaseGuards.set(original, guard);
+      releaseGuards.set(release, guard);
+    }
+    // Rebound preparation may use a shallow copy of the published sandbox.
+    // Protect every known copy of this SAME private holder release closure,
+    // never another lease or a newly fabricated holder.
+    for (const target of [
+      sandbox,
+      sandboxState.resolvedSandbox,
+      sandboxState.prefetchedManagedBoxResult,
+      ...(sandboxState.lateSandboxesAwaitingWriterDrain ?? []),
+    ]) {
+      if (target?.release === original || target?.release === guard.release)
+        target.release = guard.release;
+    }
+    return guard;
+  };
 
   // P1.2 ownership inversion: when sandboxOwnershipEnabled, the turn resolves
   // the one box by id from the group lease and injects it NON-OWNED into the
   // run. null when the flag is off (byte-for-byte the legacy build-and-discard
   // path) OR when the backend is "none". Released + dropped in `finally`.
   const releaseLateSandbox = async (sandbox: ResumedTurnSandbox): Promise<void> => {
+    guardSandboxRelease(sandbox);
     sandboxState.lateSandboxesAwaitingWriterDrain.add(sandbox);
     // Drop the holder/timer immediately, but keep its null-outcome admissions
     // fenced until the shared attempt writer drain completes. The staged
@@ -114,26 +289,48 @@ export function createSandboxTurnRuntime(deps: SandboxTurnRuntimeDeps) {
   // Platform setup (beforeAgentStart hooks + file materialization) execs against
   // THIS handle so a mid-turn sandbox_swap can never re-route those execs onto a
   // connected machine (the user's real computer).
-  const finalizeTurnOpStreamOps = async (): Promise<void> => {
+  const finalizeTurnOpStreamOps = async (toolCallIds?: readonly string[]): Promise<void> => {
     await finalizeDurableTurnOpStreams(
       [sandboxState.lazyOwnedSandbox?.session, sandboxState.resolvedSandbox?.established.session],
       sandboxState.machinePrimarySession,
+      toolCallIds,
     );
   };
   // A same-target API repair can replace the home provider while this turn is
   // alive. Keep setup/snapshot persistence on the rebound raw session while
   // preserving the SDK-owned routing proxy for eager turns. Lazy turns hold the
   // proxy separately, so their worker-side handle may replace its raw session.
-  const onHomeSandboxRebound = (rebound: {
+  const onHomeSandboxRebound = async (rebound: {
     established: EstablishedSandboxSession;
     leaseEpoch: number;
-  }): void => {
+  }): Promise<void> => {
     const current = sandboxState.resolvedSandbox;
+    if (!current) throw new Error("Home sandbox rebound before turn sandbox admission");
+    if (
+      rebound.established.backendId !== "selfhosted" &&
+      rebound.established.instanceId !== current.established.instanceId
+    ) {
+      // An older archive may lack this worker release's selected client. Only
+      // prepare that client, never replay turn-start hooks/credentials/resources.
+      // Fence the replacement itself, not the stale turn-start handle. Both
+      // mutation admission and settlement precede raw-state/route publication.
+      const commandFence = eventing.toolCancellationFenceRef.current;
+      await runWorkspaceMutationForSandbox(
+        { ...current, established: rebound.established, leaseEpoch: rebound.leaseEpoch },
+        "homeSandboxClientPreparation",
+        () =>
+          runManagedCodemodeClientHook(rebound.established.session as never, {
+            environment: {},
+            ...(commandFence
+              ? { commandRunner: commandFence.runSandboxCommand.bind(commandFence) }
+              : {}),
+          }),
+      );
+    }
     const previousSession = current?.established.session;
     const preserveRoutingProxy =
       current !== null && previousSession !== sandboxState.setupBoxSession;
     sandboxState.setupBoxSession = rebound.established.session;
-    if (!current) return;
     current.leaseEpoch = rebound.leaseEpoch;
     current.established = preserveRoutingProxy
       ? {
@@ -289,13 +486,116 @@ export function createSandboxTurnRuntime(deps: SandboxTurnRuntimeDeps) {
       }
     };
     let result: T;
+    const releaseGuard = guardSandboxRelease(sandbox);
+    releaseGuard?.pending.set(admission.id, { operation });
     const providerStartedAt = performance.now();
     let providerOutcome: "completed" | "failed" = "failed";
     try {
-      result = await mutation();
+      result = await withModalCommandStartSignal(commandStartSignal, mutation);
       providerOutcome = "completed";
     } catch (providerError) {
       observeMutationPhase("provider", providerOutcome, performance.now() - providerStartedAt);
+      const ambiguity = internalMutationUnknownCommand(providerError, identity.expectedInstanceId);
+      if (ambiguity.unknown) {
+        releaseGuard?.pending.set(admission.id, { operation, cause: providerError });
+        if (!ambiguity.command) {
+          throw new RoutingMutationOutcomeUnknownError(
+            operation,
+            `Platform workspace mutation "${operation}" has no unique exact command descriptor; its admission remains fenced and it was not replayed`,
+            { cause: providerError },
+          );
+        }
+        const process: RoutingRetainedProcess = {
+          id: crypto.randomUUID(),
+          providerSessionId: admission.workspaceGeneration,
+          providerCommand: ambiguity.command,
+        };
+        let exactRetentionVerified = false;
+        try {
+          const providerBinding = await resolveModalCheckpointProviderBindingForSession(
+            settings,
+            sandbox.established.session,
+          );
+          try {
+            await retainInternalProviderCommand(db, {
+              accountId: input.accountId,
+              workspaceId: input.workspaceId,
+              sessionId: input.sessionId,
+              processId: process.id,
+              providerSessionId: process.providerSessionId,
+              providerCommand: ambiguity.command,
+              admissionId: admission.id,
+              admittedWorkspaceGeneration: admission.workspaceGeneration,
+              operation,
+              providerBinding,
+              owner: { kind: "turn", ...identity },
+            });
+          } catch (promotionError) {
+            if (!(promotionError instanceof SandboxRetainedProcessPromotionFencedError))
+              throw promotionError;
+            const durable = promotionError.process;
+            if (
+              durable.id !== process.id ||
+              durable.providerSessionId !== process.providerSessionId ||
+              durable.parentAdmissionId !== admission.id ||
+              durable.accountId !== identity.accountId ||
+              durable.workspaceId !== identity.workspaceId ||
+              durable.sessionId !== identity.sessionId ||
+              durable.leaseId !== admission.leaseId ||
+              durable.sandboxGroupId !== identity.sandboxGroupId ||
+              durable.ownerActorKind !== admission.actorKind ||
+              durable.ownerActorId !== admission.actorId ||
+              durable.ownerTurnId !== identity.turnId ||
+              durable.ownerAttemptId !== identity.attemptId ||
+              durable.ownerExecutionGeneration !== identity.executionGeneration ||
+              durable.leaseEpoch !== identity.expectedEpoch ||
+              durable.providerBackend !== "modal" ||
+              durable.providerInstanceId !== identity.expectedInstanceId ||
+              durable.providerBindingKey !== providerBinding.key ||
+              !isDeepStrictEqual(durable.providerBinding, providerBinding.binding) ||
+              durable.routeKind !== admission.routeKind ||
+              durable.routeTargetId !== admission.routeTargetId ||
+              durable.routeEpoch !== admission.routeEpoch ||
+              durable.state !== "active"
+            )
+              throw promotionError;
+            // The established retainer committed BOTH locator and holder before
+            // rejecting stale output. Do not undo that physical retention.
+          }
+          const persistence = retainedProviderCommandPersistence(db, {
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            sessionId: input.sessionId,
+            processId: process.id,
+          });
+          if (!isDeepStrictEqual(await persistence.load(), ambiguity.command))
+            throw new Error("Internal command retention lost its exact original locator", {
+              cause: providerError,
+            });
+          exactRetentionVerified = true;
+          releaseGuard?.pending.delete(admission.id);
+          (sandbox.established.session as ProviderCommandSession).bindProviderCommand?.(
+            process.providerSessionId,
+            ambiguity.command,
+            persistence,
+          );
+        } catch (retentionError) {
+          throw new RoutingMutationOutcomeUnknownError(
+            operation,
+            `Platform workspace mutation "${operation}" remains outcome-unknown and its exact retention or observer binding failed; it was not replayed`,
+            {
+              cause: new AggregateError([providerError, retentionError]),
+              ...(exactRetentionVerified ? { retainedProcess: process } : {}),
+            },
+          );
+        }
+        throw new RoutingMutationOutcomeUnknownError(
+          operation,
+          `Platform workspace mutation "${operation}" has an unknown Start outcome; its exact original invocation is retained and it was not replayed`,
+          { cause: providerError, retainedProcess: process },
+        );
+      }
+      releaseGuard?.pending.delete(admission.id);
       const partialMutation = providerError instanceof ChannelAPartialMutationError;
       try {
         await settleMutation(partialMutation ? "resolved" : "rejected");
@@ -317,6 +617,7 @@ export function createSandboxTurnRuntime(deps: SandboxTurnRuntimeDeps) {
       }
       throw providerError;
     }
+    releaseGuard?.pending.delete(admission.id);
     observeMutationPhase("provider", providerOutcome, performance.now() - providerStartedAt);
     try {
       await settleMutation("resolved");
@@ -501,12 +802,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,
@@ -514,9 +818,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
@@ -532,15 +844,22 @@ 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
       // sandboxSnapshotIntervalMs, so a box death the reaper never sees
-      // (Modal hard timeout mid-busy, OOM, infra) costs at most one interval
-      // of work — a legit multi-day turn is otherwise completely unprotected
+      // (Modal hard timeout mid-busy, OOM, infra) has a recent recovery point
+      // when capture succeeds. This interval is not a maximum recovery-point
+      // age: live writers and failed captures can defer publication. A legit
+      // multi-day turn is otherwise completely unprotected
       // (the reaper only drain-persists IDLE leases). Uses the UN-proxied box
       // session (setupBoxSession): the routing veneer could swap mid-op and a
       // selfhosted target has no persistWorkspace anyway. Best-effort +
@@ -558,7 +877,13 @@ export function createSandboxTurnRuntime(deps: SandboxTurnRuntimeDeps) {
         })
       ) {
         const snapshot = maybePersistWarmWorkspaceSnapshot(
-          { db, settings, objectStorage },
+          {
+            db,
+            settings,
+            objectStorage,
+            sandboxMetrics: runtimeMetricsHooksForObservability(observability),
+            observability,
+          },
           {
             accountId: input.accountId,
             workspaceId: input.workspaceId,

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

@@ -1,11 +1,18 @@
 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 ResolvedAgentConfig,
   type ToolRef,
 } from "@opengeni/contracts";
 
@@ -17,6 +24,7 @@ const SESSION_TITLE_DESCRIPTION =
 export function shouldRequestMissingSessionTitle(input: {
   title: string | null;
   titleSource: "user" | "agent" | null;
+  agentConfig?: ResolvedAgentConfig | null;
   firstPartyMcpTools: readonly FirstPartyMcpToolName[];
   firstPartyMcpPermissions: readonly Permission[] | null;
 }): boolean {
@@ -24,16 +32,34 @@ export function shouldRequestMissingSessionTitle(input: {
   const needsSemanticTitle =
     input.titleSource !== "user" && (!title || title === AUTOMATIC_SESSION_TITLE_FALLBACK);
   if (!needsSemanticTitle) return false;
-  if (!input.firstPartyMcpTools.includes("set_session_title")) return false;
+  // Configured sessions title through the runtime, not an opted-in capability.
+  // Legacy sessions keep their exact selected-tool and permission admission.
+  if (!input.agentConfig && !input.firstPartyMcpTools.includes("set_session_title")) return false;
   const permissions = input.firstPartyMcpPermissions ?? DEFAULT_FIRST_PARTY_MCP_PERMISSIONS;
   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[];
+  agentConfig?: ResolvedAgentConfig | null;
   selectedFirstPartyMcpTools: readonly FirstPartyMcpToolName[];
   shouldRequestTitle: boolean;
   parallelGenerationAvailable: boolean;
+  routeAllowsTitleRequests: boolean;
 }): {
   promoteTitleTool: boolean;
   generateTitleInParallel: boolean;
@@ -42,9 +68,11 @@ 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;
+    (input.agentConfig != null ||
+      input.tools.some((tool) => tool.kind === "mcp" && tool.id === "opengeni"));
+  const titleRequestAllowed = titleToolAvailable && input.routeAllowsTitleRequests;
+  const generateTitleInParallel = titleRequestAllowed && input.parallelGenerationAvailable;
+  const promoteTitleTool = titleRequestAllowed && !generateTitleInParallel;
   return {
     promoteTitleTool,
     generateTitleInParallel,
@@ -57,6 +85,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>;