@opengeni/db 0.28.1 → 0.31.1

package/src/session-queue-commands.ts

@@ -1,19 +1,36 @@
 import {
+  DraftTimelineAnnotations,
   McpPersonalConnectionDelegations,
+  TimelineAnnotations,
   metadataWithTurnExecutionPolicyV1,
   mergeResourceRefs,
+  renderTimelineAnnotationsForModel,
   ResourceRef,
   resourceMountPath,
   stableJson,
   turnExecutionPolicyAuditMetadata,
   type McpPersonalConnectionDelegation,
+  type DraftTimelineAnnotation,
   type LatencyMode,
   type ReasoningEffort,
+  type SandboxBackend,
+  type SandboxOs,
+  type SessionEvent,
+  type SessionEventType,
+  type SessionTurn,
+  type SessionTurnSource,
+  type SessionTurnStatus,
+  type ToolRef,
   type TurnExecutionPolicyV1,
+  type TimelineAnnotation,
 } from "@opengeni/contracts";
 import { and, asc, eq, inArray, sql } from "drizzle-orm";
-import type { Database } from "./database";
-import { sanitizeEventPayload } from "./event-payload-sanitizer";
+import type { Database, SessionActivityDatabase } from "./database";
+import {
+  fromPostgresLosslessJson,
+  fromPostgresLosslessText,
+  withLosslessContentWriteVersion,
+} from "./lossless-json";
 import { closePendingSessionToolCallsInTransaction } from "./session-tool-call-settlement";
 import {
   assertAgentCommandAuthorityInTransaction,
@@ -45,6 +62,10 @@ import {
   type FrozenTurnInitiator,
 } from "./turn-initiator";
 
+type SessionEventInsertWithPayload = typeof schema.sessionEvents.$inferInsert & {
+  payload: unknown;
+};
+
 export type QueueCommandConflictCode =
   | "QUEUE_VERSION_CHANGED"
   | "QUEUE_PROMPT_STARTED"
@@ -93,6 +114,10 @@ export type SteerQueueCommandResult = QueueCommandResult & {
 export type SubmitHumanPromptResult = {
   receipt: SessionCommandReceiptRow;
   queueVersion: number;
+  accepted: SessionEvent;
+  events: SessionEvent[];
+  turn: SessionTurn;
+  /** Backward-compatible row identities for lower-level callers. */
   acceptedEventId: string;
   eventIds: string[];
   turnId: string;
@@ -102,6 +127,69 @@ export type SubmitHumanPromptResult = {
   replay: boolean;
 };
 
+function mapSubmittedPromptEvent(row: typeof schema.sessionEvents.$inferSelect): SessionEvent {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    sessionId: row.sessionId,
+    sequence: row.sequence,
+    type: row.type as SessionEventType,
+    payload: fromPostgresLosslessJson(row.payload, row.payloadCodecVersion),
+    occurredAt: row.occurredAt.toISOString(),
+    clientEventId: row.clientEventId,
+    turnId: row.turnId,
+    turnGeneration: row.turnGeneration,
+    turnAttemptId: row.turnAttemptId,
+    turnAssociation: row.turnAssociation as SessionEvent["turnAssociation"],
+    duplicateOfEventId: row.duplicateOfEventId,
+    duplicateReason: row.duplicateReason,
+  };
+}
+
+function mapSubmittedPromptTurn(row: typeof schema.sessionTurns.$inferSelect): SessionTurn {
+  const personalConnections = McpPersonalConnectionDelegations.parse(
+    row.personalConnectionDelegations,
+  ).map(({ serverId, providerDomain }) => ({ serverId, providerDomain }));
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    sessionId: row.sessionId,
+    triggerEventId: row.triggerEventId,
+    temporalWorkflowId: row.temporalWorkflowId,
+    status: row.status as SessionTurnStatus,
+    source: row.source as SessionTurnSource,
+    position: row.position,
+    prompt: fromPostgresLosslessText(row.prompt, row.promptCodecVersion),
+    annotations: TimelineAnnotations.parse(row.annotations),
+    resources: row.resources as ResourceRef[],
+    tools: row.tools as ToolRef[],
+    toolsProvided: row.toolsProvided,
+    model: row.model,
+    reasoningEffort: row.reasoningEffort as ReasoningEffort,
+    latencyMode: (row.latencyMode as LatencyMode | null | undefined) ?? "standard",
+    sandboxBackend: row.sandboxBackend as SandboxBackend,
+    sandboxOs: (row.sandboxOs as SandboxOs | null) ?? null,
+    metadata: row.metadata,
+    version: row.version,
+    executionGeneration: row.executionGeneration,
+    activeAttemptId: row.activeAttemptId,
+    lineage: row.lineage,
+    initiator: initiatorFromStorage(
+      row.initiatorKind,
+      row.initiatorSubjectId,
+      row.initiatorContext ?? {},
+    ),
+    initiatorContext: row.initiatorContext ?? {},
+    personalConnections,
+    cancelledBy: row.cancelledBy,
+    cancelReason: row.cancelReason,
+    startedAt: row.startedAt ? row.startedAt.toISOString() : null,
+    finishedAt: row.finishedAt ? row.finishedAt.toISOString() : null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
 export type AgentInternalUpdateCommandResult = {
   receipt: SessionCommandReceiptRow;
   updateId: string;
@@ -294,18 +382,22 @@ export async function supersedeSessionCurrentDirectionInTransaction(
     const cancelledHumanInputEvents = await db
       .insert(schema.sessionEvents)
       .values(
-        cancelledHumanInputs.map((request) => ({
-          accountId: input.accountId,
-          workspaceId: input.workspaceId,
-          sessionId: input.sessionId,
-          sequence: ++lastSequence,
-          type: "user.humanInputResponse",
-          turnId: current.id,
-          turnGeneration: current.executionGeneration,
-          turnAssociation: "current",
-          payload: { requestId: request.id, response: { outcome: "cancelled" } },
-          occurredAt: now,
-        })),
+        withLosslessContentWriteVersion(
+          cancelledHumanInputs.map((request) => ({
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            sessionId: input.sessionId,
+            sequence: ++lastSequence,
+            type: "user.humanInputResponse",
+            turnId: current.id,
+            turnGeneration: current.executionGeneration,
+            turnAssociation: "current",
+            payload: { requestId: request.id, response: { outcome: "cancelled" } },
+            occurredAt: now,
+          })),
+          "payload",
+          "payloadCodecVersion",
+        ),
       )
       .returning();
     const requestsById = new Map(cancelledHumanInputs.map((request) => [request.id, request]));
@@ -406,7 +498,7 @@ async function loadQueuedTurns(
 }
 
 async function normalizeQueuePositions(
-  db: Database,
+  db: SessionActivityDatabase,
   workspaceId: string,
   sessionId: string,
   orderedIds: string[],
@@ -438,7 +530,19 @@ async function normalizeQueuePositions(
 }
 
 function draftIsNonEmpty(draft: ComposerDraftRow): boolean {
-  return draft.text.length > 0 || draft.resources.length > 0 || draft.sourceTurnId !== null;
+  return (
+    draft.text.length > 0 ||
+    DraftTimelineAnnotations.parse(draft.annotations).length > 0 ||
+    draft.resources.length > 0 ||
+    draft.sourceTurnId !== null
+  );
+}
+
+function draftAnnotationsFromTurn(value: unknown): DraftTimelineAnnotation[] {
+  return TimelineAnnotations.parse(value).map(({ ordinal: _ordinal, ...annotation }) => ({
+    ...annotation,
+    source: { ...annotation.source },
+  }));
 }
 
 function withCanonicalResourceMountPaths(resources: readonly unknown[]): unknown[] {
@@ -495,6 +599,7 @@ export async function saveComposerDraftInTransaction(
     subjectId: string;
     expectedRevision: number;
     text: string;
+    annotations?: DraftTimelineAnnotation[];
     resources: ResourceRef[];
     model: string;
     reasoningEffort: ReasoningEffort;
@@ -526,6 +631,7 @@ export async function saveComposerDraftInTransaction(
     subjectId: input.subjectId,
     revision,
     text: input.text,
+    annotations: DraftTimelineAnnotations.parse(input.annotations ?? []),
     resources: withCanonicalResourceMountPaths(input.resources),
     tools: [],
     toolsProvided: false,
@@ -551,7 +657,7 @@ export async function saveComposerDraftInTransaction(
 }
 
 export async function moveQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -639,21 +745,27 @@ export async function moveQueuedTurnInTransaction(
     );
     const [event] = await db
       .insert(schema.sessionEvents)
-      .values({
-        accountId: input.accountId,
-        workspaceId: input.workspaceId,
-        sessionId: input.sessionId,
-        sequence: session.lastSequence + 1,
-        type: "session.queue.changed",
-        turnId: target.id,
-        payload: {
-          operation: "move",
-          queueVersion,
-          turnId: target.id,
-          beforeTurnId: input.beforeTurnId,
-        },
-        occurredAt: new Date(),
-      })
+      .values(
+        withLosslessContentWriteVersion(
+          {
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            sessionId: input.sessionId,
+            sequence: session.lastSequence + 1,
+            type: "session.queue.changed",
+            turnId: target.id,
+            payload: {
+              operation: "move",
+              queueVersion,
+              turnId: target.id,
+              beforeTurnId: input.beforeTurnId,
+            },
+            occurredAt: new Date(),
+          },
+          "payload",
+          "payloadCodecVersion",
+        ),
+      )
       .returning({ id: schema.sessionEvents.id });
     if (!event) throw new Error("Queue move event was not inserted");
     eventIds.push(event.id);
@@ -681,7 +793,7 @@ export async function moveQueuedTurnInTransaction(
 }
 
 export async function deleteSessionQueueItemInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -767,20 +879,26 @@ export async function deleteSessionQueueItemInTransaction(
   );
   const [event] = await db
     .insert(schema.sessionEvents)
-    .values({
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
-      sessionId: input.sessionId,
-      sequence: session.lastSequence + 1,
-      type: "session.queue.changed",
-      turnId: turn.id,
-      payload: {
-        operation: "delete",
-        queueVersion,
-        turnId: turn.id,
-      },
-      occurredAt: now,
-    })
+    .values(
+      withLosslessContentWriteVersion(
+        {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          sessionId: input.sessionId,
+          sequence: session.lastSequence + 1,
+          type: "session.queue.changed",
+          turnId: turn.id,
+          payload: {
+            operation: "delete",
+            queueVersion,
+            turnId: turn.id,
+          },
+          occurredAt: now,
+        },
+        "payload",
+        "payloadCodecVersion",
+      ),
+    )
     .returning({ id: schema.sessionEvents.id });
   if (!event) throw new Error("Queue delete event was not inserted");
   await db
@@ -806,7 +924,7 @@ export async function deleteSessionQueueItemInTransaction(
 }
 
 export async function editQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -899,6 +1017,7 @@ export async function editQueuedTurnInTransaction(
     subjectId: input.subjectId,
     revision: nextDraftRevision,
     text: turn.prompt,
+    annotations: draftAnnotationsFromTurn(turn.annotations),
     resources: withCanonicalResourceMountPaths(turn.resources),
     tools: [],
     toolsProvided: false,
@@ -939,21 +1058,27 @@ export async function editQueuedTurnInTransaction(
   );
   const [event] = await db
     .insert(schema.sessionEvents)
-    .values({
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
-      sessionId: input.sessionId,
-      sequence: session.lastSequence + 1,
-      type: "session.queue.changed",
-      turnId: turn.id,
-      payload: {
-        operation: "edit",
-        queueVersion,
-        turnId: turn.id,
-        draftRevision: nextDraftRevision,
-      },
-      occurredAt: now,
-    })
+    .values(
+      withLosslessContentWriteVersion(
+        {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          sessionId: input.sessionId,
+          sequence: session.lastSequence + 1,
+          type: "session.queue.changed",
+          turnId: turn.id,
+          payload: {
+            operation: "edit",
+            queueVersion,
+            turnId: turn.id,
+            draftRevision: nextDraftRevision,
+          },
+          occurredAt: now,
+        },
+        "payload",
+        "payloadCodecVersion",
+      ),
+    )
     .returning({ id: schema.sessionEvents.id });
   if (!event) throw new Error("Queue edit event was not inserted");
   await db
@@ -981,7 +1106,7 @@ export async function editQueuedTurnInTransaction(
 }
 
 export async function steerQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -1118,7 +1243,7 @@ export async function steerQueuedTurnInTransaction(
     input.actor.type === "agent_attempt"
       ? `attempt:${input.actor.attemptId}`
       : input.actor.subjectId;
-  const eventValues: Array<typeof schema.sessionEvents.$inferInsert> = [];
+  const eventValues: SessionEventInsertWithPayload[] = [];
   if (supersededTurnId && !liveCurrentTurnId) {
     eventValues.push({
       accountId: input.accountId,
@@ -1146,9 +1271,12 @@ export async function steerQueuedTurnInTransaction(
     },
     occurredAt: now,
   });
-  const eventRows = await db.insert(schema.sessionEvents).values(eventValues).returning({
-    id: schema.sessionEvents.id,
-  });
+  const eventRows = await db
+    .insert(schema.sessionEvents)
+    .values(withLosslessContentWriteVersion(eventValues, "payload", "payloadCodecVersion"))
+    .returning({
+      id: schema.sessionEvents.id,
+    });
   await db
     .update(schema.sessions)
     .set({
@@ -1161,19 +1289,25 @@ export async function steerQueuedTurnInTransaction(
       updatedAt: now,
     })
     .where(eq(schema.sessions.id, input.sessionId));
-  await db.insert(schema.auditEvents).values({
-    accountId: input.accountId,
-    workspaceId: input.workspaceId,
-    subjectId: actor,
-    action: "session.queue.steer",
-    targetType: "session_turn",
-    targetId: target.id,
-    metadata: {
-      operationId: reserved.receipt.id,
-      replacedTurnId: supersededTurnId,
-      interruptionCount,
-    },
-  });
+  await db.insert(schema.auditEvents).values(
+    withLosslessContentWriteVersion(
+      {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId: actor,
+        action: "session.queue.steer",
+        targetType: "session_turn",
+        targetId: target.id,
+        metadata: {
+          operationId: reserved.receipt.id,
+          replacedTurnId: supersededTurnId,
+          interruptionCount,
+        },
+      },
+      "metadata",
+      "metadataCodecVersion",
+    ),
+  );
   const wakeRevision = await registerSessionWorkflowWakeInTransaction(db, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
@@ -1205,7 +1339,7 @@ export async function steerQueuedTurnInTransaction(
 }
 
 export async function submitHumanPromptInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -1218,6 +1352,7 @@ export async function submitHumanPromptInTransaction(
     controlEtag?: string | null;
     expectedDraftRevision?: number | null;
     text: string;
+    annotations?: TimelineAnnotation[];
     turnInstructions?: string | null;
     resources: ResourceRef[];
     model?: string | null;
@@ -1235,6 +1370,8 @@ export async function submitHumanPromptInTransaction(
       context: string;
     };
     source: "user" | "api";
+    /** Record the admitted run's durable usage fact in this transaction. */
+    recordAgentRunUsage?: boolean;
     personalConnectionDelegations?: McpPersonalConnectionDelegation[];
     mcpCredentialUpdates?: Array<{
       id: string;
@@ -1242,6 +1379,7 @@ export async function submitHumanPromptInTransaction(
     }>;
   },
 ): Promise<SubmitHumanPromptResult> {
+  const annotations = TimelineAnnotations.parse(input.annotations ?? []);
   const workspaceControl = await lockWorkspaceInferenceControl(db, input.workspaceId, "update");
   await lockSessionEventWriteRows(db, {
     workspaceId: input.workspaceId,
@@ -1258,6 +1396,7 @@ export async function submitHumanPromptInTransaction(
     controlEtag: input.controlEtag ?? null,
     expectedDraftRevision: input.expectedDraftRevision ?? null,
     text: input.text,
+    annotations,
     turnInstructions: input.turnInstructions ?? null,
     resources: withCanonicalResourceMountPaths(input.resources),
     model: input.model ?? null,
@@ -1297,9 +1436,39 @@ export async function submitHumanPromptInTransaction(
     if (!turnId || !acceptedEventId || wakeRevision < 1) {
       throw new SessionControlInvariantError("Replayed prompt receipt is incomplete");
     }
+    const replayEvents = await db
+      .select()
+      .from(schema.sessionEvents)
+      .where(
+        and(
+          eq(schema.sessionEvents.workspaceId, input.workspaceId),
+          eq(schema.sessionEvents.sessionId, input.sessionId),
+          inArray(schema.sessionEvents.id, eventIds),
+        ),
+      )
+      .orderBy(asc(schema.sessionEvents.sequence));
+    const [replayTurn] = await db
+      .select()
+      .from(schema.sessionTurns)
+      .where(
+        and(
+          eq(schema.sessionTurns.workspaceId, input.workspaceId),
+          eq(schema.sessionTurns.sessionId, input.sessionId),
+          eq(schema.sessionTurns.id, turnId),
+        ),
+      )
+      .limit(1);
+    const events = replayEvents.map(mapSubmittedPromptEvent);
+    const accepted = events.find((event) => event.id === acceptedEventId);
+    if (!accepted || !replayTurn || events.length !== eventIds.length) {
+      throw new SessionControlInvariantError("Replayed prompt rows are incomplete");
+    }
     return {
       receipt: reserved.receipt,
       queueVersion: Number(reserved.receipt.appliedQueueVersion),
+      accepted,
+      events,
+      turn: mapSubmittedPromptTurn(replayTurn),
       acceptedEventId,
       eventIds,
       turnId,
@@ -1369,6 +1538,7 @@ export async function submitHumanPromptInTransaction(
       draft &&
       canonicalSessionCommandHash({
         text: draft.text,
+        annotations: DraftTimelineAnnotations.parse(draft.annotations),
         resources: withCanonicalResourceMountPaths(draft.resources),
         model: draft.model,
         reasoningEffort: draft.reasoningEffort,
@@ -1376,6 +1546,7 @@ export async function submitHumanPromptInTransaction(
       }) !==
         canonicalSessionCommandHash({
           text: input.text,
+          annotations: annotations.map(({ ordinal: _ordinal, ...annotation }) => annotation),
           resources: withCanonicalResourceMountPaths(input.resources),
           model: input.model ?? session.model,
           reasoningEffort: input.reasoningEffort ?? input.reasoningEffortFallback,
@@ -1485,7 +1656,7 @@ export async function submitHumanPromptInTransaction(
   const turnId = crypto.randomUUID();
   const workflowId = session.temporalWorkflowId ?? `session-${session.id}`;
   let sequence = session.lastSequence;
-  const eventValues: Array<typeof schema.sessionEvents.$inferInsert> = [
+  const eventValues: SessionEventInsertWithPayload[] = [
     {
       id: acceptedEventId,
       accountId: input.accountId,
@@ -1494,8 +1665,9 @@ export async function submitHumanPromptInTransaction(
       sequence: ++sequence,
       type: "user.message",
       clientEventId: input.operationKey,
-      payload: sanitizeEventPayload({
+      payload: {
         text: input.messagePresentation?.text ?? input.text,
+        ...(annotations.length > 0 ? { annotations } : {}),
         ...(input.messagePresentation
           ? {
               presentation: {
@@ -1510,56 +1682,64 @@ export async function submitHumanPromptInTransaction(
         ...(input.latencyMode ? { latencyMode: input.latencyMode } : {}),
         delivery: input.delivery,
         initiator: frozenInitiator.initiator,
-      }),
+      },
       occurredAt: now,
     },
   ];
   const existingQueued = await loadQueuedTurns(db, input.workspaceId, input.sessionId, true);
   const [turn] = await db
     .insert(schema.sessionTurns)
-    .values({
-      id: turnId,
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
-      sessionId: input.sessionId,
-      triggerEventId: acceptedEventId,
-      temporalWorkflowId: workflowId,
-      status: "queued",
-      source: input.source,
-      position: input.delivery === "steer" ? 0 : existingQueued.length + 1,
-      prompt: input.text,
-      turnInstructions:
-        editedSourceTurnInstructions !== undefined
-          ? editedSourceTurnInstructions
-          : (input.turnInstructions ?? null),
-      resources: input.resources,
-      tools: [],
-      toolsProvided: false,
-      model: input.model ?? session.model,
-      reasoningEffort: input.reasoningEffort ?? input.reasoningEffortFallback,
-      latencyMode: input.turnExecutionPolicy?.latencyMode ?? input.latencyMode ?? "standard",
-      sandboxBackend: session.sandboxBackend,
-      metadata: input.turnExecutionPolicy
-        ? metadataWithTurnExecutionPolicyV1(input.turnMetadata ?? {}, input.turnExecutionPolicy)
-        : (input.turnMetadata ?? {}),
-      lineage: { actor: input.actor.type },
-      ...initiatorColumns(frozenInitiator),
-      initiatingHumanSubjectId: editedSourceTurn
-        ? (editedSourceTurn.initiatingHumanSubjectId ??
-          (editedSourceTurn.initiatorKind === "subject"
-            ? editedSourceTurn.initiatorSubjectId
-            : null))
-        : frozenInitiator.initiator.kind === "subject"
-          ? frozenInitiator.initiator.subjectId
-          : null,
-      personalConnectionDelegations: editedSourceTurn
-        ? editedSourceTurn.personalConnectionDelegations
-        : (input.personalConnectionDelegations ?? []),
-      createdAt: now,
-      updatedAt: now,
-    })
+    .values(
+      withLosslessContentWriteVersion(
+        {
+          id: turnId,
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          sessionId: input.sessionId,
+          triggerEventId: acceptedEventId,
+          temporalWorkflowId: workflowId,
+          status: "queued",
+          source: input.source,
+          position: input.delivery === "steer" ? 0 : existingQueued.length + 1,
+          prompt: input.text,
+          annotations,
+          turnInstructions:
+            editedSourceTurnInstructions !== undefined
+              ? editedSourceTurnInstructions
+              : (input.turnInstructions ?? null),
+          resources: input.resources,
+          tools: [],
+          toolsProvided: false,
+          model: input.model ?? session.model,
+          reasoningEffort: input.reasoningEffort ?? input.reasoningEffortFallback,
+          latencyMode: input.turnExecutionPolicy?.latencyMode ?? input.latencyMode ?? "standard",
+          sandboxBackend: session.sandboxBackend,
+          metadata: input.turnExecutionPolicy
+            ? metadataWithTurnExecutionPolicyV1(input.turnMetadata ?? {}, input.turnExecutionPolicy)
+            : (input.turnMetadata ?? {}),
+          lineage: { actor: input.actor.type },
+          ...initiatorColumns(frozenInitiator),
+          initiatingHumanSubjectId: editedSourceTurn
+            ? (editedSourceTurn.initiatingHumanSubjectId ??
+              (editedSourceTurn.initiatorKind === "subject"
+                ? editedSourceTurn.initiatorSubjectId
+                : null))
+            : frozenInitiator.initiator.kind === "subject"
+              ? frozenInitiator.initiator.subjectId
+              : null,
+          personalConnectionDelegations: editedSourceTurn
+            ? editedSourceTurn.personalConnectionDelegations
+            : (input.personalConnectionDelegations ?? []),
+          createdAt: now,
+          updatedAt: now,
+        },
+        "prompt",
+        "promptCodecVersion",
+      ),
+    )
     .returning();
   if (!turn) throw new SessionControlInvariantError("Prompt turn was not inserted");
+  let committedTurn = turn;
   eventValues.push({
     accountId: input.accountId,
     workspaceId: input.workspaceId,
@@ -1610,7 +1790,7 @@ export async function submitHumanPromptInTransaction(
   // settlement has already cleared sessions.active_turn_id. Do not infer this
   // state from a local request spinner or queue position.
   if (input.delivery === "steer") {
-    await db
+    const [updatedTurn] = await db
       .update(schema.sessionTurns)
       .set({
         metadata: {
@@ -1628,7 +1808,12 @@ export async function submitHumanPromptInTransaction(
           eq(schema.sessionTurns.sessionId, input.sessionId),
           eq(schema.sessionTurns.id, turnId),
         ),
-      );
+      )
+      .returning();
+    if (!updatedTurn) {
+      throw new SessionControlInvariantError("Steer prompt turn metadata was not updated");
+    }
+    committedTurn = updatedTurn;
   }
   if (supersession.replacedTurn) {
     const current = supersession.replacedTurn;
@@ -1686,7 +1871,10 @@ export async function submitHumanPromptInTransaction(
       occurredAt: now,
     });
   }
-  const eventRows = await db.insert(schema.sessionEvents).values(eventValues).returning();
+  const eventRows = await db
+    .insert(schema.sessionEvents)
+    .values(withLosslessContentWriteVersion(eventValues, "payload", "payloadCodecVersion"))
+    .returning();
   if (input.actor.type === "human") {
     const realtimeRouting =
       input.delivery === "steer"
@@ -1705,7 +1893,7 @@ export async function submitHumanPromptInTransaction(
       text: renderRealtimeHumanInputContext({
         delivery: input.delivery,
         routing: realtimeRouting,
-        text: input.text,
+        text: renderTimelineAnnotationsForModel(input.text, annotations),
       }),
       payload: {
         delivery: input.delivery,
@@ -1742,25 +1930,52 @@ export async function submitHumanPromptInTransaction(
     reason: input.delivery === "steer" ? "prompt_steer" : "prompt_send",
     controlRequested: input.delivery === "steer",
   });
-  await db.insert(schema.auditEvents).values({
-    accountId: input.accountId,
-    workspaceId: input.workspaceId,
-    subjectId:
-      input.actor.type === "agent_attempt"
-        ? `attempt:${input.actor.attemptId}`
-        : input.actor.subjectId,
-    action: input.delivery === "steer" ? "session.prompt.steer" : "session.prompt.send",
-    targetType: "session_turn",
-    targetId: turnId,
-    metadata: {
-      operationId: reserved.receipt.id,
-      replacedTurnId,
-      interruptionCount,
-      ...(input.turnExecutionPolicy
-        ? turnExecutionPolicyAuditMetadata(input.turnExecutionPolicy, turnId)
-        : {}),
-    },
-  });
+  await db.insert(schema.auditEvents).values(
+    withLosslessContentWriteVersion(
+      {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId:
+          input.actor.type === "agent_attempt"
+            ? `attempt:${input.actor.attemptId}`
+            : input.actor.subjectId,
+        action: input.delivery === "steer" ? "session.prompt.steer" : "session.prompt.send",
+        targetType: "session_turn",
+        targetId: turnId,
+        metadata: {
+          operationId: reserved.receipt.id,
+          replacedTurnId,
+          interruptionCount,
+          ...(input.turnExecutionPolicy
+            ? turnExecutionPolicyAuditMetadata(input.turnExecutionPolicy, turnId)
+            : {}),
+        },
+      },
+      "metadata",
+      "metadataCodecVersion",
+    ),
+  );
+  if (input.recordAgentRunUsage) {
+    await db
+      .insert(schema.usageEvents)
+      .values({
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId: input.subjectId,
+        eventType: "agent_run.created",
+        quantity: 1,
+        unit: "run",
+        sourceResourceType: "session_turn",
+        sourceResourceId: turnId,
+        sessionId: input.sessionId,
+        turnId,
+        ...initiatorColumns(frozenInitiator),
+        origin: input.source,
+        idempotencyKey: `agent_run.created:${input.workspaceId}:${turnId}`,
+        occurredAt: now,
+      })
+      .onConflictDoNothing({ target: schema.usageEvents.idempotencyKey });
+  }
   const eventIds = eventRows.map((event) => event.id);
   const receipt = await updateSessionCommandReceiptResult(db, reserved.receipt.id, {
     controlRevision: resumed.revision,
@@ -1782,9 +1997,17 @@ export async function submitHumanPromptInTransaction(
         : {}),
     },
   });
+  const events = eventRows.map(mapSubmittedPromptEvent);
+  const accepted = events.find((event) => event.id === acceptedEventId);
+  if (!accepted) {
+    throw new SessionControlInvariantError("Inserted user.message event is missing");
+  }
   return {
     receipt,
     queueVersion,
+    accepted,
+    events,
+    turn: mapSubmittedPromptTurn(committedTurn),
     acceptedEventId,
     eventIds,
     turnId,
@@ -1796,7 +2019,7 @@ export async function submitHumanPromptInTransaction(
 }
 
 export async function sendAgentMessageInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -1879,46 +2102,62 @@ export async function sendAgentMessageInTransaction(
   const now = new Date();
   const [update] = await db
     .insert(schema.sessionSystemUpdates)
-    .values({
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
-      sessionId: input.targetSessionId,
-      kind: "agent_message",
-      classification: "info",
-      sourceId: input.actor.sessionId,
-      dedupeKey: `agent-message:${reserved.receipt.id}`,
-      summary: input.text,
-      payload: {
-        type: "agent_message",
-        text: input.text,
-        operationId: reserved.receipt.id,
-      },
-      lineage: {
-        callerSessionId: input.actor.sessionId,
-        callerTurnId: input.actor.turnId,
-        callerAttemptId: input.actor.attemptId,
-        callerExecutionGeneration: input.actor.executionGeneration,
-      },
-      personalConnectionDelegations,
-      state: "pending",
-    })
+    .values(
+      withLosslessContentWriteVersion(
+        withLosslessContentWriteVersion(
+          {
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            sessionId: input.targetSessionId,
+            kind: "agent_message",
+            classification: "info",
+            sourceId: input.actor.sessionId,
+            dedupeKey: `agent-message:${reserved.receipt.id}`,
+            summary: input.text,
+            payload: {
+              type: "agent_message",
+              text: input.text,
+              operationId: reserved.receipt.id,
+            },
+            lineage: {
+              callerSessionId: input.actor.sessionId,
+              callerTurnId: input.actor.turnId,
+              callerAttemptId: input.actor.attemptId,
+              callerExecutionGeneration: input.actor.executionGeneration,
+            },
+            personalConnectionDelegations,
+            state: "pending",
+          },
+          "summary",
+          "summaryCodecVersion",
+        ),
+        "payload",
+        "payloadCodecVersion",
+      ),
+    )
     .returning({ id: schema.sessionSystemUpdates.id });
   if (!update) throw new SessionControlInvariantError("Agent message was not inserted");
   const [event] = await db
     .insert(schema.sessionEvents)
-    .values({
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
-      sessionId: input.targetSessionId,
-      sequence: session.lastSequence + 1,
-      type: "system.update.pending",
-      payload: {
-        updateId: update.id,
-        kind: "agent_message",
-        sourceSessionId: input.actor.sessionId,
-      },
-      occurredAt: now,
-    })
+    .values(
+      withLosslessContentWriteVersion(
+        {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          sessionId: input.targetSessionId,
+          sequence: session.lastSequence + 1,
+          type: "system.update.pending",
+          payload: {
+            updateId: update.id,
+            kind: "agent_message",
+            sourceSessionId: input.actor.sessionId,
+          },
+          occurredAt: now,
+        },
+        "payload",
+        "payloadCodecVersion",
+      ),
+    )
     .returning({ id: schema.sessionEvents.id });
   if (!event) throw new SessionControlInvariantError("Agent message event was not inserted");
   const workflowId = session.temporalWorkflowId ?? `session-${session.id}`;
@@ -1939,21 +2178,27 @@ export async function sendAgentMessageInTransaction(
       updatedAt: now,
     })
     .where(eq(schema.sessions.id, input.targetSessionId));
-  await db.insert(schema.auditEvents).values({
-    accountId: input.accountId,
-    workspaceId: input.workspaceId,
-    subjectId: `attempt:${input.actor.attemptId}`,
-    action: "session.agent_message",
-    targetType: "session",
-    targetId: input.targetSessionId,
-    metadata: {
-      operationId: reserved.receipt.id,
-      callerSessionId: input.actor.sessionId,
-      callerTurnId: input.actor.turnId,
-      callerAttemptId: input.actor.attemptId,
-      callerExecutionGeneration: input.actor.executionGeneration,
-    },
-  });
+  await db.insert(schema.auditEvents).values(
+    withLosslessContentWriteVersion(
+      {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId: `attempt:${input.actor.attemptId}`,
+        action: "session.agent_message",
+        targetType: "session",
+        targetId: input.targetSessionId,
+        metadata: {
+          operationId: reserved.receipt.id,
+          callerSessionId: input.actor.sessionId,
+          callerTurnId: input.actor.turnId,
+          callerAttemptId: input.actor.attemptId,
+          callerExecutionGeneration: input.actor.executionGeneration,
+        },
+      },
+      "metadata",
+      "metadataCodecVersion",
+    ),
+  );
   const receipt = await updateSessionCommandReceiptResult(db, reserved.receipt.id, {
     result: {
       updateId: update.id,
@@ -1978,7 +2223,7 @@ export async function sendAgentMessageInTransaction(
 }
 
 export async function steerAgentSessionInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -2084,33 +2329,43 @@ export async function steerAgentSessionInTransaction(
   const now = new Date();
   const [update] = await db
     .insert(schema.sessionSystemUpdates)
-    .values({
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
-      sessionId: input.targetSessionId,
-      kind: "agent_steer_instruction",
-      classification: "action_required",
-      sourceId: input.actor.sessionId,
-      dedupeKey: `agent-steer:${reserved.receipt.id}`,
-      summary: input.instruction,
-      payload: {
-        type: "agent_steer_instruction",
-        instruction: input.instruction,
-        operationId: reserved.receipt.id,
-      },
-      lineage: {
-        callerSessionId: input.actor.sessionId,
-        callerTurnId: input.actor.turnId,
-        callerAttemptId: input.actor.attemptId,
-        callerExecutionGeneration: input.actor.executionGeneration,
-      },
-      personalConnectionDelegations,
-      state: "pending",
-    })
+    .values(
+      withLosslessContentWriteVersion(
+        withLosslessContentWriteVersion(
+          {
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            sessionId: input.targetSessionId,
+            kind: "agent_steer_instruction",
+            classification: "action_required",
+            sourceId: input.actor.sessionId,
+            dedupeKey: `agent-steer:${reserved.receipt.id}`,
+            summary: input.instruction,
+            payload: {
+              type: "agent_steer_instruction",
+              instruction: input.instruction,
+              operationId: reserved.receipt.id,
+            },
+            lineage: {
+              callerSessionId: input.actor.sessionId,
+              callerTurnId: input.actor.turnId,
+              callerAttemptId: input.actor.attemptId,
+              callerExecutionGeneration: input.actor.executionGeneration,
+            },
+            personalConnectionDelegations,
+            state: "pending",
+          },
+          "summary",
+          "summaryCodecVersion",
+        ),
+        "payload",
+        "payloadCodecVersion",
+      ),
+    )
     .returning({ id: schema.sessionSystemUpdates.id });
   if (!update) throw new SessionControlInvariantError("Agent Steer instruction was not inserted");
   let sequence = supersession.lastSequence;
-  const events: Array<typeof schema.sessionEvents.$inferInsert> = [];
+  const events: SessionEventInsertWithPayload[] = [];
   if (supersession.replacedTurn && !supersession.liveCurrentTurnId) {
     events.push({
       accountId: input.accountId,
@@ -2175,9 +2430,12 @@ export async function steerAgentSessionInTransaction(
       occurredAt: now,
     },
   );
-  const insertedEvents = await db.insert(schema.sessionEvents).values(events).returning({
-    id: schema.sessionEvents.id,
-  });
+  const insertedEvents = await db
+    .insert(schema.sessionEvents)
+    .values(withLosslessContentWriteVersion(events, "payload", "payloadCodecVersion"))
+    .returning({
+      id: schema.sessionEvents.id,
+    });
   const workflowId = session.temporalWorkflowId ?? `session-${session.id}`;
   const wakeRevision = await registerSessionWorkflowWakeInTransaction(db, {
     accountId: input.accountId,
@@ -2196,24 +2454,30 @@ export async function steerAgentSessionInTransaction(
       updatedAt: now,
     })
     .where(eq(schema.sessions.id, input.targetSessionId));
-  await db.insert(schema.auditEvents).values({
-    accountId: input.accountId,
-    workspaceId: input.workspaceId,
-    subjectId: `attempt:${input.actor.attemptId}`,
-    action: "session.agent_steer",
-    targetType: "session",
-    targetId: input.targetSessionId,
-    metadata: {
-      operationId: reserved.receipt.id,
-      callerSessionId: input.actor.sessionId,
-      callerTurnId: input.actor.turnId,
-      callerAttemptId: input.actor.attemptId,
-      callerExecutionGeneration: input.actor.executionGeneration,
-      controlRevision: resumed.revision,
-      interruptionCount: supersession.interruptionCount,
-      workspaceControlEventId: resumed.workspaceControlEventId,
-    },
-  });
+  await db.insert(schema.auditEvents).values(
+    withLosslessContentWriteVersion(
+      {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId: `attempt:${input.actor.attemptId}`,
+        action: "session.agent_steer",
+        targetType: "session",
+        targetId: input.targetSessionId,
+        metadata: {
+          operationId: reserved.receipt.id,
+          callerSessionId: input.actor.sessionId,
+          callerTurnId: input.actor.turnId,
+          callerAttemptId: input.actor.attemptId,
+          callerExecutionGeneration: input.actor.executionGeneration,
+          controlRevision: resumed.revision,
+          interruptionCount: supersession.interruptionCount,
+          workspaceControlEventId: resumed.workspaceControlEventId,
+        },
+      },
+      "metadata",
+      "metadataCodecVersion",
+    ),
+  );
   const eventIds = insertedEvents.map((event) => event.id);
   const receipt = await updateSessionCommandReceiptResult(db, reserved.receipt.id, {
     controlRevision: resumed.revision,