@desplega.ai/agent-swarm 1.89.0 → 1.91.0

package/src/be/scripts/typecheck.ts

@@ -50,21 +50,152 @@ export interface SwarmConfig {
 }
 
 export interface SwarmSdk {
+  // --- memory ---
   memory_search(args: { query: string; scope?: "all" | "agent" | "swarm"; limit?: number; source?: string }): Promise<unknown>;
   memory_get(args: { memoryId: string }): Promise<unknown>;
   memory_rate(args: { id: string; useful: boolean; note?: string }): Promise<unknown>;
+  // --- tasks ---
   task_list(args?: Record<string, unknown>): Promise<unknown>;
   task_get(args: { taskId: string }): Promise<unknown>;
   task_storeProgress(args: Record<string, unknown>): Promise<unknown>;
+  task_poll(args?: Record<string, unknown>): Promise<unknown>;
+  // --- kv ---
   kv_get(args: { key: string; namespace?: string }): Promise<unknown>;
   kv_set(args: { key: string; value: unknown; namespace?: string; ttlSeconds?: number; valueType?: "string" | "json" | "integer" }): Promise<unknown>;
   kv_del(args: { key: string; namespace?: string }): Promise<unknown>;
   kv_incr(args: { key: string; by?: number; namespace?: string }): Promise<unknown>;
   kv_list(args?: { prefix?: string; namespace?: string; limit?: number }): Promise<unknown>;
+  // --- repos ---
   repo_list(args?: Record<string, unknown>): Promise<unknown>;
+  // --- schedules ---
   schedule_list(args?: Record<string, unknown>): Promise<unknown>;
+  // --- scripts ---
   script_search(args: { query?: string; scope?: ScriptScope; limit?: number }): Promise<unknown>;
-  script_run(args: { name?: string; source?: string; args?: unknown; intent?: string; scope?: ScriptScope; fsMode?: ScriptFsMode }): Promise<unknown>;
+  script_run(args: { name?: string; source?: string; args?: unknown; intent?: string; scope?: ScriptScope; fsMode?: ScriptFsMode; idempotencyKey?: string }): Promise<unknown>;
+  // --- swarm / agent ---
+  swarm_get(args?: { includeFull?: boolean }): Promise<unknown>;
+  agent_info(args?: Record<string, unknown>): Promise<unknown>;
+  metrics_get(args?: Record<string, unknown>): Promise<unknown>;
+  user_resolve(args?: { kind?: string; externalId?: string; email?: string; userId?: string }): Promise<unknown>;
+  db_query(args: { sql: string; params?: unknown[] }): Promise<unknown>;
+  // --- config ---
+  config_get(args?: { agentId?: string; repoId?: string; key?: string; includeSecrets?: boolean }): Promise<unknown>;
+  config_list(args?: { scope?: "global" | "agent" | "repo"; scopeId?: string; key?: string; includeSecrets?: boolean }): Promise<unknown>;
+  // --- slack ---
+  slack_read(args?: { inboxMessageId?: string; taskId?: string; channelId?: string; threadTs?: string; limit?: number; includeFiles?: boolean }): Promise<unknown>;
+  slack_listChannels(args?: { types?: Array<"public" | "private" | "dm" | "mpim">; limit?: number }): Promise<unknown>;
+  // --- messaging ---
+  message_read(args?: { channel?: string; limit?: number; since?: string; unreadOnly?: boolean; mentionsOnly?: boolean; markAsRead?: boolean }): Promise<unknown>;
+  // --- services ---
+  service_list(args?: { agentId?: string; name?: string; status?: "starting" | "healthy" | "unhealthy" | "stopped"; includeOwn?: boolean }): Promise<unknown>;
+  // --- context / profiles ---
+  context_history(args?: { agentId?: string; field?: "soulMd" | "identityMd" | "toolsMd" | "claudeMd" | "setupScript"; limit?: number }): Promise<unknown>;
+  context_diff(args: { versionId: string; compareToVersionId?: string }): Promise<unknown>;
+  // --- workflows ---
+  workflow_list(args?: { enabled?: boolean; includeFull?: boolean }): Promise<unknown>;
+  workflow_get(args: { id: string }): Promise<unknown>;
+  workflow_listRuns(args: { workflowId: string; status?: "running" | "waiting" | "completed" | "failed" | "skipped" | "cancelled" }): Promise<unknown>;
+  workflow_getRun(args: { id: string }): Promise<unknown>;
+  // --- prompt templates ---
+  prompt_list(args?: { eventType?: string; scope?: "global" | "agent" | "repo"; scopeId?: string; isDefault?: boolean }): Promise<unknown>;
+  prompt_get(args: { id: string }): Promise<unknown>;
+  // --- tracker ---
+  tracker_status(args?: Record<string, unknown>): Promise<unknown>;
+  tracker_syncStatus(args?: Record<string, unknown>): Promise<unknown>;
+  tracker_linkTask(args: { taskId: string; externalId: string; provider?: string }): Promise<unknown>;
+  tracker_unlink(args: { taskId: string }): Promise<unknown>;
+  tracker_mapAgent(args: { agentId: string; externalId: string; provider?: string }): Promise<unknown>;
+
+  // --- write: memory ---
+  memory_delete(args: { id: string }): Promise<unknown>;
+  inject_learning(args: { content: string; name?: string; scope?: "agent" | "swarm"; source?: string; tags?: string[] }): Promise<unknown>;
+
+  // --- write: tasks ---
+  task_send(args: Record<string, unknown>): Promise<unknown>;
+  task_cancel(args: { taskId: string }): Promise<unknown>;
+  task_action(args: Record<string, unknown>): Promise<unknown>;
+
+  // --- write: config ---
+  config_set(args: { key: string; value: unknown; scope?: "global" | "agent" | "repo"; scopeId?: string; isSecret?: boolean }): Promise<unknown>;
+  config_delete(args: { id: string }): Promise<unknown>;
+
+  // --- write: slack ---
+  slack_post(args: { channelId: string; message: string; blocks?: unknown }): Promise<unknown>;
+  slack_reply(args: { channelId?: string; threadTs?: string; message: string; taskId?: string }): Promise<unknown>;
+  slack_startThread(args: { channelId: string; message: string }): Promise<unknown>;
+  slack_uploadFile(args: Record<string, unknown>): Promise<unknown>;
+  slack_downloadFile(args: { url: string }): Promise<unknown>;
+
+  // --- write: messaging (internal) ---
+  message_post(args: { channel?: string; content: string; to?: string }): Promise<unknown>;
+
+  // --- write: profiles ---
+  profile_update(args: Record<string, unknown>): Promise<unknown>;
+
+  // --- write: services ---
+  service_register(args: Record<string, unknown>): Promise<unknown>;
+  service_unregister(args: { name: string }): Promise<unknown>;
+  service_updateStatus(args: { name: string; status: "starting" | "healthy" | "unhealthy" | "stopped" }): Promise<unknown>;
+
+  // --- write: schedules ---
+  schedule_create(args: Record<string, unknown>): Promise<unknown>;
+  schedule_update(args: Record<string, unknown>): Promise<unknown>;
+  schedule_delete(args: { id: string }): Promise<unknown>;
+  schedule_runNow(args: { id: string }): Promise<unknown>;
+
+  // --- write: workflows ---
+  workflow_create(args: Record<string, unknown>): Promise<unknown>;
+  workflow_update(args: Record<string, unknown>): Promise<unknown>;
+  workflow_patch(args: Record<string, unknown>): Promise<unknown>;
+  workflow_patchNode(args: Record<string, unknown>): Promise<unknown>;
+  workflow_delete(args: { id: string }): Promise<unknown>;
+  workflow_trigger(args: { id: string; input?: Record<string, unknown> }): Promise<unknown>;
+  workflow_retryRun(args: { id: string }): Promise<unknown>;
+  workflow_cancelRun(args: { id: string }): Promise<unknown>;
+
+  // --- write: prompt templates ---
+  prompt_set(args: Record<string, unknown>): Promise<unknown>;
+  prompt_delete(args: { id: string }): Promise<unknown>;
+  prompt_preview(args: Record<string, unknown>): Promise<unknown>;
+
+  // --- write: scripts ---
+  script_upsert(args: { name: string; source: string; description?: string; intent?: string; scope?: ScriptScope; fsMode?: ScriptFsMode }): Promise<unknown>;
+  script_delete(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
+  script_queryTypes(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
+
+  // --- write: repos ---
+  repo_update(args: Record<string, unknown>): Promise<unknown>;
+
+  // --- write: agent ---
+  agent_join(args: { name: string; role?: string; description?: string; capabilities?: string[]; requestedId?: string; lead?: boolean }): Promise<unknown>;
+  user_manage(args: Record<string, unknown>): Promise<unknown>;
+
+  // --- skills ---
+  skill_list(args?: { scope?: string; scopeId?: string; includeBuiltin?: boolean }): Promise<unknown>;
+  skill_get(args: { id: string }): Promise<unknown>;
+  skill_search(args: { query: string; limit?: number }): Promise<unknown>;
+  skill_create(args: Record<string, unknown>): Promise<unknown>;
+  skill_update(args: Record<string, unknown>): Promise<unknown>;
+  skill_delete(args: { id: string }): Promise<unknown>;
+  skill_install(args: Record<string, unknown>): Promise<unknown>;
+  skill_uninstall(args: Record<string, unknown>): Promise<unknown>;
+  skill_publish(args: Record<string, unknown>): Promise<unknown>;
+
+  // --- mcp servers ---
+  mcpServer_list(args?: Record<string, unknown>): Promise<unknown>;
+  mcpServer_get(args: { id: string }): Promise<unknown>;
+  mcpServer_create(args: Record<string, unknown>): Promise<unknown>;
+  mcpServer_update(args: Record<string, unknown>): Promise<unknown>;
+  mcpServer_delete(args: { id: string }): Promise<unknown>;
+  mcpServer_install(args: Record<string, unknown>): Promise<unknown>;
+  mcpServer_uninstall(args: Record<string, unknown>): Promise<unknown>;
+
+  // --- pages & metrics ---
+  page_create(args: Record<string, unknown>): Promise<unknown>;
+  metric_create(args: Record<string, unknown>): Promise<unknown>;
+
+  // --- human input ---
+  request_humanInput(args: Record<string, unknown>): Promise<unknown>;
 }
 
 export interface ScriptStdlib {

package/src/be/seed-scripts/catalog/compound-insights.ts

@@ -0,0 +1,188 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  days: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Look back this many days (default 3)"),
+  includeToolUsage: z.boolean().optional().describe("Include tool usage histogram (default true)"),
+  includeScheduleHealth: z
+    .boolean()
+    .optional()
+    .describe("Include schedule health flags (default true)"),
+  includeMemoryHealth: z.boolean().optional().describe("Include memory health stats (default true)"),
+  includeByAgent: z
+    .boolean()
+    .optional()
+    .describe("Include per-agent task/completion/failure breakdown (default true)"),
+});
+
+/**
+ * Failure reasons that are swarm bookkeeping, not real failures. Excluded from
+ * failureClusters, scheduleHealth and byAgent failure counts (Lead Rule #16):
+ * the run engine collapses redundant sibling tasks into these statuses, so
+ * counting them produces phantom failure spikes.
+ */
+const EXCLUDED_FAIL = ["superseded_workflow_task", "cancelled"];
+
+/**
+ * `db_query` returns positional rows (`rows: unknown[][]`) plus a `columns`
+ * array — NOT an array of objects. Zip them back into objects so callers can
+ * read by column name.
+ */
+function rowsToObjects(res: any): any[] {
+  const p = res?.data ?? res;
+  const cols: string[] = p?.columns ?? [];
+  return (p?.rows ?? []).map((r: any) =>
+    Array.isArray(r) ? Object.fromEntries(cols.map((c, i) => [c, r[i]])) : r,
+  );
+}
+
+/**
+ * Daily compounding insights — compressed JSON for Phase 0 evolution.
+ *
+ * Swarm-wide by design: every section aggregates across ALL agents via direct
+ * read-only SQL (no per-agent scoping), so a single call replaces ~25 raw tool
+ * roundtrips. Parametric via `days` + the `include*` flags.
+ */
+export default async function compoundInsights(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args || {});
+  if (!parsed.success) return { error: "invalid args: " + parsed.error.message };
+  const days = parsed.data.days || 3;
+  const includeToolUsage = parsed.data.includeToolUsage !== false;
+  const includeScheduleHealth = parsed.data.includeScheduleHealth !== false;
+  const includeMemoryHealth = parsed.data.includeMemoryHealth !== false;
+  const includeByAgent = parsed.data.includeByAgent !== false;
+
+  // `days` is a validated positive int, so it is safe to interpolate into the
+  // SQLite datetime modifier. EXCLUDED_FAIL is a fixed constant list.
+  const w = `datetime('now','-${days} days')`;
+  const exclList = EXCLUDED_FAIL.map((r) => `'${r}'`).join(",");
+  // A "real" failure = status failed AND not one of the bookkeeping reasons.
+  const realFail = `t.status='failed' AND (t.failureReason IS NULL OR t.failureReason NOT IN (${exclList}))`;
+
+  const insights: any = { days, generatedAt: new Date().toISOString() };
+
+  // Task summary (all agents, direct SQL).
+  const statusRows = rowsToObjects(
+    await ctx.swarm.db_query({
+      sql: `SELECT status, count(*) as cnt FROM agent_tasks t WHERE t.createdAt > ${w} GROUP BY status`,
+    }),
+  );
+  const statusCounts: Record<string, number> = {};
+  let total = 0;
+  for (const r of statusRows) {
+    statusCounts[r.status] = r.cnt;
+    total += r.cnt;
+  }
+  const completed = statusCounts.completed ?? 0;
+  const failed = statusCounts.failed ?? 0;
+  insights.taskSummary = {
+    total,
+    completed,
+    failed,
+    completionRate: total > 0 ? Math.round((completed / total) * 1000) / 10 : 0,
+    failureRate: total > 0 ? Math.round((failed / total) * 1000) / 10 : 0,
+    statusCounts,
+  };
+
+  // Failure clusters (real failures only, normalized to a 60-char lowercased prefix).
+  insights.failureClusters = rowsToObjects(
+    await ctx.swarm.db_query({
+      sql: `SELECT substr(lower(t.failureReason),1,60) as reason, count(*) as count
+            FROM agent_tasks t
+            WHERE ${realFail} AND t.failureReason IS NOT NULL AND t.createdAt > ${w}
+            GROUP BY reason ORDER BY count DESC LIMIT 10`,
+    }),
+  );
+
+  // Schedule health (>= 2 runs, > 20% real-failure rate).
+  if (includeScheduleHealth) {
+    const sh = rowsToObjects(
+      await ctx.swarm.db_query({
+        sql: `SELECT s.name as name, s.id as id, count(t.id) as runs,
+                     sum(case when ${realFail} then 1 else 0 end) as failed
+              FROM scheduled_tasks s
+              JOIN agent_tasks t ON t.scheduleId = s.id
+              WHERE t.createdAt > ${w} AND t.status != 'cancelled'
+              GROUP BY s.id, s.name HAVING runs >= 2`,
+      }),
+    );
+    insights.scheduleHealth = sh
+      .map((r: any) => ({
+        name: r.name,
+        id: r.id,
+        runs: r.runs,
+        failureRate: r.runs > 0 ? Math.round((r.failed / r.runs) * 100) : 0,
+      }))
+      .filter((r: any) => r.failureRate > 20)
+      .sort((a: any, b: any) => b.failureRate - a.failureRate);
+  }
+
+  // Tool usage (top 25). Tool names live inside the `content` JSON of
+  // session_logs (no dedicated column), so extract the name SQL-side: the
+  // `'%"type":"tool_use"%'` filter excludes tool_result rows (which only carry
+  // `tool_use_id`), and instr/substr pull the first tool name per log line.
+  // Approximate: a log line with parallel tool_use blocks counts only its first.
+  if (includeToolUsage) {
+    insights.toolUsage = rowsToObjects(
+      await ctx.swarm.db_query({
+        sql: `WITH tu AS (
+                 SELECT substr(content, instr(content,'"type":"tool_use"')) AS tail
+                 FROM session_logs
+                 WHERE content LIKE '%"type":"tool_use"%' AND createdAt > ${w}
+               ),
+               nm AS (
+                 SELECT substr(tail, instr(tail,'"name":"')+8) AS rest
+                 FROM tu WHERE instr(tail,'"name":"') > 0
+               )
+               SELECT substr(rest,1,instr(rest,'"')-1) AS tool, count(*) AS calls
+               FROM nm GROUP BY tool ORDER BY calls DESC LIMIT 25`,
+      }),
+    ).map((r: any) => ({ tool: r.tool, calls: r.calls }));
+  }
+
+  // Memory health (whole store, by scope + source).
+  if (includeMemoryHealth) {
+    const memRows = rowsToObjects(
+      await ctx.swarm.db_query({
+        sql: `SELECT scope, source, count(*) as cnt FROM agent_memory GROUP BY scope, source`,
+      }),
+    );
+    const totalMem = memRows.reduce((s: number, r: any) => s + (r.cnt ?? 0), 0);
+    insights.memoryHealth = {
+      total: totalMem,
+      byScope: memRows.reduce((m: any, r: any) => {
+        m[r.scope] = (m[r.scope] ?? 0) + r.cnt;
+        return m;
+      }, {}),
+      bySource: memRows.reduce((m: any, r: any) => {
+        m[r.source] = (m[r.source] ?? 0) + r.cnt;
+        return m;
+      }, {}),
+    };
+  }
+
+  // Per-agent breakdown — covers every agent that ran a task in the window.
+  if (includeByAgent) {
+    insights.byAgent = rowsToObjects(
+      await ctx.swarm.db_query({
+        sql: `SELECT a.name as agent, count(*) as total,
+                     sum(case when t.status='completed' then 1 else 0 end) as completed,
+                     sum(case when ${realFail} then 1 else 0 end) as failed
+              FROM agent_tasks t LEFT JOIN agents a ON a.id = t.agentId
+              WHERE t.createdAt > ${w} AND t.agentId IS NOT NULL
+              GROUP BY t.agentId, a.name ORDER BY total DESC LIMIT 30`,
+      }),
+    ).map((r: any) => ({
+      agent: r.agent,
+      total: r.total,
+      completed: r.completed,
+      failed: r.failed,
+    }));
+  }
+
+  return insights;
+}

package/src/be/seed-scripts/catalog/schedule-health.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  days: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Look back this many days (default 7)"),
+  failureThreshold: z
+    .number()
+    .optional()
+    .describe("Flag schedules with failure rate above this (0-1, default 0.2)"),
+});
+
+/** Per-schedule health check: failure rates and flagging unhealthy schedules. */
+export default async function scheduleHealth(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args);
+  if (!parsed.success) return { error: "invalid args: " + parsed.error.message };
+  const days = parsed.data.days || 7;
+  const threshold = parsed.data.failureThreshold ?? 0.2;
+  const since = new Date(Date.now() - days * 86400000).toISOString();
+
+  // Get schedules
+  const schedRes: any = await ctx.swarm.schedule_list({});
+  const schedPayload = schedRes?.data ?? schedRes;
+  const schedules: any[] = schedPayload?.schedules ?? [];
+
+  if (!schedules.length) return { days, schedules: [], flagged: [] };
+
+  // Get recent tasks to correlate with schedules
+  const taskRes: any = await ctx.swarm.task_list({ createdAfter: since, limit: 2000 });
+  const taskPayload = taskRes?.data ?? taskRes;
+  const tasks: any[] = taskPayload?.tasks ?? [];
+
+  // Group by scheduleId
+  const bySchedule = new Map<string, { total: number; failed: number; completed: number }>();
+  for (const t of tasks) {
+    if (!t.scheduleId) continue;
+    const entry = bySchedule.get(t.scheduleId) ?? { total: 0, failed: 0, completed: 0 };
+    entry.total++;
+    if (t.status === "failed") entry.failed++;
+    if (t.status === "completed") entry.completed++;
+    bySchedule.set(t.scheduleId, entry);
+  }
+
+  const results = schedules.map((s: any) => {
+    const stats = bySchedule.get(s.id) ?? { total: 0, failed: 0, completed: 0 };
+    const failureRate = stats.total > 0 ? stats.failed / stats.total : 0;
+    return {
+      id: s.id,
+      name: s.name,
+      enabled: s.enabled,
+      targetAgentId: s.targetAgentId,
+      runs: stats.total,
+      failed: stats.failed,
+      completed: stats.completed,
+      failureRate: Math.round(failureRate * 1000) / 1000,
+      flagged: stats.total >= 3 && failureRate > threshold,
+    };
+  });
+
+  const flagged = results.filter((r: any) => r.flagged);
+
+  return {
+    days,
+    threshold,
+    totalSchedules: schedules.length,
+    flaggedCount: flagged.length,
+    schedules: results.sort((a: any, b: any) => b.failureRate - a.failureRate),
+    flagged,
+  };
+}

package/src/be/seed-scripts/catalog/smart-recall.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  queries: z
+    .array(z.string())
+    .min(1)
+    .describe("One or more search queries to fan out against the memory store"),
+  scope: z
+    .enum(["all", "agent", "swarm"])
+    .optional()
+    .describe("Memory scope filter (default all)"),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Max results per query (default 10)"),
+  dedupThreshold: z
+    .number()
+    .optional()
+    .describe("Similarity threshold for dedup — memories above this are merged (default 0.92)"),
+});
+
+/** Multi-query fan-out memory recall with dedup and composite reranking. */
+export default async function smartRecall(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args);
+  if (!parsed.success) return { error: "invalid args: " + parsed.error.message };
+  const { queries, scope = "all", limit = 10, dedupThreshold = 0.92 } = parsed.data;
+
+  const allResults: any[] = [];
+  for (const q of queries) {
+    const res: any = await ctx.swarm.memory_search({ query: q, limit, scope });
+    const payload = res?.data ?? res;
+    const results = payload?.results ?? [];
+    for (const r of results) {
+      allResults.push({ ...r, querySource: q });
+    }
+  }
+
+  // Dedup by ID, keeping best similarity per memory
+  const seen = new Map<string, any>();
+  const hitCounts = new Map<string, number>();
+  for (const r of allResults) {
+    hitCounts.set(r.id, (hitCounts.get(r.id) ?? 0) + 1);
+    const existing = seen.get(r.id);
+    if (!existing || r.similarity > existing.similarity) {
+      seen.set(r.id, r);
+    }
+  }
+
+  // Composite rerank: bestSimilarity + 0.05 * hitCount
+  const deduped = Array.from(seen.values()).map((r) => ({
+    ...r,
+    hits: hitCounts.get(r.id) ?? 1,
+    compositeScore: r.similarity + 0.05 * (hitCounts.get(r.id) ?? 1),
+  }));
+  deduped.sort((a: any, b: any) => b.compositeScore - a.compositeScore);
+
+  return {
+    queriesRun: queries.length,
+    totalCandidates: allResults.length,
+    uniqueMemories: deduped.length,
+    memories: deduped.slice(0, limit * 2),
+  };
+}

package/src/be/seed-scripts/catalog/tool-usage.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  days: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Look back this many days (default 7)"),
+  agentId: z.string().optional().describe("Filter by agent ID (default: all agents)"),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Top N tools to return (default 20)"),
+});
+
+/** Tool usage histogram from session_logs — top tools by call count. */
+export default async function toolUsage(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args);
+  if (!parsed.success) return { error: "invalid args: " + parsed.error.message };
+  const days = parsed.data.days || 7;
+  const limit = parsed.data.limit || 20;
+  const agentId = parsed.data.agentId;
+
+  const agentFilter = agentId ? `AND agent_id = '${agentId}'` : "";
+  const query = `
+    SELECT tool_name, count(*) as calls
+    FROM session_logs
+    WHERE tool_name IS NOT NULL
+      AND created_at > datetime('now', '-${days} days')
+      ${agentFilter}
+    GROUP BY tool_name
+    ORDER BY calls DESC
+    LIMIT ${limit}
+  `;
+
+  const res: any = await ctx.swarm.db_query({ query });
+  const payload = res?.data ?? res;
+  const rows: any[] = payload?.rows ?? [];
+
+  const totalCalls = rows.reduce((sum: number, r: any) => sum + (r.calls ?? 0), 0);
+
+  return {
+    days,
+    agentId: agentId ?? "all",
+    totalDistinctTools: rows.length,
+    totalCalls,
+    tools: rows.map((r: any) => ({
+      tool: r.tool_name,
+      calls: r.calls,
+      pct: totalCalls > 0 ? Math.round((r.calls / totalCalls) * 1000) / 10 : 0,
+    })),
+  };
+}

package/src/be/seed-scripts/index.ts

@@ -22,6 +22,7 @@ import { getScript, upsertScriptByName } from "../scripts/db";
 import { extractArgsJsonSchema } from "../scripts/extract-schema";
 import { typecheckScript } from "../scripts/typecheck";
 import type { Seeder, SeedItem } from "../seed/types";
+import compoundInsightsSrc from "./catalog/compound-insights.ts" with { type: "text" };
 import dateResolveSrc from "./catalog/date-resolve.ts" with { type: "text" };
 import fetchReadableSrc from "./catalog/fetch-readable.ts" with { type: "text" };
 import ghPrSnapshotSrc from "./catalog/gh-pr-snapshot.ts" with { type: "text" };
@@ -29,9 +30,12 @@ import groupCountSrc from "./catalog/group-count.ts" with { type: "text" };
 import jsonQuerySrc from "./catalog/json-query.ts" with { type: "text" };
 import linearIssueSrc from "./catalog/linear-issue.ts" with { type: "text" };
 import memoryDedupCheckSrc from "./catalog/memory-dedup-check.ts" with { type: "text" };
+import scheduleHealthSrc from "./catalog/schedule-health.ts" with { type: "text" };
 import slackThreadFlattenSrc from "./catalog/slack-thread-flatten.ts" with { type: "text" };
+import smartRecallSrc from "./catalog/smart-recall.ts" with { type: "text" };
 import taskFailureAuditSrc from "./catalog/task-failure-audit.ts" with { type: "text" };
 import textDiffSrc from "./catalog/text-diff.ts" with { type: "text" };
+import toolUsageSrc from "./catalog/tool-usage.ts" with { type: "text" };
 
 export type SeedScript = {
   name: string;
@@ -122,6 +126,38 @@ export const SEED_SCRIPTS: SeedScript[] = [
     intent: "Turn a Slack thread into plain text for summarizing or as task context.",
     source: asText(slackThreadFlattenSrc),
   },
+  {
+    name: "smart-recall",
+    description:
+      "Multi-query fan-out memory search with dedup and composite reranking (bestSimilarity + 0.05 * hitCount). Returns unique memories across all queries.",
+    intent:
+      "Recall relevant memories using multiple search angles — better coverage than a single query. Use for task onboarding, context gathering, or before writing new memories.",
+    source: asText(smartRecallSrc),
+  },
+  {
+    name: "schedule-health",
+    description:
+      "Per-schedule failure rate check over recent tasks — flags schedules with failure rates above a configurable threshold.",
+    intent:
+      "Find unhealthy schedules that keep failing — for daily compounding, reliability reviews, or ops triage.",
+    source: asText(scheduleHealthSrc),
+  },
+  {
+    name: "tool-usage",
+    description:
+      "Tool usage histogram from session_logs — top tools by call count over a time window, optionally filtered by agent.",
+    intent:
+      "See which MCP tools agents use most — for SDK gap analysis, optimization, or daily ops snapshots.",
+    source: asText(toolUsageSrc),
+  },
+  {
+    name: "compound-insights",
+    description:
+      "All-in-one swarm-wide daily ops snapshot: task completion/failure summary, real failure clusters (excludes superseded/cancelled bookkeeping), schedule health flags, tool usage top-25, memory health stats, and a per-agent breakdown. Aggregates across ALL agents via direct read-only SQL.",
+    intent:
+      "Single-call daily compounding Phase 0 helper — replaces ~25 raw tool roundtrips with one compressed JSON result covering every agent. For daily evolution, ops reviews, or heartbeat context.",
+    source: asText(compoundInsightsSrc),
+  },
 ];
 
 /** A catalog entry resolved into a generic {@link SeedItem}. */

package/src/commands/artifact.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { createArtifactServer } from "../artifact-sdk";
 import { getApiKey } from "../utils/api-key";
+import { getMcpBaseUrl } from "../utils/constants";
 
 interface ArtifactArgs {
   additionalArgs: string[];
@@ -139,7 +140,7 @@ async function artifactServe(args: ArtifactArgs) {
 
 async function artifactList() {
   const apiKey = getApiKey();
-  const mcpBaseUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const mcpBaseUrl = getMcpBaseUrl();
   const agentId = process.env.AGENT_ID || "";
 
   try {
@@ -197,7 +198,7 @@ async function artifactStop(args: ArtifactArgs) {
   }
 
   const apiKey = getApiKey();
-  const mcpBaseUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const mcpBaseUrl = getMcpBaseUrl();
   const agentId = process.env.AGENT_ID || "";
 
   // 1. Try to stop PM2 process