@desplega.ai/agent-swarm 1.51.2 → 1.52.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.51.2",
+  "version": "1.52.1",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -74,6 +74,7 @@
     "e2e:workflows:docker": "bun scripts/e2e-workflow-test.ts --with-docker",
     "docs:mcp": "bun scripts/generate-mcp-docs.ts",
     "docs:openapi": "bun scripts/generate-openapi.ts",
+    "docs:business-use": "bun scripts/generate-business-use-docs.ts",
     "pm2-start": "pm2 start ecosystem.config.cjs",
     "pm2-stop": "pm2 stop ecosystem.config.cjs",
     "pm2-restart": "pm2 restart ecosystem.config.cjs",
@@ -93,6 +94,7 @@
   "dependencies": {
     "@ai-sdk/openai": "^3.0.41",
     "@asteasolutions/zod-to-openapi": "^8.0.0",
+    "@desplega.ai/business-use": "^0.4.2",
     "@desplega.ai/localtunnel": "^2.2.0",
     "@inkjs/ui": "^2.0.0",
     "@linear/sdk": "^77.0.0",

package/src/be/db.ts

@@ -8,6 +8,7 @@ import type {
   AgentMemory,
   AgentMemoryScope,
   AgentMemorySource,
+  AgentSkill,
   AgentStatus,
   AgentTask,
   AgentTaskSource,
@@ -32,6 +33,10 @@ import type {
   ServiceStatus,
   SessionCost,
   SessionLog,
+  Skill,
+  SkillScope,
+  SkillType,
+  SkillWithInstallInfo,
   SwarmConfig,
   SwarmRepo,
   TriggerConfig,
@@ -935,6 +940,23 @@ export function getTasksByAgentId(agentId: string): AgentTask[] {
   return taskQueries.getByAgentId().all(agentId).map(rowToAgentTask);
 }
 
+/**
+ * Get the most recently updated in-progress task for an agent.
+ * Used as a fallback when X-Source-Task-Id header is missing (e.g. lead agent HITL requests).
+ *
+ * Note: if agent has multiple in-progress tasks, returns the most recently
+ * updated one. This is a best-effort fallback — the X-Source-Task-Id header
+ * is the authoritative source when available.
+ */
+export function getAgentCurrentTask(agentId: string): AgentTask | null {
+  const row = getDb()
+    .prepare<AgentTaskRow, [string]>(
+      "SELECT * FROM agent_tasks WHERE agentId = ? AND status = 'in_progress' ORDER BY lastUpdatedAt DESC LIMIT 1",
+    )
+    .get(agentId);
+  return row ? rowToAgentTask(row) : null;
+}
+
 export function getTasksByStatus(status: AgentTaskStatus): AgentTask[] {
   return taskQueries.getByStatus().all(status).map(rowToAgentTask);
 }
@@ -6722,3 +6744,650 @@ export function upsertChannelActivityCursor(channelId: string, lastSeenTs: strin
     )
     .run(channelId, lastSeenTs);
 }
+
+// ============================================================================
+// Approval Requests
+// ============================================================================
+
+export interface ApprovalRequest {
+  id: string;
+  title: string;
+  questions: unknown[];
+  workflowRunId: string | null;
+  workflowRunStepId: string | null;
+  sourceTaskId: string | null;
+  approvers: unknown;
+  status: "pending" | "approved" | "rejected" | "timeout";
+  responses: unknown | null;
+  resolvedBy: string | null;
+  resolvedAt: string | null;
+  timeoutSeconds: number | null;
+  expiresAt: string | null;
+  notificationChannels: unknown[] | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ApprovalRequestRow {
+  id: string;
+  title: string;
+  questions: string;
+  workflowRunId: string | null;
+  workflowRunStepId: string | null;
+  sourceTaskId: string | null;
+  approvers: string;
+  status: string;
+  responses: string | null;
+  resolvedBy: string | null;
+  resolvedAt: string | null;
+  timeoutSeconds: number | null;
+  expiresAt: string | null;
+  notificationChannels: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+function rowToApprovalRequest(row: ApprovalRequestRow): ApprovalRequest {
+  return {
+    id: row.id,
+    title: row.title,
+    questions: JSON.parse(row.questions),
+    workflowRunId: row.workflowRunId,
+    workflowRunStepId: row.workflowRunStepId,
+    sourceTaskId: row.sourceTaskId,
+    approvers: JSON.parse(row.approvers),
+    status: row.status as ApprovalRequest["status"],
+    responses: row.responses ? JSON.parse(row.responses) : null,
+    resolvedBy: row.resolvedBy,
+    resolvedAt: row.resolvedAt,
+    timeoutSeconds: row.timeoutSeconds,
+    expiresAt: row.expiresAt,
+    notificationChannels: row.notificationChannels ? JSON.parse(row.notificationChannels) : null,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export function createApprovalRequest(data: {
+  id: string;
+  title: string;
+  questions: unknown[];
+  approvers: unknown;
+  workflowRunId?: string;
+  workflowRunStepId?: string;
+  sourceTaskId?: string;
+  timeoutSeconds?: number;
+  notificationChannels?: unknown[];
+}): ApprovalRequest {
+  const now = new Date().toISOString();
+  const expiresAt = data.timeoutSeconds
+    ? new Date(Date.now() + data.timeoutSeconds * 1000).toISOString()
+    : null;
+
+  const row = getDb()
+    .prepare<
+      ApprovalRequestRow,
+      [
+        string,
+        string,
+        string,
+        string | null,
+        string | null,
+        string | null,
+        string,
+        number | null,
+        string | null,
+        string | null,
+        string,
+        string,
+      ]
+    >(
+      `INSERT INTO approval_requests (id, title, questions, workflowRunId, workflowRunStepId, sourceTaskId, approvers, timeoutSeconds, expiresAt, notificationChannels, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING *`,
+    )
+    .get(
+      data.id,
+      data.title,
+      JSON.stringify(data.questions),
+      data.workflowRunId ?? null,
+      data.workflowRunStepId ?? null,
+      data.sourceTaskId ?? null,
+      JSON.stringify(data.approvers),
+      data.timeoutSeconds ?? null,
+      expiresAt,
+      data.notificationChannels ? JSON.stringify(data.notificationChannels) : null,
+      now,
+      now,
+    );
+
+  return rowToApprovalRequest(row!);
+}
+
+export function getApprovalRequestById(id: string): ApprovalRequest | null {
+  const row = getDb()
+    .prepare<ApprovalRequestRow, [string]>("SELECT * FROM approval_requests WHERE id = ?")
+    .get(id);
+  return row ? rowToApprovalRequest(row) : null;
+}
+
+export function resolveApprovalRequest(
+  id: string,
+  data: {
+    status: "approved" | "rejected" | "timeout";
+    responses?: unknown;
+    resolvedBy?: string;
+  },
+): ApprovalRequest | null {
+  const now = new Date().toISOString();
+  const row = getDb()
+    .prepare<ApprovalRequestRow, [string, string | null, string | null, string, string, string]>(
+      `UPDATE approval_requests
+       SET status = ?, responses = ?, resolvedBy = ?, resolvedAt = ?, updatedAt = ?
+       WHERE id = ? AND status = 'pending'
+       RETURNING *`,
+    )
+    .get(
+      data.status,
+      data.responses ? JSON.stringify(data.responses) : null,
+      data.resolvedBy ?? null,
+      now,
+      now,
+      id,
+    );
+  return row ? rowToApprovalRequest(row) : null;
+}
+
+export function updateApprovalRequestNotifications(
+  id: string,
+  notificationChannels: Array<{ channel: string; target: string; messageTs?: string }>,
+): void {
+  const now = new Date().toISOString();
+  getDb()
+    .prepare("UPDATE approval_requests SET notificationChannels = ?, updatedAt = ? WHERE id = ?")
+    .run(JSON.stringify(notificationChannels), now, id);
+}
+
+export function listApprovalRequests(filters?: {
+  status?: string;
+  workflowRunId?: string;
+  limit?: number;
+}): ApprovalRequest[] {
+  const conditions: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (filters?.status) {
+    conditions.push("status = ?");
+    params.push(filters.status);
+  }
+  if (filters?.workflowRunId) {
+    conditions.push("workflowRunId = ?");
+    params.push(filters.workflowRunId);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = filters?.limit ?? 100;
+  params.push(limit);
+
+  const stmt = getDb().prepare(
+    `SELECT * FROM approval_requests ${where} ORDER BY createdAt DESC LIMIT ?`,
+  );
+  const rows = stmt.all(...params) as ApprovalRequestRow[];
+
+  return rows.map(rowToApprovalRequest);
+}
+
+export interface StuckApprovalRun {
+  runId: string;
+  stepId: string;
+  nodeId: string;
+  workflowId: string;
+  approvalId: string;
+  approvalStatus: string;
+  approvalResponses: string | null;
+  expiresAt: string | null;
+}
+
+export function getStuckApprovalRuns(): StuckApprovalRun[] {
+  return getDb()
+    .prepare<StuckApprovalRun, []>(
+      `SELECT
+        wr.id as runId,
+        wrs.id as stepId,
+        wrs.nodeId,
+        wr.workflowId,
+        ar.id as approvalId,
+        ar.status as approvalStatus,
+        ar.responses as approvalResponses,
+        ar.expiresAt
+      FROM workflow_runs wr
+      JOIN workflow_run_steps wrs ON wrs.runId = wr.id AND wrs.status = 'waiting'
+      JOIN approval_requests ar ON ar.workflowRunStepId = wrs.id
+      WHERE wr.status = 'waiting'
+        AND (ar.status IN ('approved', 'rejected', 'timeout')
+             OR (ar.status = 'pending' AND ar.expiresAt IS NOT NULL AND ar.expiresAt < datetime('now')))`,
+    )
+    .all();
+}
+
+export function getApprovalRequestByStepId(stepId: string): ApprovalRequest | null {
+  const row = getDb()
+    .prepare<ApprovalRequestRow, [string]>(
+      "SELECT * FROM approval_requests WHERE workflowRunStepId = ?",
+    )
+    .get(stepId);
+  return row ? rowToApprovalRequest(row) : null;
+}
+
+// TODO: Wire into a periodic cron/sweep to auto-timeout expired approval requests (Phase 2)
+export function getExpiredPendingApprovals(): ApprovalRequest[] {
+  const rows = getDb()
+    .prepare<ApprovalRequestRow, []>(
+      `SELECT * FROM approval_requests
+       WHERE status = 'pending'
+         AND expiresAt IS NOT NULL
+         AND expiresAt < datetime('now')`,
+    )
+    .all();
+  return rows.map(rowToApprovalRequest);
+}
+
+// ============================================================================
+// Skills
+// ============================================================================
+
+type SkillRow = {
+  id: string;
+  name: string;
+  description: string;
+  content: string;
+  type: string;
+  scope: string;
+  ownerAgentId: string | null;
+  sourceUrl: string | null;
+  sourceRepo: string | null;
+  sourcePath: string | null;
+  sourceBranch: string;
+  sourceHash: string | null;
+  isComplex: number;
+  allowedTools: string | null;
+  model: string | null;
+  effort: string | null;
+  context: string | null;
+  agent: string | null;
+  disableModelInvocation: number;
+  userInvocable: number;
+  version: number;
+  isEnabled: number;
+  createdAt: string;
+  lastUpdatedAt: string;
+  lastFetchedAt: string | null;
+};
+
+function rowToSkill(row: SkillRow): Skill {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description,
+    content: row.content,
+    type: row.type as SkillType,
+    scope: row.scope as SkillScope,
+    ownerAgentId: row.ownerAgentId,
+    sourceUrl: row.sourceUrl,
+    sourceRepo: row.sourceRepo,
+    sourcePath: row.sourcePath,
+    sourceBranch: row.sourceBranch,
+    sourceHash: row.sourceHash,
+    isComplex: row.isComplex === 1,
+    allowedTools: row.allowedTools,
+    model: row.model,
+    effort: row.effort,
+    context: row.context,
+    agent: row.agent,
+    disableModelInvocation: row.disableModelInvocation === 1,
+    userInvocable: row.userInvocable === 1,
+    version: row.version,
+    isEnabled: row.isEnabled === 1,
+    createdAt: row.createdAt,
+    lastUpdatedAt: row.lastUpdatedAt,
+    lastFetchedAt: row.lastFetchedAt,
+  };
+}
+
+type AgentSkillRow = {
+  id: string;
+  agentId: string;
+  skillId: string;
+  isActive: number;
+  installedAt: string;
+};
+
+function rowToAgentSkill(row: AgentSkillRow): AgentSkill {
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    skillId: row.skillId,
+    isActive: row.isActive === 1,
+    installedAt: row.installedAt,
+  };
+}
+
+type SkillWithInstallRow = SkillRow & { isActive: number; installedAt: string };
+
+function rowToSkillWithInstall(row: SkillWithInstallRow): SkillWithInstallInfo {
+  return {
+    ...rowToSkill(row),
+    isActive: row.isActive === 1,
+    installedAt: row.installedAt,
+  };
+}
+
+export interface SkillInsert {
+  name: string;
+  description: string;
+  content: string;
+  type?: SkillType;
+  scope?: SkillScope;
+  ownerAgentId?: string;
+  sourceUrl?: string;
+  sourceRepo?: string;
+  sourcePath?: string;
+  sourceBranch?: string;
+  sourceHash?: string;
+  isComplex?: boolean;
+  allowedTools?: string;
+  model?: string;
+  effort?: string;
+  context?: string;
+  agent?: string;
+  disableModelInvocation?: boolean;
+  userInvocable?: boolean;
+}
+
+export function createSkill(data: SkillInsert): Skill {
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+
+  const row = getDb()
+    .prepare<SkillRow, (string | number | null)[]>(
+      `INSERT INTO skills (
+        id, name, description, content, type, scope, ownerAgentId,
+        sourceUrl, sourceRepo, sourcePath, sourceBranch, sourceHash, isComplex,
+        allowedTools, model, effort, context, agent, disableModelInvocation, userInvocable,
+        version, isEnabled, createdAt, lastUpdatedAt
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 1, ?, ?) RETURNING *`,
+    )
+    .get(
+      id,
+      data.name,
+      data.description,
+      data.content,
+      data.type ?? "personal",
+      data.scope ?? "agent",
+      data.ownerAgentId ?? null,
+      data.sourceUrl ?? null,
+      data.sourceRepo ?? null,
+      data.sourcePath ?? null,
+      data.sourceBranch ?? "main",
+      data.sourceHash ?? null,
+      data.isComplex ? 1 : 0,
+      data.allowedTools ?? null,
+      data.model ?? null,
+      data.effort ?? null,
+      data.context ?? null,
+      data.agent ?? null,
+      data.disableModelInvocation ? 1 : 0,
+      data.userInvocable === false ? 0 : 1,
+      now,
+      now,
+    );
+
+  if (!row) throw new Error("Failed to create skill");
+  return rowToSkill(row);
+}
+
+export function updateSkill(
+  id: string,
+  updates: Partial<SkillInsert> & { isEnabled?: boolean; lastFetchedAt?: string },
+): Skill | null {
+  const existing = getSkillById(id);
+  if (!existing) return null;
+
+  const now = new Date().toISOString();
+  const sets: string[] = ["lastUpdatedAt = ?"];
+  const params: (string | number | null)[] = [now];
+
+  if (updates.name !== undefined) {
+    sets.push("name = ?");
+    params.push(updates.name);
+  }
+  if (updates.description !== undefined) {
+    sets.push("description = ?");
+    params.push(updates.description);
+  }
+  if (updates.content !== undefined) {
+    sets.push("content = ?");
+    params.push(updates.content);
+  }
+  if (updates.scope !== undefined) {
+    sets.push("scope = ?");
+    params.push(updates.scope);
+  }
+  if (updates.isEnabled !== undefined) {
+    sets.push("isEnabled = ?");
+    params.push(updates.isEnabled ? 1 : 0);
+  }
+  if (updates.allowedTools !== undefined) {
+    sets.push("allowedTools = ?");
+    params.push(updates.allowedTools ?? null);
+  }
+  if (updates.model !== undefined) {
+    sets.push("model = ?");
+    params.push(updates.model ?? null);
+  }
+  if (updates.effort !== undefined) {
+    sets.push("effort = ?");
+    params.push(updates.effort ?? null);
+  }
+  if (updates.context !== undefined) {
+    sets.push("context = ?");
+    params.push(updates.context ?? null);
+  }
+  if (updates.agent !== undefined) {
+    sets.push("agent = ?");
+    params.push(updates.agent ?? null);
+  }
+  if (updates.disableModelInvocation !== undefined) {
+    sets.push("disableModelInvocation = ?");
+    params.push(updates.disableModelInvocation ? 1 : 0);
+  }
+  if (updates.userInvocable !== undefined) {
+    sets.push("userInvocable = ?");
+    params.push(updates.userInvocable ? 1 : 0);
+  }
+  if (updates.sourceUrl !== undefined) {
+    sets.push("sourceUrl = ?");
+    params.push(updates.sourceUrl ?? null);
+  }
+  if (updates.sourceRepo !== undefined) {
+    sets.push("sourceRepo = ?");
+    params.push(updates.sourceRepo ?? null);
+  }
+  if (updates.sourcePath !== undefined) {
+    sets.push("sourcePath = ?");
+    params.push(updates.sourcePath ?? null);
+  }
+  if (updates.sourceBranch !== undefined) {
+    sets.push("sourceBranch = ?");
+    params.push(updates.sourceBranch ?? "main");
+  }
+  if (updates.sourceHash !== undefined) {
+    sets.push("sourceHash = ?");
+    params.push(updates.sourceHash ?? null);
+  }
+  if (updates.isComplex !== undefined) {
+    sets.push("isComplex = ?");
+    params.push(updates.isComplex ? 1 : 0);
+  }
+  if (updates.lastFetchedAt !== undefined) {
+    sets.push("lastFetchedAt = ?");
+    params.push(updates.lastFetchedAt);
+  }
+
+  // Bump version when content changes
+  if (updates.content !== undefined) {
+    sets.push("version = version + 1");
+  }
+
+  params.push(id);
+  const row = getDb()
+    .prepare<SkillRow, (string | number | null)[]>(
+      `UPDATE skills SET ${sets.join(", ")} WHERE id = ? RETURNING *`,
+    )
+    .get(...params);
+
+  return row ? rowToSkill(row) : null;
+}
+
+export function deleteSkill(id: string): boolean {
+  const result = getDb().prepare("DELETE FROM skills WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+export function getSkillById(id: string): Skill | null {
+  const row = getDb().prepare<SkillRow, [string]>("SELECT * FROM skills WHERE id = ?").get(id);
+  return row ? rowToSkill(row) : null;
+}
+
+export function getSkillByName(
+  name: string,
+  scope: SkillScope,
+  ownerAgentId?: string,
+): Skill | null {
+  const row = getDb()
+    .prepare<SkillRow, [string, string, string]>(
+      "SELECT * FROM skills WHERE name = ? AND scope = ? AND COALESCE(ownerAgentId, '') = ?",
+    )
+    .get(name, scope, ownerAgentId ?? "");
+  return row ? rowToSkill(row) : null;
+}
+
+export interface SkillFilters {
+  type?: SkillType;
+  scope?: SkillScope;
+  ownerAgentId?: string;
+  isEnabled?: boolean;
+  search?: string;
+  limit?: number;
+  includeContent?: boolean;
+}
+
+export function listSkills(filters?: SkillFilters): Skill[] {
+  const columns =
+    filters?.includeContent === false
+      ? "id, name, description, type, scope, ownerAgentId, sourceUrl, sourceRepo, sourcePath, sourceBranch, sourceHash, isComplex, allowedTools, model, effort, context, agent, disableModelInvocation, userInvocable, version, isEnabled, createdAt, lastUpdatedAt, lastFetchedAt, '' as content"
+      : "*";
+  let query = `SELECT ${columns} FROM skills WHERE 1=1`;
+  const params: (string | number)[] = [];
+
+  if (filters?.type) {
+    query += " AND type = ?";
+    params.push(filters.type);
+  }
+  if (filters?.scope) {
+    query += " AND scope = ?";
+    params.push(filters.scope);
+  }
+  if (filters?.ownerAgentId) {
+    query += " AND ownerAgentId = ?";
+    params.push(filters.ownerAgentId);
+  }
+  if (filters?.isEnabled !== undefined) {
+    query += " AND isEnabled = ?";
+    params.push(filters.isEnabled ? 1 : 0);
+  }
+  if (filters?.search) {
+    query += " AND (name LIKE ? OR description LIKE ?)";
+    const term = `%${filters.search}%`;
+    params.push(term, term);
+  }
+
+  query += " ORDER BY name ASC";
+
+  if (filters?.limit) {
+    query += " LIMIT ?";
+    params.push(filters.limit);
+  }
+
+  return getDb()
+    .prepare<SkillRow, (string | number)[]>(query)
+    .all(...params)
+    .map(rowToSkill);
+}
+
+export function searchSkills(query: string, limit = 20): Skill[] {
+  const term = `%${query}%`;
+  return getDb()
+    .prepare<SkillRow, [string, string, number]>(
+      "SELECT * FROM skills WHERE (name LIKE ? OR description LIKE ?) AND isEnabled = 1 ORDER BY name ASC LIMIT ?",
+    )
+    .all(term, term, limit)
+    .map(rowToSkill);
+}
+
+export function installSkill(agentId: string, skillId: string): AgentSkill {
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+
+  const row = getDb()
+    .prepare<AgentSkillRow, [string, string, string, string]>(
+      `INSERT INTO agent_skills (id, agentId, skillId, isActive, installedAt)
+       VALUES (?, ?, ?, 1, ?)
+       ON CONFLICT(agentId, skillId) DO UPDATE SET isActive = 1
+       RETURNING *`,
+    )
+    .get(id, agentId, skillId, now);
+
+  if (!row) throw new Error("Failed to install skill");
+  return rowToAgentSkill(row);
+}
+
+export function uninstallSkill(agentId: string, skillId: string): boolean {
+  const result = getDb()
+    .prepare("DELETE FROM agent_skills WHERE agentId = ? AND skillId = ?")
+    .run(agentId, skillId);
+  return result.changes > 0;
+}
+
+export function getAgentSkills(agentId: string, activeOnly = true): SkillWithInstallInfo[] {
+  const query = `
+    SELECT s.*, as2.isActive, as2.installedAt
+    FROM skills s
+    JOIN agent_skills as2 ON s.id = as2.skillId
+    WHERE as2.agentId = ?
+      ${activeOnly ? "AND as2.isActive = 1" : ""}
+      AND s.isEnabled = 1
+    ORDER BY
+      CASE WHEN s.type = 'personal' THEN 0 ELSE 1 END,
+      s.name
+  `;
+
+  const rows = getDb().prepare<SkillWithInstallRow, [string]>(query).all(agentId);
+
+  // Deduplicate by name — personal skills take precedence (already sorted first)
+  const seen = new Set<string>();
+  return rows
+    .filter((r) => {
+      if (seen.has(r.name)) return false;
+      seen.add(r.name);
+      return true;
+    })
+    .map(rowToSkillWithInstall);
+}
+
+export function toggleAgentSkill(agentId: string, skillId: string, isActive: boolean): boolean {
+  const result = getDb()
+    .prepare("UPDATE agent_skills SET isActive = ? WHERE agentId = ? AND skillId = ?")
+    .run(isActive ? 1 : 0, agentId, skillId);
+  return result.changes > 0;
+}