@opengeni/core 0.21.2 → 0.24.1

package/src/domain/sessions.ts

@@ -35,6 +35,8 @@ import {
   type SessionMcpCredentialUpdateInput,
   type SessionMcpServerInput,
   type SessionMcpServerMetadata,
+  type SubmittedTimelineAnnotation,
+  type TimelineAnnotation,
   type UpdateSessionMcpApprovalPolicyResponse,
   type UpdateSessionToolPolicyRequest,
   type SessionAuthorizationPort,
@@ -59,7 +61,6 @@ import {
   getSession,
   SessionIdConflictError,
   getSessionSpawnDenialByIdempotencyKey,
-  getSessionEvent,
   getWorkspaceControlEvent,
   getSessionLineage,
   getSessionTurn,
@@ -71,12 +72,13 @@ import {
   submitHumanPromptInTransaction,
   appendSessionEventsWithLockedSessionUpdate,
   updateSessionTitle as updateSessionTitleRow,
-  withWorkspaceSubjectRls,
+  withWorkspaceSubjectSessionActivityRls,
   type CreateSessionMcpServerInput,
   type Database,
   type UpdateSessionMcpServerCredentialsInput,
   QueueCommandConflictError,
   AgentCommandAuthorityError,
+  runIdempotentPersistenceTransaction,
   SessionSpawnDeniedDbError,
   SessionControlConflictError,
   SessionToolPolicyVersionConflictError,
@@ -99,6 +101,7 @@ import type {
 import { requireSessionAuthorization } from "../session-authorization";
 import { swapActiveSandbox, type FleetContext } from "../sandbox/fleet";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
+import { validateSubmittedTimelineAnnotations } from "./timeline-annotations";
 import { requireVariableSetEncryption, validateVariableSetAttachment } from "./environments";
 import {
   freezePersonalConnectionDelegations,
@@ -241,7 +244,9 @@ export function creationInitiatorForGrant(grant: AccessGrant): FrozenCreationIni
       !Number.isSafeInteger(callerExecutionGeneration) ||
       callerExecutionGeneration < 1
     ) {
-      throw new HTTPException(403, { message: "caller attempt claims are incomplete" });
+      throw new HTTPException(403, {
+        message: "caller attempt claims are incomplete",
+      });
     }
     const actor = {
       type: "agent_attempt",
@@ -284,11 +289,15 @@ function normalizedSessionMcpCredentialHeaders(
   const seen = new Set<string>();
   for (const [name, value] of entries) {
     if (!sessionMcpCredentialHeaderName.test(name)) {
-      throw new HTTPException(422, { message: `invalid credential header name: ${name}` });
+      throw new HTTPException(422, {
+        message: `invalid credential header name: ${name}`,
+      });
     }
     const lower = name.toLowerCase();
     if (seen.has(lower)) {
-      throw new HTTPException(422, { message: `duplicate credential header name: ${name}` });
+      throw new HTTPException(422, {
+        message: `duplicate credential header name: ${name}`,
+      });
     }
     seen.add(lower);
     if (value.length === 0 || value.length > maxSessionMcpCredentialHeaderValueLength) {
@@ -388,11 +397,15 @@ function validateSessionMcpServersForCreate(
   const metadata: SessionMcpServerMetadata[] = [];
   for (const server of servers) {
     if (seenIds.has(server.id)) {
-      throw new HTTPException(422, { message: `duplicate session MCP server id: ${server.id}` });
+      throw new HTTPException(422, {
+        message: `duplicate session MCP server id: ${server.id}`,
+      });
     }
     seenIds.add(server.id);
     if (reservedSessionMcpServerIds.has(server.id) || existingIds.has(server.id)) {
-      throw new HTTPException(422, { message: `MCP server id already exists: ${server.id}` });
+      throw new HTTPException(422, {
+        message: `MCP server id already exists: ${server.id}`,
+      });
     }
     const headers = normalizedSessionMcpCredentialHeaders(server.headers);
     const headersEncrypted = Object.fromEntries(
@@ -490,7 +503,9 @@ function validateSessionMcpCredentialUpdates(input: {
     }
     seenIds.add(update.id);
     if (!knownIds.has(update.id)) {
-      throw new HTTPException(422, { message: `unknown session MCP server id: ${update.id}` });
+      throw new HTTPException(422, {
+        message: `unknown session MCP server id: ${update.id}`,
+      });
     }
     const headers = normalizedSessionMcpCredentialHeaders(update.headers);
     return {
@@ -506,7 +521,22 @@ function validateSessionMcpCredentialUpdates(input: {
   return encryptedUpdates;
 }
 
-export async function createAndStartSession(input: {
+export type CreateSessionOutcome = {
+  session: CreateSessionResponse;
+  /** The committed create/start effect represented by this request. */
+  outcome: "created" | "repaired" | "replayed";
+  /** Backward-compatible replay flag for existing entity-oriented callers. */
+  replay: boolean;
+  /** True when the request created/repaired start state or committed a new wake revision. */
+  changed: boolean;
+};
+
+export type CreateSessionRequestOutcome = CreateSessionOutcome & {
+  /** Billing telemetry is recorded after the committed session start. */
+  usageRecording: "recorded" | "failed";
+};
+
+export async function createAndStartSessionWithOutcome(input: {
   requestedSessionId?: string;
   db: Database;
   bus: EventBus;
@@ -587,17 +617,24 @@ export async function createAndStartSession(input: {
   // target fails the create (422) — never a silent fall-back to the default box.
   // `workingDir` (optional) is the path/cwd base the chosen machine runs under,
   // seeded alongside the pointer through the epoch-fenced CAS.
-  seedTargetSandbox?: { sandboxId: string; settings: Settings; workingDir?: string | null } | null;
+  seedTargetSandbox?: {
+    sandboxId: string;
+    settings: Settings;
+    workingDir?: string | null;
+  } | null;
   // Exact actor-private pre-session draft represented by this create. The
   // initializer consumes it only after the first durable runnable unit commits.
-  consumeNewSessionDraft?: { subjectId: string; expectedRevision: number } | null;
+  consumeNewSessionDraft?: {
+    subjectId: string;
+    expectedRevision: number;
+  } | null;
   // A child may lower its inherited nested-agent depth limit freely; increases
   // are authorized by the caller's workspace:admin grant and checked again by
   // the database admission transaction.
   maxNestedAgentDepthOverride?: number | null;
   allowNestedAgentDepthIncrease?: boolean;
   subjectId?: string | null;
-}): Promise<CreateSessionResponse> {
+}): Promise<CreateSessionOutcome> {
   const sessionMetadata = {
     ...input.metadata,
     model: input.model,
@@ -647,12 +684,24 @@ export async function createAndStartSession(input: {
     }
     const { session: keyed, created } = keyedResult;
     if (!created) {
-      return await finishStartSession(
+      const finished = await finishStartSession(
         keyed.temporalWorkflowId ? { ...input, seedTargetSandbox: null } : input,
         keyed,
       );
+      return {
+        session: finished.session,
+        outcome: finished.changed ? "repaired" : "replayed",
+        replay: !finished.changed,
+        changed: finished.changed,
+      };
     }
-    return await finishStartSession(input, keyed);
+    const finished = await finishStartSession(input, keyed);
+    return {
+      session: finished.session,
+      outcome: "created",
+      replay: false,
+      changed: true,
+    };
   }
   let session: Session;
   try {
@@ -694,7 +743,20 @@ export async function createAndStartSession(input: {
     }
     throw error;
   }
-  return await finishStartSession(input, session);
+  const finished = await finishStartSession(input, session);
+  return {
+    session: finished.session,
+    outcome: "created",
+    replay: false,
+    changed: true,
+  };
+}
+
+/** Backward-compatible entity-returning create path used by existing callers. */
+export async function createAndStartSession(
+  input: Parameters<typeof createAndStartSessionWithOutcome>[0],
+): Promise<CreateSessionResponse> {
+  return (await createAndStartSessionWithOutcome(input)).session;
 }
 
 /**
@@ -727,10 +789,13 @@ async function finishStartSession(
       settings: Settings;
       workingDir?: string | null;
     } | null;
-    consumeNewSessionDraft?: { subjectId: string; expectedRevision: number } | null;
+    consumeNewSessionDraft?: {
+      subjectId: string;
+      expectedRevision: number;
+    } | null;
   },
   session: Session,
-): Promise<CreateSessionResponse> {
+): Promise<{ session: CreateSessionResponse; changed: boolean }> {
   // Create-time machine targeting (A-2a): seed the active-sandbox pointer BEFORE
   // the atomic initial turn transaction, so the FIRST turn routes to the chosen
   // machine. swapActiveSandbox does
@@ -750,7 +815,11 @@ async function finishStartSession(
       sessionGroupId: session.sandboxGroupId,
     };
     const seeded = await swapActiveSandbox(
-      { db: input.db, settings: input.seedTargetSandbox.settings, bus: input.bus },
+      {
+        db: input.db,
+        settings: input.seedTargetSandbox.settings,
+        bus: input.bus,
+      },
       ctx,
       input.seedTargetSandbox.sandboxId,
       // The working dir is committed in the SAME epoch-fenced CAS that seeds the
@@ -773,7 +842,10 @@ async function finishStartSession(
     createdEventPayload: {
       toolPolicy: input.toolPolicy,
       ...(input.variableSet
-        ? { variableSetId: input.variableSet.id, variableSetName: input.variableSet.name }
+        ? {
+            variableSetId: input.variableSet.id,
+            variableSetName: input.variableSet.name,
+          }
         : {}),
       ...(input.sessionMcpServers?.length ? { mcpServers: input.sessionMcpServers } : {}),
     },
@@ -806,7 +878,10 @@ async function finishStartSession(
     started.turn?.id ??
     (await listSessionTurns(input.db, session.workspaceId, session.id, 1))[0]?.id ??
     null;
-  return { ...persisted, initialTurnId };
+  return {
+    session: { ...persisted, initialTurnId },
+    changed: started.changed,
+  };
 }
 
 export function workflowIdForSession(sessionId: string): string {
@@ -820,10 +895,10 @@ export function workflowIdForSession(sessionId: string): string {
  * it cannot be resolved to a provider at run time, so we fail the request at
  * the API edge with 422 rather than enqueuing a turn the worker can't honor.
  *
- * `model` is the explicit, caller-supplied value (null/undefined when omitted).
- * An omitted model defaults to `settings.openaiModel` downstream — which is
- * always first in `configuredAllowedModels` — so only an explicit value is
- * checked. Centralized here so every model-carrying choke point
+ * `model` is the effective value selected by the caller's boundary. Top-level
+ * omission defaults to `settings.openaiModel`; child-session omission inherits
+ * the worker-signed calling turn before reaching this helper. Centralized here
+ * so every model-carrying choke point
  * (create-session, user-message/turn-accept, queued-turn update, and
  * scheduled-task agentConfig — a scheduled task is a session the worker runs
  * later) and the MCP surfaces that share them validate identically and cannot
@@ -980,6 +1055,7 @@ export async function postUserMessageTurn(input: {
   workspaceId: string;
   sessionId: string;
   text: string;
+  annotations?: TimelineAnnotation[];
   turnInstructions?: string | null;
   resources: ResourceRef[];
   model?: string | null;
@@ -997,7 +1073,14 @@ export async function postUserMessageTurn(input: {
   expectedDraftRevision?: number | null;
   reasoningEffortFallback?: Settings["openaiReasoningEffort"];
   turnExecutionPolicy: TurnExecutionPolicyV1;
-}): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
+  recordAgentRunUsage?: boolean;
+  schedulePostCommit?: (task: () => Promise<void>) => void;
+}): Promise<{
+  accepted: SessionEvent;
+  turn: SessionTurn;
+  interruptionCount: number;
+  replay: boolean;
+}> {
   const { db, bus, workflowClient, settings, accountId, workspaceId, sessionId } = input;
   const requestedModel = canonicalConfiguredModel(settings, input.model ?? null) ?? null;
   const requestedReasoningEffort = input.reasoningEffort ?? null;
@@ -1018,35 +1101,50 @@ export async function postUserMessageTurn(input: {
   const operationKey = input.clientEventId ?? crypto.randomUUID();
   let result;
   try {
-    result = await withWorkspaceSubjectRls(db, workspaceId, input.actor ?? accountId, (scoped) =>
-      scoped.transaction((tx) =>
-        submitHumanPromptInTransaction(tx as unknown as Database, {
-          accountId,
+    result = await runIdempotentPersistenceTransaction(
+      {
+        stage: "session.prompt.submit",
+        eventTypes: ["user.message", "turn.queued", "session.status.changed"],
+        maxAttempts: 3,
+      },
+      async () =>
+        await withWorkspaceSubjectSessionActivityRls(
+          db,
           workspaceId,
-          sessionId,
-          subjectId: input.actor ?? accountId,
-          ...(input.actorLabel ? { subjectLabel: input.actorLabel } : {}),
-          actor: input.commandActor ?? {
-            type: "human",
-            subjectId: input.actor ?? accountId,
-          },
-          operationKey,
-          delivery: input.delivery ?? "send",
-          controlEtag: input.controlEtag ?? null,
-          expectedDraftRevision: input.expectedDraftRevision ?? null,
-          text: input.text,
-          turnInstructions: input.turnInstructions ?? null,
-          resources: input.resources,
-          model: requestedModel,
-          reasoningEffort: requestedReasoningEffort,
-          latencyMode: input.latencyMode ?? null,
-          reasoningEffortFallback: input.reasoningEffortFallback ?? settings.openaiReasoningEffort,
-          turnExecutionPolicy: input.turnExecutionPolicy,
-          source: input.origin === "operator" ? "api" : "user",
-          personalConnectionDelegations: input.personalConnectionDelegations ?? [],
-          mcpCredentialUpdates: input.mcpCredentialUpdates ?? [],
-        }),
-      ),
+          input.actor ?? accountId,
+          (scoped) =>
+            submitHumanPromptInTransaction(scoped, {
+              accountId,
+              workspaceId,
+              sessionId,
+              subjectId: input.actor ?? accountId,
+              ...(input.actorLabel ? { subjectLabel: input.actorLabel } : {}),
+              actor: input.commandActor ?? {
+                type: "human",
+                subjectId: input.actor ?? accountId,
+              },
+              operationKey,
+              delivery: input.delivery ?? "send",
+              controlEtag: input.controlEtag ?? null,
+              expectedDraftRevision: input.expectedDraftRevision ?? null,
+              text: input.text,
+              annotations: input.annotations ?? [],
+              turnInstructions: input.turnInstructions ?? null,
+              resources: input.resources,
+              model: requestedModel,
+              reasoningEffort: requestedReasoningEffort,
+              latencyMode: input.latencyMode ?? null,
+              reasoningEffortFallback:
+                input.reasoningEffortFallback ?? settings.openaiReasoningEffort,
+              turnExecutionPolicy: input.turnExecutionPolicy,
+              source: input.origin === "operator" ? "api" : "user",
+              ...(input.recordAgentRunUsage !== undefined
+                ? { recordAgentRunUsage: input.recordAgentRunUsage }
+                : {}),
+              personalConnectionDelegations: input.personalConnectionDelegations ?? [],
+              mcpCredentialUpdates: input.mcpCredentialUpdates ?? [],
+            }),
+        ),
     );
   } catch (error) {
     if (
@@ -1063,53 +1161,68 @@ export async function postUserMessageTurn(input: {
     }
     throw error;
   }
-  const events = await Promise.all(
-    result.eventIds.map((eventId) => getSessionEvent(db, workspaceId, eventId)),
-  );
-  if (events.some((event) => event === null)) {
-    throw new Error("Committed prompt events could not be reloaded");
-  }
-  const turn = await getSessionTurn(db, workspaceId, result.turnId);
-  if (!turn) throw new Error("Committed prompt turn could not be reloaded");
-  const accepted = events.find((event) => event?.id === result.acceptedEventId);
-  if (!accepted) throw new Error("Committed user.message event could not be reloaded");
-  await publishDurableSessionEvents(
-    bus,
-    workspaceId,
-    sessionId,
-    events.filter((event): event is SessionEvent => event !== null),
-  );
-  if (result.workspaceControlEventId) {
-    const controlEvent = await getWorkspaceControlEvent(
-      db,
-      workspaceId,
-      result.workspaceControlEventId,
-    );
-    if (!controlEvent) {
-      throw new Error(
-        `Committed workspace control event disappeared: ${result.workspaceControlEventId}`,
-      );
+  const postCommitTask = async () => {
+    try {
+      await publishDurableSessionEvents(bus, workspaceId, sessionId, result.events);
+      if (result.workspaceControlEventId) {
+        const controlEvent = await getWorkspaceControlEvent(
+          db,
+          workspaceId,
+          result.workspaceControlEventId,
+        );
+        if (!controlEvent) {
+          throw new Error(
+            `Committed workspace control event disappeared: ${result.workspaceControlEventId}`,
+          );
+        }
+        await publishDurableWorkspaceControlEvent(bus, workspaceId, controlEvent);
+      }
+    } catch {
+      console.warn("[sessions] prompt event fanout failed; durable rows remain replayable", {
+        errorClass: "PromptEventFanoutOperationError",
+        errorCode: "session_prompt_event_fanout_failed",
+        origin: "core",
+      });
     }
-    await publishDurableWorkspaceControlEvent(bus, workspaceId, controlEvent);
-  }
+    try {
+      await workflowClient.wakeSessionWorkflow({
+        accountId,
+        workspaceId,
+        sessionId,
+        workflowId: result.turn.temporalWorkflowId,
+        wakeRevision: result.wakeRevision,
+        ...((input.delivery ?? "send") === "steer" || result.interruptionCount > 0
+          ? { interruptionRequested: true }
+          : {}),
+      });
+    } catch {
+      console.warn("[sessions] workflow wake failed; durable outbox will retry", {
+        errorClass: "WorkflowWakeOperationError",
+        errorCode: "session_workflow_wake_failed",
+        origin: "core",
+      });
+    }
+  };
+  const schedulePostCommit =
+    input.schedulePostCommit ??
+    ((task: () => Promise<void>) => {
+      void task();
+    });
   try {
-    await workflowClient.wakeSessionWorkflow({
-      accountId,
-      workspaceId,
-      sessionId,
-      workflowId: turn.temporalWorkflowId,
-      wakeRevision: result.wakeRevision,
-      ...((input.delivery ?? "send") === "steer" || result.interruptionCount > 0
-        ? { interruptionRequested: true }
-        : {}),
+    schedulePostCommit(postCommitTask);
+  } catch {
+    console.warn("[sessions] prompt post-commit scheduling failed; durable recovery remains", {
+      errorClass: "PromptPostCommitScheduleError",
+      errorCode: "session_prompt_post_commit_schedule_failed",
+      origin: "core",
     });
-  } catch (error) {
-    console.warn(
-      `[sessions] workflow wake failed for committed prompt ${workspaceId}/${sessionId}; durable outbox will retry`,
-      error,
-    );
   }
-  return { accepted, turn };
+  return {
+    accepted: result.accepted,
+    turn: result.turn,
+    interruptionCount: result.interruptionCount,
+    replay: result.replay,
+  };
 }
 
 /**
@@ -1121,12 +1234,12 @@ export async function postUserMessageTurn(input: {
  * trusted immediate parent, while explicit arrays (including []) win. A
  * top-level create with omitted tools applies workspace-default capability MCPs.
  */
-export async function createSessionForRequest(
+export async function createSessionForRequestWithOutcome(
   deps: ApiRouteDeps,
   grant: AccessGrant,
   workspaceId: string,
   rawPayload: unknown,
-): Promise<Session> {
+): Promise<CreateSessionRequestOutcome> {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   const payload = CreateSessionRequest.parse(rawPayload);
   if (hasReservedOpenGeniSlackBotSessionMetadata(payload.metadata)) {
@@ -1169,10 +1282,24 @@ export async function createSessionForRequest(
       message: `parent session not found in workspace: ${parentSessionId}`,
     });
   }
+  const creationInitiator = creationInitiatorForGrant(grant);
+  const parentCallingTurn =
+    parentSession && creationInitiator.actor
+      ? await getSessionTurn(db, workspaceId, creationInitiator.actor.turnId)
+      : null;
+  if (
+    creationInitiator.actor &&
+    (!parentCallingTurn || parentCallingTurn.sessionId !== parentSession?.id)
+  ) {
+    throw new HTTPException(403, {
+      message: "caller attempt does not belong to the parent session",
+    });
+  }
   const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(
     db,
     workspaceId,
     settings,
+    { subjectId: grant.subjectId },
   );
   const sessionMcpServers = hasOwnProperty(rawPayload, "mcpServers")
     ? validateSessionMcpServersForCreate(capabilityRuntimeSettings, grant, payload.mcpServers)
@@ -1219,7 +1346,10 @@ export async function createSessionForRequest(
         "child tools may only narrow the parent session tool policy",
       );
       selectedTools = requestedTools;
-      toolPolicy = { mode: "explicit", inheritedFromSessionId: parentSession.id };
+      toolPolicy = {
+        mode: "explicit",
+        inheritedFromSessionId: parentSession.id,
+      };
     } else {
       selectedTools = parentEffective;
       toolPolicy = {
@@ -1252,7 +1382,9 @@ export async function createSessionForRequest(
   });
   await validateGitHubRepositorySelection(db, workspaceId, resources);
   if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
-    throw new HTTPException(503, { message: "object storage is not configured" });
+    throw new HTTPException(503, {
+      message: "object storage is not configured",
+    });
   }
   await validateFileResources(db, workspaceId, resources);
   // VariableSet attachment requires variable-sets:use on the calling grant
@@ -1297,25 +1429,56 @@ export async function createSessionForRequest(
       frozenRigVersionId = rig.activeVersion.id;
     }
   }
-  const model = canonicalConfiguredModel(settings, payload.model ?? settings.openaiModel);
+  // A spawned worker is causally part of the exact turn that created it. Omitted
+  // execution policy fields therefore inherit that calling turn rather than the
+  // deployment defaults. This is especially important for Codex subscription
+  // managers: falling back to the deployment model would silently move a child
+  // onto the OpenGeni-credits billing path. Legacy session-bound grants without
+  // exact attempt claims fall back to the parent session's persisted defaults.
+  const inheritedModel = parentCallingTurn?.model ?? parentSession?.model ?? settings.openaiModel;
+  const model = canonicalConfiguredModel(settings, payload.model ?? inheritedModel);
   if (model === null || model === undefined) {
     throw new Error("effective session model unexpectedly resolved to null");
   }
-  // Session creation persists the EFFECTIVE model — an omitted payload.model
-  // stamps the deployment default onto the session — so the policy must vet
-  // that effective value, not just explicit ones (a restricted workspace's
-  // default-model session would otherwise be born blocked).
+  // Session creation persists the EFFECTIVE model — the explicit selection,
+  // inherited calling-turn model, or deployment default — so the policy must
+  // vet that effective value, not just explicit ones (a restricted workspace's
+  // inherited/default-model session would otherwise be born blocked).
   await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, model);
-  const reasoningEffort = payload.reasoningEffort ?? settings.openaiReasoningEffort;
-  const latencyMode = payload.latencyMode ?? "standard";
+  const inheritedReasoningEffort =
+    parentCallingTurn?.reasoningEffort ??
+    (parentSession
+      ? reasoningEffortForSession(parentSession.metadata, settings.openaiReasoningEffort)
+      : settings.openaiReasoningEffort);
+  const inheritedLatencyMode =
+    parentCallingTurn?.latencyMode ??
+    (parentSession ? latencyModeForSession(parentSession.metadata, "standard") : "standard");
+  const reasoningEffort = payload.reasoningEffort ?? inheritedReasoningEffort;
+  const latencyMode = payload.latencyMode ?? inheritedLatencyMode;
+  const inheritedFromParent = parentSession !== null;
   const turnExecutionPolicy = resolveTurnExecutionPolicyV1(settings, {
     modelId: model,
     requestedModelId: payload.model ?? null,
-    modelSource: payload.model === undefined ? "deployment" : "explicit",
+    modelSource:
+      payload.model === undefined
+        ? inheritedFromParent
+          ? "continuation"
+          : "deployment"
+        : "explicit",
     reasoningEffort,
-    reasoningSource: payload.reasoningEffort === undefined ? "deployment" : "explicit",
+    reasoningSource:
+      payload.reasoningEffort === undefined
+        ? inheritedFromParent
+          ? "continuation"
+          : "deployment"
+        : "explicit",
     latencyMode,
-    latencyModeSource: payload.latencyMode === undefined ? "deployment" : "explicit",
+    latencyModeSource:
+      payload.latencyMode === undefined
+        ? inheritedFromParent
+          ? "continuation"
+          : "deployment"
+        : "explicit",
   });
   // Parent linkage was resolved above, before context validation. A child with
   // no explicit permission override inherits the creating session's effective
@@ -1620,10 +1783,9 @@ export async function createSessionForRequest(
       model,
     });
   }
-  const creationInitiator = creationInitiatorForGrant(grant);
-  let session: CreateSessionResponse;
+  let createOutcome: CreateSessionOutcome;
   try {
-    session = await createAndStartSession({
+    createOutcome = await createAndStartSessionWithOutcome({
       ...(payload.requestedSessionId ? { requestedSessionId: payload.requestedSessionId } : {}),
       db,
       bus,
@@ -1683,7 +1845,11 @@ export async function createSessionForRequest(
       // (after the row exists, before the first turn dispatches). Validation
       // (ownership/liveness) lives in swapActiveSandbox; an invalid target 422s.
       seedTargetSandbox: payload.targetSandboxId
-        ? { sandboxId: payload.targetSandboxId, settings, workingDir: payload.workingDir ?? null }
+        ? {
+            sandboxId: payload.targetSandboxId,
+            settings,
+            workingDir: payload.workingDir ?? null,
+          }
         : null,
       consumeNewSessionDraft:
         payload.expectedNewSessionDraftRevision !== undefined
@@ -1704,24 +1870,52 @@ export async function createSessionForRequest(
     }
     throw error;
   }
+  let usageRecording: CreateSessionRequestOutcome["usageRecording"] = "recorded";
   if (payload.startMode !== "realtime") {
-    await recordWorkspaceUsage(deps, {
-      accountId: grant.accountId,
-      workspaceId,
-      subjectId: grant.subjectId,
-      eventType: "agent_run.created",
-      quantity: 1,
-      unit: "run",
-      sourceResourceType: "session",
-      sourceResourceId: session.id,
-      sessionId: session.id,
-      initiator: session.createdBy,
-      initiatorContext: session.createdByContext,
-      origin: creationInitiator.actor ? "system" : "user",
-      idempotencyKey: `agent_run.created:${workspaceId}:${session.id}`,
-    });
+    try {
+      await recordWorkspaceUsage(deps, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        eventType: "agent_run.created",
+        quantity: 1,
+        unit: "run",
+        sourceResourceType: "session",
+        sourceResourceId: createOutcome.session.id,
+        sessionId: createOutcome.session.id,
+        initiator: createOutcome.session.createdBy,
+        initiatorContext: createOutcome.session.createdByContext,
+        origin: creationInitiator.actor ? "system" : "user",
+        idempotencyKey: `agent_run.created:${workspaceId}:${createOutcome.session.id}`,
+      });
+    } catch (error) {
+      usageRecording = "failed";
+      reportSessionUsageRecordingFailure(error);
+    }
   }
-  return session;
+  return { ...createOutcome, usageRecording };
+}
+
+/** @internal Fixed public projection; the committed session outcome remains authoritative. */
+export function reportSessionUsageRecordingFailure(_error: unknown): void {
+  console.warn(
+    "[sessions] usage recording failed after committed session create; returning committed outcome",
+    {
+      errorClass: "UsageRecordingError",
+      errorCode: "session_create_usage_recording_failed",
+      origin: "core",
+    },
+  );
+}
+
+/** Backward-compatible entity-returning request path for REST and core callers. */
+export async function createSessionForRequest(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  workspaceId: string,
+  rawPayload: unknown,
+): Promise<CreateSessionResponse> {
+  return (await createSessionForRequestWithOutcome(deps, grant, workspaceId, rawPayload)).session;
 }
 
 /**
@@ -1731,13 +1925,14 @@ export async function createSessionForRequest(
  * enqueue, and usage recording. `toolsProvided: false` durably preserves an
  * Tool selection is durable session state and never rides a follow-up prompt.
  */
-export async function acceptSessionUserMessage(
+export async function acceptSessionUserMessageWithOutcome(
   deps: AcceptSessionUserMessageDependencies,
   grant: AccessGrant,
   workspaceId: string,
   sessionId: string,
   input: {
     text: string;
+    annotations?: SubmittedTimelineAnnotation[];
     turnInstructions?: string | null;
     resources?: ResourceRef[];
     model?: string | null;
@@ -1750,7 +1945,12 @@ export async function acceptSessionUserMessage(
     controlEtag?: string | null;
     expectedDraftRevision?: number | null;
   },
-): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
+): Promise<{
+  accepted: SessionEvent;
+  turn: SessionTurn;
+  interruptionCount: number;
+  replay: boolean;
+}> {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   await requireSessionAuthorization(deps, grant, {
     sessionId,
@@ -1792,6 +1992,12 @@ export async function acceptSessionUserMessage(
     latencyModeSource: input.latencyMode == null ? "session" : "explicit",
   });
   const requestedResources = normalizeResources(input.resources ?? []);
+  const annotations = await validateSubmittedTimelineAnnotations(
+    db,
+    workspaceId,
+    sessionId,
+    input.annotations ?? [],
+  );
   await requireLimit(deps, {
     accountId: grant.accountId,
     workspaceId,
@@ -1800,7 +2006,9 @@ export async function acceptSessionUserMessage(
     model: effectiveModel,
   });
   if (requestedResources.some((resource) => resource.kind === "file") && !objectStorage) {
-    throw new HTTPException(503, { message: "object storage is not configured" });
+    throw new HTTPException(503, {
+      message: "object storage is not configured",
+    });
   }
   await validateFileResources(db, workspaceId, requestedResources);
   await validateGitHubRepositorySelection(db, workspaceId, [
@@ -1813,7 +2021,9 @@ export async function acceptSessionUserMessage(
     session: existingSession,
     updates: input.mcpCredentialUpdates ?? [],
   });
-  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
+  const runtimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings, {
+    subjectId: grant.subjectId,
+  });
   const personalConnectionDelegations = await freezePersonalConnectionDelegations({
     db,
     workspaceId,
@@ -1822,7 +2032,7 @@ export async function acceptSessionUserMessage(
     source: personalConnectionDelegationSourceForGrant(grant),
   });
   const delegatedServiceInitiator = serviceInitiatorForGrant(grant);
-  const { accepted, turn } = await postUserMessageTurn({
+  const { accepted, turn, interruptionCount, replay } = await postUserMessageTurn({
     db,
     bus,
     workflowClient,
@@ -1831,6 +2041,7 @@ export async function acceptSessionUserMessage(
     workspaceId,
     sessionId,
     text: input.text,
+    annotations,
     turnInstructions: input.turnInstructions ?? null,
     resources: requestedResources,
     model: input.model ?? null,
@@ -1861,24 +2072,33 @@ export async function acceptSessionUserMessage(
       ? { expectedDraftRevision: input.expectedDraftRevision }
       : {}),
     ...(input.clientEventId ? { clientEventId: input.clientEventId } : {}),
+    recordAgentRunUsage: true,
+    ...(deps.schedulePromptPostCommit ? { schedulePostCommit: deps.schedulePromptPostCommit } : {}),
   });
-  await recordWorkspaceUsage(deps, {
-    accountId: grant.accountId,
+  return { accepted, turn, interruptionCount, replay };
+}
+
+/** Backward-compatible entity-returning path used by existing REST callers. */
+export async function acceptSessionUserMessage(
+  deps: Parameters<typeof acceptSessionUserMessageWithOutcome>[0],
+  grant: Parameters<typeof acceptSessionUserMessageWithOutcome>[1],
+  workspaceId: Parameters<typeof acceptSessionUserMessageWithOutcome>[2],
+  sessionId: Parameters<typeof acceptSessionUserMessageWithOutcome>[3],
+  input: Parameters<typeof acceptSessionUserMessageWithOutcome>[4],
+): Promise<{
+  accepted: SessionEvent;
+  turn: SessionTurn;
+  interruptionCount: number;
+  replay: boolean;
+}> {
+  const { accepted, turn, interruptionCount, replay } = await acceptSessionUserMessageWithOutcome(
+    deps,
+    grant,
     workspaceId,
-    subjectId: grant.subjectId,
-    eventType: "agent_run.created",
-    quantity: 1,
-    unit: "run",
-    sourceResourceType: "session_turn",
-    sourceResourceId: turn.id,
     sessionId,
-    turnId: turn.id,
-    initiator: turn.initiator,
-    initiatorContext: turn.initiatorContext,
-    origin: turn.source,
-    idempotencyKey: `agent_run.created:${workspaceId}:${turn.id}`,
-  });
-  return { accepted, turn };
+    input,
+  );
+  return { accepted, turn, interruptionCount, replay };
 }
 
 /**
@@ -1912,7 +2132,12 @@ export async function updateSessionTitle(
     surface: "core",
   });
   const workspaceId = grant.workspaceId;
-  const result = await updateSessionTitleRow(db, { workspaceId, sessionId, title, source });
+  const result = await updateSessionTitleRow(db, {
+    workspaceId,
+    sessionId,
+    title,
+    source,
+  });
   if (result.updated) {
     await appendAndPublishEvents(db, bus, workspaceId, sessionId, [
       {
@@ -1963,7 +2188,9 @@ export async function updateSessionMcpApprovalPolicy(
     async (_session, context) => {
       const result = await context.updateSessionMcpApprovalPolicy(serverId, normalizedPolicy);
       if (!result.server) {
-        throw new HTTPException(404, { message: "session MCP server not found" });
+        throw new HTTPException(404, {
+          message: "session MCP server not found",
+        });
       }
       outcome.server = result.server;
       return {
@@ -1980,6 +2207,7 @@ export async function updateSessionMcpApprovalPolicy(
           : [],
       };
     },
+    { activity: "semantic" },
   );
   const updatedServer = outcome.server;
   if (!updatedServer) {
@@ -2063,6 +2291,7 @@ export async function updateSessionToolPolicy(
     deps.db,
     grant.workspaceId,
     deps.settings,
+    { subjectId: grant.subjectId },
   );
   const runtimeSettings = settingsWithSessionMcpServerMetadata(
     capabilityRuntimeSettings,
@@ -2078,7 +2307,9 @@ export async function updateSessionToolPolicy(
           (tool) => !validatedIds.has(`${tool.kind}:${tool.id}`),
         );
         if (unknown) {
-          throw new HTTPException(422, { message: `unknown MCP server id: ${unknown.id}` });
+          throw new HTTPException(422, {
+            message: `unknown MCP server id: ${unknown.id}`,
+          });
         }
         return withFirstPartyTools(validatedTools, runtimeSettings);
       })()
@@ -2107,7 +2338,9 @@ export async function updateSessionToolPolicy(
       if (session.parentSessionId) {
         const parent = await context.getLockedSession(session.parentSessionId);
         if (!parent) {
-          throw new HTTPException(409, { message: "parent session is no longer available" });
+          throw new HTTPException(409, {
+            message: "parent session is no longer available",
+          });
         }
         const parentTracksWorkspaceDefaults = parent.toolPolicy?.mode === "workspace_default";
         const parentEffective = withFirstPartyTools(
@@ -2220,7 +2453,7 @@ export async function updateSessionToolPolicy(
         },
       };
     },
-    { lockParentSession: true },
+    { activity: "semantic", lockParentSession: true },
   );
   if (events.length > 0) {
     await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, events);