@opengeni/db 0.22.1 → 0.23.0

package/dist/schema.js

@@ -95,6 +95,10 @@ import {
   sessionMcpServers,
   sessionPendingToolCalls,
   sessionPins,
+  sessionRealtimeConnections,
+  sessionRealtimeContextProjections,
+  sessionRealtimeEntries,
+  sessionRealtimeModes,
   sessionRecordingCodecValues,
   sessionRecordingModeValues,
   sessionRecordingStateValues,
@@ -125,6 +129,7 @@ import {
   workspaceInstructionPolicyActivationEvents,
   workspaceInstructionPolicyHeads,
   workspaceInstructionPolicyRevisions,
+  workspaceInstructionPolicySnapshots,
   workspaceMemberships,
   workspaceModelPolicies,
   workspacePacks,
@@ -132,7 +137,7 @@ import {
   workspaceVariableSetVariables,
   workspaceVariableSets,
   workspaces
-} from "./chunk-CYGFLLMN.js";
+} from "./chunk-3UCHDMKG.js";
 import "./chunk-PZ5AY32C.js";
 export {
   agentRunStates,
@@ -231,6 +236,10 @@ export {
   sessionMcpServers,
   sessionPendingToolCalls,
   sessionPins,
+  sessionRealtimeConnections,
+  sessionRealtimeContextProjections,
+  sessionRealtimeEntries,
+  sessionRealtimeModes,
   sessionRecordingCodecValues,
   sessionRecordingModeValues,
   sessionRecordingStateValues,
@@ -261,6 +270,7 @@ export {
   workspaceInstructionPolicyActivationEvents,
   workspaceInstructionPolicyHeads,
   workspaceInstructionPolicyRevisions,
+  workspaceInstructionPolicySnapshots,
   workspaceMemberships,
   workspaceModelPolicies,
   workspacePacks,

package/dist/session-control.d.ts

@@ -288,6 +288,12 @@ export type SessionControlMutationResult = {
     workspaceControlEventId: string;
     interruptionCount: number;
     wakeCount: number;
+    cancelledSessionCount: number;
+    cancelledTurnCount: number;
+    affectedSessionEvents: Array<{
+        sessionId: string;
+        eventIds: string[];
+    }>;
     replay: boolean;
 };
 export declare function mutateSessionControlInTransaction(db: Database, input: {
@@ -296,7 +302,7 @@ export declare function mutateSessionControlInTransaction(db: Database, input: {
     sessionId: string;
     actor: SessionCommandActor;
     operationKey: string;
-    action: "pause" | "resume";
+    action: "pause" | "resume" | "cancel";
     reason?: string | null;
     expectedControlEtag?: string | null;
 }): Promise<SessionControlMutationResult>;

package/dist/session-queue-commands.d.ts

@@ -157,6 +157,14 @@ export declare function submitHumanPromptInTransaction(db: Database, input: {
     reasoningEffortFallback: ReasoningEffort;
     /** Trusted API/core admission snapshot. Omitted only by legacy low-level callers. */
     turnExecutionPolicy?: TurnExecutionPolicyV1;
+    /** Trusted core-only metadata attached to the admitted turn. */
+    turnMetadata?: Record<string, unknown>;
+    /** Trusted display projection; the durable turn still receives `text`. */
+    messagePresentation?: {
+        kind: "realtime_voice" | "realtime_voice_handoff";
+        text: string;
+        context: string;
+    };
     source: "user" | "api";
     personalConnectionDelegations?: McpPersonalConnectionDelegation[];
     mcpCredentialUpdates?: Array<{

package/dist/session-realtime-context.d.ts

@@ -0,0 +1,56 @@
+import type { Database } from "./index";
+export declare const SESSION_REALTIME_CONTEXT_MAX_BYTES = 65536;
+export declare const SESSION_REALTIME_TAIL_SOURCE = "transcript_tail_flush";
+export declare const SESSION_REALTIME_TAIL_INSTRUCTION = "The user just ended their realtime session. Here is the remaining handoff/transcript tail. You probably do not have to do anything; acknowledge the handoff unless the transcript itself asks for something.";
+export type SessionRealtimeContextProjection = {
+    id: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    context: string | null;
+    sourceModeCount: number;
+    sourceEntryCount: number;
+    includedEntryCount: number;
+    omittedEntryCount: number;
+    createdAt: string;
+};
+export type SessionRealtimeContextSourceEntry = {
+    id: string;
+    realtimeId: string;
+    sequence: number;
+    role: string | null;
+    text: string | null;
+    payload: Record<string, unknown>;
+};
+export type SessionRealtimeContinuityEntry = {
+    realtimeId: string;
+    sequence: number;
+    role: "user" | "assistant";
+    text: string;
+    turnId: string;
+    createdAt: string;
+};
+/** Render the exact finalized tail after the latest provider delegation fence. */
+export declare function renderSessionRealtimeTail(entries: readonly SessionRealtimeContextSourceEntry[]): {
+    context: string | null;
+    includedEntryCount: number;
+    omittedEntryCount: number;
+};
+/**
+ * Codex-style end fence: route only finalized voice transcript after the last
+ * delegation into the same canonical Steer-or-start path used by a human.
+ */
+export declare function flushSessionRealtimeTranscriptTailInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    realtimeId: string;
+    ownerSubjectId: string;
+    now?: Date;
+}): Promise<SessionRealtimeContextProjection | null>;
+export declare function listSessionRealtimeContinuityEntriesInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    maximumEntries?: number;
+}): Promise<SessionRealtimeContinuityEntry[]>;

package/dist/session-realtime-ledger.d.ts

@@ -0,0 +1,188 @@
+import { type SessionRealtimeMode } from "@opengeni/contracts";
+import type { Database } from "./index";
+import { type AssertSessionRealtimeOwnerInput } from "./session-realtime";
+export declare const SESSION_REALTIME_LEDGER_MAX_BATCH = 64;
+export declare const SESSION_REALTIME_LEDGER_MAX_TEXT_BYTES = 131072;
+export declare const SESSION_REALTIME_LEDGER_MAX_PAYLOAD_BYTES = 131072;
+export declare const SESSION_REALTIME_LEDGER_MAX_OUTBOUND = 100;
+export declare const SESSION_REALTIME_STARTUP_MAX_ENTRIES = 100;
+export type SessionRealtimeConnectionState = "negotiating" | "ready" | "active" | "failed" | "closed";
+export type SessionRealtimeConnectionPromotionMode = "legacy" | "staged";
+export type SessionRealtimeConnection = {
+    id: string;
+    realtimeId: string;
+    operationId: string;
+    connectionEpoch: number;
+    startupFenceSequence: number;
+    promotionMode: SessionRealtimeConnectionPromotionMode;
+    state: SessionRealtimeConnectionState;
+    sdpAnswer: string | null;
+    failureCode: string | null;
+    providerSessionId: string | null;
+    startupEventId: string | null;
+    startupAcknowledgedAt: string | null;
+    negotiatedAt: string | null;
+    closedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ClaimSessionRealtimeConnectionInput = AssertSessionRealtimeOwnerInput & {
+    operationId: string;
+    expectedConnectionEpoch: number;
+    rotate: boolean;
+    promotionMode?: SessionRealtimeConnectionPromotionMode | undefined;
+};
+export type ClaimSessionRealtimeConnectionResult = {
+    connection: SessionRealtimeConnection;
+    startupEntries: SessionRealtimeLedgerEntry[];
+    mode: SessionRealtimeMode;
+    modeVersion: number;
+    replay: boolean;
+};
+export type CompleteSessionRealtimeConnectionInput = {
+    workspaceId: string;
+    sessionId: string;
+    realtimeId: string;
+    connectionId: string;
+    operationId: string;
+    connectionEpoch: number;
+    sdpAnswer: string;
+    now?: Date;
+};
+export type CompleteSessionRealtimeConnectionResult = {
+    connection: SessionRealtimeConnection;
+    replay: boolean;
+};
+export type ActivateSessionRealtimeConnectionInput = AssertSessionRealtimeOwnerInput & {
+    operationId: string;
+    connectionId: string;
+    connectionEpoch: number;
+    expectedConnectionEpoch: number;
+};
+export type ActivateSessionRealtimeConnectionResult = {
+    connection: SessionRealtimeConnection;
+    mode: SessionRealtimeMode;
+    replay: boolean;
+};
+export type FailSessionRealtimeConnectionInput = Omit<CompleteSessionRealtimeConnectionInput, "sdpAnswer"> & {
+    failureCode: string;
+};
+export type FailSessionRealtimeConnectionResult = {
+    connection: SessionRealtimeConnection;
+    replay: boolean;
+};
+export type SessionRealtimeLedgerDirection = "provider_in" | "provider_out";
+export type SessionRealtimeLedgerKind = "user_transcript" | "assistant_transcript" | "delegation_call" | "delegation_progress" | "delegation_result" | "interruption" | "session_update" | "error";
+export type SessionRealtimeLedgerEntry = {
+    id: string;
+    realtimeId: string;
+    operationId: string;
+    connectionEpoch: number;
+    sequence: number;
+    direction: SessionRealtimeLedgerDirection;
+    kind: SessionRealtimeLedgerKind;
+    role: "user" | "assistant" | null;
+    providerEventId: string | null;
+    delegationItemId: string | null;
+    sourceUpdateId: string | null;
+    historyItemId: string | null;
+    turnId: string | null;
+    text: string | null;
+    payload: Record<string, unknown>;
+    clientAckedAt: string | null;
+    providerAckedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type SessionRealtimeInboundEntryInput = {
+    operationId: string;
+    kind: Exclude<SessionRealtimeLedgerKind, "delegation_progress" | "delegation_result" | "session_update">;
+    role?: "user" | "assistant" | null | undefined;
+    providerEventId?: string | null | undefined;
+    delegationItemId?: string | null | undefined;
+    text?: string | null | undefined;
+    payload?: Record<string, unknown> | undefined;
+};
+export type SyncSessionRealtimeLedgerInput = AssertSessionRealtimeOwnerInput & {
+    connectionId: string;
+    connectionEpoch: number;
+    entries?: SessionRealtimeInboundEntryInput[] | undefined;
+    clientAckThroughSequence?: number | null | undefined;
+    providerAckSequences?: number[] | undefined;
+    providerStarted?: {
+        providerSessionId: string;
+        providerEventId?: string | null | undefined;
+    } | undefined;
+};
+export type SyncSessionRealtimeLedgerResult = {
+    accepted: Array<{
+        entry: SessionRealtimeLedgerEntry;
+        replay: boolean;
+    }>;
+    outbound: SessionRealtimeLedgerEntry[];
+    eventIds: string[];
+    workflowWakeRevision: number | null;
+};
+export type SyncSessionRealtimeLedgerHooks = {
+    /** Test-only failure injection after both durable admission rows exist. */
+    afterDelegationAdmission?: ((admission: {
+        entryId: string;
+        turnId: string;
+    }) => void | Promise<void>) | undefined;
+};
+export type AppendSessionRealtimeOutboundInput = {
+    workspaceId: string;
+    sessionId: string;
+    realtimeId: string;
+    operationId: string;
+    connectionEpoch: number;
+    kind: Extract<SessionRealtimeLedgerKind, "delegation_result" | "error">;
+    delegationItemId?: string | null;
+    text?: string | null;
+    payload?: Record<string, unknown>;
+    now?: Date;
+};
+export type AppendSessionRealtimeOutboundResult = {
+    entry: SessionRealtimeLedgerEntry;
+    replay: boolean;
+};
+export { projectSessionRealtimeDelegationTerminalInTransaction, type ProjectSessionRealtimeDelegationTerminalInput, type ProjectSessionRealtimeDelegationTerminalResult, } from "./session-realtime-terminal";
+export type ProjectSessionRealtimeDelegationProgressInput = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    events: ReadonlyArray<{
+        id: string;
+        sequence: number;
+        type: string;
+        payload: unknown;
+    }>;
+    now?: Date;
+};
+export type ProjectSessionRealtimeDelegationProgressResult = {
+    entries: SessionRealtimeLedgerEntry[];
+};
+/** True only for an exact provider-call-linked ordinary turn shape. */
+export declare function isSessionRealtimeDelegationTurnMetadata(metadata: Record<string, unknown>): boolean;
+export declare function claimSessionRealtimeConnectionInTransaction(db: Database, input: ClaimSessionRealtimeConnectionInput): Promise<ClaimSessionRealtimeConnectionResult>;
+export declare function completeSessionRealtimeConnectionInTransaction(db: Database, input: CompleteSessionRealtimeConnectionInput): Promise<CompleteSessionRealtimeConnectionResult>;
+export declare function activateSessionRealtimeConnectionInTransaction(db: Database, input: ActivateSessionRealtimeConnectionInput): Promise<ActivateSessionRealtimeConnectionResult>;
+export declare function failSessionRealtimeConnectionInTransaction(db: Database, input: FailSessionRealtimeConnectionInput): Promise<FailSessionRealtimeConnectionResult>;
+export declare function syncSessionRealtimeLedgerInTransaction(db: Database, input: SyncSessionRealtimeLedgerInput, hooks?: SyncSessionRealtimeLedgerHooks): Promise<SyncSessionRealtimeLedgerResult>;
+export declare function appendSessionRealtimeOutboundInTransaction(db: Database, input: AppendSessionRealtimeOutboundInput): Promise<AppendSessionRealtimeOutboundResult>;
+/**
+ * Under the caller's canonical session/turn fence, mirror accepted assistant
+ * text deltas into the active delegation's durable provider-out stream. One
+ * append batch becomes one or more bounded progress rows, preserving the
+ * ordinary event order without making the browser's live SSE authoritative.
+ */
+export declare function projectSessionRealtimeDelegationProgressInTransaction(db: Database, input: ProjectSessionRealtimeDelegationProgressInput): Promise<ProjectSessionRealtimeDelegationProgressResult>;
+/**
+ * Project the authoritative terminal event of an accepted same-session
+ * delegation into exactly one outbound ledger row. The caller already owns the
+ * canonical session/turn settlement locks; this helper deliberately does not
+ * require the original provider connection (or even the mode) to remain
+ * active. A later valid rotation may therefore replay the same durable row,
+ * while the immutable realtime id prevents projection into another mode.
+ */

package/dist/session-realtime-mirror.d.ts

@@ -0,0 +1,30 @@
+import type { Database } from "./index";
+import * as schema from "./schema";
+export type SessionRealtimeMirrorChannel = "speakable" | "commentary" | null;
+export type MirrorSessionRealtimeContextInput = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    sourceKind: "human_input" | "assistant_progress" | "assistant_terminal";
+    sourceId: string;
+    text: string;
+    channel: SessionRealtimeMirrorChannel;
+    turnId?: string | null;
+    payload?: Record<string, unknown> | undefined;
+    now?: Date | undefined;
+};
+export type MirrorSessionRealtimeContextResult = {
+    entry: typeof schema.sessionRealtimeEntries.$inferSelect;
+    replay: boolean;
+} | null;
+/**
+ * Append one canonical same-session fact to the active realtime conversation.
+ * The caller already owns the session event-write lock. Locking the active mode
+ * serializes sequence allocation with lifecycle end and browser ledger sync.
+ */
+export declare function mirrorSessionRealtimeContextInTransaction(db: Database, input: MirrorSessionRealtimeContextInput): Promise<MirrorSessionRealtimeContextResult>;
+export declare function renderRealtimeHumanInputContext(input: {
+    delivery: "send" | "steer";
+    routing: "accepted_for_execution" | "queued_for_execution" | "accepted_for_steering";
+    text: string;
+}): string;

package/dist/session-realtime-state.d.ts

@@ -0,0 +1,2 @@
+import type { Database } from "./index";
+export declare function sessionRealtimeIsActiveInTransaction(db: Database, workspaceId: string, sessionId: string, now?: Date): Promise<boolean>;

package/dist/session-realtime-terminal.d.ts

@@ -0,0 +1,40 @@
+import type { Database } from "./index";
+export type ProjectSessionRealtimeDelegationTerminalInput = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    turnStatus: "completed" | "failed" | "cancelled" | "superseded";
+    terminalEvent: {
+        type: "turn.completed" | "turn.failed" | "turn.cancelled" | "turn.superseded";
+        payload: Record<string, unknown>;
+    };
+    now?: Date;
+};
+export type SessionRealtimeTerminalEntry = {
+    id: string;
+    realtimeId: string;
+    operationId: string;
+    connectionEpoch: number;
+    sequence: number;
+    direction: "provider_in" | "provider_out";
+    kind: "user_transcript" | "assistant_transcript" | "delegation_call" | "delegation_progress" | "delegation_result" | "interruption" | "session_update" | "error";
+    role: "user" | "assistant" | null;
+    providerEventId: string | null;
+    delegationItemId: string | null;
+    sourceUpdateId: string | null;
+    historyItemId: string | null;
+    turnId: string | null;
+    text: string | null;
+    payload: Record<string, unknown>;
+    clientAckedAt: string | null;
+    providerAckedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ProjectSessionRealtimeDelegationTerminalResult = {
+    entry: SessionRealtimeTerminalEntry;
+    replay: boolean;
+} | null;
+/** One terminal projection for every realtime-delegated durable turn. */
+export declare function projectSessionRealtimeDelegationTerminalInTransaction(db: Database, input: ProjectSessionRealtimeDelegationTerminalInput): Promise<ProjectSessionRealtimeDelegationTerminalResult>;

package/dist/session-realtime.d.ts

@@ -0,0 +1,59 @@
+import type { SessionRealtimeEndReason, SessionRealtimeMode, SessionRealtimeModel } from "@opengeni/contracts";
+import type { Database } from "./index";
+import * as schema from "./schema";
+export { sessionRealtimeIsActiveInTransaction } from "./session-realtime-state";
+export declare const SESSION_REALTIME_LEASE_MS = 30000;
+export type SessionRealtimeConflictCode = "SESSION_CANCELLED" | "CONTROL_NOT_ACTIVE" | "REALTIME_ACTIVE" | "REALTIME_NOT_FOUND" | "REALTIME_NOT_ACTIVE" | "REALTIME_OWNER_MISMATCH" | "REALTIME_VERSION_CHANGED" | "REALTIME_CONNECTION_CHANGED" | "REALTIME_CONNECTION_ACTIVE" | "REALTIME_CONNECTION_NOT_FOUND" | "REALTIME_CONNECTION_STATE_CHANGED" | "REALTIME_PROVIDER_NOT_STARTED" | "REALTIME_DELEGATION_CHANGED" | "REALTIME_ENTRY_CHANGED" | "REALTIME_ACK_INVALID";
+export declare class SessionRealtimeConflictError extends Error {
+    readonly code: SessionRealtimeConflictCode;
+    readonly name = "SessionRealtimeConflictError";
+    constructor(code: SessionRealtimeConflictCode, message: string);
+}
+type SessionRow = typeof schema.sessions.$inferSelect;
+export type BeginSessionRealtimeInput = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    operationId: string;
+    ownerSubjectId: string;
+    browserInstanceId: string;
+    ownerKey: string;
+    model: SessionRealtimeModel;
+    now?: Date;
+    leaseMs?: number;
+};
+export type RenewSessionRealtimeInput = {
+    workspaceId: string;
+    sessionId: string;
+    realtimeId: string;
+    ownerSubjectId: string;
+    browserInstanceId: string;
+    ownerKey: string;
+    expectedVersion: number;
+    now?: Date;
+    leaseMs?: number;
+};
+export type EndSessionRealtimeInput = Omit<RenewSessionRealtimeInput, "leaseMs"> & {
+    reason: Extract<SessionRealtimeEndReason, "user_stop" | "browser_unload">;
+};
+export type AssertSessionRealtimeOwnerInput = Omit<RenewSessionRealtimeInput, "leaseMs">;
+export type SessionRealtimeMutationResult = {
+    mode: SessionRealtimeMode;
+    replay: boolean;
+    eventIds: string[];
+    workflowWakeRevision: number | null;
+};
+export type RenewSessionRealtimeResult = SessionRealtimeMutationResult & {
+    expired: boolean;
+};
+export declare function beginSessionRealtimeInTransaction(db: Database, input: BeginSessionRealtimeInput): Promise<SessionRealtimeMutationResult>;
+/**
+ * Fence a provider connection to the exact active authenticated browser owner.
+ * The caller must finish this transaction before contacting the provider; owner
+ * proof is authorization material and must never cross that boundary.
+ */
+export declare function assertSessionRealtimeOwnerInTransaction(db: Database, input: AssertSessionRealtimeOwnerInput): Promise<SessionRealtimeMode>;
+export declare function renewSessionRealtimeInTransaction(db: Database, input: RenewSessionRealtimeInput): Promise<RenewSessionRealtimeResult>;
+export declare function endSessionRealtimeInTransaction(db: Database, input: EndSessionRealtimeInput): Promise<SessionRealtimeMutationResult>;
+/** Lazily settle an expired voice lease under the canonical session lock. */
+export declare function settleExpiredSessionRealtimeInTransaction(db: Database, session: SessionRow, now?: Date): Promise<SessionRow>;