@shipers-dev/multi 0.10.0 → 0.11.0

package/dist/index.js

@@ -5696,14 +5696,153 @@ async function ensureWorktree(workingDir, issueKey) {
   return { path: wtPath, branch, created: true };
 }
 
+// src/materializer.ts
+import { mkdirSync as mkdirSync3, existsSync as existsSync3, writeFileSync as writeFileSync3, readFileSync as readFileSync3, rmSync, symlinkSync, lstatSync } from "fs";
+import { join as join3, dirname as dirname2 } from "path";
+var HOME2 = process.env.HOME || process.env.USERPROFILE || ".";
+var MULTI_DIR = join3(HOME2, ".multi");
+var MULTI_SKILLS = join3(MULTI_DIR, "skills");
+var MULTI_AGENTS = join3(MULTI_DIR, "agents");
+var STATE_PATH = join3(MULTI_DIR, "materialized.json");
+var CLAUDE_DIR = join3(HOME2, ".claude");
+var CLAUDE_SKILLS = join3(CLAUDE_DIR, "skills");
+var CLAUDE_AGENTS = join3(CLAUDE_DIR, "agents");
+var MARKER = ".multi-managed";
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "unnamed";
+}
+function loadState() {
+  try {
+    return JSON.parse(readFileSync3(STATE_PATH, "utf8"));
+  } catch {
+    return { revision: -1, skill_slugs: [], agent_slugs: [] };
+  }
+}
+function saveState(s) {
+  mkdirSync3(MULTI_DIR, { recursive: true });
+  writeFileSync3(STATE_PATH, JSON.stringify(s, null, 2));
+}
+function safeRmManaged(path) {
+  if (!existsSync3(path))
+    return;
+  try {
+    const st = lstatSync(path);
+    if (st.isSymbolicLink()) {
+      rmSync(path);
+      return;
+    }
+    if (st.isDirectory() && existsSync3(join3(path, MARKER))) {
+      rmSync(path, { recursive: true, force: true });
+      return;
+    }
+    if (st.isFile() && path.endsWith(".md")) {
+      const head = readFileSync3(path, "utf8").slice(0, 200);
+      if (head.includes("multi-managed: true"))
+        rmSync(path);
+    }
+  } catch {}
+}
+function writeManagedSkill(slug, skill) {
+  const dir = join3(MULTI_SKILLS, slug);
+  mkdirSync3(dir, { recursive: true });
+  writeFileSync3(join3(dir, MARKER), `skill_id=${skill.id}
+revision=${Date.now()}
+`);
+  if (skill.body)
+    writeFileSync3(join3(dir, "SKILL.md"), skill.body);
+  for (const f of skill.files || []) {
+    if (f.path.includes("..") || f.path.startsWith("/"))
+      continue;
+    if (f.path === MARKER)
+      continue;
+    const out = join3(dir, f.path);
+    mkdirSync3(dirname2(out), { recursive: true });
+    writeFileSync3(out, f.content);
+  }
+  mkdirSync3(CLAUDE_SKILLS, { recursive: true });
+  const link = join3(CLAUDE_SKILLS, slug);
+  safeRmManaged(link);
+  if (!existsSync3(link)) {
+    try {
+      symlinkSync(dir, link, "dir");
+    } catch {}
+  }
+}
+function writeManagedAgent(slug, agent, skillsForAgent) {
+  if (agent.type !== "claude-code")
+    return;
+  mkdirSync3(CLAUDE_AGENTS, { recursive: true });
+  const out = join3(CLAUDE_AGENTS, `${slug}.md`);
+  safeRmManaged(out);
+  const tools = agent.allowed_tools ? `
+tools: ${agent.allowed_tools}` : "";
+  const skillsLine = skillsForAgent.length ? `
+skills: [${skillsForAgent.join(", ")}]` : "";
+  const fm = `---
+name: ${agent.name}
+description: managed by multi-agent (id=${agent.id})${tools}${skillsLine}
+multi-managed: true
+---
+
+`;
+  writeFileSync3(out, fm + (agent.prompt || ""));
+}
+async function materializeBundle(apiUrl, deviceId, log) {
+  const res = await apiClient.get(`${apiUrl}/api/devices/${deviceId}/agent_bundle`);
+  if (!res.success || !res.data) {
+    log(`materialize: bundle fetch failed: ${res.error || "unknown"}`);
+    return null;
+  }
+  const bundle = res.data;
+  const prev = loadState();
+  const linksByAgent = new Map;
+  for (const l of bundle.links) {
+    if (!linksByAgent.has(l.agent_id))
+      linksByAgent.set(l.agent_id, []);
+    linksByAgent.get(l.agent_id).push(l.skill_id);
+  }
+  const newSkillSlugs = [];
+  const skillIdToSlug = new Map;
+  for (const s of bundle.skills) {
+    const slug = slugify(s.name);
+    skillIdToSlug.set(s.id, slug);
+    writeManagedSkill(slug, s);
+    newSkillSlugs.push(slug);
+  }
+  const newAgentSlugs = [];
+  for (const a of bundle.agents) {
+    const slug = slugify(a.name);
+    const skillSlugs = (linksByAgent.get(a.id) || []).map((id) => skillIdToSlug.get(id)).filter(Boolean);
+    writeManagedAgent(slug, a, skillSlugs);
+    newAgentSlugs.push(slug);
+  }
+  for (const old of prev.skill_slugs) {
+    if (!newSkillSlugs.includes(old)) {
+      safeRmManaged(join3(MULTI_SKILLS, old));
+      safeRmManaged(join3(CLAUDE_SKILLS, old));
+    }
+  }
+  for (const old of prev.agent_slugs) {
+    if (!newAgentSlugs.includes(old)) {
+      safeRmManaged(join3(CLAUDE_AGENTS, `${old}.md`));
+    }
+  }
+  saveState({ revision: bundle.revision, skill_slugs: newSkillSlugs, agent_slugs: newAgentSlugs });
+  log(`materialize: revision=${bundle.revision} agents=${bundle.agents.length} skills=${bundle.skills.length}`);
+  return { revision: bundle.revision };
+}
+function lastMaterializedRevision() {
+  return loadState().revision;
+}
+
 // src/index.ts
 import { parseArgs } from "util";
-import { mkdirSync as mkdirSync3, existsSync as existsSync3, writeFileSync as writeFileSync3, readFileSync as readFileSync3, appendFileSync as appendFileSync2, unlinkSync, readdirSync, statSync } from "fs";
-import { join as join3, dirname as dirname2 } from "path";
+import { mkdirSync as mkdirSync4, existsSync as existsSync4, writeFileSync as writeFileSync4, readFileSync as readFileSync4, appendFileSync as appendFileSync2, unlinkSync, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join4, dirname as dirname3 } from "path";
 // package.json
 var package_default = {
   name: "@shipers-dev/multi",
-  version: "0.10.0",
+  version: "0.11.0",
   type: "module",
   bin: {
     "multi-agent": "./dist/index.js"
@@ -5719,15 +5858,15 @@ var package_default = {
 };
 
 // src/index.ts
-var HOME2 = process.env.HOME || process.env.USERPROFILE || ".";
-var MULTI_DIR = join3(HOME2, ".multi");
-var CONFIG_PATH = join3(MULTI_DIR, "config.json");
-var PID_PATH = join3(MULTI_DIR, "agent.pid");
-var PORT_PATH = join3(MULTI_DIR, "agent.port");
-var LOG_PATH2 = join3(MULTI_DIR, "logs", "agent.log");
-var SKILLS_DIR = join3(MULTI_DIR, "skills");
-var STOP_PATH = join3(MULTI_DIR, "stop.flag");
-var TASKS_DB_PATH = join3(MULTI_DIR, "tasks.db");
+var HOME3 = process.env.HOME || process.env.USERPROFILE || ".";
+var MULTI_DIR2 = join4(HOME3, ".multi");
+var CONFIG_PATH = join4(MULTI_DIR2, "config.json");
+var PID_PATH = join4(MULTI_DIR2, "agent.pid");
+var PORT_PATH = join4(MULTI_DIR2, "agent.port");
+var LOG_PATH2 = join4(MULTI_DIR2, "logs", "agent.log");
+var SKILLS_DIR = join4(MULTI_DIR2, "skills");
+var STOP_PATH = join4(MULTI_DIR2, "stop.flag");
+var TASKS_DB_PATH = join4(MULTI_DIR2, "tasks.db");
 var VERSION = package_default.version;
 var COMMANDS = {
   setup: "Register this device with a workspace",
@@ -5740,9 +5879,9 @@ var COMMANDS = {
   reset: "Reset acpx session for an issue (--issue <id>)"
 };
 function ensureDirs() {
-  for (const d of [MULTI_DIR, join3(MULTI_DIR, "logs"), SKILLS_DIR]) {
-    if (!existsSync3(d))
-      mkdirSync3(d, { recursive: true });
+  for (const d of [MULTI_DIR2, join4(MULTI_DIR2, "logs"), SKILLS_DIR]) {
+    if (!existsSync4(d))
+      mkdirSync4(d, { recursive: true });
   }
 }
 function log(msg) {
@@ -5912,23 +6051,16 @@ async function cmdSetup(name, apiUrl) {
   const workspaceId = dev.data?.workspace_id;
   if (workspaceId) {
     saveConfig({ deviceId: approved.device_id, token: approved.token, dispatchSecret: approved.dispatch_secret, workspaceId, apiUrl });
-    await syncSkills(apiUrl, workspaceId);
+    try {
+      await materializeBundle(apiUrl, approved.device_id, (m) => console.log(`   ${m}`));
+    } catch (e) {
+      console.log(`   materialize failed: ${String(e)}`);
+    }
   }
   console.log(`
 Next: link to an agent with: multi-agent link --agent <agentId>`);
   console.log("Then: multi-agent connect");
 }
-async function syncSkills(apiUrl, workspaceId) {
-  const res = await apiClient.get(`${apiUrl}/api/skills?workspace_id=${workspaceId}`);
-  if (!res.success || !Array.isArray(res.data))
-    return;
-  ensureDirs();
-  for (const skill of res.data) {
-    writeFileSync3(join3(SKILLS_DIR, `${skill.name}.json`), JSON.stringify(skill, null, 2));
-  }
-  if (res.data.length)
-    console.log(`   Synced ${res.data.length} skill(s) \u2192 ${SKILLS_DIR}`);
-}
 async function cmdLink(apiUrl, config, agentId) {
   if (!config.deviceId) {
     console.log('\u274C Not registered. Run "multi-agent setup" first.');
@@ -5954,8 +6086,8 @@ async function cmdConnect(apiUrl, config) {
     console.log('\u274C Missing dispatch secret. Re-pair via "multi-agent setup".');
     process.exit(1);
   }
-  if (existsSync3(PID_PATH)) {
-    const pid = Number(readFileSync3(PID_PATH, "utf8").trim());
+  if (existsSync4(PID_PATH)) {
+    const pid = Number(readFileSync4(PID_PATH, "utf8").trim());
     if (pid && isRunning(pid)) {
       console.log(`\u274C Daemon already running (pid ${pid}).`);
       process.exit(1);
@@ -5963,8 +6095,8 @@ async function cmdConnect(apiUrl, config) {
     unlinkSync(PID_PATH);
   }
   ensureDirs();
-  writeFileSync3(PID_PATH, String(process.pid));
-  if (existsSync3(STOP_PATH))
+  writeFileSync4(PID_PATH, String(process.pid));
+  if (existsSync4(STOP_PATH))
     unlinkSync(STOP_PATH);
   const detected = await detectAgents();
   log(`\uD83D\uDE80 Starting daemon for device ${config.deviceId} (pid ${process.pid})`);
@@ -6145,7 +6277,7 @@ async function cmdConnect(apiUrl, config) {
   });
   log(`\uD83C\uDF10 Local server: http://127.0.0.1:${port}`);
   try {
-    writeFileSync3(PORT_PATH, String(port));
+    writeFileSync4(PORT_PATH, String(port));
   } catch {}
   let tunnel = await startTunnel(port);
   if (!tunnel) {
@@ -6158,6 +6290,16 @@ async function cmdConnect(apiUrl, config) {
   log(`\u2601\uFE0F  Tunnel up: ${tunnel.url}`);
   const heartbeat = async () => {
     const res = await apiClient.post(`${apiUrl}/api/devices/${config.deviceId}/heartbeat`, { status: "online", tunnel_url: tunnel?.url });
+    if (res.success && res.data) {
+      const remoteRev = Number(res.data.agent_skill_revision ?? 0);
+      if (remoteRev > 0 && remoteRev !== lastMaterializedRevision()) {
+        try {
+          await materializeBundle(apiUrl, config.deviceId, log);
+        } catch (e) {
+          log(`materialize error: ${String(e)}`);
+        }
+      }
+    }
     return res.success && res.data?.pending_dispatches || 0;
   };
   {
@@ -6181,11 +6323,11 @@ async function cmdConnect(apiUrl, config) {
     try {
       await apiClient.post(`${apiUrl}/api/devices/${config.deviceId}/heartbeat`, { status: "offline", tunnel_url: null });
     } catch {}
-    if (existsSync3(PID_PATH))
+    if (existsSync4(PID_PATH))
       unlinkSync(PID_PATH);
-    if (existsSync3(STOP_PATH))
+    if (existsSync4(STOP_PATH))
       unlinkSync(STOP_PATH);
-    if (existsSync3(PORT_PATH))
+    if (existsSync4(PORT_PATH))
       unlinkSync(PORT_PATH);
     db.close();
     log("\uD83D\uDC4B Disconnected");
@@ -6194,30 +6336,38 @@ async function cmdConnect(apiUrl, config) {
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   schedule();
+  let restarting = false;
   const restartTunnel = async (reason) => {
-    if (!alive)
+    if (!alive || restarting)
       return;
-    log(`\uD83D\uDD01 Restarting tunnel (${reason})`);
+    restarting = true;
     try {
-      tunnel?.child.kill();
-    } catch {}
-    for (let attempt = 1;alive; attempt++) {
-      const next = await startTunnel(port);
-      if (next) {
-        tunnel = next;
-        log(`\u2601\uFE0F  Tunnel up: ${tunnel.url}`);
-        try {
-          const pending = await heartbeat();
-          if (pending > 0)
-            drainOfflineDispatches(apiUrl, config.deviceId, config.dispatchSecret, db, () => schedule());
-        } catch (e) {
-          log(`heartbeat error after tunnel restart: ${String(e)}`);
+      log(`\uD83D\uDD01 Restarting tunnel (${reason})`);
+      const old = tunnel;
+      tunnel = null;
+      try {
+        old?.child.kill();
+      } catch {}
+      for (let attempt = 1;alive; attempt++) {
+        const next = await startTunnel(port);
+        if (next) {
+          tunnel = next;
+          log(`\u2601\uFE0F  Tunnel up: ${tunnel.url}`);
+          try {
+            const pending = await heartbeat();
+            if (pending > 0)
+              drainOfflineDispatches(apiUrl, config.deviceId, config.dispatchSecret, db, () => schedule());
+          } catch (e) {
+            log(`heartbeat error after tunnel restart: ${String(e)}`);
+          }
+          return;
         }
-        return;
+        const wait = Math.min(30000, 2000 * attempt);
+        log(`tunnel restart failed, retry in ${wait}ms`);
+        await sleep(wait);
       }
-      const wait = Math.min(30000, 2000 * attempt);
-      log(`tunnel restart failed, retry in ${wait}ms`);
-      await sleep(wait);
+    } finally {
+      restarting = false;
     }
   };
   (async () => {
@@ -6239,7 +6389,7 @@ async function cmdConnect(apiUrl, config) {
   const PROBE_EVERY = 6;
   while (alive) {
     await sleep(20000);
-    if (existsSync3(STOP_PATH)) {
+    if (existsSync4(STOP_PATH)) {
       await shutdown("stop flag");
       break;
     }
@@ -6295,8 +6445,8 @@ async function probeTunnel(url) {
   }
 }
 async function cmdConnectDetached(apiUrl) {
-  if (existsSync3(PID_PATH)) {
-    const pid = Number(readFileSync3(PID_PATH, "utf8").trim());
+  if (existsSync4(PID_PATH)) {
+    const pid = Number(readFileSync4(PID_PATH, "utf8").trim());
     if (pid && isRunning(pid)) {
       console.log(`\u274C Daemon already running (pid ${pid}).`);
       process.exit(1);
@@ -6370,7 +6520,7 @@ async function markStopped(apiUrl, issueId, reason) {
 async function handleRunTask(apiUrl, deviceId, task, detected, ctx) {
   const issueId = task.issue_id;
   const isFollowup = !!task.followup;
-  const baseWorkingDir = task.working_dir && existsSync3(task.working_dir) ? task.working_dir : undefined;
+  const baseWorkingDir = task.working_dir && existsSync4(task.working_dir) ? task.working_dir : undefined;
   let workingDir = baseWorkingDir;
   let worktreeBranch = "";
   if (baseWorkingDir) {
@@ -6388,13 +6538,13 @@ async function handleRunTask(apiUrl, deviceId, task, detected, ctx) {
   await postStream(apiUrl, issueId, "progress", { message: `Device ${deviceId} picked up ${isFollowup ? "follow-up" : "task"}` });
   let attachmentRefs = [];
   if (task.from_comment_id) {
-    const baseDir = workingDir || join3(MULTI_DIR, "tmp", issueId);
-    const inDir = join3(baseDir, ".multi-in", task.from_comment_id);
+    const baseDir = workingDir || join4(MULTI_DIR2, "tmp", issueId);
+    const inDir = join4(baseDir, ".multi-in", task.from_comment_id);
     attachmentRefs = await downloadCommentAttachments(apiUrl, task.from_comment_id, inDir);
     if (attachmentRefs.length)
       log(`  fetched ${attachmentRefs.length} attachment(s) \u2192 ${inDir}`);
   }
-  const outDir = join3(workingDir || join3(MULTI_DIR, "tmp", issueId), ".multi-out");
+  const outDir = join4(workingDir || join4(MULTI_DIR2, "tmp", issueId), ".multi-out");
   let liveCommentId;
   let liveBody = "";
   let hadError = false;
@@ -6891,11 +7041,11 @@ You are acting on a sub-issue spawned by another agent. You MAY emit a \`multi-p
       }
     }
   } catch {}
-  return `# Planning & delegation
+  return `# Planning, delegation, and self-service
 
-After finishing your reply, you may append ONE fenced block to create child issues, update any issue in this project, or delegate to another agent. The daemon parses this block and executes the actions after your turn.
+After finishing your reply, you may append ONE fenced \`multi-plan\` block. The daemon parses it and executes after your turn.
 
-Syntax:
+Issue actions:
 
 \`\`\`multi-plan
 {"actions":[
@@ -6905,14 +7055,26 @@ Syntax:
 ]}
 \`\`\`
 
+Agent + skill self-service (use sparingly \u2014 only when you genuinely need a new capability that isn't covered by an existing agent or skill):
+
+\`\`\`multi-plan
+{"actions":[
+  {"type":"agent.create","name":"refactor-bot","agent_type":"claude-code","prompt":"You refactor TS code...","skill_ids":["sk_xxx"],"allowed_tools":["Read","Edit","Bash"]},
+  {"type":"agent.update","id":"ag_xxx","prompt":"new prompt..."},
+  {"type":"skill.create","name":"run-tests","description":"Run the test suite","body":"---\\nname: run-tests\\n---\\n\\n# Run tests\\n..."},
+  {"type":"skill.attach","agent_id":"ag_xxx","skill_id":"sk_yyy"},
+  {"type":"skill.detach","agent_id":"ag_xxx","skill_id":"sk_yyy"}
+]}
+\`\`\`
+
 Rules:
-- Omit the block entirely if no actions are needed.
-- Max 10 actions per turn; additional actions are dropped.
-- Planning depth is capped at ${PLANNING_DEPTH_LIMIT}: descendants beyond that depth may only \`update\` their own issue.
-- \`create\` defaults \`project_id\` to the current project and \`parent_id\` to the current issue.
-- \`update\` may change title, description, status (todo/in_progress/done/failed), priority, assignee_type, assignee_id.
-- \`delegate\` is shorthand for reassigning and resetting status to todo.
-- Only target issues in the current project (${projectId || "this project"}).
+- Omit the block if no actions are needed.
+- Max 10 actions per turn. Sub-caps: agent.create=2, skill.create=3 per turn.
+- Planning depth capped at ${PLANNING_DEPTH_LIMIT}. At depth \u2265 1 you can only \`update\` your own issue \u2014 no creates, no agents, no skills.
+- \`agent.create\` produces an agent in **pending** status. A human must approve it before any issue can be dispatched to it.
+- \`skill.create\` ALWAYS waits for human review (skill bodies become future system prompts).
+- \`allowed_tools\` on a new agent must be a subset of your own tools.
+- \`create\` / \`update\` / \`delegate\` target issues only in the current project (${projectId || "this project"}).
 
 ${agentsBlock ? `Available agents you can delegate to:
 ${agentsBlock}
@@ -6946,11 +7108,24 @@ async function executePlanActions(apiUrl, parentTask, actions, ctx) {
   }
   const depth = typeof parentTask.planning_depth === "number" ? parentTask.planning_depth : 0;
   if (depth >= PLANNING_DEPTH_LIMIT) {
-    const blocked = actions.filter((a) => a.type === "create" || a.type === "delegate").length;
+    const blocked = actions.filter((a) => a.type !== "update").length;
     actions = actions.filter((a) => a.type === "update");
     if (blocked)
-      lines.push(`- \u26A0 ${blocked} create/delegate action(s) blocked (planning depth limit ${PLANNING_DEPTH_LIMIT})`);
-  }
+      lines.push(`- \u26A0 ${blocked} non-update action(s) blocked (planning depth limit ${PLANNING_DEPTH_LIMIT})`);
+  }
+  const SUBCAPS = { "agent.create": 2, "skill.create": 3, "skill.attach": 5, "skill.detach": 5, "agent.update": 5 };
+  const counts = {};
+  actions = actions.filter((a) => {
+    const cap = SUBCAPS[a.type];
+    if (cap === undefined)
+      return true;
+    counts[a.type] = (counts[a.type] || 0) + 1;
+    if (counts[a.type] > cap) {
+      lines.push(`- \u26A0 ${a.type} sub-cap ${cap} hit, dropping extra`);
+      return false;
+    }
+    return true;
+  });
   const parentId = parentTask.issue_id;
   const parentProjectId = await (async () => {
     try {
@@ -6960,7 +7135,7 @@ async function executePlanActions(apiUrl, parentTask, actions, ctx) {
       return null;
     }
   })();
-  const headers = { "x-agent-id": parentTask.agent_id };
+  const headers = { "x-agent-id": parentTask.agent_id, "x-origin-issue-id": parentTask.issue_id };
   if (typeof ctx.refreshLocalAgents === "function") {
     try {
       await ctx.refreshLocalAgents();
@@ -7000,6 +7175,44 @@ async function executePlanActions(apiUrl, parentTask, actions, ctx) {
           continue;
         }
         lines.push(`- \u2713 delegated ${res.data.key} \u2192 ${a.assignee_id}`);
+      } else if (a.type === "agent.create") {
+        const res = await apiClient.post(`${apiUrl}/api/agent_ops/agents/mutate`, { action: "create", name: a.name, type: a.agent_type, prompt: a.prompt, skill_ids: a.skill_ids, allowed_tools: a.allowed_tools }, { headers });
+        if (!res.success) {
+          lines.push(`- \u274C agent.create "${a.name}": ${res.error || res.status}`);
+          continue;
+        }
+        if (res.data?.queued)
+          lines.push(`- \u23F3 agent.create "${a.name}" queued for human approval (op ${res.data.pending_op_id})`);
+        else
+          lines.push(`- \u2713 agent.create "${a.name}" \u2192 ${res.data?.agent_id} (status=pending \u2014 needs human approval before dispatch)`);
+      } else if (a.type === "agent.update") {
+        const res = await apiClient.post(`${apiUrl}/api/agent_ops/agents/mutate`, { action: "update", ...a }, { headers });
+        if (!res.success) {
+          lines.push(`- \u274C agent.update ${a.id}: ${res.error || res.status}`);
+          continue;
+        }
+        if (res.data?.queued)
+          lines.push(`- \u23F3 agent.update ${a.id} queued`);
+        else
+          lines.push(`- \u2713 agent.update ${a.id}`);
+      } else if (a.type === "skill.create") {
+        const res = await apiClient.post(`${apiUrl}/api/agent_ops/skills/mutate`, { action: "create", name: a.name, version: a.version, description: a.description, body: a.body, files: a.files }, { headers });
+        if (!res.success) {
+          lines.push(`- \u274C skill.create "${a.name}": ${res.error || res.status}`);
+          continue;
+        }
+        lines.push(`- \u23F3 skill.create "${a.name}" queued for human review (op ${res.data?.pending_op_id})`);
+      } else if (a.type === "skill.attach" || a.type === "skill.detach") {
+        const action = a.type === "skill.attach" ? "attach_skill" : "detach_skill";
+        const res = await apiClient.post(`${apiUrl}/api/agent_ops/agents/mutate`, { action, agent_id: a.agent_id, skill_id: a.skill_id }, { headers });
+        if (!res.success) {
+          lines.push(`- \u274C ${a.type} ${a.skill_id}\u2192${a.agent_id}: ${res.error || res.status}`);
+          continue;
+        }
+        if (res.data?.queued)
+          lines.push(`- \u23F3 ${a.type} queued`);
+        else
+          lines.push(`- \u2713 ${a.type} ${a.skill_id} \u2194 ${a.agent_id}`);
       }
     } catch (e) {
       lines.push(`- \u274C ${a.type} failed: ${String(e)}`);
@@ -7054,25 +7267,25 @@ function statusIcon(status) {
   }
 }
 async function resolveAcpAdapter(agentType, detectedPath) {
-  if (agentType === "pi" && detectedPath && existsSync3(detectedPath)) {
+  if (agentType === "pi" && detectedPath && existsSync4(detectedPath)) {
     return [detectedPath, "--mode", "rpc"];
   }
   const adapterName = "claude-code-acp";
   const candidates = [
-    join3(HOME2, ".bun", "install", "global", "node_modules", ".bin", adapterName)
+    join4(HOME3, ".bun", "install", "global", "node_modules", ".bin", adapterName)
   ];
   try {
     const here = new URL(import.meta.url).pathname;
     let dir = here;
     for (let i = 0;i < 8; i++) {
-      dir = dirname2(dir);
-      const bin = join3(dir, "node_modules", ".bin", adapterName);
-      if (existsSync3(bin))
+      dir = dirname3(dir);
+      const bin = join4(dir, "node_modules", ".bin", adapterName);
+      if (existsSync4(bin))
         return [bin];
     }
   } catch {}
   for (const c of candidates)
-    if (existsSync3(c))
+    if (existsSync4(c))
       return [c];
   return null;
 }
@@ -7124,7 +7337,7 @@ async function postStream(apiUrl, issueId, event_type, payload) {
   try {
     ensureDirs();
     const date = new Date().toISOString().slice(0, 10);
-    const path = join3(MULTI_DIR, "logs", `events-${date}.ndjson`);
+    const path = join4(MULTI_DIR2, "logs", `events-${date}.ndjson`);
     appendFileSync2(path, JSON.stringify({ ts: Date.now(), issue_id: issueId, event_type, payload }) + `
 `);
   } catch {}
@@ -7136,7 +7349,7 @@ async function downloadCommentAttachments(apiUrl, commentId, destDir) {
     const items = list.data?.results || list.data || [];
     if (!Array.isArray(items) || items.length === 0)
       return [];
-    mkdirSync3(destDir, { recursive: true });
+    mkdirSync4(destDir, { recursive: true });
     const token = authTokenHeader();
     const out = [];
     for (const it of items) {
@@ -7145,8 +7358,8 @@ async function downloadCommentAttachments(apiUrl, commentId, destDir) {
         continue;
       const buf = new Uint8Array(await res.arrayBuffer());
       const safe = it.filename.replace(/[^A-Za-z0-9._-]/g, "_");
-      const p = join3(destDir, safe);
-      writeFileSync3(p, buf);
+      const p = join4(destDir, safe);
+      writeFileSync4(p, buf);
       out.push({ filename: it.filename, path: p });
     }
     return out;
@@ -7159,16 +7372,16 @@ function authTokenHeader() {
   return cfg.token ? `Bearer ${cfg.token}` : null;
 }
 async function uploadOutputDir(apiUrl, commentId, dir) {
-  if (!existsSync3(dir))
+  if (!existsSync4(dir))
     return 0;
   const files = [];
   const walk = (d, depth = 0) => {
     if (depth > 3)
       return;
-    for (const name of readdirSync(d)) {
-      const p = join3(d, name);
+    for (const name of readdirSync2(d)) {
+      const p = join4(d, name);
       try {
-        const st = statSync(p);
+        const st = statSync2(p);
         if (st.isDirectory())
           walk(p, depth + 1);
         else if (st.isFile())
@@ -7183,7 +7396,7 @@ async function uploadOutputDir(apiUrl, commentId, dir) {
   let uploaded = 0;
   for (const f of files) {
     try {
-      const data = readFileSync3(f);
+      const data = readFileSync4(f);
       const form = new FormData;
       const blob = new Blob([data]);
       form.append("file", blob, f.split("/").pop() || "file");
@@ -7410,7 +7623,7 @@ async function cmdStatus(apiUrl, config) {
     process.exit(1);
   }
   const d = res.data;
-  const pid = existsSync3(PID_PATH) ? readFileSync3(PID_PATH, "utf8").trim() : null;
+  const pid = existsSync4(PID_PATH) ? readFileSync4(PID_PATH, "utf8").trim() : null;
   const daemon = pid && isRunning(Number(pid)) ? `running (pid ${pid})` : "stopped";
   console.log(`
 Device Status
@@ -7424,18 +7637,18 @@ Daemon:    ${daemon}
 `);
 }
 async function cmdStop() {
-  if (!existsSync3(PID_PATH)) {
+  if (!existsSync4(PID_PATH)) {
     console.log("No daemon running.");
     return;
   }
-  const pid = Number(readFileSync3(PID_PATH, "utf8").trim());
+  const pid = Number(readFileSync4(PID_PATH, "utf8").trim());
   if (!pid || !isRunning(pid)) {
     unlinkSync(PID_PATH);
     console.log("Cleaned stale pidfile.");
     return;
   }
   ensureDirs();
-  writeFileSync3(STOP_PATH, "1");
+  writeFileSync4(STOP_PATH, "1");
   try {
     process.kill(pid, "SIGTERM");
     console.log(`Sent SIGTERM to ${pid}`);
@@ -7446,11 +7659,11 @@ async function cmdReset(issueId) {
     console.error("Usage: multi-agent reset --issue <issue_id>");
     process.exit(2);
   }
-  if (!existsSync3(PORT_PATH)) {
+  if (!existsSync4(PORT_PATH)) {
     console.error("Daemon not running (no port file).");
     process.exit(1);
   }
-  const port = Number(readFileSync3(PORT_PATH, "utf8").trim());
+  const port = Number(readFileSync4(PORT_PATH, "utf8").trim());
   const config = loadConfig();
   if (!config.dispatchSecret) {
     console.error("No dispatchSecret in config \u2014 run `multi-agent setup` first.");
@@ -7469,11 +7682,11 @@ async function cmdReset(issueId) {
   console.log(body);
 }
 async function cmdRestart(apiUrl) {
-  if (existsSync3(PID_PATH)) {
-    const pid = Number(readFileSync3(PID_PATH, "utf8").trim());
+  if (existsSync4(PID_PATH)) {
+    const pid = Number(readFileSync4(PID_PATH, "utf8").trim());
     if (pid && isRunning(pid)) {
       ensureDirs();
-      writeFileSync3(STOP_PATH, "1");
+      writeFileSync4(STOP_PATH, "1");
       try {
         process.kill(pid, "SIGTERM");
       } catch {}
@@ -7489,12 +7702,12 @@ async function cmdRestart(apiUrl) {
       }
     }
     try {
-      if (existsSync3(PID_PATH))
+      if (existsSync4(PID_PATH))
         unlinkSync(PID_PATH);
     } catch {}
   }
   try {
-    if (existsSync3(STOP_PATH))
+    if (existsSync4(STOP_PATH))
       unlinkSync(STOP_PATH);
   } catch {}
   console.log("\uD83D\uDD04 Relaunching daemon...");
@@ -7513,11 +7726,11 @@ async function cmdRestart(apiUrl) {
   process.exit(0);
 }
 async function cmdLogs() {
-  if (!existsSync3(LOG_PATH2)) {
+  if (!existsSync4(LOG_PATH2)) {
     console.log("No logs yet.");
     return;
   }
-  const content = readFileSync3(LOG_PATH2, "utf8");
+  const content = readFileSync4(LOG_PATH2, "utf8");
   console.log(content.split(`
 `).slice(-100).join(`
 `));
@@ -7563,16 +7776,16 @@ function openTasksDb() {
 }
 function loadConfig() {
   try {
-    if (!existsSync3(CONFIG_PATH))
+    if (!existsSync4(CONFIG_PATH))
       return {};
-    return JSON.parse(readFileSync3(CONFIG_PATH, "utf8"));
+    return JSON.parse(readFileSync4(CONFIG_PATH, "utf8"));
   } catch {
     return {};
   }
 }
 function saveConfig(config) {
   ensureDirs();
-  writeFileSync3(CONFIG_PATH, JSON.stringify(config, null, 2));
+  writeFileSync4(CONFIG_PATH, JSON.stringify(config, null, 2));
 }
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipers-dev/multi",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "bin": {
     "multi-agent": "./dist/index.js"

package/src/index.ts

@@ -6,6 +6,7 @@ import { Database } from 'bun:sqlite';
 import { runAcp } from './acp-runner';
 import { runAcpx } from './acpx-runner';
 import { ensureWorktree } from './worktree';
+import { materializeBundle, lastMaterializedRevision } from './materializer';
 import { parseArgs } from 'util';
 import { mkdirSync, existsSync, writeFileSync, readFileSync, appendFileSync, unlinkSync, readdirSync, statSync } from 'fs';
 import { join, dirname } from 'path';
@@ -204,22 +205,12 @@ async function cmdSetup(name?: string, apiUrl?: string) {
   const workspaceId = dev.data?.workspace_id;
   if (workspaceId) {
     saveConfig({ deviceId: approved.device_id, token: approved.token, dispatchSecret: approved.dispatch_secret, workspaceId, apiUrl });
-    await syncSkills(apiUrl!, workspaceId);
+    try { await materializeBundle(apiUrl!, approved.device_id, (m) => console.log(`   ${m}`)); } catch (e) { console.log(`   materialize failed: ${String(e)}`); }
   }
   console.log('\nNext: link to an agent with: multi-agent link --agent <agentId>');
   console.log('Then: multi-agent connect');
 }
 
-async function syncSkills(apiUrl: string, workspaceId: string) {
-  const res = await apiClient.get<any[]>(`${apiUrl}/api/skills?workspace_id=${workspaceId}`);
-  if (!res.success || !Array.isArray(res.data)) return;
-  ensureDirs();
-  for (const skill of res.data) {
-    writeFileSync(join(SKILLS_DIR, `${skill.name}.json`), JSON.stringify(skill, null, 2));
-  }
-  if (res.data.length) console.log(`   Synced ${res.data.length} skill(s) → ${SKILLS_DIR}`);
-}
-
 async function cmdLink(apiUrl: string, config: Config, agentId?: string) {
   if (!config.deviceId) {
     console.log('❌ Not registered. Run "multi-agent setup" first.');
@@ -447,7 +438,14 @@ async function cmdConnect(apiUrl: string, config: Config) {
   log(`☁️  Tunnel up: ${tunnel.url}`);
 
   const heartbeat = async (): Promise<number> => {
-    const res = await apiClient.post<{ pending_dispatches?: number }>(`${apiUrl}/api/devices/${config.deviceId}/heartbeat`, { status: 'online', tunnel_url: tunnel?.url });
+    const res = await apiClient.post<{ pending_dispatches?: number; agent_skill_revision?: number }>(`${apiUrl}/api/devices/${config.deviceId}/heartbeat`, { status: 'online', tunnel_url: tunnel?.url });
+    if (res.success && res.data) {
+      const remoteRev = Number(res.data.agent_skill_revision ?? 0);
+      if (remoteRev > 0 && remoteRev !== lastMaterializedRevision()) {
+        try { await materializeBundle(apiUrl, config.deviceId!, log); }
+        catch (e) { log(`materialize error: ${String(e)}`); }
+      }
+    }
     return (res.success && res.data?.pending_dispatches) || 0;
   };
   {
@@ -481,27 +479,36 @@ async function cmdConnect(apiUrl: string, config: Config) {
   schedule();
 
   // Tunnel self-heal: relaunch cloudflared if child exits or DNS stops resolving.
+  // `restarting` guards against two entries racing (probe-failure + exit-watcher
+  // both firing when we kill the child as part of our own restart).
+  let restarting = false;
   const restartTunnel = async (reason: string) => {
-    if (!alive) return;
-    log(`🔁 Restarting tunnel (${reason})`);
-    try { tunnel?.child.kill(); } catch {}
-    // Small backoff so we don't spam cloudflared edge under prolonged outage.
-    for (let attempt = 1; alive; attempt++) {
-      const next = await startTunnel(port);
-      if (next) {
-        tunnel = next;
-        log(`☁️  Tunnel up: ${tunnel.url}`);
-        try {
-          const pending = await heartbeat();
-          if (pending > 0) void drainOfflineDispatches(apiUrl, config.deviceId!, config.dispatchSecret!, db, () => schedule());
-        } catch (e) {
-          log(`heartbeat error after tunnel restart: ${String(e)}`);
+    if (!alive || restarting) return;
+    restarting = true;
+    try {
+      log(`🔁 Restarting tunnel (${reason})`);
+      const old = tunnel;
+      tunnel = null; // null first so the exit-watcher's `tunnel === t` check skips our own kill
+      try { old?.child.kill(); } catch {}
+      for (let attempt = 1; alive; attempt++) {
+        const next = await startTunnel(port);
+        if (next) {
+          tunnel = next;
+          log(`☁️  Tunnel up: ${tunnel.url}`);
+          try {
+            const pending = await heartbeat();
+            if (pending > 0) void drainOfflineDispatches(apiUrl, config.deviceId!, config.dispatchSecret!, db, () => schedule());
+          } catch (e) {
+            log(`heartbeat error after tunnel restart: ${String(e)}`);
+          }
+          return;
         }
-        return;
+        const wait = Math.min(30000, 2000 * attempt);
+        log(`tunnel restart failed, retry in ${wait}ms`);
+        await sleep(wait);
       }
-      const wait = Math.min(30000, 2000 * attempt);
-      log(`tunnel restart failed, retry in ${wait}ms`);
-      await sleep(wait);
+    } finally {
+      restarting = false;
     }
   };
 
@@ -512,6 +519,7 @@ async function cmdConnect(apiUrl: string, config: Config) {
       if (!t) { await sleep(1000); continue; }
       const code = await t.child.exited;
       if (!alive) return;
+      // If `tunnel` was nulled by restartTunnel, we killed it ourselves — skip.
       if (tunnel === t) await restartTunnel(`cloudflared exited code=${code}`);
     }
   })();
@@ -1092,11 +1100,11 @@ You are acting on a sub-issue spawned by another agent. You MAY emit a \`multi-p
     }
   } catch {}
 
-  return `# Planning & delegation
+  return `# Planning, delegation, and self-service
 
-After finishing your reply, you may append ONE fenced block to create child issues, update any issue in this project, or delegate to another agent. The daemon parses this block and executes the actions after your turn.
+After finishing your reply, you may append ONE fenced \`multi-plan\` block. The daemon parses it and executes after your turn.
 
-Syntax:
+Issue actions:
 
 \`\`\`multi-plan
 {"actions":[
@@ -1106,14 +1114,26 @@ Syntax:
 ]}
 \`\`\`
 
+Agent + skill self-service (use sparingly — only when you genuinely need a new capability that isn't covered by an existing agent or skill):
+
+\`\`\`multi-plan
+{"actions":[
+  {"type":"agent.create","name":"refactor-bot","agent_type":"claude-code","prompt":"You refactor TS code...","skill_ids":["sk_xxx"],"allowed_tools":["Read","Edit","Bash"]},
+  {"type":"agent.update","id":"ag_xxx","prompt":"new prompt..."},
+  {"type":"skill.create","name":"run-tests","description":"Run the test suite","body":"---\\nname: run-tests\\n---\\n\\n# Run tests\\n..."},
+  {"type":"skill.attach","agent_id":"ag_xxx","skill_id":"sk_yyy"},
+  {"type":"skill.detach","agent_id":"ag_xxx","skill_id":"sk_yyy"}
+]}
+\`\`\`
+
 Rules:
-- Omit the block entirely if no actions are needed.
-- Max 10 actions per turn; additional actions are dropped.
-- Planning depth is capped at ${PLANNING_DEPTH_LIMIT}: descendants beyond that depth may only \`update\` their own issue.
-- \`create\` defaults \`project_id\` to the current project and \`parent_id\` to the current issue.
-- \`update\` may change title, description, status (todo/in_progress/done/failed), priority, assignee_type, assignee_id.
-- \`delegate\` is shorthand for reassigning and resetting status to todo.
-- Only target issues in the current project (${projectId || 'this project'}).
+- Omit the block if no actions are needed.
+- Max 10 actions per turn. Sub-caps: agent.create=2, skill.create=3 per turn.
+- Planning depth capped at ${PLANNING_DEPTH_LIMIT}. At depth ≥ 1 you can only \`update\` your own issue — no creates, no agents, no skills.
+- \`agent.create\` produces an agent in **pending** status. A human must approve it before any issue can be dispatched to it.
+- \`skill.create\` ALWAYS waits for human review (skill bodies become future system prompts).
+- \`allowed_tools\` on a new agent must be a subset of your own tools.
+- \`create\` / \`update\` / \`delegate\` target issues only in the current project (${projectId || 'this project'}).
 
 ${agentsBlock ? `Available agents you can delegate to:\n${agentsBlock}\n` : ''}`;
 }
@@ -1121,7 +1141,12 @@ ${agentsBlock ? `Available agents you can delegate to:\n${agentsBlock}\n` : ''}`
 type PlanAction =
   | { type: 'create'; project_id?: string; title: string; description?: string; priority?: string; assignee_type?: string; assignee_id?: string; parent_id?: string }
   | { type: 'update'; id: string; title?: string; description?: string; status?: string; priority?: string; assignee_type?: string; assignee_id?: string }
-  | { type: 'delegate'; id: string; assignee_id: string };
+  | { type: 'delegate'; id: string; assignee_id: string }
+  | { type: 'agent.create'; name: string; agent_type: string; prompt?: string; skill_ids?: string[]; allowed_tools?: string[] }
+  | { type: 'agent.update'; id: string; name?: string; prompt?: string | null; allowed_tools?: string[] | null }
+  | { type: 'skill.create'; name: string; version?: string; description?: string; body: string; files?: { path: string; content: string }[] }
+  | { type: 'skill.attach'; agent_id: string; skill_id: string }
+  | { type: 'skill.detach'; agent_id: string; skill_id: string };
 
 // Extract JSON action blocks fenced as ```multi-plan ... ```
 function extractPlanActions(text: string): PlanAction[] {
@@ -1153,10 +1178,23 @@ async function executePlanActions(apiUrl: string, parentTask: any, actions: Plan
   // `planning_depth` is carried on each dispatched task (set server-side from issue row).
   const depth = typeof parentTask.planning_depth === 'number' ? parentTask.planning_depth : 0;
   if (depth >= PLANNING_DEPTH_LIMIT) {
-    const blocked = actions.filter(a => a.type === 'create' || a.type === 'delegate').length;
+    const blocked = actions.filter(a => a.type !== 'update').length;
     actions = actions.filter(a => a.type === 'update');
-    if (blocked) lines.push(`- ⚠ ${blocked} create/delegate action(s) blocked (planning depth limit ${PLANNING_DEPTH_LIMIT})`);
+    if (blocked) lines.push(`- ⚠ ${blocked} non-update action(s) blocked (planning depth limit ${PLANNING_DEPTH_LIMIT})`);
   }
+  // Sub-caps: agent/skill creation is rare, prevent runaway turns.
+  const SUBCAPS = { 'agent.create': 2, 'skill.create': 3, 'skill.attach': 5, 'skill.detach': 5, 'agent.update': 5 } as Record<string, number>;
+  const counts: Record<string, number> = {};
+  actions = actions.filter(a => {
+    const cap = SUBCAPS[a.type];
+    if (cap === undefined) return true;
+    counts[a.type] = (counts[a.type] || 0) + 1;
+    if (counts[a.type] > cap) {
+      lines.push(`- ⚠ ${a.type} sub-cap ${cap} hit, dropping extra`);
+      return false;
+    }
+    return true;
+  });
   const parentId = parentTask.issue_id;
   const parentProjectId = await (async () => {
     try {
@@ -1164,7 +1202,7 @@ async function executePlanActions(apiUrl: string, parentTask: any, actions: Plan
       return r.data?.project_id;
     } catch { return null; }
   })();
-  const headers = { 'x-agent-id': parentTask.agent_id };
+  const headers: Record<string, string> = { 'x-agent-id': parentTask.agent_id, 'x-origin-issue-id': parentTask.issue_id };
 
   // Refresh the set of agents linked to this device once per plan execution.
   if (typeof ctx.refreshLocalAgents === 'function') {
@@ -1193,6 +1231,26 @@ async function executePlanActions(apiUrl: string, parentTask: any, actions: Plan
         const res = await apiClient.post<any>(`${apiUrl}/api/issues/agent/mutate`, { action: 'update', id: a.id, assignee_type: 'agent', assignee_id: a.assignee_id, status: 'todo' }, { headers });
         if (!res.success) { lines.push(`- ❌ delegate ${a.id}: ${res.error || res.status}`); continue; }
         lines.push(`- ✓ delegated ${res.data.key} → ${a.assignee_id}`);
+      } else if (a.type === 'agent.create') {
+        const res = await apiClient.post<any>(`${apiUrl}/api/agent_ops/agents/mutate`, { action: 'create', name: a.name, type: a.agent_type, prompt: a.prompt, skill_ids: a.skill_ids, allowed_tools: a.allowed_tools }, { headers });
+        if (!res.success) { lines.push(`- ❌ agent.create "${a.name}": ${res.error || res.status}`); continue; }
+        if (res.data?.queued) lines.push(`- ⏳ agent.create "${a.name}" queued for human approval (op ${res.data.pending_op_id})`);
+        else lines.push(`- ✓ agent.create "${a.name}" → ${res.data?.agent_id} (status=pending — needs human approval before dispatch)`);
+      } else if (a.type === 'agent.update') {
+        const res = await apiClient.post<any>(`${apiUrl}/api/agent_ops/agents/mutate`, { action: 'update', ...a }, { headers });
+        if (!res.success) { lines.push(`- ❌ agent.update ${a.id}: ${res.error || res.status}`); continue; }
+        if (res.data?.queued) lines.push(`- ⏳ agent.update ${a.id} queued`);
+        else lines.push(`- ✓ agent.update ${a.id}`);
+      } else if (a.type === 'skill.create') {
+        const res = await apiClient.post<any>(`${apiUrl}/api/agent_ops/skills/mutate`, { action: 'create', name: a.name, version: a.version, description: a.description, body: a.body, files: a.files }, { headers });
+        if (!res.success) { lines.push(`- ❌ skill.create "${a.name}": ${res.error || res.status}`); continue; }
+        lines.push(`- ⏳ skill.create "${a.name}" queued for human review (op ${res.data?.pending_op_id})`);
+      } else if (a.type === 'skill.attach' || a.type === 'skill.detach') {
+        const action = a.type === 'skill.attach' ? 'attach_skill' : 'detach_skill';
+        const res = await apiClient.post<any>(`${apiUrl}/api/agent_ops/agents/mutate`, { action, agent_id: a.agent_id, skill_id: a.skill_id }, { headers });
+        if (!res.success) { lines.push(`- ❌ ${a.type} ${a.skill_id}→${a.agent_id}: ${res.error || res.status}`); continue; }
+        if (res.data?.queued) lines.push(`- ⏳ ${a.type} queued`);
+        else lines.push(`- ✓ ${a.type} ${a.skill_id} ↔ ${a.agent_id}`);
       }
     } catch (e) {
       lines.push(`- ❌ ${a.type} failed: ${String(e)}`);

package/src/materializer.ts

@@ -0,0 +1,166 @@
+// Materialize agents + skills onto disk so claude-code (and the agent itself
+// via Read/Bash) can load them. Pulls /api/devices/:id/agent_bundle on demand
+// (heartbeat revision mismatch), writes to ~/.multi/skills/<slug>/ and ~/.multi/agents/,
+// then symlinks/copies into ~/.claude/{skills,agents} marked with .multi-managed
+// so we never clobber a user-authored skill or agent definition.
+
+import { mkdirSync, existsSync, writeFileSync, readFileSync, rmSync, symlinkSync, readdirSync, statSync, lstatSync } from 'fs';
+import { join, dirname } from 'path';
+import { apiClient } from './client';
+
+const HOME = process.env.HOME || process.env.USERPROFILE || '.';
+const MULTI_DIR = join(HOME, '.multi');
+const MULTI_SKILLS = join(MULTI_DIR, 'skills');
+const MULTI_AGENTS = join(MULTI_DIR, 'agents');
+const STATE_PATH = join(MULTI_DIR, 'materialized.json');
+const CLAUDE_DIR = join(HOME, '.claude');
+const CLAUDE_SKILLS = join(CLAUDE_DIR, 'skills');
+const CLAUDE_AGENTS = join(CLAUDE_DIR, 'agents');
+const MARKER = '.multi-managed';
+
+type BundleSkill = {
+  id: string;
+  name: string;
+  version: string | null;
+  description: string | null;
+  body: string | null;
+  files: { path: string; content: string }[];
+};
+
+type BundleAgent = {
+  id: string;
+  name: string;
+  type: string;
+  prompt: string | null;
+  approval_status: string;
+  allowed_tools: string | null;
+};
+
+type Bundle = {
+  revision: number;
+  agents: BundleAgent[];
+  skills: BundleSkill[];
+  links: { agent_id: string; skill_id: string }[];
+};
+
+type State = {
+  revision: number;
+  skill_slugs: string[];
+  agent_slugs: string[];
+};
+
+function slugify(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64) || 'unnamed';
+}
+
+function loadState(): State {
+  try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')); }
+  catch { return { revision: -1, skill_slugs: [], agent_slugs: [] }; }
+}
+
+function saveState(s: State) {
+  mkdirSync(MULTI_DIR, { recursive: true });
+  writeFileSync(STATE_PATH, JSON.stringify(s, null, 2));
+}
+
+function safeRmManaged(path: string) {
+  if (!existsSync(path)) return;
+  try {
+    const st = lstatSync(path);
+    if (st.isSymbolicLink()) { rmSync(path); return; }
+    if (st.isDirectory() && existsSync(join(path, MARKER))) {
+      rmSync(path, { recursive: true, force: true });
+      return;
+    }
+    if (st.isFile() && path.endsWith('.md')) {
+      const head = readFileSync(path, 'utf8').slice(0, 200);
+      if (head.includes('multi-managed: true')) rmSync(path);
+    }
+  } catch {}
+}
+
+function writeManagedSkill(slug: string, skill: BundleSkill) {
+  const dir = join(MULTI_SKILLS, slug);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, MARKER), `skill_id=${skill.id}\nrevision=${Date.now()}\n`);
+  if (skill.body) writeFileSync(join(dir, 'SKILL.md'), skill.body);
+  for (const f of skill.files || []) {
+    if (f.path.includes('..') || f.path.startsWith('/')) continue; // path traversal guard
+    if (f.path === MARKER) continue;
+    const out = join(dir, f.path);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, f.content);
+  }
+  // Symlink into ~/.claude/skills/<slug>; replace any prior managed link/dir.
+  mkdirSync(CLAUDE_SKILLS, { recursive: true });
+  const link = join(CLAUDE_SKILLS, slug);
+  safeRmManaged(link);
+  if (!existsSync(link)) {
+    try { symlinkSync(dir, link, 'dir'); } catch {}
+  }
+}
+
+function writeManagedAgent(slug: string, agent: BundleAgent, skillsForAgent: string[]) {
+  if (agent.type !== 'claude-code') return; // acpx agents don't read ~/.claude/agents
+  mkdirSync(CLAUDE_AGENTS, { recursive: true });
+  const out = join(CLAUDE_AGENTS, `${slug}.md`);
+  safeRmManaged(out);
+  const tools = agent.allowed_tools ? `\ntools: ${agent.allowed_tools}` : '';
+  const skillsLine = skillsForAgent.length ? `\nskills: [${skillsForAgent.join(', ')}]` : '';
+  const fm = `---\nname: ${agent.name}\ndescription: managed by multi-agent (id=${agent.id})${tools}${skillsLine}\nmulti-managed: true\n---\n\n`;
+  writeFileSync(out, fm + (agent.prompt || ''));
+}
+
+export async function materializeBundle(apiUrl: string, deviceId: string, log: (m: string) => void): Promise<{ revision: number } | null> {
+  const res = await apiClient.get<Bundle>(`${apiUrl}/api/devices/${deviceId}/agent_bundle`);
+  if (!res.success || !res.data) {
+    log(`materialize: bundle fetch failed: ${res.error || 'unknown'}`);
+    return null;
+  }
+  const bundle = res.data;
+  const prev = loadState();
+
+  const linksByAgent = new Map<string, string[]>();
+  for (const l of bundle.links) {
+    if (!linksByAgent.has(l.agent_id)) linksByAgent.set(l.agent_id, []);
+    linksByAgent.get(l.agent_id)!.push(l.skill_id);
+  }
+
+  const newSkillSlugs: string[] = [];
+  const skillIdToSlug = new Map<string, string>();
+  for (const s of bundle.skills) {
+    const slug = slugify(s.name);
+    skillIdToSlug.set(s.id, slug);
+    writeManagedSkill(slug, s);
+    newSkillSlugs.push(slug);
+  }
+
+  const newAgentSlugs: string[] = [];
+  for (const a of bundle.agents) {
+    const slug = slugify(a.name);
+    const skillSlugs = (linksByAgent.get(a.id) || []).map(id => skillIdToSlug.get(id)).filter(Boolean) as string[];
+    writeManagedAgent(slug, a, skillSlugs);
+    newAgentSlugs.push(slug);
+  }
+
+  // Prune managed entries no longer in bundle.
+  for (const old of prev.skill_slugs) {
+    if (!newSkillSlugs.includes(old)) {
+      safeRmManaged(join(MULTI_SKILLS, old));
+      safeRmManaged(join(CLAUDE_SKILLS, old));
+    }
+  }
+  for (const old of prev.agent_slugs) {
+    if (!newAgentSlugs.includes(old)) {
+      safeRmManaged(join(CLAUDE_AGENTS, `${old}.md`));
+    }
+  }
+
+  saveState({ revision: bundle.revision, skill_slugs: newSkillSlugs, agent_slugs: newAgentSlugs });
+  log(`materialize: revision=${bundle.revision} agents=${bundle.agents.length} skills=${bundle.skills.length}`);
+  return { revision: bundle.revision };
+}
+
+export function lastMaterializedRevision(): number {
+  return loadState().revision;
+}