@desplega.ai/agent-swarm 1.173.0 → 2.1.0

package/src/be/db/model-profiles.ts

@@ -0,0 +1,315 @@
+/**
+ * Model profiles: a named (harness, model, effort) picked per task (`profile`)
+ * or applied as an agent's default (agent-scoped `MODEL_PROFILE` config row).
+ * Claim resolves them (`src/be/model-tier-resolution.ts`). See
+ * runbooks/model-tiers.md § Model profiles.
+ */
+import {
+  type ModelProfile,
+  type ProviderName,
+  ProviderNameSchema,
+  type ReasoningEffort,
+  ReasoningEffortSchema,
+} from "../../types";
+import { vcsRepoName, vcsRepoUrlMatches } from "../../utils/vcs-repo-match";
+import { getDbClient } from "./runtime";
+import { SUPERSEDED_RESUME_REPAIR_WINDOW_MS } from "./tasks/read";
+
+/** Agent-scoped swarm_config key holding the agent's default profile name. */
+export const MODEL_PROFILE_CONFIG_KEY = "MODEL_PROFILE";
+
+type ModelProfileRow = {
+  id: string;
+  name: string;
+  harness: string;
+  model: string;
+  effort: string | null;
+  allowCustomModel: number;
+  description: string | null;
+  seededFrom: string | null;
+  createdAt: string;
+  lastUpdatedAt: string;
+};
+
+function rowToModelProfile(row: ModelProfileRow): ModelProfile {
+  return {
+    id: row.id,
+    name: row.name,
+    harness: ProviderNameSchema.parse(row.harness),
+    model: row.model,
+    effort: ReasoningEffortSchema.safeParse(row.effort).success
+      ? (row.effort as ReasoningEffort)
+      : null,
+    allowCustomModel: row.allowCustomModel === 1,
+    description: row.description,
+    seededFrom: row.seededFrom,
+    createdAt: row.createdAt,
+    lastUpdatedAt: row.lastUpdatedAt,
+  };
+}
+
+export async function listModelProfiles(
+  filter: { harness?: ProviderName } = {},
+): Promise<ModelProfile[]> {
+  const rows = filter.harness
+    ? await getDbClient().query<ModelProfileRow>(
+        "SELECT * FROM model_profiles WHERE harness = ? ORDER BY harness, name",
+        [filter.harness],
+      )
+    : await getDbClient().query<ModelProfileRow>(
+        "SELECT * FROM model_profiles ORDER BY harness, name",
+      );
+  return rows.map(rowToModelProfile);
+}
+
+export async function getModelProfileByName(name: string): Promise<ModelProfile | null> {
+  const row = await getDbClient().get<ModelProfileRow>(
+    "SELECT * FROM model_profiles WHERE name = ?",
+    [name.trim()],
+  );
+  return row ? rowToModelProfile(row) : null;
+}
+
+export interface ModelProfileInput {
+  name: string;
+  harness: ProviderName;
+  model: string;
+  effort?: ReasoningEffort | null;
+  allowCustomModel?: boolean;
+  description?: string | null;
+  seededFrom?: string | null;
+}
+
+/** Insert a profile. Returns null when the name is taken. */
+export async function createModelProfile(
+  input: ModelProfileInput,
+  audit: { userId?: string | null } = {},
+): Promise<ModelProfile | null> {
+  const now = new Date().toISOString();
+  const row = await getDbClient().get<ModelProfileRow>(
+    `INSERT INTO model_profiles
+       (id, name, harness, model, effort, allowCustomModel, description, seededFrom, createdAt, lastUpdatedAt, created_by, updated_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(name) DO NOTHING
+     RETURNING *`,
+    [
+      crypto.randomUUID(),
+      input.name,
+      input.harness,
+      input.model,
+      input.effort ?? null,
+      input.allowCustomModel ? 1 : 0,
+      input.description ?? null,
+      input.seededFrom ?? null,
+      now,
+      now,
+      audit.userId ?? null,
+      audit.userId ?? null,
+    ],
+  );
+  return row ? rowToModelProfile(row) : null;
+}
+
+export type ModelProfilePatch = Partial<
+  Pick<ModelProfileInput, "model" | "effort" | "allowCustomModel" | "description">
+>;
+
+/** Update a profile's model, effort or description. The name and harness are fixed. */
+export async function updateModelProfile(
+  name: string,
+  patch: ModelProfilePatch,
+  audit: { userId?: string | null } = {},
+): Promise<ModelProfile | null> {
+  const sets: string[] = [];
+  const params: (string | number | null)[] = [];
+  if (patch.model !== undefined) {
+    sets.push("model = ?");
+    params.push(patch.model);
+  }
+  if (patch.effort !== undefined) {
+    sets.push("effort = ?");
+    params.push(patch.effort);
+  }
+  if (patch.allowCustomModel !== undefined) {
+    sets.push("allowCustomModel = ?");
+    params.push(patch.allowCustomModel ? 1 : 0);
+  }
+  if (patch.description !== undefined) {
+    sets.push("description = ?");
+    params.push(patch.description);
+  }
+  sets.push("lastUpdatedAt = ?", "updated_by = ?");
+  params.push(new Date().toISOString(), audit.userId ?? null);
+  const row = await getDbClient().get<ModelProfileRow>(
+    `UPDATE model_profiles SET ${sets.join(", ")} WHERE name = ? RETURNING *`,
+    [...params, name],
+  );
+  return row ? rowToModelProfile(row) : null;
+}
+
+/**
+ * Tasks (alias `t`) that still hold their profile: unfinished ones, and
+ * superseded ones still owed a resume. The resume copies the profile in a
+ * later write than the supersede (HTTP supersede, heartbeat remediation), and
+ * after a restart the heartbeat's orphan repair makes it, inside the same
+ * window (`SUPERSEDED_RESUME_REPAIR_WINDOW_MS`). Binds one parameter: the
+ * oldest `finishedAt` the repair still covers.
+ */
+const TASK_HOLDS_PROFILE_SQL = `(
+  t.status NOT IN ('completed', 'failed', 'cancelled', 'superseded')
+  OR (t.status = 'superseded'
+      AND t.workflowRunStepId IS NULL
+      AND (t.finishedAt IS NULL OR t.finishedAt > ?)
+      AND NOT EXISTS (
+        SELECT 1 FROM agent_tasks c WHERE c.parentTaskId = t.id AND c.taskType = 'resume')))`;
+
+function repairWindowStart(): string {
+  return new Date(Date.now() - SUPERSEDED_RESUME_REPAIR_WINDOW_MS).toISOString();
+}
+
+/** Who still points at a profile: agents with it as default, and tasks that still hold it. */
+export async function modelProfileReferences(
+  name: string,
+): Promise<{ agentIds: string[]; openTaskCount: number }> {
+  const agents = await getDbClient().query<{ scopeId: string }>(
+    "SELECT scopeId FROM swarm_config WHERE scope = 'agent' AND key = ? AND value = ?",
+    [MODEL_PROFILE_CONFIG_KEY, name],
+  );
+  const tasks = await getDbClient().get<{ n: number }>(
+    `SELECT COUNT(*) AS n FROM agent_tasks t WHERE t.profile = ? AND ${TASK_HOLDS_PROFILE_SQL}`,
+    [name, repairWindowStart()],
+  );
+  return { agentIds: agents.map((a) => a.scopeId), openTaskCount: tasks?.n ?? 0 };
+}
+
+/**
+ * Which migration-220 reference trigger refused a write: `missing` when a task
+ * or an agent default names a profile that does not exist.
+ */
+export function modelProfileRefError(error: unknown): "missing" | null {
+  const message = error instanceof Error ? error.message : "";
+  return message.includes("model-profile-missing:") ? "missing" : null;
+}
+
+/**
+ * Delete a profile unless a task still holds it (`TASK_HOLDS_PROFILE_SQL`) or
+ * an agent default names it. The check is part of the DELETE statement, so a
+ * reference written after the caller's own count still makes it `in-use`; the
+ * triggers in migration 220 refuse the opposite order (a reference written
+ * after this delete).
+ */
+export async function deleteModelProfile(name: string): Promise<"deleted" | "missing" | "in-use"> {
+  const row = await getDbClient().get<{ id: string }>(
+    `DELETE FROM model_profiles
+      WHERE name = ?
+        AND NOT EXISTS (
+          SELECT 1 FROM agent_tasks t
+           WHERE t.profile = model_profiles.name AND ${TASK_HOLDS_PROFILE_SQL})
+        AND NOT EXISTS (
+          SELECT 1 FROM swarm_config
+           WHERE scope = 'agent' AND key = ? AND trim(value) = model_profiles.name)
+      RETURNING id`,
+    [name, repairWindowStart(), MODEL_PROFILE_CONFIG_KEY],
+  );
+  if (row) return "deleted";
+  return (await getModelProfileByName(name)) ? "in-use" : "missing";
+}
+
+/** The agent's default profile name (agent-scoped MODEL_PROFILE), or null. */
+export async function getAgentDefaultProfileName(agentId: string): Promise<string | null> {
+  const row = await getDbClient().get<{ value: string }>(
+    "SELECT value FROM swarm_config WHERE scope = 'agent' AND scopeId = ? AND key = ?",
+    [agentId, MODEL_PROFILE_CONFIG_KEY],
+  );
+  return row?.value.trim() || null;
+}
+
+/**
+ * Which of MODEL_OVERRIDE / REASONING_EFFORT_OVERRIDE the task's repo sets at
+ * repo scope, exported or not. The worker env takes a repo row over the
+ * agent's own (repo > agent), and a withheld one removes the key, so the
+ * agent's default profile must not supply that axis. Finds the repo the way
+ * the worker does (`fetchRepoConfig`). `includeSecrets: false` leaves out
+ * secret rows, as `/api/config/resolved` does for a worker that cannot read
+ * them (`readsRepoSecrets`): that worker's env never gets them.
+ */
+export async function repoModelOverrideKeys(
+  vcsRepo: string | null | undefined,
+  { includeSecrets = true }: { includeSecrets?: boolean } = {},
+): Promise<Set<string>> {
+  if (!vcsRepo?.trim()) return new Set();
+  const repos = await getDbClient().query<{ id: string; url: string }>(
+    "SELECT id, url FROM swarm_repos WHERE name = ? ORDER BY name ASC",
+    [vcsRepoName(vcsRepo)],
+  );
+  const repo = repos.find((r) => vcsRepoUrlMatches(r.url, vcsRepo));
+  if (!repo) return new Set();
+  const rows = await getDbClient().query<{ key: string }>(
+    `SELECT key FROM swarm_config
+      WHERE scope = 'repo' AND scopeId = ? AND key IN ('MODEL_OVERRIDE', 'REASONING_EFFORT_OVERRIDE')
+        ${includeSecrets ? "" : "AND isSecret = 0"}`,
+    [repo.id],
+  );
+  return new Set(rows.map((row) => row.key));
+}
+
+/**
+ * Why a task cannot ask for `profile`, or null when it can. PR 1 validity is
+ * the harness only: the profile must exist and, when the target agent is known
+ * and has a harness, run on that harness. `profile` is exclusive with `model`
+ * and `modelTier`, which pick the model another way.
+ */
+export async function taskProfileError(check: {
+  profile?: string | null;
+  model?: string | null;
+  modelTier?: string | null;
+  agentId?: string | null;
+}): Promise<string | null> {
+  const name = check.profile?.trim();
+  if (!name) return null;
+  if (check.model?.trim() || check.modelTier?.trim()) {
+    return "Pass `profile`, or `model`/`modelTier`, not both.";
+  }
+  const profile = await getModelProfileByName(name);
+  if (!profile) {
+    return `Unknown model profile "${name}". List profiles with list-model-profiles.`;
+  }
+  if (!check.agentId) return null;
+  const agent = await getDbClient().get<{ harness: string | null }>(
+    "SELECT COALESCE(harness_provider, provider) AS harness FROM agents WHERE id = ?",
+    [check.agentId],
+  );
+  if (agent?.harness && agent.harness !== profile.harness) {
+    return `Model profile "${name}" runs on the ${profile.harness} harness; the target agent runs ${agent.harness}.`;
+  }
+  return null;
+}
+
+type OverrideRowState = { value: string; exportToEnv?: number } | null;
+
+/** What a config row does to the worker env: its value, withheld (exportToEnv off), or absent. */
+function effectiveOverride(row: OverrideRowState): string | null {
+  if (!row) return null;
+  return row.exportToEnv === 0 ? "\u0000withheld" : row.value;
+}
+
+/**
+ * An agent's default model profile (MODEL_PROFILE) beats its MODEL_OVERRIDE and
+ * REASONING_EFFORT_OVERRIDE at claim. An effective change to either override, by
+ * any path, drops the profile default, so a stale default never beats a fresh
+ * override. Effective means what the worker env sees: the value, and whether
+ * the row is exported (`exportToEnv`).
+ */
+export async function clearAgentModelProfileOnOverrideChange(
+  agentId: string,
+  key: string,
+  before: OverrideRowState,
+  after: OverrideRowState,
+): Promise<void> {
+  if (key !== "MODEL_OVERRIDE" && key !== "REASONING_EFFORT_OVERRIDE") return;
+  if (effectiveOverride(before) === effectiveOverride(after)) return;
+  await getDbClient().run(
+    "DELETE FROM swarm_config WHERE scope = 'agent' AND scopeId = ? AND key = ?",
+    [agentId, MODEL_PROFILE_CONFIG_KEY],
+  );
+}

package/src/be/db/page-versions.ts

@@ -0,0 +1,15 @@
+import { getDbClient } from "./runtime";
+
+/**
+ * The page's edit counter, `MAX(page_versions.version) + 1`, or 1 before the
+ * first snapshot. Reads one indexed aggregate instead of every snapshot body:
+ * loading all versions of a large, often-edited page blocked the event loop
+ * for seconds per call.
+ */
+export async function getPageEditCounter(pageId: string): Promise<number> {
+  const row = await getDbClient().get<{ latest: number | null }>(
+    "SELECT MAX(version) AS latest FROM page_versions WHERE pageId = ?",
+    [pageId],
+  );
+  return (row?.latest ?? 0) + 1;
+}

package/src/be/db/runtime.ts

@@ -104,7 +104,34 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   db = new Database(dbPath, { create: true });
   console.log(`Database initialized at ${dbPath}`);
 
-  const database = db;
+  // Boot must finish before getDb() hands this handle out. A step below can
+  // throw SQLITE_BUSY while another connection holds the file, and the
+  // db-client retries BUSY by calling getDb() again. With `db` still assigned,
+  // that retry got a connection whose encryption key was never resolved, and
+  // the server died on "Encryption key not resolved yet". Drop the handle so
+  // the retry runs boot again.
+  const opened = db;
+  try {
+    return bootOpenedDb(opened, dbPath, resolvePromptTemplate, autoEncryptLegacyPlaintextSecrets);
+  } catch (error) {
+    if (db === opened) {
+      db = null;
+      try {
+        opened.close();
+      } catch {
+        // Already closed by the step that failed.
+      }
+    }
+    throw error;
+  }
+}
+
+function bootOpenedDb(
+  database: Database,
+  dbPath: string,
+  resolvePromptTemplate: typeof import("../db").resolvePromptTemplate,
+  autoEncryptLegacyPlaintextSecrets: typeof import("../db").autoEncryptLegacyPlaintextSecrets,
+): Database {
   database.run("PRAGMA journal_mode = WAL;");
   database.run("PRAGMA busy_timeout = 5000;");
   database.run("PRAGMA foreign_keys = ON;");
@@ -140,7 +167,7 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   // Old databases have CHECK(status IN ('pending','in_progress','completed','failed'))
   // which blocks 'cancelled', 'paused', 'offered', 'unassigned' statuses
   try {
-    const taskSchemaInfo = db
+    const taskSchemaInfo = database
       .prepare<{ sql: string | null }, []>(
         "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'agent_tasks'",
       )
@@ -153,7 +180,7 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
 
     if (needsStatusMigration) {
       console.log("[Migration] Removing restrictive CHECK constraint on agent_tasks.status");
-      db.run("PRAGMA foreign_keys=off");
+      database.run("PRAGMA foreign_keys=off");
 
       // Migrations run before this compatibility guard, so a legacy table now
       // carries every current column. Rebuilding from an old hard-coded column
@@ -169,12 +196,12 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
       if (rebuiltSchemaSql === schemaSql || !/agent_tasks_new/i.test(rebuiltSchemaSql)) {
         throw new Error("Could not derive agent_tasks schema without legacy status CHECK");
       }
-      const columns = db
+      const columns = database
         .prepare<{ name: string }, []>('PRAGMA table_info("agent_tasks")')
         .all()
         .map((column) => `"${column.name.replaceAll('"', '""')}"`)
         .join(", ");
-      const schemaObjects = db
+      const schemaObjects = database
         .prepare<{ sql: string }, []>(
           `SELECT sql FROM sqlite_master
            WHERE tbl_name = 'agent_tasks'
@@ -194,13 +221,13 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
         for (const sql of schemaObjects) database.run(sql);
       })();
 
-      db.run("PRAGMA foreign_keys=on");
+      database.run("PRAGMA foreign_keys=on");
       console.log("[Migration] Successfully removed CHECK constraint on agent_tasks.status");
     }
   } catch (e) {
     console.error("[Migration] Failed to update agent_tasks CHECK constraint:", e);
     try {
-      db.run("PRAGMA foreign_keys=on");
+      database.run("PRAGMA foreign_keys=on");
     } catch (cleanupError) {
       console.error("[Migration] Failed to re-enable SQLite foreign_keys pragma:", cleanupError);
     }
@@ -291,7 +318,7 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
     throw err;
   }
 
-  return db;
+  return database;
 }
 
 export function getDb(path?: string): Database {

package/src/be/db/skill-name-resolution.ts

@@ -0,0 +1,36 @@
+import { getDbClient } from "./runtime";
+
+export type SwarmSkillNameResolution =
+  | { kind: "found"; skillId: string }
+  | { kind: "ambiguous"; skillIds: string[] }
+  | { kind: "none" };
+
+/**
+ * Resolve a swarm-scope skill name for `skill-get`.
+ *
+ * Migration 019 makes a name unique only per scope + owner, so a swarm name can
+ * match one ownerless row plus any number of agent-owned rows. Precedence:
+ * the ownerless row, then the caller's own row, then a single owned row.
+ * Several foreign-owned rows are ambiguous; the caller must pass a skillId.
+ *
+ * `getSkillByName(name, "swarm")` stays ownerless-only: the seeder relies on it.
+ */
+export async function resolveSwarmSkillByName(
+  name: string,
+  callerAgentId?: string,
+): Promise<SwarmSkillNameResolution> {
+  const rows = await getDbClient().query<{ id: string; ownerAgentId: string | null }>(
+    "SELECT id, ownerAgentId FROM skills WHERE name = ? AND scope = 'swarm' ORDER BY createdAt, id",
+    [name],
+  );
+
+  const ownerless = rows.find((row) => !row.ownerAgentId);
+  if (ownerless) return { kind: "found", skillId: ownerless.id };
+
+  const own = callerAgentId ? rows.find((row) => row.ownerAgentId === callerAgentId) : undefined;
+  if (own) return { kind: "found", skillId: own.id };
+
+  if (rows.length === 1) return { kind: "found", skillId: rows[0]!.id };
+  if (rows.length > 1) return { kind: "ambiguous", skillIds: rows.map((row) => row.id) };
+  return { kind: "none" };
+}