@opengeni/db 0.36.1 → 1.0.1

package/src/schema.ts

@@ -2464,10 +2464,10 @@ export const sessions = pgTable(
     status: text("status").notNull().default("queued"),
     initialMessage: losslessText("initial_message").notNull(),
     initialMessageCodecVersion: losslessCodecVersion("initial_message_codec_version"),
-    // Invisible host context frozen with the winning session create. The
-    // initial turn copies this value so an idempotent repair can never adopt a
-    // retrying caller's different instructions.
-    initialTurnInstructions: text("initial_turn_instructions"),
+    // Model-visible application context frozen with the winning create. The
+    // initial turn copies it into the canonical user message so an idempotent
+    // repair cannot adopt a retrying caller's different message context.
+    initialModelContext: text("initial_model_context"),
     title: text("title"),
     titleSource: text("title_source"),
     // Per-session agent persona/system instructions supplied at create (the
@@ -2762,6 +2762,11 @@ export const sessions = pgTable(
       table.rootSessionId,
       table.nestedAgentDepth,
     ),
+    initialModelContextValid: check(
+      "sessions_initial_model_context_check",
+      sql`${table.initialModelContext} is null
+        or opengeni_private.model_context_value_valid(${table.initialModelContext})`,
+    ),
   }),
 );
 
@@ -3115,6 +3120,9 @@ export const sessionRealtimeEntries = pgTable(
     textCodecVersion: losslessCodecVersion("text_codec_version"),
     payload: losslessJsonb("payload").$type<Record<string, unknown>>().notNull().default({}),
     payloadCodecVersion: losslessCodecVersion("payload_codec_version"),
+    // Application context for an exact provider-in delegation or finalized
+    // transcript. It is materialized as ordinary user-role message content.
+    modelContext: text("model_context"),
     clientAckedAt: timestamp("client_acked_at", { withTimezone: true }),
     providerAckedAt: timestamp("provider_acked_at", { withTimezone: true }),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
@@ -3190,6 +3198,15 @@ export const sessionRealtimeEntries = pgTable(
         or (${table.kind} = 'assistant_transcript' and ${table.role} = 'assistant' and ${table.text} is not null)
         or (${table.kind} not in ('user_transcript', 'assistant_transcript') and ${table.role} is null)`,
     ),
+    modelContextValid: check(
+      "session_realtime_entries_model_context_check",
+      sql`${table.modelContext} is null
+        or (
+          ${table.direction} = 'provider_in'
+          and ${table.kind} in ('delegation_call', 'user_transcript', 'assistant_transcript')
+          and opengeni_private.model_context_value_valid(${table.modelContext})
+        )`,
+    ),
   }),
 );
 
@@ -4497,9 +4514,10 @@ export const sessionTurns = pgTable(
     prompt: losslessText("prompt").notNull(),
     promptCodecVersion: losslessCodecVersion("prompt_codec_version"),
     annotations: jsonb("annotations").$type<TimelineAnnotation[]>().notNull().default([]),
-    // Host context for this exact turn. System-level at runtime and deliberately
-    // separate from the visible prompt/event payload.
-    turnInstructions: text("turn_instructions"),
+    // Application context for this exact user message. It is copied into the
+    // canonical user-role history item at claim and omitted from public queue
+    // projections; full event/audit data retains it.
+    modelContext: text("model_context"),
     resources: jsonb("resources").$type<unknown[]>().notNull().default([]),
     tools: jsonb("tools").$type<unknown[]>().notNull().default([]),
     // false = inherit the durable session policy; true = this turn explicitly
@@ -4579,6 +4597,11 @@ export const sessionTurns = pgTable(
       "session_turns_latency_mode_check",
       sql`${table.latencyMode} in ('standard', 'priority', 'fast')`,
     ),
+    modelContextValid: check(
+      "session_turns_model_context_check",
+      sql`${table.modelContext} is null
+        or opengeni_private.model_context_value_valid(${table.modelContext})`,
+    ),
   }),
 );
 

package/src/session-queue-commands.ts

@@ -1414,7 +1414,7 @@ export async function submitHumanPromptInTransaction(
     expectedDraftRevision?: number | null;
     text: string;
     annotations?: TimelineAnnotation[];
-    turnInstructions?: string | null;
+    modelContext?: string | null;
     resources: ResourceRef[];
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
@@ -1458,7 +1458,7 @@ export async function submitHumanPromptInTransaction(
     expectedDraftRevision: input.expectedDraftRevision ?? null,
     text: input.text,
     annotations,
-    turnInstructions: input.turnInstructions ?? null,
+    modelContext: input.modelContext ?? null,
     resources: withCanonicalResourceMountPaths(input.resources),
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
@@ -1626,7 +1626,7 @@ export async function submitHumanPromptInTransaction(
   }
 
   let editedSourceTurn: QueuedTurnRow | undefined;
-  let editedSourceTurnInstructions: string | null | undefined;
+  let editedSourceModelContext: string | null | undefined;
   if (draft?.sourceTurnId) {
     const sourceLocks = await lockSessionEventWriteRows(db, {
       workspaceId: input.workspaceId,
@@ -1661,14 +1661,11 @@ export async function submitHumanPromptInTransaction(
         },
       );
     }
-    // This is the sole private-instruction source for an edited replacement.
-    // It is deliberately held separately from the public draft and event
-    // projections below. The public draft is expected to differ after editing;
-    // source identity is fenced by its exact withdrawn row version, not by
-    // comparing the replacement content with the old prompt. A client-supplied
-    // instruction value must never override the private source value.
+    // Preserve the non-rendered message segment when editing only the visible
+    // draft. Source identity is fenced by the exact withdrawn row version; a
+    // replacement request cannot accidentally detach or replace its context.
     editedSourceTurn = sourceTurn;
-    editedSourceTurnInstructions = sourceTurn.turnInstructions ?? null;
+    editedSourceModelContext = sourceTurn.modelContext ?? null;
   }
 
   for (const update of input.mcpCredentialUpdates ?? []) {
@@ -1725,6 +1722,10 @@ export async function submitHumanPromptInTransaction(
   const acceptedEventId = crypto.randomUUID();
   const turnId = crypto.randomUUID();
   const workflowId = session.temporalWorkflowId ?? `session-${session.id}`;
+  const effectiveModelContext =
+    editedSourceModelContext !== undefined
+      ? editedSourceModelContext
+      : (input.modelContext ?? null);
   let sequence = session.lastSequence;
   const eventValues: SessionEventInsertWithPayload[] = [
     {
@@ -1747,6 +1748,7 @@ export async function submitHumanPromptInTransaction(
             }
           : {}),
         ...(input.resources.length ? { resources: input.resources } : {}),
+        ...(effectiveModelContext ? { modelContext: effectiveModelContext } : {}),
         ...(input.model ? { model: input.model } : {}),
         ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
         ...(input.latencyMode ? { latencyMode: input.latencyMode } : {}),
@@ -1773,10 +1775,7 @@ export async function submitHumanPromptInTransaction(
           position: input.delivery === "steer" ? 0 : existingQueued.length + 1,
           prompt: input.text,
           annotations,
-          turnInstructions:
-            editedSourceTurnInstructions !== undefined
-              ? editedSourceTurnInstructions
-              : (input.turnInstructions ?? null),
+          modelContext: effectiveModelContext,
           resources: input.resources,
           tools: [],
           toolsProvided: false,

package/src/session-realtime-context.ts

@@ -237,6 +237,7 @@ export async function flushSessionRealtimeTranscriptTailInTransaction(
       textCodecVersion: schema.sessionRealtimeEntries.textCodecVersion,
       payload: schema.sessionRealtimeEntries.payload,
       payloadCodecVersion: schema.sessionRealtimeEntries.payloadCodecVersion,
+      modelContext: schema.sessionRealtimeEntries.modelContext,
     })
     .from(schema.sessionRealtimeEntries)
     .where(
@@ -258,6 +259,20 @@ export async function flushSessionRealtimeTranscriptTailInTransaction(
   }));
   const rendered = renderSessionRealtimeTail(decodedRows);
   if (!rendered.context) return null;
+  const renderedRows = decodedRows.slice(decodedRows.length - rendered.includedEntryCount);
+  let foundUserTranscript = false;
+  let modelContext: string | null = null;
+  for (let index = renderedRows.length - 1; index >= 0; index -= 1) {
+    const entry = renderedRows[index]!;
+    if (entry.role === "user") {
+      foundUserTranscript = true;
+      modelContext = entry.modelContext;
+      break;
+    }
+  }
+  if (!foundUserTranscript) {
+    modelContext = renderedRows.at(-1)?.modelContext ?? null;
+  }
 
   const [session] = await db
     .select({ metadata: schema.sessions.metadata })
@@ -286,6 +301,7 @@ export async function flushSessionRealtimeTranscriptTailInTransaction(
     operationKey: deterministicUuid(`opengeni:session-realtime-tail-flush:${mode.id}`),
     delivery: "steer",
     text: rendered.context,
+    modelContext,
     messagePresentation: {
       kind: "realtime_voice_handoff",
       text: "Voice session ended. Remaining conversation context was sent to the agent.",

package/src/session-realtime-ledger.ts

@@ -155,6 +155,7 @@ export type SessionRealtimeInboundEntryInput = {
   delegationItemId?: string | null | undefined;
   text?: string | null | undefined;
   payload?: Record<string, unknown> | undefined;
+  modelContext?: string | undefined;
 };
 
 export type SyncSessionRealtimeLedgerInput = AssertSessionRealtimeOwnerInput & {
@@ -1016,12 +1017,34 @@ function canonicalJsonValue(value: unknown): unknown {
   return value;
 }
 
+function normalizedModelContext(input: SessionRealtimeInboundEntryInput): string | null {
+  const value = input.modelContext?.trim();
+  if (!value) {
+    if (input.modelContext !== undefined) {
+      throw new Error("Realtime modelContext must not be empty");
+    }
+    return null;
+  }
+  if (value.length > 32_768) {
+    throw new Error("Realtime modelContext exceeds the server limit");
+  }
+  if (
+    input.kind !== "delegation_call" &&
+    input.kind !== "user_transcript" &&
+    input.kind !== "assistant_transcript"
+  ) {
+    throw new Error("Realtime modelContext requires a delegation or finalized transcript");
+  }
+  return value;
+}
+
 function inboundReplayMatches(
   row: EntryRow,
   input: SessionRealtimeInboundEntryInput,
   role: "user" | "assistant" | null,
   text: string | null,
   payload: Record<string, unknown>,
+  modelContext: string | null,
 ): boolean {
   const storedText =
     row.text === null ? null : fromPostgresLosslessText(row.text, row.textCodecVersion);
@@ -1034,11 +1057,32 @@ function inboundReplayMatches(
     row.delegationItemId === (input.delegationItemId ?? null) &&
     row.sourceUpdateId === null &&
     storedText === text &&
+    row.modelContext === modelContext &&
     JSON.stringify(canonicalJsonValue(storedPayload)) ===
       JSON.stringify(canonicalJsonValue(payload))
   );
 }
 
+async function delegationModelContextMatches(
+  db: Database,
+  row: EntryRow,
+  modelContext: string | null,
+): Promise<boolean> {
+  if (row.kind !== "delegation_call" || row.turnId === null) return true;
+  const [turn] = await db
+    .select({ modelContext: schema.sessionTurns.modelContext })
+    .from(schema.sessionTurns)
+    .where(
+      and(
+        eq(schema.sessionTurns.workspaceId, row.workspaceId),
+        eq(schema.sessionTurns.sessionId, row.sessionId),
+        eq(schema.sessionTurns.id, row.turnId),
+      ),
+    )
+    .limit(1);
+  return turn?.modelContext === modelContext;
+}
+
 async function appendInvalidDelegationFailure(
   db: Database,
   input: Pick<
@@ -1083,6 +1127,7 @@ async function admitRealtimeDelegationInTransaction(
   accountId: string,
   incoming: SessionRealtimeInboundEntryInput,
   entryId: string,
+  modelContext: string | null,
 ): Promise<{ turnId: string; eventIds: string[]; wakeRevision: number }> {
   const [session] = await db
     .select()
@@ -1142,6 +1187,7 @@ async function admitRealtimeDelegationInTransaction(
     operationKey: incoming.operationId,
     delivery: "steer",
     text: incoming.text!,
+    modelContext,
     messagePresentation: {
       kind: "realtime_voice",
       text: inputTranscript,
@@ -1359,6 +1405,7 @@ export async function syncSessionRealtimeLedgerInTransaction(
     const payload = boundedPayload(incoming.payload);
     const role = expectedRole(incoming);
     const text = incoming.text ?? null;
+    const modelContext = normalizedModelContext(incoming);
     assertBoundedString(text, SESSION_REALTIME_LEDGER_MAX_TEXT_BYTES, "Realtime text");
     if (
       (incoming.kind === "user_transcript" || incoming.kind === "assistant_transcript") &&
@@ -1392,7 +1439,10 @@ export async function syncSessionRealtimeLedgerInTransaction(
       )
       .limit(1);
     if (existing) {
-      if (!inboundReplayMatches(existing, incoming, role, text, payload)) {
+      if (
+        !inboundReplayMatches(existing, incoming, role, text, payload, modelContext) ||
+        !(await delegationModelContextMatches(db, existing, modelContext))
+      ) {
         throw new SessionRealtimeConflictError(
           incoming.kind === "delegation_call"
             ? "REALTIME_DELEGATION_CHANGED"
@@ -1423,6 +1473,7 @@ export async function syncSessionRealtimeLedgerInTransaction(
         textCodecVersion: LOSSLESS_CONTENT_CODEC_VERSION,
         payload,
         payloadCodecVersion: LOSSLESS_CONTENT_CODEC_VERSION,
+        modelContext,
         createdAt: now,
         updatedAt: now,
       })
@@ -1447,6 +1498,7 @@ export async function syncSessionRealtimeLedgerInTransaction(
           modeRow.accountId,
           incoming,
           entry.id,
+          modelContext,
         );
         const [linked] = await db
           .update(schema.sessionRealtimeEntries)