@opengeni/db 0.28.9 → 0.31.1

package/src/session-control.ts

@@ -7,7 +7,7 @@ import {
   type TurnInitiatorContext,
 } from "@opengeni/contracts";
 import { and, eq, inArray, sql } from "drizzle-orm";
-import type { Database } from "./database";
+import type { Database, SessionActivityDatabase } from "./database";
 import { withLosslessContentWriteVersion } from "./lossless-json";
 import * as schema from "./schema";
 import { closePendingSessionToolCallsInTransaction } from "./session-tool-call-settlement";
@@ -1163,7 +1163,10 @@ export async function evaluateSessionDiscoveryControls(
     );
   }
 
-  const workspace = await lockWorkspaceInferenceControl(db, workspaceId, "share");
+  // Discovery owns one read-only repeatable-read snapshot, so this projection
+  // must not join the writer lock graph merely to keep workspace/session facts
+  // coherent. The snapshot is the consistency boundary.
+  const workspace = await lockWorkspaceInferenceControl(db, workspaceId, "none");
   const workspacePauseRevision = asSafeRevision(
     workspace.workspacePauseRevision,
     "workspace pause revision",
@@ -2050,7 +2053,7 @@ async function assertSessionBranchIsNotCancelled(
 }
 
 async function cancelSessionSubtreeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -2375,7 +2378,7 @@ async function cancelSessionSubtreeInTransaction(
 }
 
 export async function mutateSessionControlInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -2694,7 +2697,7 @@ export async function mutateSessionControlInTransaction(
 }
 
 export async function autoResumeSessionBranchInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     workspaceId: string;
     sessionId: string;

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 { withLosslessContentWriteVersion } from "./lossless-json";
+import type { Database, SessionActivityDatabase } from "./database";
+import {
+  fromPostgresLosslessJson,
+  fromPostgresLosslessText,
+  withLosslessContentWriteVersion,
+} from "./lossless-json";
 import { closePendingSessionToolCallsInTransaction } from "./session-tool-call-settlement";
 import {
   assertAgentCommandAuthorityInTransaction,
@@ -97,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;
@@ -106,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;
@@ -414,7 +498,7 @@ async function loadQueuedTurns(
 }
 
 async function normalizeQueuePositions(
-  db: Database,
+  db: SessionActivityDatabase,
   workspaceId: string,
   sessionId: string,
   orderedIds: string[],
@@ -446,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[] {
@@ -503,6 +599,7 @@ export async function saveComposerDraftInTransaction(
     subjectId: string;
     expectedRevision: number;
     text: string;
+    annotations?: DraftTimelineAnnotation[];
     resources: ResourceRef[];
     model: string;
     reasoningEffort: ReasoningEffort;
@@ -534,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,
@@ -559,7 +657,7 @@ export async function saveComposerDraftInTransaction(
 }
 
 export async function moveQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -695,7 +793,7 @@ export async function moveQueuedTurnInTransaction(
 }
 
 export async function deleteSessionQueueItemInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -826,7 +924,7 @@ export async function deleteSessionQueueItemInTransaction(
 }
 
 export async function editQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -919,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,
@@ -1007,7 +1106,7 @@ export async function editQueuedTurnInTransaction(
 }
 
 export async function steerQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -1240,7 +1339,7 @@ export async function steerQueuedTurnInTransaction(
 }
 
 export async function submitHumanPromptInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -1253,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;
@@ -1270,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;
@@ -1277,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,
@@ -1293,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,
@@ -1332,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,
@@ -1404,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,
@@ -1411,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,
@@ -1531,6 +1667,7 @@ export async function submitHumanPromptInTransaction(
       clientEventId: input.operationKey,
       payload: {
         text: input.messagePresentation?.text ?? input.text,
+        ...(annotations.length > 0 ? { annotations } : {}),
         ...(input.messagePresentation
           ? {
               presentation: {
@@ -1565,6 +1702,7 @@ export async function submitHumanPromptInTransaction(
           source: input.source,
           position: input.delivery === "steer" ? 0 : existingQueued.length + 1,
           prompt: input.text,
+          annotations,
           turnInstructions:
             editedSourceTurnInstructions !== undefined
               ? editedSourceTurnInstructions
@@ -1601,6 +1739,7 @@ export async function submitHumanPromptInTransaction(
     )
     .returning();
   if (!turn) throw new SessionControlInvariantError("Prompt turn was not inserted");
+  let committedTurn = turn;
   eventValues.push({
     accountId: input.accountId,
     workspaceId: input.workspaceId,
@@ -1651,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: {
@@ -1669,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;
@@ -1749,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,
@@ -1811,6 +1955,27 @@ export async function submitHumanPromptInTransaction(
       "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,
@@ -1832,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,
@@ -1846,7 +2019,7 @@ export async function submitHumanPromptInTransaction(
 }
 
 export async function sendAgentMessageInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -2050,7 +2223,7 @@ export async function sendAgentMessageInTransaction(
 }
 
 export async function steerAgentSessionInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;

package/src/session-realtime-context.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { ReasoningEffort } from "@opengeni/contracts";
 import { and, asc, desc, eq, inArray, isNull, sql } from "drizzle-orm";
 
-import type { Database } from "./database";
+import type { Database, SessionActivityDatabase } from "./database";
 import { fromPostgresLosslessJson, fromPostgresLosslessText } from "./lossless-json";
 import * as schema from "./schema";
 import { submitHumanPromptInTransaction } from "./session-queue-commands";
@@ -178,7 +178,7 @@ function mapProjection(
  * delegation into the same canonical Steer-or-start path used by a human.
  */
 export async function flushSessionRealtimeTranscriptTailInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;

package/src/session-realtime-ledger.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { LatencyMode, ReasoningEffort, type SessionRealtimeMode } from "@opengeni/contracts";
 import { and, asc, desc, eq, inArray, isNull, or, sql } from "drizzle-orm";
 
-import type { Database } from "./database";
+import type { Database, SessionActivityDatabase } from "./database";
 import {
   fromPostgresLosslessJson,
   fromPostgresLosslessText,
@@ -1075,7 +1075,7 @@ async function appendInvalidDelegationFailure(
 }
 
 async function admitRealtimeDelegationInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: Pick<
     SyncSessionRealtimeLedgerInput,
     "workspaceId" | "sessionId" | "realtimeId" | "connectionEpoch" | "ownerSubjectId"
@@ -1268,7 +1268,7 @@ function assertProviderAckSequences(values: number[] | undefined, maximum: numbe
 }
 
 export async function syncSessionRealtimeLedgerInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: SyncSessionRealtimeLedgerInput,
   hooks: SyncSessionRealtimeLedgerHooks = {},
 ): Promise<SyncSessionRealtimeLedgerResult> {

package/src/session-realtime.ts

@@ -8,7 +8,7 @@ import type {
 } from "@opengeni/contracts";
 import { and, asc, eq, gt, inArray, isNull, or } from "drizzle-orm";
 
-import type { Database } from "./database";
+import type { Database, SessionActivityDatabase } from "./database";
 import { LOSSLESS_CONTENT_CODEC_VERSION } from "./lossless-json";
 import { flushSessionRealtimeTranscriptTailInTransaction } from "./session-realtime-context";
 import {
@@ -161,7 +161,7 @@ function assertOwner(
 }
 
 async function appendRealtimeLifecycleEvent(
-  db: Database,
+  db: SessionActivityDatabase,
   session: SessionRow,
   sequence: number,
   type: Extract<SessionEventType, "session.realtime.started" | "session.realtime.ended">,
@@ -259,7 +259,7 @@ async function registerNormalModeWake(db: Database, session: SessionRow, reason:
 }
 
 async function endWithEvent(
-  db: Database,
+  db: SessionActivityDatabase,
   session: SessionRow,
   row: RealtimeRow,
   reason: SessionRealtimeEndReason,
@@ -352,7 +352,7 @@ function assertRealtimeAdmission(session: SessionRow): void {
 }
 
 export async function beginSessionRealtimeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: BeginSessionRealtimeInput,
 ): Promise<SessionRealtimeMutationResult> {
   const now = input.now ?? new Date();
@@ -553,7 +553,7 @@ export async function assertSessionRealtimeOwnerInTransaction(
 }
 
 export async function renewSessionRealtimeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: RenewSessionRealtimeInput,
 ): Promise<RenewSessionRealtimeResult> {
   const now = input.now ?? new Date();
@@ -616,7 +616,7 @@ export async function renewSessionRealtimeInTransaction(
 }
 
 export async function endSessionRealtimeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: EndSessionRealtimeInput,
 ): Promise<SessionRealtimeMutationResult> {
   const now = input.now ?? new Date();
@@ -649,7 +649,7 @@ export async function endSessionRealtimeInTransaction(
 
 /** Lazily settle an expired voice lease under the canonical session lock. */
 export async function settleExpiredSessionRealtimeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   session: SessionRow,
   now = new Date(),
 ): Promise<SessionRow> {

package/src/session-tool-call-settlement.ts

@@ -4,6 +4,7 @@ import { and, asc, eq, sql } from "drizzle-orm";
 import type { Database } from "./database";
 import { fromPostgresLosslessJson, LOSSLESS_CONTENT_CODEC_VERSION } from "./lossless-json";
 import * as schema from "./schema";
+import { cancelUnacceptedVideoGenerationsForToolCallsInTransaction } from "./video-generation";
 
 export const TOOL_RESULT_TYPE_BY_CALL_TYPE: Readonly<Record<string, string>> = {
   function_call: "function_call_result",
@@ -326,6 +327,14 @@ export async function closePendingSessionToolCallsInTransaction(
     eventValues.length > 0
       ? await tx.insert(schema.sessionEvents).values(eventValues).returning()
       : [];
+  await cancelUnacceptedVideoGenerationsForToolCallsInTransaction(tx, {
+    workspaceId: input.workspaceId,
+    sessionId: input.sessionId,
+    turnId: input.turnId,
+    toolCallIds: pending.map((call) => call.callId),
+    reason: input.reason,
+    now: input.now,
+  });
   await tx
     .delete(schema.sessionPendingToolCalls)
     .where(