@opengeni/db 0.4.1 → 0.6.1

package/src/index.ts

@@ -9,9 +9,17 @@ import type {
   CapabilityKind,
   CapabilityPack,
   CapabilitySource,
+  ConnectionKind,
+  ConnectionMetadata,
+  ConnectionStatus,
+  McpServerConnectionRef,
   FileAsset,
   FileStatus,
   FileUploadStatus,
+  KnowledgeMemory,
+  KnowledgeMemoryKind,
+  KnowledgeMemoryStatus,
+  KnowledgeSourceRef,
   ManagedAccount,
   Permission,
   PackInstallation,
@@ -58,7 +66,7 @@ import { isCodexBilledModel } from "@opengeni/codex";
 // Re-exported so consumers get the whole codex-billed detection surface (the pure
 // prefix test + the credential-aware predicates below) from a single import.
 export { isCodexBilledModel } from "@opengeni/codex";
-import { and, asc, desc, eq, gt, gte, inArray, lt, ne, sql, type SQL } from "drizzle-orm";
+import { and, asc, desc, eq, gt, gte, inArray, isNull, lt, ne, or, sql, type SQL } from "drizzle-orm";
 import type { PgDatabase } from "drizzle-orm/pg-core";
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
@@ -347,6 +355,8 @@ export const allWorkspacePermissions: Permission[] = [
   "github:manage",
   "github:use",
   "api_keys:manage",
+  "connections:read",
+  "connections:write",
   "environments:manage",
   "environments:use",
   "mcp_servers:attach",
@@ -1132,6 +1142,38 @@ export type RegisterWorkspacePackInput = {
   pack: CapabilityPack;
 };
 
+export type CreateKnowledgeMemoryInput = {
+  accountId: string;
+  workspaceId: string;
+  status?: KnowledgeMemoryStatus | undefined;
+  kind?: KnowledgeMemoryKind | undefined;
+  scope?: string | undefined;
+  text: string;
+  sourceRefs?: KnowledgeSourceRef[] | undefined;
+  confidence?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
+  createdBySessionId?: string | null | undefined;
+};
+
+export type UpdateKnowledgeMemoryInput = {
+  status?: KnowledgeMemoryStatus | undefined;
+  kind?: KnowledgeMemoryKind | undefined;
+  scope?: string | undefined;
+  text?: string | undefined;
+  sourceRefs?: KnowledgeSourceRef[] | undefined;
+  confidence?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
+  reviewedBy?: string | null | undefined;
+};
+
+export type ListKnowledgeMemoryOptions = {
+  query?: string | undefined;
+  status?: KnowledgeMemoryStatus | undefined;
+  kind?: KnowledgeMemoryKind | undefined;
+  scope?: string | undefined;
+  limit?: number | undefined;
+};
+
 export type CreateSocialConnectionInput = {
   accountId: string;
   workspaceId: string;
@@ -1159,6 +1201,95 @@ export type CreateSocialPostInput = {
   raw?: Record<string, unknown>;
 };
 
+export type CreateConnectionInput = {
+  accountId: string;
+  workspaceId: string;
+  subjectId?: string | null;
+  providerDomain: string;
+  kind: ConnectionKind;
+  status?: ConnectionStatus;
+  credentialEncrypted: string;
+  grantedScopes?: string[];
+  expiresAt?: Date | null;
+  metadata?: Record<string, unknown>;
+  createdBySubjectId?: string | null;
+  updatedBySubjectId?: string | null;
+};
+
+export type UpdateConnectionInput = {
+  workspaceId: string;
+  connectionId: string;
+  visibleToSubjectId?: string | null;
+  expectedVersion?: number | undefined;
+  subjectId?: string | null;
+  providerDomain?: string;
+  kind?: ConnectionKind;
+  status?: ConnectionStatus;
+  credentialEncrypted?: string;
+  grantedScopes?: string[];
+  expiresAt?: Date | null;
+  metadata?: Record<string, unknown>;
+  updatedBySubjectId?: string | null;
+};
+
+export type ConnectionCredentialForBroker = {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  subjectId: string | null;
+  providerDomain: string;
+  kind: ConnectionKind;
+  status: ConnectionStatus;
+  credential: Record<string, unknown>;
+  grantedScopes: string[];
+  expiresAt: Date | null;
+  lastRefreshAt: Date | null;
+  version: number;
+  metadata: Record<string, unknown>;
+};
+
+export type IntegrationOAuthClientForUse = {
+  id: string;
+  issuer: string;
+  authorizationServer: string;
+  clientId: string;
+  clientSecret: string | null;
+  tokenEndpointAuthMethod: string;
+  metadata: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type StoredIntegrationOAuthClient = {
+  id: string;
+  issuer: string;
+  authorizationServer: string;
+  clientId: string;
+  clientSecretEncrypted: string | null;
+  tokenEndpointAuthMethod: string;
+  metadata: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type StoreIntegrationOAuthClientInput = {
+  issuer: string;
+  authorizationServer: string;
+  clientId: string;
+  clientSecretEncrypted?: string | null;
+  tokenEndpointAuthMethod?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export type ConsumeOAuthStateNonceInput = {
+  accountId: string;
+  workspaceId: string;
+  subjectId: string;
+  nonce: string;
+  expiresAt: Date;
+  now: Date;
+};
+
 export type CreateCapabilityCatalogItemInput = {
   accountId: string;
   workspaceId: string;
@@ -1176,6 +1307,69 @@ export type CreateCapabilityCatalogItemInput = {
   metadata?: Record<string, unknown>;
 };
 
+export type ImportBatch = {
+  id: string;
+  source: string;
+  snapshotDate: string;
+  snapshotRef: string | null;
+  attributionNote: string;
+  importedCount: number;
+  skippedCount: number;
+  quarantinedCount: number;
+  logoFailureCount: number;
+  staleCount: number;
+  details: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type CreateImportBatchInput = {
+  source: string;
+  snapshotDate: Date;
+  snapshotRef?: string | null;
+  attributionNote: string;
+  importedCount?: number;
+  skippedCount?: number;
+  quarantinedCount?: number;
+  logoFailureCount?: number;
+  staleCount?: number;
+  details?: Record<string, unknown>;
+};
+
+export type UpdateImportBatchCountsInput = {
+  importedCount: number;
+  skippedCount: number;
+  quarantinedCount: number;
+  logoFailureCount: number;
+  staleCount: number;
+  details?: Record<string, unknown>;
+};
+
+export type RegistryCapabilityCatalogItemInput = {
+  id: string;
+  providerDomain: string;
+  name: string;
+  description?: string | null;
+  mcpUrl: string;
+  transport: string;
+  authKind: "oauth2" | "api_key" | "none" | "unknown";
+  credentialFacts: Array<Record<string, unknown>>;
+  tier: "verified" | "community";
+  provenance: string;
+  logoAssetPath?: string | null;
+  importBatchId: string;
+  scopesHint?: string[];
+  homepageUrl?: string | null;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+};
+
+export type RegistryCatalogSurfaceKey = {
+  id: string;
+  providerDomain: string;
+  mcpUrl: string;
+};
+
 export type EnableCapabilityInstallationInput = {
   accountId: string;
   workspaceId: string;
@@ -1200,6 +1394,7 @@ export type EnabledMcpCapabilityServer = {
    * capability API surface.
    */
   headersEncrypted?: Record<string, string>;
+  connectionRef?: McpServerConnectionRef;
 };
 
 export type CreateSessionMcpServerInput = {
@@ -1209,6 +1404,7 @@ export type CreateSessionMcpServerInput = {
   allowedTools?: string[] | null;
   timeoutMs?: number | null;
   cacheToolsList?: boolean | null;
+  requireApproval?: boolean | string[] | null;
   headersEncrypted?: Record<string, string>;
 };
 
@@ -1226,6 +1422,7 @@ export type SessionMcpServerForRun = SessionMcpServerMetadata & {
   allowedTools?: string[];
   timeoutMs?: number;
   cacheToolsList?: boolean;
+  requireApproval?: boolean | string[];
   headers: Record<string, string>;
 };
 
@@ -1485,6 +1682,152 @@ export async function deleteWorkspacePack(db: Database, workspaceId: string, pac
   });
 }
 
+const registryCapabilitySource = "registry" as CapabilitySource;
+
+export async function createImportBatch(db: Database, input: CreateImportBatchInput): Promise<ImportBatch> {
+  const [row] = await db.insert(schema.importBatches).values({
+    source: input.source,
+    snapshotDate: input.snapshotDate,
+    snapshotRef: input.snapshotRef ?? null,
+    attributionNote: input.attributionNote,
+    importedCount: input.importedCount ?? 0,
+    skippedCount: input.skippedCount ?? 0,
+    quarantinedCount: input.quarantinedCount ?? 0,
+    logoFailureCount: input.logoFailureCount ?? 0,
+    staleCount: input.staleCount ?? 0,
+    details: input.details ?? {},
+  }).returning();
+  if (!row) {
+    throw new Error("Failed to create import batch");
+  }
+  return mapImportBatch(row);
+}
+
+export async function updateImportBatchCounts(db: Database, id: string, input: UpdateImportBatchCountsInput): Promise<ImportBatch> {
+  const [row] = await db.update(schema.importBatches).set({
+    importedCount: input.importedCount,
+    skippedCount: input.skippedCount,
+    quarantinedCount: input.quarantinedCount,
+    logoFailureCount: input.logoFailureCount,
+    staleCount: input.staleCount,
+    ...(input.details ? { details: input.details } : {}),
+    updatedAt: new Date(),
+  }).where(eq(schema.importBatches.id, id)).returning();
+  if (!row) {
+    throw new Error(`Import batch not found: ${id}`);
+  }
+  return mapImportBatch(row);
+}
+
+export async function upsertRegistryCapabilityCatalogItem(db: Database, input: RegistryCapabilityCatalogItemInput): Promise<CapabilityCatalogItem> {
+  const now = new Date();
+  const metadata = {
+    registry: "integrations.sh",
+    providerDomain: input.providerDomain,
+    scopesHint: input.scopesHint ?? [],
+    ...input.metadata,
+  };
+  const values = {
+    id: input.id,
+    accountId: null,
+    workspaceId: null,
+    kind: "mcp" as Exclude<CapabilityKind, "pack">,
+    source: registryCapabilitySource,
+    name: input.name,
+    description: input.description ?? null,
+    category: "integrations",
+    tags: input.tags ?? ["mcp", "integration", input.tier],
+    homepageUrl: input.homepageUrl ?? `https://${input.providerDomain}`,
+    endpointUrl: input.mcpUrl,
+    installUrl: input.homepageUrl ?? `https://${input.providerDomain}`,
+    authModel: input.authKind === "none" ? null : "credential_ref",
+    providerDomain: input.providerDomain,
+    surfaceType: "mcp",
+    transport: input.transport,
+    mcpUrl: input.mcpUrl,
+    authKind: input.authKind,
+    credentialFacts: input.credentialFacts,
+    tier: input.tier,
+    provenance: input.provenance,
+    logoAssetPath: input.logoAssetPath ?? null,
+    importBatchId: input.importBatchId,
+    stale: false,
+    staleAt: null,
+    metadata,
+    updatedAt: now,
+  };
+  const updateValues = {
+    id: values.id,
+    kind: values.kind,
+    name: values.name,
+    description: values.description,
+    category: values.category,
+    tags: values.tags,
+    homepageUrl: values.homepageUrl,
+    endpointUrl: values.endpointUrl,
+    installUrl: values.installUrl,
+    authModel: values.authModel,
+    surfaceType: values.surfaceType,
+    transport: values.transport,
+    authKind: values.authKind,
+    credentialFacts: values.credentialFacts,
+    tier: values.tier,
+    provenance: values.provenance,
+    logoAssetPath: sql`coalesce(excluded.logo_asset_path, ${schema.capabilityCatalogItems.logoAssetPath})`,
+    importBatchId: values.importBatchId,
+    stale: false,
+    staleAt: null,
+    metadata: values.metadata,
+    updatedAt: values.updatedAt,
+  };
+  const [row] = await db.insert(schema.capabilityCatalogItems).values(values)
+    .onConflictDoUpdate({
+      target: [
+        schema.capabilityCatalogItems.source,
+        schema.capabilityCatalogItems.providerDomain,
+        schema.capabilityCatalogItems.mcpUrl,
+      ],
+      set: updateValues,
+    })
+    .returning();
+  if (!row) {
+    throw new Error("Failed to upsert registry capability catalog item");
+  }
+  return mapCapabilityCatalogItem(row);
+}
+
+export async function listRegistryCatalogSurfaceKeys(db: Database): Promise<RegistryCatalogSurfaceKey[]> {
+  const rows = await db.select({
+    id: schema.capabilityCatalogItems.id,
+    providerDomain: schema.capabilityCatalogItems.providerDomain,
+    mcpUrl: schema.capabilityCatalogItems.mcpUrl,
+  }).from(schema.capabilityCatalogItems)
+    .where(eq(schema.capabilityCatalogItems.source, registryCapabilitySource));
+  return rows.flatMap((row) => row.providerDomain && row.mcpUrl
+    ? [{ id: row.id, providerDomain: row.providerDomain, mcpUrl: row.mcpUrl }]
+    : []);
+}
+
+export async function markStaleRegistryCatalogItems(db: Database, activeKeys: Iterable<{ providerDomain: string; mcpUrl: string }>, importBatchId: string): Promise<number> {
+  const active = new Set([...activeKeys].map((key) => `${key.providerDomain}\n${key.mcpUrl}`));
+  const existing = await listRegistryCatalogSurfaceKeys(db);
+  const stale = existing.filter((row) => !active.has(`${row.providerDomain}\n${row.mcpUrl}`));
+  if (stale.length === 0) {
+    return 0;
+  }
+  const now = new Date();
+  const updated = await db.update(schema.capabilityCatalogItems).set({
+    stale: true,
+    staleAt: now,
+    importBatchId,
+    updatedAt: now,
+  }).where(and(
+    eq(schema.capabilityCatalogItems.source, registryCapabilitySource),
+    inArray(schema.capabilityCatalogItems.id, stale.map((row) => row.id)),
+  )).returning({ id: schema.capabilityCatalogItems.id });
+  return updated.length;
+}
+
 export async function upsertCapabilityCatalogItem(db: Database, input: CreateCapabilityCatalogItemInput): Promise<CapabilityCatalogItem> {
   return await withRlsContext(db, { accountId: input.accountId, workspaceId: input.workspaceId }, async (scopedDb) => {
     const now = new Date();
@@ -1502,6 +1845,18 @@ export async function upsertCapabilityCatalogItem(db: Database, input: CreateCap
       endpointUrl: input.endpointUrl ?? null,
       installUrl: input.installUrl ?? null,
       authModel: input.authModel ?? null,
+      providerDomain: null,
+      surfaceType: null,
+      transport: null,
+      mcpUrl: null,
+      authKind: null,
+      credentialFacts: [],
+      tier: null,
+      provenance: null,
+      logoAssetPath: null,
+      importBatchId: null,
+      stale: false,
+      staleAt: null,
       metadata: input.metadata ?? {},
       updatedAt: now,
     };
@@ -1516,6 +1871,18 @@ export async function upsertCapabilityCatalogItem(db: Database, input: CreateCap
       endpointUrl: values.endpointUrl,
       installUrl: values.installUrl,
       authModel: values.authModel,
+      providerDomain: values.providerDomain,
+      surfaceType: values.surfaceType,
+      transport: values.transport,
+      mcpUrl: values.mcpUrl,
+      authKind: values.authKind,
+      credentialFacts: values.credentialFacts,
+      tier: values.tier,
+      provenance: values.provenance,
+      logoAssetPath: values.logoAssetPath,
+      importBatchId: values.importBatchId,
+      stale: values.stale,
+      staleAt: values.staleAt,
       metadata: values.metadata,
       updatedAt: values.updatedAt,
     };
@@ -1535,7 +1902,16 @@ export async function upsertCapabilityCatalogItem(db: Database, input: CreateCap
 export async function listCapabilityCatalogItems(db: Database, workspaceId: string): Promise<CapabilityCatalogItem[]> {
   return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
     const rows = await scopedDb.select().from(schema.capabilityCatalogItems)
-      .where(eq(schema.capabilityCatalogItems.workspaceId, workspaceId))
+      .where(or(
+        eq(schema.capabilityCatalogItems.workspaceId, workspaceId),
+        and(
+          isNull(schema.capabilityCatalogItems.workspaceId),
+          or(
+            ne(schema.capabilityCatalogItems.source, registryCapabilitySource),
+            eq(schema.capabilityCatalogItems.stale, false),
+          ),
+        ),
+      ))
       .orderBy(asc(schema.capabilityCatalogItems.kind), asc(schema.capabilityCatalogItems.name));
     return rows.map(mapCapabilityCatalogItem);
   });
@@ -1544,7 +1920,11 @@ export async function listCapabilityCatalogItems(db: Database, workspaceId: stri
 export async function getCapabilityCatalogItem(db: Database, workspaceId: string, capabilityId: string): Promise<CapabilityCatalogItem | null> {
   return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
     const [row] = await scopedDb.select().from(schema.capabilityCatalogItems)
-      .where(and(eq(schema.capabilityCatalogItems.workspaceId, workspaceId), eq(schema.capabilityCatalogItems.id, capabilityId)))
+      .where(and(
+        eq(schema.capabilityCatalogItems.id, capabilityId),
+        or(eq(schema.capabilityCatalogItems.workspaceId, workspaceId), isNull(schema.capabilityCatalogItems.workspaceId)),
+      ))
+      .orderBy(asc(sql`(${schema.capabilityCatalogItems.workspaceId} is null)`))
       .limit(1);
     return row ? mapCapabilityCatalogItem(row) : null;
   });
@@ -1625,7 +2005,10 @@ export async function listEnabledMcpCapabilityServers(db: Database, workspaceId:
     installation: schema.capabilityInstallations,
   }).from(schema.capabilityInstallations)
     .innerJoin(schema.capabilityCatalogItems, and(
-      eq(schema.capabilityInstallations.workspaceId, schema.capabilityCatalogItems.workspaceId),
+      or(
+        eq(schema.capabilityInstallations.workspaceId, schema.capabilityCatalogItems.workspaceId),
+        isNull(schema.capabilityCatalogItems.workspaceId),
+      ),
       eq(schema.capabilityInstallations.capabilityId, schema.capabilityCatalogItems.id),
     ))
     .where(and(
@@ -1635,14 +2018,28 @@ export async function listEnabledMcpCapabilityServers(db: Database, workspaceId:
     ))
     .orderBy(asc(schema.capabilityCatalogItems.name)));
 
-  return rows.flatMap(({ item, installation }) => {
+  // A workspace-scoped catalog row and a global registry row can share the
+  // same capability id; the join then matches one installation twice. Keep
+  // one row per installation, preferring the workspace-scoped catalog row
+  // (same precedence as getCapabilityCatalogItem).
+  const preferredByInstallation = new Map<string, (typeof rows)[number]>();
+  for (const row of rows) {
+    const existing = preferredByInstallation.get(row.installation.id);
+    if (!existing || (existing.item.workspaceId === null && row.item.workspaceId !== null)) {
+      preferredByInstallation.set(row.installation.id, row);
+    }
+  }
+
+  return [...preferredByInstallation.values()].flatMap(({ item, installation }) => {
     if (!item.endpointUrl || !mcpConnectivityOk(installation.metadata)) {
       return [];
     }
     const headersEncrypted = encryptedHeadersConfig(installation.config.headersEncrypted);
-    if (item.authModel && !headersEncrypted) {
-      // Credential-gated MCPs are runnable only when credential headers were
-      // stored at enable time.
+    const connectionRef = connectionRefConfig(installation.config.connectionRef);
+    if (item.authModel && !headersEncrypted && !connectionRef) {
+      // Credential-gated MCPs are runnable only when either legacy static
+      // credential headers or the connections broker ref were stored at enable
+      // time.
       return [];
     }
     const metadata = item.metadata;
@@ -1659,6 +2056,7 @@ export async function listEnabledMcpCapabilityServers(db: Database, workspaceId:
       ...(timeoutMs ? { timeoutMs } : {}),
       ...(cacheToolsList !== undefined ? { cacheToolsList } : {}),
       ...(headersEncrypted ? { headersEncrypted } : {}),
+      ...(connectionRef ? { connectionRef } : {}),
     }];
   });
 }
@@ -1715,6 +2113,441 @@ export function mcpServerIdForCapability(capabilityId: string, metadata: Record<
   return `cap-${body}-${shortHash(capabilityId)}`;
 }
 
+const connectionMetadataColumns = {
+  id: schema.connections.id,
+  accountId: schema.connections.accountId,
+  workspaceId: schema.connections.workspaceId,
+  subjectId: schema.connections.subjectId,
+  providerDomain: schema.connections.providerDomain,
+  kind: schema.connections.kind,
+  status: schema.connections.status,
+  grantedScopes: schema.connections.grantedScopes,
+  expiresAt: schema.connections.expiresAt,
+  lastRefreshAt: schema.connections.lastRefreshAt,
+  lastUsedAt: schema.connections.lastUsedAt,
+  lastError: schema.connections.lastError,
+  version: schema.connections.version,
+  metadata: schema.connections.metadata,
+  createdBySubjectId: schema.connections.createdBySubjectId,
+  updatedBySubjectId: schema.connections.updatedBySubjectId,
+  createdAt: schema.connections.createdAt,
+  updatedAt: schema.connections.updatedAt,
+};
+
+function connectionSubjectVisibility(subjectId?: string | null): SQL {
+  return subjectId
+    ? or(isNull(schema.connections.subjectId), eq(schema.connections.subjectId, subjectId))!
+    : isNull(schema.connections.subjectId);
+}
+
+export async function createConnection(db: Database, input: CreateConnectionInput): Promise<ConnectionMetadata> {
+  return await withRlsContext(db, { accountId: input.accountId, workspaceId: input.workspaceId }, async (scopedDb) => {
+    const [row] = await scopedDb.insert(schema.connections).values({
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.subjectId ?? null,
+      providerDomain: input.providerDomain,
+      kind: input.kind,
+      status: input.status ?? "active",
+      credentialEncrypted: input.credentialEncrypted,
+      grantedScopes: input.grantedScopes ?? [],
+      expiresAt: input.expiresAt ?? null,
+      metadata: input.metadata ?? {},
+      createdBySubjectId: input.createdBySubjectId ?? null,
+      updatedBySubjectId: input.updatedBySubjectId ?? input.createdBySubjectId ?? null,
+    }).returning(connectionMetadataColumns);
+    if (!row) {
+      throw new Error("Failed to create connection");
+    }
+    return mapConnectionMetadata(row);
+  });
+}
+
+export async function listConnectionsMetadata(db: Database, workspaceId: string, subjectId?: string | null): Promise<ConnectionMetadata[]> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const rows = await scopedDb.select(connectionMetadataColumns).from(schema.connections)
+      .where(and(eq(schema.connections.workspaceId, workspaceId), connectionSubjectVisibility(subjectId)))
+      .orderBy(desc(schema.connections.createdAt));
+    return rows.map(mapConnectionMetadata);
+  });
+}
+
+export async function getConnectionMetadata(db: Database, workspaceId: string, connectionId: string, subjectId?: string | null): Promise<ConnectionMetadata | null> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const [row] = await scopedDb.select(connectionMetadataColumns).from(schema.connections)
+      .where(and(
+        eq(schema.connections.workspaceId, workspaceId),
+        eq(schema.connections.id, connectionId),
+        connectionSubjectVisibility(subjectId),
+      ))
+      .limit(1);
+    return row ? mapConnectionMetadata(row) : null;
+  });
+}
+
+export async function updateConnection(db: Database, input: UpdateConnectionInput): Promise<ConnectionMetadata | null> {
+  return await withWorkspaceRls(db, input.workspaceId, async (scopedDb) => {
+    const set = {
+      updatedAt: new Date(),
+      ...(input.providerDomain !== undefined ? { providerDomain: input.providerDomain } : {}),
+      ...(input.subjectId !== undefined ? { subjectId: input.subjectId } : {}),
+      ...(input.kind !== undefined ? { kind: input.kind } : {}),
+      ...(input.status !== undefined ? { status: input.status } : {}),
+      ...(input.credentialEncrypted !== undefined
+        ? {
+          credentialEncrypted: input.credentialEncrypted,
+          version: sql`${schema.connections.version} + 1`,
+          lastError: null,
+        }
+        : {}),
+      ...(input.grantedScopes !== undefined ? { grantedScopes: input.grantedScopes } : {}),
+      ...(input.expiresAt !== undefined ? { expiresAt: input.expiresAt } : {}),
+      ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+      ...(input.updatedBySubjectId !== undefined ? { updatedBySubjectId: input.updatedBySubjectId } : {}),
+    };
+    const [row] = await scopedDb.update(schema.connections).set(set)
+      .where(and(
+        eq(schema.connections.workspaceId, input.workspaceId),
+        eq(schema.connections.id, input.connectionId),
+        connectionSubjectVisibility(input.visibleToSubjectId),
+        ...(input.expectedVersion !== undefined ? [eq(schema.connections.version, input.expectedVersion)] : []),
+      ))
+      .returning(connectionMetadataColumns);
+    return row ? mapConnectionMetadata(row) : null;
+  });
+}
+
+export async function revokeConnection(db: Database, workspaceId: string, connectionId: string, updatedBySubjectId?: string | null): Promise<ConnectionMetadata | null> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const [row] = await scopedDb.update(schema.connections).set({
+      status: "revoked",
+      // The version bump invalidates any in-flight refresh's (id, version) CAS,
+      // so a racing refresh cannot commit and flip the row back to active.
+      version: sql`${schema.connections.version} + 1`,
+      updatedBySubjectId: updatedBySubjectId ?? null,
+      updatedAt: new Date(),
+    })
+      .where(and(
+        eq(schema.connections.workspaceId, workspaceId),
+        eq(schema.connections.id, connectionId),
+        // Same visibility rule as get/update: shared rows plus the caller's own
+        // subject rows. Cross-subject revocation (admin janitorial) arrives with
+        // the subject-connections UX in I5, deliberately not before.
+        connectionSubjectVisibility(updatedBySubjectId),
+      ))
+      .returning(connectionMetadataColumns);
+    return row ? mapConnectionMetadata(row) : null;
+  });
+}
+
+export async function loadConnectionCredentialForBroker(db: Database, settings: Settings, input: {
+  workspaceId: string;
+  connectionId?: string;
+  providerDomain: string;
+  kind?: ConnectionKind;
+  subjectId?: string | null;
+  allowSubjectOwned?: boolean;
+}): Promise<ConnectionCredentialForBroker | null> {
+  const key = environmentsEncryptionKeyBytes(settings);
+  if (!key) {
+    throw new Error("connection credential present but OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is not configured");
+  }
+  const subjectPredicate = input.allowSubjectOwned
+    ? connectionSubjectVisibility(input.subjectId)
+    : isNull(schema.connections.subjectId);
+  const conditions: SQL[] = [
+    eq(schema.connections.workspaceId, input.workspaceId),
+    subjectPredicate,
+  ];
+  if (input.connectionId) {
+    conditions.push(eq(schema.connections.id, input.connectionId));
+  } else {
+    conditions.push(eq(schema.connections.providerDomain, input.providerDomain));
+    if (input.kind) {
+      conditions.push(eq(schema.connections.kind, input.kind));
+    }
+  }
+  return await withWorkspaceRls(db, input.workspaceId, async (scopedDb) => {
+    // Prefer active rows: a revoke bumps updatedAt, so recency alone would let a
+    // freshly revoked connection shadow an active replacement for the provider.
+    const [row] = await scopedDb.select().from(schema.connections)
+      .where(and(...conditions))
+      .orderBy(desc(sql`(${schema.connections.status} = 'active')`), desc(schema.connections.updatedAt))
+      .limit(1);
+    if (!row) {
+      return null;
+    }
+    let credential: unknown;
+    try {
+      credential = JSON.parse(decryptEnvironmentValue(key, row.credentialEncrypted));
+    } catch (error) {
+      throw new Error(`connection credential could not be decrypted for ${row.id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!credential || typeof credential !== "object" || Array.isArray(credential)) {
+      throw new Error(`connection credential bundle for ${row.id} is not a JSON object`);
+    }
+    return {
+      id: row.id,
+      accountId: row.accountId,
+      workspaceId: row.workspaceId,
+      subjectId: row.subjectId,
+      providerDomain: row.providerDomain,
+      kind: row.kind as ConnectionKind,
+      status: row.status as ConnectionStatus,
+      credential: credential as Record<string, unknown>,
+      grantedScopes: row.grantedScopes,
+      expiresAt: row.expiresAt,
+      lastRefreshAt: row.lastRefreshAt,
+      version: row.version,
+      metadata: row.metadata,
+    };
+  });
+}
+
+export async function recordConnectionTokenRefresh(db: Database, input: {
+  id: string;
+  version: number;
+  workspaceId: string;
+  credentialEncrypted: string;
+  expiresAt: Date | null;
+  grantedScopes?: string[];
+  lastRefreshAt: Date;
+}): Promise<boolean> {
+  return await withWorkspaceRls(db, input.workspaceId, async (scopedDb) => {
+    const set = {
+      credentialEncrypted: input.credentialEncrypted,
+      expiresAt: input.expiresAt,
+      lastRefreshAt: input.lastRefreshAt,
+      status: "active",
+      lastError: null,
+      version: sql`${schema.connections.version} + 1`,
+      updatedAt: new Date(),
+      ...(input.grantedScopes !== undefined ? { grantedScopes: input.grantedScopes } : {}),
+    };
+    const updated = await scopedDb.update(schema.connections).set(set)
+      .where(and(
+        eq(schema.connections.id, input.id),
+        eq(schema.connections.workspaceId, input.workspaceId),
+        eq(schema.connections.version, input.version),
+        // A refresh may only ever renew a live credential; revoked/errored rows
+        // stay dead even if a status change somewhere forgot to bump version.
+        eq(schema.connections.status, "active"),
+      ))
+      .returning({ id: schema.connections.id });
+    return updated.length > 0;
+  });
+}
+
+export async function setConnectionStatus(db: Database, workspaceId: string, status: ConnectionStatus, lastError: string | null, guard: { id: string; version: number }): Promise<boolean> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const updated = await scopedDb.update(schema.connections).set({
+      status,
+      lastError,
+      version: sql`${schema.connections.version} + 1`,
+      updatedAt: new Date(),
+    }).where(and(
+      eq(schema.connections.workspaceId, workspaceId),
+      eq(schema.connections.id, guard.id),
+      eq(schema.connections.version, guard.version),
+    )).returning({ id: schema.connections.id });
+    return updated.length > 0;
+  });
+}
+
+export async function recordConnectionUsed(db: Database, workspaceId: string, connectionId: string): Promise<void> {
+  await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    await scopedDb.update(schema.connections).set({
+      lastUsedAt: new Date(),
+      updatedAt: new Date(),
+    }).where(and(eq(schema.connections.workspaceId, workspaceId), eq(schema.connections.id, connectionId)));
+  });
+}
+
+export async function loadIntegrationOAuthClient(
+  db: Database,
+  settings: Settings,
+  issuer: string,
+): Promise<IntegrationOAuthClientForUse | null> {
+  const [row] = await db.select().from(schema.integrationOauthClients)
+    .where(eq(schema.integrationOauthClients.issuer, issuer))
+    .limit(1);
+  if (!row) {
+    return null;
+  }
+  let clientSecret: string | null = null;
+  if (row.clientSecretEncrypted) {
+    const key = environmentsEncryptionKeyBytes(settings);
+    if (!key) {
+      throw new Error("OAuth client secret present but OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is not configured");
+    }
+    clientSecret = decryptEnvironmentValue(key, row.clientSecretEncrypted);
+  }
+  return {
+    id: row.id,
+    issuer: row.issuer,
+    authorizationServer: row.authorizationServer,
+    clientId: row.clientId,
+    clientSecret,
+    tokenEndpointAuthMethod: row.tokenEndpointAuthMethod,
+    metadata: row.metadata,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export async function storeIntegrationOAuthClient(
+  db: Database,
+  input: StoreIntegrationOAuthClientInput,
+): Promise<StoredIntegrationOAuthClient> {
+  const [inserted] = await db.insert(schema.integrationOauthClients).values({
+    issuer: input.issuer,
+    authorizationServer: input.authorizationServer,
+    clientId: input.clientId,
+    clientSecretEncrypted: input.clientSecretEncrypted ?? null,
+    tokenEndpointAuthMethod: input.tokenEndpointAuthMethod ?? "none",
+    metadata: input.metadata ?? {},
+  }).onConflictDoNothing({
+    target: schema.integrationOauthClients.issuer,
+  }).returning();
+  if (inserted) {
+    return mapStoredIntegrationOAuthClient(inserted);
+  }
+  const [winner] = await db.select().from(schema.integrationOauthClients)
+    .where(eq(schema.integrationOauthClients.issuer, input.issuer))
+    .limit(1);
+  if (!winner) {
+    throw new Error(`OAuth client registration conflict winner not found for issuer ${input.issuer}`);
+  }
+  return mapStoredIntegrationOAuthClient(winner);
+}
+
+function mapStoredIntegrationOAuthClient(row: typeof schema.integrationOauthClients.$inferSelect): StoredIntegrationOAuthClient {
+  return {
+    id: row.id,
+    issuer: row.issuer,
+    authorizationServer: row.authorizationServer,
+    clientId: row.clientId,
+    clientSecretEncrypted: row.clientSecretEncrypted,
+    tokenEndpointAuthMethod: row.tokenEndpointAuthMethod,
+    metadata: row.metadata,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export async function consumeIntegrationOAuthStateNonce(
+  db: Database,
+  input: ConsumeOAuthStateNonceInput,
+): Promise<boolean> {
+  return await withRlsContext(db, { accountId: input.accountId, workspaceId: input.workspaceId }, async (scopedDb) => {
+    await scopedDb.delete(schema.integrationOauthStateNonces)
+      .where(and(
+        eq(schema.integrationOauthStateNonces.workspaceId, input.workspaceId),
+        lt(schema.integrationOauthStateNonces.expiresAt, input.now),
+      ));
+    const inserted = await scopedDb.insert(schema.integrationOauthStateNonces).values({
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.subjectId,
+      nonce: input.nonce,
+      expiresAt: input.expiresAt,
+      usedAt: input.now,
+    }).onConflictDoNothing({ target: schema.integrationOauthStateNonces.nonce })
+      .returning({ nonce: schema.integrationOauthStateNonces.nonce });
+    return inserted.length > 0;
+  });
+}
+
+export async function createKnowledgeMemory(db: Database, input: CreateKnowledgeMemoryInput): Promise<KnowledgeMemory> {
+  const text = requireDbString(input.text, "knowledge memory text");
+  const scope = cleanDbString(input.scope) ?? "workspace";
+  return await withRlsContext(db, { accountId: input.accountId, workspaceId: input.workspaceId }, async (scopedDb) => {
+    const [row] = await scopedDb.insert(schema.knowledgeMemories).values({
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      status: input.status ?? "proposed",
+      kind: input.kind ?? "semantic",
+      scope,
+      text,
+      sourceRefs: input.sourceRefs ?? [],
+      confidence: confidenceToStorage(input.confidence ?? 0.5),
+      metadata: input.metadata ?? {},
+      createdBySessionId: input.createdBySessionId ?? null,
+    }).returning();
+    if (!row) {
+      throw new Error("Failed to create knowledge memory");
+    }
+    return mapKnowledgeMemory(row);
+  });
+}
+
+export async function updateKnowledgeMemory(db: Database, workspaceId: string, memoryId: string, input: UpdateKnowledgeMemoryInput): Promise<KnowledgeMemory> {
+  const reviewStatus = input.status === "approved" || input.status === "rejected";
+  const scope = input.scope !== undefined ? requireDbString(input.scope, "knowledge memory scope") : undefined;
+  const text = input.text !== undefined ? requireDbString(input.text, "knowledge memory text") : undefined;
+  const reviewedBy = input.reviewedBy === null
+    ? null
+    : input.reviewedBy !== undefined
+      ? requireDbString(input.reviewedBy, "knowledge memory reviewer")
+      : undefined;
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const [row] = await scopedDb.update(schema.knowledgeMemories).set({
+      ...(input.status !== undefined ? { status: input.status } : {}),
+      ...(input.kind !== undefined ? { kind: input.kind } : {}),
+      ...(scope !== undefined ? { scope } : {}),
+      ...(text !== undefined ? { text } : {}),
+      ...(input.sourceRefs !== undefined ? { sourceRefs: input.sourceRefs } : {}),
+      ...(input.confidence !== undefined ? { confidence: confidenceToStorage(input.confidence) } : {}),
+      ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+      // Re-proposing clears review metadata; an explicit reviewedBy in the same
+      // update still wins via the later spread.
+      ...(input.status === "proposed" ? { reviewedBy: null, reviewedAt: null } : {}),
+      ...(reviewedBy !== undefined ? { reviewedBy } : {}),
+      ...(reviewStatus ? { reviewedAt: new Date() } : {}),
+      updatedAt: new Date(),
+    }).where(and(eq(schema.knowledgeMemories.workspaceId, workspaceId), eq(schema.knowledgeMemories.id, memoryId))).returning();
+    if (!row) {
+      throw new Error(`Knowledge memory not found: ${memoryId}`);
+    }
+    return mapKnowledgeMemory(row);
+  });
+}
+
+export async function getKnowledgeMemory(db: Database, workspaceId: string, memoryId: string): Promise<KnowledgeMemory | null> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const [row] = await scopedDb.select().from(schema.knowledgeMemories)
+      .where(and(eq(schema.knowledgeMemories.workspaceId, workspaceId), eq(schema.knowledgeMemories.id, memoryId)))
+      .limit(1);
+    return row ? mapKnowledgeMemory(row) : null;
+  });
+}
+
+export async function listKnowledgeMemories(db: Database, workspaceId: string, options: ListKnowledgeMemoryOptions = {}): Promise<KnowledgeMemory[]> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const conditions: SQL[] = [eq(schema.knowledgeMemories.workspaceId, workspaceId)];
+    if (options.status) {
+      conditions.push(eq(schema.knowledgeMemories.status, options.status));
+    }
+    if (options.kind) {
+      conditions.push(eq(schema.knowledgeMemories.kind, options.kind));
+    }
+    const scope = cleanDbString(options.scope);
+    if (scope) {
+      conditions.push(eq(schema.knowledgeMemories.scope, scope));
+    }
+    const query = cleanDbString(options.query);
+    if (query) {
+      conditions.push(sql`to_tsvector('simple', ${schema.knowledgeMemories.text}) @@ plainto_tsquery('simple', ${query})`);
+    }
+    const limit = Math.min(Math.max(options.limit ?? 20, 1), 100);
+    const rows = await scopedDb.select().from(schema.knowledgeMemories)
+      .where(and(...conditions))
+      .orderBy(desc(schema.knowledgeMemories.updatedAt))
+      .limit(limit);
+    return rows.map(mapKnowledgeMemory);
+  });
+}
+
 export async function createSocialConnection(db: Database, input: CreateSocialConnectionInput): Promise<SocialConnection> {
   return await withRlsContext(db, { accountId: input.accountId, workspaceId: input.workspaceId }, async (scopedDb) => {
     const [row] = await scopedDb.insert(schema.socialConnections).values({
@@ -3166,6 +3999,7 @@ async function insertSessionMcpServers(db: Database, input: {
     allowedTools: server.allowedTools ?? null,
     timeoutMs: server.timeoutMs ?? null,
     cacheToolsList: server.cacheToolsList ?? false,
+    requireApproval: server.requireApproval ?? null,
     headersEncrypted: server.headersEncrypted ?? {},
   }))).returning();
   return rows.map(mapSessionMcpServerMetadata);
@@ -3257,6 +4091,7 @@ export async function listSessionMcpServersForRun(
         ...(row.allowedTools ? { allowedTools: row.allowedTools } : {}),
         ...(row.timeoutMs ? { timeoutMs: row.timeoutMs } : {}),
         ...(row.cacheToolsList ? { cacheToolsList: row.cacheToolsList } : {}),
+        ...(row.requireApproval != null ? { requireApproval: row.requireApproval } : {}),
         headers,
       };
     });
@@ -3542,6 +4377,41 @@ export async function listSessionEvents(
   });
 }
 
+export type ToolspaceCallReservation =
+  | { reserved: true; count: number }
+  | { reserved: false };
+
+/**
+ * Atomically reserve one toolspace call against a turn's per-turn budget.
+ *
+ * A single conditional UPDATE increments `toolspace_call_count` only while it is
+ * below `limit` and returns the post-increment value. Concurrent reservations
+ * for the same turn serialize on the row lock, so exactly `limit` of N
+ * simultaneous callers observe `reserved: true` — closing the read-then-append
+ * TOCTOU the event-count approach had. `reserved: false` means the turn is at or
+ * over budget (or the turn row no longer exists).
+ */
+export async function reserveToolspaceCallForTurn(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  turnId: string,
+  limit: number,
+): Promise<ToolspaceCallReservation> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const [row] = await scopedDb.update(schema.sessionTurns)
+      .set({ toolspaceCallCount: sql`${schema.sessionTurns.toolspaceCallCount} + 1` })
+      .where(and(
+        eq(schema.sessionTurns.workspaceId, workspaceId),
+        eq(schema.sessionTurns.sessionId, sessionId),
+        eq(schema.sessionTurns.id, turnId),
+        sql`${schema.sessionTurns.toolspaceCallCount} < ${limit}`,
+      ))
+      .returning({ count: schema.sessionTurns.toolspaceCallCount });
+    return row ? { reserved: true, count: Number(row.count) } : { reserved: false };
+  });
+}
+
 function normalizeEventSequence(value: number | undefined, fallback: number): number {
   if (value === undefined || !Number.isFinite(value)) {
     return fallback;
@@ -5139,6 +6009,22 @@ export async function countSandboxLeasesByLiveness(db: Database): Promise<Record
   return counts;
 }
 
+export type CreditBalanceByAccount = {
+  accountId: string;
+  balanceMicros: number;
+};
+
+export async function listCreditBalancesByAccount(db: Database): Promise<CreditBalanceByAccount[]> {
+  const rows = await rawRows<{ account_id: string; balance_micros: number | string }>(db, sql`
+    select account_id, balance_micros
+    from opengeni_private.credit_balance_by_account()
+  `);
+  return rows.map((row) => ({
+    accountId: row.account_id,
+    balanceMicros: Number(row.balance_micros),
+  }));
+}
+
 // Cross-workspace live Modal lease read for the provider-side orphan sweep. The
 // SECURITY DEFINER function is the sanctioned RLS bypass; see migration 0036.
 export async function listLiveModalSandboxLeaseAttributions(db: Database): Promise<LiveModalSandboxLeaseAttribution[]> {
@@ -5410,6 +6296,9 @@ export type EnrollmentRecord = {
   pubkey: string;
   exposure: EnrollmentExposure;
   hasDisplay: boolean;
+  /** Set when a display exists but capture is not permitted (macOS Screen Recording
+   *  not granted); null when capture is permitted or the machine is headless. */
+  desktopUnavailableReason: string | null;
   allowScreenControl: boolean;
   status: EnrollmentStatus;
   os: EnrollmentOs;
@@ -5428,6 +6317,7 @@ function mapEnrollment(row: typeof schema.enrollments.$inferSelect): EnrollmentR
     pubkey: row.pubkey,
     exposure: row.exposure as EnrollmentExposure,
     hasDisplay: row.hasDisplay,
+    desktopUnavailableReason: row.desktopUnavailableReason ?? null,
     allowScreenControl: row.allowScreenControl,
     status: row.status as EnrollmentStatus,
     os: row.os as EnrollmentOs,
@@ -5573,23 +6463,40 @@ export async function touchEnrollmentLastSeen(db: Database, input: {
 // at enroll time from the enroll-offer snapshot, this tracks REALITY across the
 // machine's life — a Mac that later grants Screen Recording, or a Linux box whose
 // Xvfb starts after enrollment, flips false→true on its next Hello (and a display
-// that goes away flips true→false). CHANGE-GUARDED at the SQL layer (the `ne`
-// predicate): a Hello that reports the same value the row already holds updates
-// zero rows, so a steady state never churns a write. Returns whether a row was
-// actually changed. Best-effort — the caller swallows failures so a display
-// refresh never breaks the agent's connect.
-export async function setEnrollmentHasDisplay(db: Database, input: {
-  accountId: string; workspaceId: string; enrollmentId: string; hasDisplay: boolean;
+// that goes away flips true→false).
+//
+// `desktopUnavailableReason` rides alongside: a machine can have a display it
+// cannot CAPTURE (macOS Screen Recording / TCC not granted). In that case
+// has_display is false BUT the reason is a human, actionable string, so the
+// Machines dashboard can show "display: capture not granted" instead of a bare
+// "headless". null means capture is permitted OR the machine is genuinely headless.
+//
+// CHANGE-GUARDED at the SQL layer: the write fires only when EITHER field differs
+// from what the row already holds (`hasDisplay` via `ne`, the nullable reason via
+// `IS DISTINCT FROM`), so a steady-state Hello updates zero rows and never churns.
+// Returns whether a row was actually changed. Best-effort — the caller swallows
+// failures so a display refresh never breaks the agent's connect.
+export async function setEnrollmentDisplayState(db: Database, input: {
+  accountId: string; workspaceId: string; enrollmentId: string;
+  hasDisplay: boolean; desktopUnavailableReason: string | null;
 }): Promise<{ updated: boolean }> {
   return await withRlsContext(db, { accountId: input.accountId, workspaceId: input.workspaceId }, async (scopedDb) => {
     const rows = await scopedDb.update(schema.enrollments)
-      .set({ hasDisplay: input.hasDisplay, updatedAt: new Date() })
+      .set({
+        hasDisplay: input.hasDisplay,
+        desktopUnavailableReason: input.desktopUnavailableReason,
+        updatedAt: new Date(),
+      })
       .where(and(
         eq(schema.enrollments.workspaceId, input.workspaceId),
         eq(schema.enrollments.id, input.enrollmentId),
-        // Only write on a CHANGE — an unchanged display must not churn a write on
-        // every reconnect Hello.
-        ne(schema.enrollments.hasDisplay, input.hasDisplay),
+        // Only write on a CHANGE to EITHER field — an unchanged display state must
+        // not churn a write on every reconnect Hello. `IS DISTINCT FROM` is the
+        // null-safe inequality (a plain `ne` skips NULL rows).
+        or(
+          ne(schema.enrollments.hasDisplay, input.hasDisplay),
+          sql`${schema.enrollments.desktopUnavailableReason} IS DISTINCT FROM ${input.desktopUnavailableReason}`,
+        ),
       ))
       .returning({ id: schema.enrollments.id });
     return { updated: rows.length > 0 };
@@ -7941,12 +8848,30 @@ function mapWorkspacePack(row: typeof schema.workspacePacks.$inferSelect): Works
   };
 }
 
+function mapImportBatch(row: typeof schema.importBatches.$inferSelect): ImportBatch {
+  return {
+    id: row.id,
+    source: row.source,
+    snapshotDate: row.snapshotDate.toISOString(),
+    snapshotRef: row.snapshotRef,
+    attributionNote: row.attributionNote,
+    importedCount: row.importedCount,
+    skippedCount: row.skippedCount,
+    quarantinedCount: row.quarantinedCount,
+    logoFailureCount: row.logoFailureCount,
+    staleCount: row.staleCount,
+    details: row.details,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
 function mapCapabilityCatalogItem(row: typeof schema.capabilityCatalogItems.$inferSelect): CapabilityCatalogItem {
   const runtime = row.kind === "mcp" && row.endpointUrl
     ? {
       available: true,
       mcpServerId: mcpServerIdForCapability(row.id, row.metadata),
-      transport: "streamable-http",
+      transport: row.transport ?? "streamable-http",
       notes: row.authModel
         ? "Requires credential headers supplied in the enable request."
         : null,
@@ -7959,8 +8884,8 @@ function mapCapabilityCatalogItem(row: typeof schema.capabilityCatalogItems.$inf
     };
   return {
     id: row.id,
-    accountId: row.accountId,
-    workspaceId: row.workspaceId,
+    ...(row.accountId ? { accountId: row.accountId } : {}),
+    ...(row.workspaceId ? { workspaceId: row.workspaceId } : {}),
     kind: row.kind as CapabilityKind,
     source: row.source as CapabilitySource,
     name: row.name,
@@ -7971,10 +8896,25 @@ function mapCapabilityCatalogItem(row: typeof schema.capabilityCatalogItems.$inf
     endpointUrl: row.endpointUrl,
     installUrl: row.installUrl,
     authModel: row.authModel,
+    providerDomain: row.providerDomain,
+    surfaceType: row.surfaceType,
+    transport: row.transport,
+    mcpUrl: row.mcpUrl,
+    authKind: row.authKind as CapabilityCatalogItem["authKind"],
+    credentialFacts: row.credentialFacts,
+    tier: row.tier as CapabilityCatalogItem["tier"],
+    provenance: row.provenance,
+    logoAssetPath: row.logoAssetPath,
+    importBatchId: row.importBatchId,
+    stale: row.stale,
+    staleAt: row.staleAt?.toISOString() ?? null,
     tools: [],
     runtime,
     enabled: false,
     enabledReason: null,
+    // Overwritten by applyCapabilityEnablement in @opengeni/core, which knows
+    // the installation; a freshly-read catalog row carries no connection.
+    connectionRef: null,
     metadata: row.metadata,
     createdAt: row.createdAt.toISOString(),
     updatedAt: row.updatedAt.toISOString(),
@@ -8035,6 +8975,67 @@ function redactInstallationConfig(config: Record<string, unknown>): Record<strin
   return { ...rest, headerNames: Object.keys(headersEncrypted).sort() };
 }
 
+function mapConnectionMetadata(row: {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  subjectId: string | null;
+  providerDomain: string;
+  kind: string;
+  status: string;
+  grantedScopes: string[];
+  expiresAt: Date | null;
+  lastRefreshAt: Date | null;
+  lastUsedAt: Date | null;
+  lastError: string | null;
+  version: number;
+  metadata: Record<string, unknown>;
+  createdBySubjectId: string | null;
+  updatedBySubjectId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}): ConnectionMetadata {
+  return {
+    id: row.id,
+    accountId: row.accountId,
+    workspaceId: row.workspaceId,
+    subjectId: row.subjectId,
+    providerDomain: row.providerDomain,
+    kind: row.kind as ConnectionKind,
+    status: row.status as ConnectionStatus,
+    grantedScopes: row.grantedScopes,
+    expiresAt: row.expiresAt?.toISOString() ?? null,
+    lastRefreshAt: row.lastRefreshAt?.toISOString() ?? null,
+    lastUsedAt: row.lastUsedAt?.toISOString() ?? null,
+    lastError: row.lastError,
+    version: row.version,
+    metadata: row.metadata,
+    createdBySubjectId: row.createdBySubjectId,
+    updatedBySubjectId: row.updatedBySubjectId,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+function mapKnowledgeMemory(row: typeof schema.knowledgeMemories.$inferSelect): KnowledgeMemory {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    status: row.status as KnowledgeMemoryStatus,
+    kind: row.kind as KnowledgeMemoryKind,
+    scope: row.scope,
+    text: row.text,
+    sourceRefs: Array.isArray(row.sourceRefs) ? row.sourceRefs as KnowledgeSourceRef[] : [],
+    confidence: confidenceFromStorage(row.confidence),
+    metadata: row.metadata,
+    createdBySessionId: row.createdBySessionId,
+    reviewedBy: row.reviewedBy,
+    reviewedAt: row.reviewedAt ? row.reviewedAt.toISOString() : null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
 function mapSocialConnection(row: typeof schema.socialConnections.$inferSelect): SocialConnection {
   return {
     id: row.id,
@@ -8128,6 +9129,30 @@ function stringArrayConfig(value: unknown): string[] | undefined {
   return values.length > 0 ? [...new Set(values.map((item) => item.trim()))] : undefined;
 }
 
+function cleanDbString(value: string | undefined | null): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function requireDbString(value: string, field: string): string {
+  const trimmed = cleanDbString(value);
+  if (!trimmed) {
+    throw new Error(`${field} is required`);
+  }
+  return trimmed;
+}
+
+function confidenceToStorage(value: number): number {
+  if (!Number.isFinite(value)) {
+    return 50;
+  }
+  return Math.round(Math.min(Math.max(value, 0), 1) * 100);
+}
+
+function confidenceFromStorage(value: number): number {
+  return Number((Math.min(Math.max(value, 0), 100) / 100).toFixed(2));
+}
+
 function positiveIntegerConfig(value: unknown): number | undefined {
   if (typeof value === "number" && Number.isInteger(value) && value > 0) {
     return value;
@@ -8153,7 +9178,37 @@ function encryptedHeadersConfig(value: unknown): Record<string, string> | undefi
 
 function mcpConnectivityOk(metadata: Record<string, unknown>): boolean {
   const value = metadata.mcpConnectivity;
-  return !!value && typeof value === "object" && "status" in value && value.status === "ok";
+  return !!value && typeof value === "object" && "status" in value && (value.status === "ok" || value.status === "auth_deferred");
+}
+
+function connectionRefConfig(value: unknown): McpServerConnectionRef | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.providerDomain !== "string" || record.providerDomain.length === 0) {
+    return undefined;
+  }
+  const ref: McpServerConnectionRef = { providerDomain: record.providerDomain };
+  if (typeof record.connectionId === "string" && record.connectionId.length > 0) {
+    ref.connectionId = record.connectionId;
+  }
+  if (typeof record.kind === "string" && ["oauth2", "api_key", "app_install", "delegated"].includes(record.kind)) {
+    ref.kind = record.kind as ConnectionKind;
+  }
+  if (Array.isArray(record.scopes)) {
+    const scopes = record.scopes.filter((scope): scope is string => typeof scope === "string" && scope.length > 0);
+    if (scopes.length > 0) {
+      ref.scopes = scopes;
+    }
+  }
+  if (typeof record.resource === "string" && record.resource.length > 0) {
+    ref.resource = record.resource;
+  }
+  if (record.subjectScope === "workspace" || record.subjectScope === "subject") {
+    ref.subjectScope = record.subjectScope;
+  }
+  return ref;
 }
 
 function shortHash(value: string): string {
@@ -8171,3 +9226,4 @@ function shortHash(value: string): string {
 // recordCodexAccountUsage) is already initialized when its default-deps bag
 // evaluates under the index↔resolver module cycle.
 export * from "./codex-token-resolver";
+export * from "./connection-token-resolver";