@intx/db 0.1.2

package/migrations/meta/_journal.json

@@ -0,0 +1,209 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1771377177003,
+      "tag": "0000_brown_wither",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1771454692193,
+      "tag": "0001_white_aqueduct",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1771459003764,
+      "tag": "0002_clever_falcon",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1771541707112,
+      "tag": "0003_stiff_tyrannus",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1771630000000,
+      "tag": "0004_rename_capability_to_offering",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1771630000000,
+      "tag": "0005_gigantic_cardiac",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1771630000001,
+      "tag": "0006_sidecar",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1771630000002,
+      "tag": "0007_agent_running_session",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1771630000003,
+      "tag": "0008_session",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1771630000004,
+      "tag": "0009_session_messages",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1771630000005,
+      "tag": "0010_agent_sidecar_pubkey",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1776890951476,
+      "tag": "0011_session_message_from",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1776909616212,
+      "tag": "0012_agent_instance",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1776917900630,
+      "tag": "0013_instance_session_id",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1776921400366,
+      "tag": "0014_drop_agent_runtime_columns",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1776930080691,
+      "tag": "0015_add_instance_id_to_session_message",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1777049455797,
+      "tag": "0016_jazzy_gamma_corps",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1777050475351,
+      "tag": "0017_hesitant_marvex",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1777053065460,
+      "tag": "0018_natural_sinister_six",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1777180800000,
+      "tag": "0019_rename_grant_source_to_origin",
+      "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1777085874297,
+      "tag": "0020_add_agent_role",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1777228941707,
+      "tag": "0021_acoustic_ozymandias",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1777229396694,
+      "tag": "0022_material_sleepwalker",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "7",
+      "when": 1777235039207,
+      "tag": "0023_flawless_scarlet_witch",
+      "breakpoints": true
+    },
+    {
+      "idx": 24,
+      "version": "7",
+      "when": 1780344351218,
+      "tag": "0024_bumpy_sharon_ventura",
+      "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "7",
+      "when": 1780357614241,
+      "tag": "0025_curvy_firestar",
+      "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "7",
+      "when": 1780358149943,
+      "tag": "0026_keen_ultimo",
+      "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1780377246076,
+      "tag": "0027_git_tokens",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "7",
+      "when": 1780502952568,
+      "tag": "0028_wet_sugar_man",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@intx/db",
+  "version": "0.1.2",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./schema": {
+      "types": "./src/schema/index.ts",
+      "default": "./src/schema/index.ts"
+    }
+  },
+  "scripts": {
+    "db:generate": "drizzle-kit generate --config=drizzle.config.ts",
+    "db:migrate": "drizzle-kit migrate --config=drizzle.config.ts"
+  },
+  "dependencies": {
+    "@intx/log": "0.0.0",
+    "@intx/types": "0.0.0",
+    "arktype": "^2.1.29",
+    "drizzle-orm": "^0.45.1",
+    "postgres": "^3.4.8"
+  }
+}

package/src/client.ts

@@ -0,0 +1,24 @@
+import { type } from "arktype";
+import { drizzle } from "drizzle-orm/postgres-js";
+
+import { DBConfig } from "./config";
+import { createConnection } from "./connection";
+import * as schema from "./schema";
+
+export function createDB(raw: unknown) {
+  const config = DBConfig(raw);
+  if (config instanceof type.errors) {
+    throw new Error(`Invalid database config: ${config.summary}`);
+  }
+
+  const sql = createConnection(config);
+  const db = drizzle(sql, { schema });
+
+  return {
+    db,
+    transaction: db.transaction.bind(db),
+    close: () => sql.end(),
+  };
+}
+
+export type DB = ReturnType<typeof createDB>;

package/src/config.ts

@@ -0,0 +1,19 @@
+import { type } from "arktype";
+
+export const DBConfig = type({
+  host: "string",
+  port: "number.integer > 0",
+  user: "string",
+  password: "string",
+  database: "string",
+  "ssl?": "boolean",
+  "max?": "number.integer > 0",
+  // Postgres schema name. When set, the connection's `search_path` is
+  // pinned to this schema and migrations apply into it. This is the
+  // mechanism the integration-test harness uses to give each spawned
+  // hub a dedicated, droppable schema. When unset, the connection uses
+  // postgres' default `search_path` (which begins with `public`).
+  "schema?": "string",
+});
+
+export type DBConfig = typeof DBConfig.infer;

package/src/connection.ts

@@ -0,0 +1,27 @@
+import postgres from "postgres";
+
+import type { DBConfig } from "./config";
+
+function quoteIdentifier(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+export function createConnection(config: DBConfig) {
+  return postgres({
+    host: config.host,
+    port: config.port,
+    user: config.user,
+    password: config.password,
+    database: config.database,
+    max: config.max ?? 10,
+    ...(config.ssl !== undefined && { ssl: config.ssl }),
+    ...(config.schema !== undefined && {
+      // Pin the connection's search_path so unqualified table
+      // references resolve to the caller's schema. The migration
+      // runner emits SQL with the schema baked into FK references,
+      // but ORM-issued queries bind table names without a schema
+      // qualifier and rely on this setting.
+      connection: { search_path: quoteIdentifier(config.schema) },
+    }),
+  });
+}

package/src/credential-resolution.ts

@@ -0,0 +1,378 @@
+import { eq, and, isNull } from "drizzle-orm";
+import { type } from "arktype";
+
+import { getLogger } from "@intx/log";
+import { CredentialRequirement as CredentialRequirementType } from "@intx/types";
+import type { InferenceSource } from "@intx/types/runtime";
+
+import type { DB } from "./client";
+import { agent } from "./schema/agents";
+import { agentSession } from "./schema/sessions";
+import { credential } from "./schema/credentials";
+import { oauthClient } from "./schema/oauth-clients";
+import { provider } from "./schema/providers";
+import { getAncestorChain } from "./tenant-hierarchy";
+
+const log = getLogger(["db", "credentials"]);
+
+const CredentialRequirements = CredentialRequirementType.array();
+
+export const ProviderMetadata = type({ baseURL: "string" });
+
+const AgentModelConfig = type({ defaultModel: "string" });
+
+/**
+ * Resolves a provider by name, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveProviderByName(
+  db: DB["db"],
+  tenantId: string,
+  name: string,
+) {
+  const chain = await getAncestorChain(db, tenantId);
+
+  for (const tid of chain) {
+    const row = await db.query.provider.findFirst({
+      where: and(eq(provider.tenantId, tid), eq(provider.name, name)),
+    });
+    if (row) return row;
+  }
+
+  return null;
+}
+
+/**
+ * Resolves an OAuth client for a provider, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveOAuthClient(
+  db: DB["db"],
+  tenantId: string,
+  providerId: string,
+) {
+  const chain = await getAncestorChain(db, tenantId);
+
+  for (const tid of chain) {
+    const row = await db.query.oauthClient.findFirst({
+      where: and(
+        eq(oauthClient.tenantId, tid),
+        eq(oauthClient.providerId, providerId),
+      ),
+    });
+    if (row) return row;
+  }
+
+  return null;
+}
+
+/**
+ * Resolves a credential by name, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveCredentialByName(
+  db: DB["db"],
+  tenantId: string,
+  name: string,
+) {
+  const chain = await getAncestorChain(db, tenantId);
+
+  for (const tid of chain) {
+    const row = await db.query.credential.findFirst({
+      where: and(eq(credential.tenantId, tid), eq(credential.name, name)),
+    });
+    if (row) return row;
+  }
+
+  return null;
+}
+
+/**
+ * Resolves a credential by ID, validating that it belongs to the
+ * given tenant or one of its ancestors.
+ */
+export async function resolveCredentialById(
+  db: DB["db"],
+  tenantId: string,
+  credentialId: string,
+) {
+  const row = await db.query.credential.findFirst({
+    where: eq(credential.id, credentialId),
+  });
+
+  if (!row) return null;
+
+  const chain = await getAncestorChain(db, tenantId);
+  if (!chain.includes(row.tenantId)) return null;
+
+  return row;
+}
+
+type CredentialRequirement = {
+  providerName: string;
+  scopes?: string[];
+  source: "tenant" | "creator" | "invoker";
+  name?: string;
+};
+
+/**
+ * Resolves a credential matching an agent definition requirement.
+ * Used at agent launch time by the control plane.
+ */
+export async function resolveCredentialRequirement(
+  db: DB["db"],
+  tenantId: string,
+  requirement: CredentialRequirement,
+  creatorPrincipalId: string | null,
+  invokerPrincipalId: string | null,
+) {
+  const resolvedProvider = await resolveProviderByName(
+    db,
+    tenantId,
+    requirement.providerName,
+  );
+  if (!resolvedProvider) return null;
+
+  const chain = await getAncestorChain(db, tenantId);
+
+  const principalFilter =
+    requirement.source === "tenant"
+      ? null
+      : requirement.source === "creator"
+        ? creatorPrincipalId
+        : invokerPrincipalId;
+
+  for (const tid of chain) {
+    const conditions = [
+      eq(credential.tenantId, tid),
+      eq(credential.providerId, resolvedProvider.id),
+      eq(credential.status, "active"),
+    ];
+
+    if (principalFilter === null) {
+      conditions.push(isNull(credential.principalId));
+    } else if (principalFilter) {
+      conditions.push(eq(credential.principalId, principalFilter));
+    }
+
+    if (requirement.name) {
+      conditions.push(eq(credential.name, requirement.name));
+    }
+
+    const rows = await db.query.credential.findMany({
+      where: and(...conditions),
+    });
+
+    const matching = rows.filter((row) => {
+      if (!requirement.scopes || requirement.scopes.length === 0) return true;
+      const rowScopes = row.scopes ?? [];
+      return requirement.scopes.every((s) => rowScopes.includes(s));
+    });
+
+    const [sole] = matching;
+    if (matching.length === 1 && sole) return sole;
+    if (matching.length > 1) {
+      throw new Error(
+        `Ambiguous credential match: ${matching.length} credentials match ` +
+          `provider=${requirement.providerName} source=${requirement.source} ` +
+          `in tenant ${tid}. Specify a name to disambiguate.`,
+      );
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Outcome of resolving one credential requirement to an
+ * `InferenceSource`. Callers map `failed` variants to their own
+ * error-handling convention (the API route surfaces 409s; the
+ * background credential pushers log and continue).
+ */
+export type CredentialOutcome =
+  | { ok: true; source: InferenceSource }
+  | {
+      ok: false;
+      reason: "credential_error";
+      requirement: CredentialRequirement;
+      message: string;
+    }
+  | {
+      ok: false;
+      reason: "credential_missing";
+      requirement: CredentialRequirement;
+    }
+  | {
+      ok: false;
+      reason: "skipped";
+      requirement: CredentialRequirement;
+    }
+  | {
+      ok: false;
+      reason: "provider_missing";
+      credentialId: string;
+    }
+  | {
+      ok: false;
+      reason: "provider_misconfigured";
+      providerName: string;
+      summary: string;
+    };
+
+/**
+ * Resolve one credential requirement to an `InferenceSource`, stamping
+ * `defaultModel` as the model identity. Skips silently (`reason:
+ * "skipped"`) when the requirement targets a principal that does not
+ * exist (creator without a creator id, invoker without a session
+ * principal); all other failure modes are surfaced with structured
+ * reasons.
+ */
+export async function resolveOneCredential(
+  db: DB["db"],
+  tenantId: string,
+  req: CredentialRequirement,
+  creatorPrincipalId: string | null,
+  invokerPrincipalId: string | null,
+  defaultModel: string,
+): Promise<CredentialOutcome> {
+  // Reject requirements whose targeted principal does not exist. Without
+  // these guards a null creator or invoker would fall through to
+  // `resolveCredentialRequirement`, where the principal filter becomes
+  // `isNull(credential.principalId)` — the tenant-credential lookup — and
+  // a tenant credential would be returned as if it satisfied the
+  // creator- or invoker-source requirement.
+  if (req.source === "creator" && !creatorPrincipalId) {
+    return { ok: false, reason: "skipped", requirement: req };
+  }
+  if (req.source === "invoker" && !invokerPrincipalId) {
+    return { ok: false, reason: "skipped", requirement: req };
+  }
+
+  let resolved;
+  try {
+    resolved = await resolveCredentialRequirement(
+      db,
+      tenantId,
+      req,
+      creatorPrincipalId,
+      invokerPrincipalId,
+    );
+  } catch (err: unknown) {
+    return {
+      ok: false,
+      reason: "credential_error",
+      requirement: req,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+  if (!resolved) {
+    return { ok: false, reason: "credential_missing", requirement: req };
+  }
+
+  const providerRow = await db.query.provider.findFirst({
+    where: eq(provider.id, resolved.providerId),
+  });
+  if (!providerRow) {
+    return { ok: false, reason: "provider_missing", credentialId: resolved.id };
+  }
+
+  const metadata = ProviderMetadata(providerRow.metadata ?? {});
+  if (metadata instanceof type.errors) {
+    return {
+      ok: false,
+      reason: "provider_misconfigured",
+      providerName: providerRow.name,
+      summary: metadata.summary,
+    };
+  }
+
+  return {
+    ok: true,
+    source: {
+      id: `${providerRow.plugin}:${defaultModel}`,
+      provider: providerRow.plugin,
+      baseURL: metadata.baseURL,
+      apiKey: resolved.secret,
+      model: defaultModel,
+    },
+  };
+}
+
+/**
+ * Resolve the full `InferenceSource[]` for a single running instance by
+ * re-resolving each credential requirement from the agent definition.
+ *
+ * Failure modes (invalid agent definition, malformed `modelConfig`, any
+ * per-credential resolution failure) collapse to an empty array with
+ * structured `db.credentials` log lines. Callers that need to surface
+ * per-credential outcomes to operators should call `resolveOneCredential`
+ * directly — see `packages/hub-api/src/routes/instances.ts` for the
+ * 409-mapping pattern.
+ */
+export async function resolveInstanceSources(
+  db: DB["db"],
+  tenantId: string,
+  instance: { agentId: string; sessionId: string | null },
+): Promise<InferenceSource[]> {
+  const agentRow = await db.query.agent.findFirst({
+    where: eq(agent.id, instance.agentId),
+  });
+  if (!agentRow) return [];
+
+  const requirements = CredentialRequirements(
+    agentRow.credentialRequirements ?? [],
+  );
+  if (requirements instanceof type.errors) {
+    log.warn`Invalid credential requirements for agent ${agentRow.id}: ${requirements.summary}`;
+    return [];
+  }
+
+  const modelConfig = AgentModelConfig(agentRow.modelConfig ?? {});
+  if (modelConfig instanceof type.errors) {
+    log.warn`Invalid modelConfig for agent ${agentRow.id}: ${modelConfig.summary}`;
+    return [];
+  }
+  const defaultModel = modelConfig.defaultModel;
+
+  let invokerPrincipalId: string | null = null;
+  if (instance.sessionId) {
+    const session = await db.query.agentSession.findFirst({
+      where: eq(agentSession.id, instance.sessionId),
+    });
+    if (session) {
+      invokerPrincipalId = session.principalId;
+    }
+  }
+
+  const sources: InferenceSource[] = [];
+  for (const req of requirements) {
+    const outcome = await resolveOneCredential(
+      db,
+      tenantId,
+      req,
+      agentRow.creatorPrincipalId,
+      invokerPrincipalId,
+      defaultModel,
+    );
+    if (outcome.ok) {
+      sources.push(outcome.source);
+      continue;
+    }
+    switch (outcome.reason) {
+      case "skipped":
+        break;
+      case "credential_error":
+        log.warn`Failed to resolve credential for provider ${outcome.requirement.providerName}: ${outcome.message}`;
+        break;
+      case "credential_missing":
+        break;
+      case "provider_missing":
+        break;
+      case "provider_misconfigured":
+        log.warn`Invalid provider metadata for provider ${outcome.providerName}: ${outcome.summary}`;
+        break;
+    }
+  }
+
+  return sources;
+}