maestro-agent 0.0.1 → 0.0.3

package/src/inbox/index.ts

@@ -0,0 +1,500 @@
+import { generateId, getDb, now } from "../core/db";
+import { getWorkflowForTask, listTaskActions, transitionTask, workflowStatusesForProject } from "../workflows";
+import { findProjectExecutionBlocker, isTaskAssignedToAgent } from "../ops/project-serial";
+
+export interface InboxCommandOptions {
+  hubDir: string;
+  agentId?: string;
+}
+
+export interface InboxCommandResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+export async function runInboxCommand(args: string[], opts: InboxCommandOptions): Promise<InboxCommandResult> {
+  const db = getDb(opts.hubDir);
+  const jsonMode = hasFlag(args, "--json");
+  const command = args[0];
+  const agentId = opts.agentId || process.env.MAESTRO_AGENT_ID || "";
+
+  try {
+    if (command === "whoami") {
+      requireAgent(agentId);
+      const agent = db.query("SELECT * FROM agent WHERE id = ?").get(agentId);
+      if (!agent) return fail(`Agent not found: ${agentId}`);
+      return ok(agent, jsonMode, `agent ${agentId}`);
+    }
+
+    if (command === "roles") {
+      const roles = db.query("SELECT * FROM role ORDER BY id ASC").all();
+      return ok(roles, jsonMode, renderRows(roles as any[], "no roles", (role) => `${role.id}\t${role.name}`));
+    }
+
+    if (command === "agents") {
+      const agents = db.query("SELECT * FROM agent ORDER BY status DESC, created_at ASC").all();
+      return ok(agents, jsonMode, renderRows(agents as any[], "no agents", (agent) => `${agent.id}\t${agent.status}\t${agent.name}`));
+    }
+
+    if (command === "tasks") {
+      const mode = args.includes("--mine") ? "mine" : args.includes("--available") ? "available" : args.includes("--watching") ? "watching" : "";
+      const skill = flagValue(args, "--skill");
+      const rows = db.query("SELECT * FROM task ORDER BY priority DESC, created_at ASC").all() as any[];
+      const tasks = rows.filter((task) => {
+        if (mode === "mine") return task.assignee_agent_id === agentId;
+        if (mode === "available") return isOpenTaskAvailableForAgent(db, task, agentId) && skillMatches(task, skill);
+        if (mode === "watching") return isWatchingTask(db, task.id, agentId);
+        return true;
+      });
+      return ok(tasks, jsonMode, renderTaskList(tasks));
+    }
+
+    if (command === "work") {
+      requireAgent(agentId);
+      const skill = flagValue(args, "--skill");
+      const wait = hasFlag(args, "--wait");
+      const interval = Number(flagValue(args, "--interval") || "3000");
+      const timeout = Number(flagValue(args, "--timeout") || "300000");
+
+      const hubUrl = process.env.MAESTRO_HUB_URL;
+
+      // If hub URL available, use long-poll API
+      if (wait && hubUrl) {
+        const deadline = Date.now() + timeout;
+        while (Date.now() < deadline) {
+          const pollTimeout = Math.min(30000, deadline - Date.now());
+          try {
+            const url = `${hubUrl}/api/inbox/poll?agent_id=${encodeURIComponent(agentId)}&timeout=${pollTimeout}${skill ? `&skill=${encodeURIComponent(skill)}` : ""}`;
+            const resp = await fetch(url);
+            if (resp.status === 200) {
+              const task = await resp.json() as any;
+              claimTask(db, task.id, agentId);
+              const claimed = db.query("SELECT * FROM task WHERE id = ?").get(task.id);
+              return ok(claimed, jsonMode, `claimed ${task.id}`);
+            }
+            // 204 = timeout, loop again
+          } catch {
+            // Network error, fallback to sleep
+            await Bun.sleep(interval);
+          }
+        }
+        return ok(null, jsonMode, "timeout");
+      }
+
+      let task = nextAvailableTask(db, skill, agentId);
+      if (!task && wait) {
+        const deadline = Date.now() + timeout;
+        while (!task && Date.now() < deadline) {
+          await Bun.sleep(interval);
+          task = nextAvailableTask(db, skill, agentId);
+        }
+      }
+      if (!task) return ok(null, jsonMode, wait ? "timeout" : "no available task");
+      claimTask(db, task.id, agentId);
+      const claimed = db.query("SELECT * FROM task WHERE id = ?").get(task.id) as any;
+      const workPacket = buildWorkPacket(db, claimed);
+      return ok(workPacket, jsonMode, `claimed ${task.id}`);
+    }
+
+    if (command === "task") {
+      return runTaskCommand(args.slice(1), opts, jsonMode);
+    }
+
+    if (command === "memory") {
+      return runMemoryCommand(args.slice(1), opts, jsonMode);
+    }
+
+    if (command === "notify-user") {
+      requireAgent(agentId);
+      const kind = flagValue(args, "--kind") || "report";
+      const messageBody = flagValue(args, "--body");
+      if (!messageBody) return fail("notify-user requires --body");
+      const id = generateId("msg");
+      const ts = now();
+      db.run(
+        `INSERT INTO inbox_message (id, kind, from_actor, to_actor, subject, body, ref_json, status, created_at)
+         VALUES (?, ?, ?, 'user', ?, ?, ?, 'unread', ?)`,
+        [id, kind, agentId, `Agent ${kind}`, messageBody, JSON.stringify({ agent_id: agentId }), ts],
+      );
+      const row = db.query("SELECT * FROM inbox_message WHERE id = ?").get(id);
+      return ok(row, jsonMode, `notified user: ${kind}`);
+    }
+
+    if (command === "status") {
+      requireAgent(agentId);
+      const assignedTasks = db.query("SELECT * FROM task WHERE assignee_agent_id = ? ORDER BY updated_at DESC").all(agentId) as any[];
+      const currentTask = assignedTasks.find((task) => !isTerminalTask(db, task));
+      const activeSession = db.query("SELECT * FROM session WHERE agent_id = ? AND status = 'running' LIMIT 1").get(agentId);
+      const recentDone = assignedTasks.filter((task) => isDoneTask(db, task)).slice(0, 3);
+      const agent = db.query("SELECT * FROM agent WHERE id = ?").get(agentId) as any;
+      const result = { agent_id: agentId, agent_status: agent?.status, current_task: currentTask, active_session: activeSession, recent_done: recentDone };
+      return ok(result, jsonMode, renderStatus(result));
+    }
+
+    if (command === "heartbeat") {
+      requireAgent(agentId);
+      const ts = now();
+      db.run("UPDATE agent SET last_active_at = ? WHERE id = ?", [ts, agentId]);
+      return ok({ agent_id: agentId, heartbeat_at: ts }, jsonMode, `heartbeat ${agentId}`);
+    }
+
+    if (command === "retire") {
+      requireAgent(agentId);
+      const ts = now();
+      db.run("UPDATE agent SET status = 'offline', last_active_at = ? WHERE id = ?", [ts, agentId]);
+      return ok({ agent_id: agentId, status: "offline" }, jsonMode, `retired ${agentId}`);
+    }
+
+    return fail(`Unknown inbox command: ${command || ""}`);
+  } catch (err: any) {
+    return fail(err.message);
+  }
+}
+
+function runTaskCommand(args: string[], opts: InboxCommandOptions, jsonMode: boolean): InboxCommandResult {
+  const db = getDb(opts.hubDir);
+  const subcommand = args[0];
+  const agentId = opts.agentId || process.env.MAESTRO_AGENT_ID || "agent";
+
+  if (subcommand === "show") {
+    const task = taskWithThread(db, args[1]);
+    if (!task) return fail(`Task not found: ${args[1]}`);
+    return ok(task, jsonMode, renderTask(task));
+  }
+
+  if (subcommand === "claim") {
+    requireAgent(agentId);
+    const taskId = args[1];
+    claimTask(db, taskId, agentId);
+    const task = db.query("SELECT * FROM task WHERE id = ?").get(taskId);
+    return ok(task, jsonMode, `claimed ${taskId}`);
+  }
+
+  if (subcommand === "actions") {
+    const taskId = args[1];
+    if (!taskId) return fail("task actions requires <id>");
+    try {
+      const actions = listTaskActions(db, taskId);
+      return ok(actions, jsonMode, renderTaskActions(actions));
+    } catch (err: any) {
+      return fail(err.message);
+    }
+  }
+
+  if (subcommand === "transition") {
+    const taskId = args[1];
+    const actionId = args[2];
+    if (!taskId || !actionId) return fail("task transition requires <id> <action_id>");
+    const input = collectTransitionInput(args.slice(3));
+    const result = transitionTask(
+      { db, bus: { publish: () => {} } } as any,
+      taskId,
+      actionId,
+      input,
+      { actorId: agentId },
+    );
+    if (!result.ok) return fail(result.error);
+    return ok(result, jsonMode, `transitioned ${taskId} via ${actionId}`);
+  }
+
+  if (subcommand === "progress") {
+    const taskId = args[1];
+    const content = args.slice(2).join(" ");
+    addThreadItem(db, taskId, "status_update", agentId, content);
+    return ok({ task_id: taskId, kind: "status_update", content }, jsonMode, `progress ${taskId}`);
+  }
+
+  if (subcommand === "comment") {
+    const taskId = args[1];
+    const content = args.slice(2).join(" ");
+    addThreadItem(db, taskId, "comment", agentId, content);
+    return ok({ task_id: taskId, kind: "comment", content }, jsonMode, `commented ${taskId}`);
+  }
+
+  if (subcommand === "attach") {
+    const taskId = args[1];
+    const ref = args[2];
+    if (!taskId || !ref) return fail("task attach requires <id> <path|url>");
+    const kind = flagValue(args, "--kind") || "file";
+    const id = generateId("art");
+    const ts = now();
+    const isUrl = /^https?:\/\//.test(ref);
+    db.run(
+      "INSERT INTO artifact (id, task_id, kind, path, url, meta_json, created_at) VALUES (?, ?, ?, ?, ?, '{}', ?)",
+      [id, taskId, kind, isUrl ? null : ref, isUrl ? ref : null, ts],
+    );
+    addThreadItem(db, taskId, "artifact", agentId, ref, id);
+    const artifact = db.query("SELECT * FROM artifact WHERE id = ?").get(id);
+    return ok(artifact, jsonMode, `attached ${ref}`);
+  }
+
+  if (subcommand === "handoff") {
+    const taskId = args[1];
+    const to = flagValue(args, "--to");
+    const reason = flagValue(args, "--reason") || "";
+    if (!taskId || !to) return fail("task handoff requires <id> --to <agent_or_role>");
+    const ts = now();
+    const workflow = getWorkflowForTask(db, taskId);
+    db.run("UPDATE task SET assignee_agent_id = ?, status = ?, updated_at = ? WHERE id = ?", [to, workflow.initial_status, ts, taskId]);
+    addThreadItem(db, taskId, "handoff", agentId, reason, to);
+    const task = db.query("SELECT * FROM task WHERE id = ?").get(taskId);
+    return ok(task, jsonMode, `handoff ${taskId} to ${to}`);
+  }
+
+  if (subcommand === "review") {
+    const taskId = args[1];
+    const reviewBody = flagValue(args, "--body") || args.slice(2).filter(a => !a.startsWith("--")).join(" ");
+    if (!taskId || !reviewBody) return fail("task review requires <id> --body <text>");
+    addThreadItem(db, taskId, "review", agentId, reviewBody);
+    return ok({ task_id: taskId, kind: "review", content: reviewBody }, jsonMode, `reviewed ${taskId}`);
+  }
+
+  if (subcommand === "spawn") {
+    const parentId = flagValue(args, "--parent");
+    const title = flagValue(args, "--title");
+    if (!parentId || !title) return fail("task spawn requires --parent and --title");
+    const parent = db.query("SELECT * FROM task WHERE id = ?").get(parentId) as any;
+    if (!parent) return fail(`Task not found: ${parentId}`);
+    const skill = flagValue(args, "--skill");
+    const id = generateId("task");
+    const ts = now();
+    const lineageDepth = (parent.lineage_depth || 0) + 1;
+    db.run(
+      `INSERT INTO task (id, project_id, parent_task_id, title, description, status, required_capabilities_json, priority, lineage_depth, created_by, created_at, updated_at)
+       VALUES (?, ?, ?, ?, '', ?, ?, 0, ?, ?, ?, ?)`,
+      [id, parent.project_id, parentId, title, workflowStatusesForProject(db, parent.project_id)[0]?.id || "open", JSON.stringify(skill ? [skill] : []), lineageDepth, agentId, ts, ts]
+    );
+    addThreadItem(db, parentId, "spawn_task", agentId, title, id);
+    const task = db.query("SELECT * FROM task WHERE id = ?").get(id);
+    return ok(task, jsonMode, `spawned ${id}`);
+  }
+
+  return fail(`Unknown task command: ${subcommand || ""}`);
+}
+
+function runMemoryCommand(args: string[], opts: InboxCommandOptions, jsonMode: boolean): InboxCommandResult {
+  const db = getDb(opts.hubDir);
+  const subcommand = args[0];
+  const key = args[1];
+  const agentId = opts.agentId || process.env.MAESTRO_AGENT_ID || "";
+  const scope = flagValue(args, "--scope") || "project";
+  const scopeId = resolveMemoryScopeId(db, agentId, scope);
+  if (!key) return fail("memory command requires <key>");
+
+  if (subcommand === "get") {
+    const row = db.query("SELECT * FROM memory WHERE scope = ? AND scope_id = ? AND key = ?").get(scope, scopeId, key);
+    return ok(row || null, jsonMode, row ? `${key}=${(row as any).value}` : "not found");
+  }
+
+  if (subcommand === "set") {
+    const value = args.slice(2).filter((part) => !part.startsWith("--")).join(" ");
+    if (!value) return fail("memory set requires <value>");
+    const id = generateId("mem");
+    const ts = now();
+    db.run(
+      `INSERT INTO memory (id, scope, scope_id, key, value, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(scope, scope_id, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`,
+      [id, scope, scopeId, key, value, ts],
+    );
+    const row = db.query("SELECT * FROM memory WHERE scope = ? AND scope_id = ? AND key = ?").get(scope, scopeId, key);
+    return ok(row, jsonMode, `set ${key}`);
+  }
+
+  return fail(`Unknown memory command: ${subcommand || ""}`);
+}
+
+function buildWorkPacket(db: ReturnType<typeof getDb>, task: any) {
+  const artifacts = db.query("SELECT * FROM artifact WHERE task_id = ? ORDER BY created_at DESC").all(task.id);
+  const dependencies = db.query(
+    "SELECT t.id, t.title, t.status FROM task_dependency d JOIN task t ON t.id = d.depends_on WHERE d.task_id = ?"
+  ).all(task.id);
+  const thread_recent_5 = db.query(
+    "SELECT * FROM task_thread_item WHERE task_id = ? ORDER BY created_at DESC LIMIT 5"
+  ).all(task.id);
+  return {
+    task,
+    done_when: task.acceptance_criteria || "",
+    artifacts,
+    dependencies,
+    thread_recent_5,
+  };
+}
+
+function claimTask(db: ReturnType<typeof getDb>, taskId: string, agentId: string) {
+  const task = db.query("SELECT * FROM task WHERE id = ?").get(taskId) as any;
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  const workflow = getWorkflowForTask(db, taskId);
+  const claimAction = workflow.actions.find((action) => action.id === "claim" && action.from.includes(task.status));
+  if (task.status !== workflow.initial_status && task.assignee_agent_id !== agentId) {
+    throw new Error(`Task is not available: ${taskId}`);
+  }
+  if (!claimAction && task.assignee_agent_id !== agentId) {
+    throw new Error(`No claim action is available from ${task.status}`);
+  }
+  if (task.status === workflow.initial_status) {
+    const blocker = findProjectExecutionBlocker(db, {
+      projectId: task.project_id,
+      excludeTaskId: task.id,
+      claimedStatus: claimAction?.to,
+    });
+    if (blocker) throw new Error(`Project already has active task: ${blocker.id}`);
+  }
+
+  const ts = now();
+  db.run(
+    "UPDATE task SET status = ?, assignee_agent_id = ?, claim_token = ?, updated_at = ? WHERE id = ?",
+    [claimAction?.to || task.status, agentId, crypto.randomUUID().slice(0, 8), ts, taskId]
+  );
+}
+
+function nextAvailableTask(db: ReturnType<typeof getDb>, skill: string | undefined, agentId: string) {
+  const rows = db.query("SELECT * FROM task ORDER BY priority DESC, created_at ASC").all() as any[];
+  return rows.find((task) => {
+    return isOpenTaskAvailableForAgent(db, task, agentId) && skillMatches(task, skill);
+  });
+}
+
+function isOpenTaskAvailableForAgent(db: ReturnType<typeof getDb>, task: any, agentId: string) {
+  const workflow = getWorkflowForTask(db, task.id);
+  if (task.status !== workflow.initial_status) return false;
+  if (!isTaskAssignedToAgent(task, agentId)) return false;
+  const claimAction = workflow.actions.find((action) => action.id === "claim" && action.from.includes(task.status));
+  return !findProjectExecutionBlocker(db, {
+    projectId: task.project_id,
+    excludeTaskId: task.id,
+    claimedStatus: claimAction?.to,
+  });
+}
+
+function taskWithThread(db: ReturnType<typeof getDb>, taskId: string) {
+  const task = db.query("SELECT * FROM task WHERE id = ?").get(taskId) as any;
+  if (!task) return null;
+  const thread = db.query("SELECT * FROM task_thread_item WHERE task_id = ? ORDER BY created_at ASC").all(taskId);
+  return { ...task, thread };
+}
+
+function addThreadItem(
+  db: ReturnType<typeof getDb>,
+  taskId: string,
+  kind: string,
+  author: string,
+  content: string,
+  refId?: string,
+) {
+  const ts = now();
+  db.run(
+    "INSERT INTO task_thread_item (id, task_id, kind, author, content, ref_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+    [generateId("ti"), taskId, kind, author || "agent", content, refId || null, ts]
+  );
+}
+
+function isWatchingTask(db: ReturnType<typeof getDb>, taskId: string, agentId: string) {
+  if (!agentId) return false;
+  const row = db.query("SELECT id FROM task_thread_item WHERE task_id = ? AND author = ? LIMIT 1").get(taskId, agentId);
+  return Boolean(row);
+}
+
+function resolveMemoryScopeId(db: ReturnType<typeof getDb>, agentId: string, scope: string): string {
+  if (scope === "agent") return agentId;
+  const task = db.query("SELECT project_id FROM task WHERE assignee_agent_id = ? ORDER BY updated_at DESC LIMIT 1").get(agentId) as any;
+  if (scope === "workspace") {
+    const projectId = task?.project_id || (db.query("SELECT id FROM project ORDER BY created_at ASC LIMIT 1").get() as any)?.id;
+    return (db.query("SELECT workspace_id FROM project WHERE id = ?").get(projectId) as any)?.workspace_id || "global";
+  }
+  return task?.project_id || (db.query("SELECT id FROM project ORDER BY created_at ASC LIMIT 1").get() as any)?.id || "global";
+}
+
+function skillMatches(task: any, skill?: string) {
+  if (!skill) return true;
+  const requiredCapabilities = JSON.parse(task.required_capabilities_json || "[]");
+  return requiredCapabilities.length === 0 || requiredCapabilities.includes(skill);
+}
+
+function flagValue(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  if (index === -1) return undefined;
+  return args[index + 1];
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+function collectTransitionInput(args: string[]): Record<string, string> {
+  const input: Record<string, string> = {};
+  for (let index = 0; index < args.length; index++) {
+    const part = args[index];
+    if (!part.startsWith("--")) continue;
+    const key = part.slice(2).replace(/-/g, "_");
+    const value = args[index + 1];
+    if (value && !value.startsWith("--")) {
+      input[key] = value;
+      index++;
+    } else {
+      input[key] = "true";
+    }
+  }
+  return input;
+}
+
+function requireAgent(agentId: string) {
+  if (!agentId) throw new Error("Missing agent identity. Set MAESTRO_AGENT_ID.");
+}
+
+function ok(data: unknown, jsonMode: boolean, text: string): InboxCommandResult {
+  return {
+    status: 0,
+    stdout: jsonMode ? `${JSON.stringify(data)}\n` : `${text}\n`,
+    stderr: "",
+  };
+}
+
+function fail(message: string): InboxCommandResult {
+  return { status: 1, stdout: "", stderr: `${message}\n` };
+}
+
+function renderTaskList(tasks: any[]) {
+  if (tasks.length === 0) return "no tasks";
+  return tasks.map((task) => `${task.id}\t${task.status}\t${task.title}`).join("\n");
+}
+
+function renderTask(task: any) {
+  return `${task.id}\t${task.status}\t${task.title}`;
+}
+
+function renderTaskActions(result: any) {
+  if (result.actions.length === 0) return "no actions";
+  return result.actions
+    .map((action: any) => `${action.id}\t${result.status} -> ${action.to}\t${(action.requires || []).join(",")}`)
+    .join("\n");
+}
+
+function renderStatus(result: any) {
+  const lines: string[] = [];
+  lines.push(`agent: ${result.agent_id} (${result.agent_status || "unknown"})`);
+  if (result.current_task) lines.push(`task: ${result.current_task.id}\t${result.current_task.title}`);
+  else lines.push("task: none");
+  if (result.active_session) lines.push(`session: ${result.active_session.id} (running)`);
+  else lines.push("session: none");
+  if (result.recent_done?.length) {
+    lines.push(`done: ${result.recent_done.map((t: any) => t.id).join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+function renderRows(rows: any[], empty: string, render: (row: any) => string) {
+  if (rows.length === 0) return empty;
+  return rows.map(render).join("\n");
+}
+
+function isTerminalTask(db: ReturnType<typeof getDb>, task: any): boolean {
+  const workflow = getWorkflowForTask(db, task.id);
+  return Boolean(workflow.statuses.find((status) => status.id === task.status)?.terminal);
+}
+
+function isDoneTask(db: ReturnType<typeof getDb>, task: any): boolean {
+  const workflow = getWorkflowForTask(db, task.id);
+  return task.status === workflow.done_status;
+}

package/src/ops/artifact-sync.ts

@@ -0,0 +1,65 @@
+import { copyFileSync, existsSync, mkdirSync } from "fs";
+import { join, basename } from "path";
+import type { Database } from "bun:sqlite";
+
+export interface SyncResult {
+  synced: number;
+  failed: number;
+  errors: string[];
+}
+
+export async function syncArtifacts(hubDir: string, db: Database, agentId: string): Promise<SyncResult> {
+  const agent = db.query("SELECT * FROM agent WHERE id = ?").get(agentId) as any;
+  if (!agent) return { synced: 0, failed: 0, errors: ["Agent not found"] };
+
+  const runtime = db.query("SELECT * FROM agent_runtime WHERE id = ?").get(agent.runtime_id) as any;
+  if (!runtime) return { synced: 0, failed: 0, errors: ["Runtime not found"] };
+
+  const artifacts = db.query(
+    "SELECT a.* FROM artifact a JOIN task t ON t.id = a.task_id WHERE t.assignee_agent_id = ? AND a.path IS NOT NULL"
+  ).all(agentId) as any[];
+
+  const destDir = join(hubDir, "artifacts", agentId);
+  mkdirSync(destDir, { recursive: true });
+
+  const result: SyncResult = { synced: 0, failed: 0, errors: [] };
+
+  for (const artifact of artifacts) {
+    try {
+      if (runtime.transport === "local-pty") {
+        // Local: direct copy
+        if (existsSync(artifact.path)) {
+          copyFileSync(artifact.path, join(destDir, basename(artifact.path)));
+          result.synced++;
+        } else {
+          result.errors.push(`File not found: ${artifact.path}`);
+          result.failed++;
+        }
+      } else if (runtime.transport === "ssh" && runtime.target) {
+        // SSH: use scp
+        const dest = join(destDir, basename(artifact.path));
+        const proc = Bun.spawn(["scp", "-o", "StrictHostKeyChecking=no", `${runtime.target}:${artifact.path}`, dest]);
+        const code = await proc.exited;
+        if (code === 0) result.synced++;
+        else { result.failed++; result.errors.push(`scp failed for ${artifact.path}`); }
+      } else if (runtime.transport === "http-api" && artifact.url) {
+        // HTTP: download
+        const resp = await fetch(artifact.url);
+        if (resp.ok) {
+          const buf = await resp.arrayBuffer();
+          const dest = join(destDir, basename(artifact.url));
+          Bun.write(dest, buf);
+          result.synced++;
+        } else {
+          result.failed++;
+          result.errors.push(`HTTP download failed: ${artifact.url}`);
+        }
+      }
+    } catch (err: any) {
+      result.failed++;
+      result.errors.push(err.message);
+    }
+  }
+
+  return result;
+}