@shipers-dev/multi 0.6.7 → 0.7.0

package/dist/index.js

@@ -96,8 +96,8 @@ async function request(url, options) {
 }
 var apiClient = {
   get: (url) => request(url),
-  post: (url, body) => request(url, { method: "POST", body: JSON.stringify(body) }),
-  patch: (url, body) => request(url, { method: "PATCH", body: JSON.stringify(body) }),
+  post: (url, body, opts) => request(url, { method: "POST", body: JSON.stringify(body), headers: opts?.headers }),
+  patch: (url, body, opts) => request(url, { method: "PATCH", body: JSON.stringify(body), headers: opts?.headers }),
   delete: (url) => request(url, { method: "DELETE" })
 };
 
@@ -5199,6 +5199,7 @@ async function runAcp(opts) {
   const stream2 = ndJsonStream(output, input);
   let activeSessionId = opts.sessionId || null;
   let recording = false;
+  let chunkCount = 0;
   const alwaysAllow = new Set;
   const client = {
     async sessionUpdate(params) {
@@ -5263,12 +5264,33 @@ async function runAcp(opts) {
       }
     }
     recording = true;
-    const res = await conn.prompt({
-      sessionId: activeSessionId,
-      prompt: [{ type: "text", text: opts.prompt }]
-    });
-    await opts.onEvent({ event_type: "result", payload: { stopReason: res.stopReason } });
-    return { stopReason: res.stopReason, sessionId: activeSessionId };
+    const runPrompt = async () => {
+      chunkCount = 0;
+      return await conn.prompt({
+        sessionId: activeSessionId,
+        prompt: [{ type: "text", text: opts.prompt }]
+      });
+    };
+    let res = await runPrompt();
+    let stopReason = res.stopReason;
+    if (chunkCount === 0 && opts.sessionId) {
+      await opts.onEvent({ event_type: "progress", payload: { message: `resumed session produced no output (stopReason=${stopReason}); retrying with fresh session` } });
+      try {
+        const fresh = await conn.newSession({ cwd: opts.cwd || process.cwd(), mcpServers: [] });
+        activeSessionId = fresh.sessionId;
+        if (opts.onSession)
+          await opts.onSession(fresh.sessionId);
+        res = await runPrompt();
+        stopReason = res.stopReason;
+      } catch (e) {
+        await opts.onEvent({ event_type: "error", payload: { message: `retry with fresh session failed: ${String(e)}` } });
+      }
+    }
+    if (chunkCount === 0) {
+      await opts.onEvent({ event_type: "error", payload: { message: `agent produced no output (stopReason=${stopReason})` } });
+    }
+    await opts.onEvent({ event_type: "result", payload: { stopReason } });
+    return { stopReason, sessionId: activeSessionId };
   } finally {
     try {
       child.kill();
@@ -5281,12 +5303,15 @@ async function runAcp(opts) {
       case "agent_message_chunk":
       case "agent_thought_chunk": {
         const text = extractText(u.content);
-        if (text)
+        if (text) {
+          chunkCount++;
           await o.onEvent({ event_type: "assistant_text", payload: { text } });
+        }
         break;
       }
       case "tool_call":
       case "tool_call_update": {
+        chunkCount++;
         await o.onEvent({ event_type: "tool_call", payload: {
           id: u.toolCallId || u.id,
           tool: u.title || u.toolName || "tool",
@@ -5574,7 +5599,7 @@ var LOG_PATH2 = join2(MULTI_DIR, "logs", "agent.log");
 var SKILLS_DIR = join2(MULTI_DIR, "skills");
 var STOP_PATH = join2(MULTI_DIR, "stop.flag");
 var TASKS_DB_PATH = join2(MULTI_DIR, "tasks.db");
-var VERSION = "0.6.7";
+var VERSION = "0.7.0";
 var COMMANDS = {
   setup: "Register this device with a workspace",
   connect: "Connect device to realtime hub and execute assigned tasks",
@@ -5813,6 +5838,26 @@ async function cmdConnect(apiUrl, config) {
       workerWake = null;
     } catch {}
   };
+  const localAgentIds = new Set;
+  const refreshLocalAgents = async () => {
+    try {
+      const res = await apiClient.get(`${apiUrl}/api/devices/${config.deviceId}/agents`);
+      const rows = res.data?.results || res.data || [];
+      if (Array.isArray(rows)) {
+        localAgentIds.clear();
+        for (const a of rows)
+          if (a?.id)
+            localAgentIds.add(a.id);
+      }
+    } catch {}
+  };
+  await refreshLocalAgents();
+  const enqueueLocal = (task) => {
+    const taskId = task?.issue_id ? `${task.issue_id}-${Date.now()}` : crypto.randomUUID();
+    db.run("INSERT INTO tasks (id, status, payload) VALUES (?, ?, ?)", [taskId, "pending", JSON.stringify(task)]);
+    notifyWorker();
+    return taskId;
+  };
   const port = await pickFreePort();
   const expectedAuth = `Bearer ${config.dispatchSecret}`;
   const server = Bun.serve({
@@ -5897,7 +5942,7 @@ async function cmdConnect(apiUrl, config) {
       db.run("UPDATE tasks SET status = 'running', started_at = unixepoch(), attempts = attempts + 1 WHERE id = ?", [row.id]);
       try {
         const task = JSON.parse(row.payload);
-        await handleRunTask(apiUrl, config.deviceId, task, detected);
+        await handleRunTask(apiUrl, config.deviceId, task, detected, { localAgentIds, enqueueLocal, refreshLocalAgents });
         db.run("UPDATE tasks SET status = 'done', finished_at = unixepoch() WHERE id = ?", [row.id]);
       } catch (e) {
         log(`task ${row.id} error: ${String(e)}`);
@@ -5977,7 +6022,7 @@ async function parseTunnelUrl(stream2) {
   }
   return null;
 }
-async function handleRunTask(apiUrl, deviceId, task, detected) {
+async function handleRunTask(apiUrl, deviceId, task, detected, ctx) {
   const issueId = task.issue_id;
   const isFollowup = !!task.followup;
   const workingDir = task.working_dir && existsSync2(task.working_dir) ? task.working_dir : undefined;
@@ -6283,6 +6328,7 @@ ${body}
       } catch (e) {
         log(`preamble fetch failed: ${String(e)}`);
       }
+      preamble += await buildPlanningPreamble(apiUrl, task);
       const prompt = preamble ? `${preamble}
 ---
 
@@ -6342,6 +6388,7 @@ ${body}
           }
         }
       } catch {}
+      preamble += await buildPlanningPreamble(apiUrl, task);
       const base = `${task.title}
 
 ${task.description || ""}`.trim();
@@ -6395,6 +6442,24 @@ ${userPart}` : userPart;
       if (n > 0)
         log(`  \uD83D\uDCCE uploaded ${n} output file(s)`);
     }
+    if (ctx) {
+      const fullText = turn.blocks.filter((b) => b.kind === "text").map((b) => b.text).join(`
+`);
+      const actions = extractPlanActions(fullText);
+      if (actions.length) {
+        const summary = await executePlanActions(apiUrl, task, actions, ctx);
+        if (summary) {
+          try {
+            await apiClient.post(`${apiUrl}/api/issues/${issueId}/comments`, { author_type: "agent", author_id: task.agent_id, author_name: "agent", body: summary });
+          } catch {}
+        }
+      }
+    }
+    if (!hasAssistantText && !hadError) {
+      const stopReason = turn.result?.stopReason || "unknown";
+      await postComment(`\u26A0\uFE0F Agent returned no output (stopReason=${stopReason}). Adapter may be stuck on a stale session \u2014 try starting a new issue or clearing session_id.`);
+      log(`  \u26A0 ${task.key} produced no assistant output (stopReason=${stopReason})`);
+    }
     if (hadError) {
       await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {});
       log(`  \u2717 ${task.key} failed`);
@@ -6409,6 +6474,180 @@ ${userPart}` : userPart;
     log(`  \u2717 ${task.key} failed: ${String(e)}`);
   }
 }
+async function buildPlanningPreamble(apiUrl, task) {
+  const depth = typeof task.planning_depth === "number" ? task.planning_depth : 0;
+  if (depth >= 1) {
+    return `# Planning (sub-task context)
+
+You are acting on a sub-issue spawned by another agent. You MAY emit a \`multi-plan\` block to update your own issue's status (e.g. mark done/failed) but CANNOT create child issues or delegate further.
+
+\`\`\`multi-plan
+{"actions":[{"type":"update","id":"<this issue id>","status":"done"}]}
+\`\`\`
+
+`;
+  }
+  let projectId = "";
+  let agentsBlock = "";
+  try {
+    const issueRes = await apiClient.get(`${apiUrl}/api/issues/${task.issue_id}`);
+    projectId = issueRes.data?.project_id || "";
+    const agentRes = await apiClient.get(`${apiUrl}/api/agents/${task.agent_id}`);
+    const workspaceId = agentRes.data?.workspace_id;
+    if (workspaceId) {
+      const ag = await apiClient.get(`${apiUrl}/api/agents?workspace_id=${workspaceId}`);
+      const list = Array.isArray(ag.data) ? ag.data : [];
+      const others = list.filter((a) => a.id !== task.agent_id);
+      if (others.length) {
+        agentsBlock = others.map((a) => `- \`${a.id}\` (${a.name}${a.type ? `, ${a.type}` : ""})`).join(`
+`);
+      }
+    }
+  } catch {}
+  return `# Planning & delegation
+
+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.
+
+Syntax:
+
+\`\`\`multi-plan
+{"actions":[
+  {"type":"create","title":"...","description":"...","assignee_type":"agent","assignee_id":"<agent id>"},
+  {"type":"update","id":"<issue id>","status":"done"},
+  {"type":"delegate","id":"<issue id>","assignee_id":"<agent id>"}
+]}
+\`\`\`
+
+Rules:
+- Omit the block entirely if no actions are needed.
+- Max 10 actions per turn; additional actions are dropped.
+- Sub-issues spawned from your plan run one-shot: they cannot themselves spawn further children (only \`update\` allowed there).
+- \`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"}).
+
+${agentsBlock ? `Available agents you can delegate to:
+${agentsBlock}
+` : ""}`;
+}
+function extractPlanActions(text) {
+  const out = [];
+  if (!text)
+    return out;
+  const re = /```multi-plan\s*\n([\s\S]*?)\n```/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    try {
+      const parsed = JSON.parse(m[1]);
+      const actions = Array.isArray(parsed?.actions) ? parsed.actions : Array.isArray(parsed) ? parsed : [parsed];
+      for (const a of actions)
+        if (a && typeof a === "object" && typeof a.type === "string")
+          out.push(a);
+    } catch {}
+  }
+  return out;
+}
+var PLAN_ACTION_LIMIT = 10;
+async function executePlanActions(apiUrl, parentTask, actions, ctx) {
+  const lines = [];
+  let truncated = false;
+  if (actions.length > PLAN_ACTION_LIMIT) {
+    truncated = true;
+    actions = actions.slice(0, PLAN_ACTION_LIMIT);
+  }
+  const depth = typeof parentTask.planning_depth === "number" ? parentTask.planning_depth : 0;
+  if (depth >= 1) {
+    const blocked = actions.filter((a) => a.type === "create" || a.type === "delegate").length;
+    actions = actions.filter((a) => a.type === "update");
+    if (blocked)
+      lines.push(`- \u26A0 ${blocked} create/delegate action(s) blocked (planning depth limit)`);
+  }
+  const parentId = parentTask.issue_id;
+  const parentProjectId = await (async () => {
+    try {
+      const r = await apiClient.get(`${apiUrl}/api/issues/${parentId}`);
+      return r.data?.project_id;
+    } catch {
+      return null;
+    }
+  })();
+  const headers = { "x-agent-id": parentTask.agent_id };
+  await ctx.refreshLocalAgents();
+  for (const a of actions) {
+    try {
+      if (a.type === "create") {
+        const body = {
+          action: "create",
+          project_id: a.project_id || parentProjectId,
+          title: a.title,
+          description: a.description,
+          priority: a.priority,
+          assignee_type: a.assignee_type,
+          assignee_id: a.assignee_id,
+          parent_id: a.parent_id || parentId
+        };
+        const res = await apiClient.post(`${apiUrl}/api/issues/agent/mutate`, body, { headers });
+        if (!res.success) {
+          lines.push(`- \u274C create "${a.title}": ${res.error || res.status}`);
+          continue;
+        }
+        const created = res.data;
+        lines.push(`- \u2713 created **${created.key}** \u2014 ${created.title}${created.assignee_id ? ` \u2192 @${created.assignee_id}` : ""}`);
+        if (created.assignee_type === "agent" && created.assignee_id && ctx.localAgentIds.has(created.assignee_id)) {
+          ctx.enqueueLocal({
+            issue_id: created.id,
+            key: created.key,
+            title: created.title,
+            description: created.description,
+            agent_id: created.assignee_id,
+            session_id: null,
+            working_dir: parentTask.working_dir || null,
+            planning_depth: depth + 1
+          });
+          lines.push(`  \u21B3 dispatched locally (same runtime)`);
+        }
+      } else if (a.type === "update") {
+        const res = await apiClient.post(`${apiUrl}/api/issues/agent/mutate`, { action: "update", ...a }, { headers });
+        if (!res.success) {
+          lines.push(`- \u274C update ${a.id}: ${res.error || res.status}`);
+          continue;
+        }
+        lines.push(`- \u2713 updated ${res.data.key}`);
+      } else if (a.type === "delegate") {
+        const res = await apiClient.post(`${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(`- \u274C delegate ${a.id}: ${res.error || res.status}`);
+          continue;
+        }
+        lines.push(`- \u2713 delegated ${res.data.key} \u2192 ${a.assignee_id}`);
+        if (ctx.localAgentIds.has(a.assignee_id)) {
+          ctx.enqueueLocal({
+            issue_id: res.data.id,
+            key: res.data.key,
+            title: res.data.title,
+            description: res.data.description,
+            agent_id: a.assignee_id,
+            session_id: res.data.session_id || null,
+            working_dir: parentTask.working_dir || null,
+            planning_depth: depth + 1
+          });
+          lines.push(`  \u21B3 dispatched locally (same runtime)`);
+        }
+      }
+    } catch (e) {
+      lines.push(`- \u274C ${a.type} failed: ${String(e)}`);
+    }
+  }
+  if (truncated)
+    lines.push(`- \u26A0 action list truncated at ${PLAN_ACTION_LIMIT}`);
+  if (!lines.length)
+    return "";
+  return `**Planning actions**
+
+${lines.join(`
+`)}`;
+}
 function stripMd(s) {
   return s.replace(/[`*_]/g, "").trim();
 }

package/package.json

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

package/src/acp-runner.ts

@@ -57,6 +57,7 @@ export async function runAcp(opts: AcpRunOpts): Promise<{ stopReason: string; se
 
   let activeSessionId: string | null = opts.sessionId || null;
   let recording = false; // only forward events after prompt() starts
+  let chunkCount = 0; // assistant_text + tool_call chunks seen during prompt()
   const alwaysAllow = new Set<string>(); // keys: toolName|kind that user said "always allow"
 
   const client: Client = {
@@ -122,13 +123,38 @@ export async function runAcp(opts: AcpRunOpts): Promise<{ stopReason: string; se
     }
 
     recording = true;
-    const res = await conn.prompt({
-      sessionId: activeSessionId!,
-      prompt: [{ type: 'text', text: opts.prompt }],
-    } as any);
+    const runPrompt = async () => {
+      chunkCount = 0;
+      return await conn.prompt({
+        sessionId: activeSessionId!,
+        prompt: [{ type: 'text', text: opts.prompt }],
+      } as any);
+    };
+
+    let res = await runPrompt();
+    let stopReason = (res as any).stopReason;
+
+    // Resumed session that returned zero chunks → session is likely stale in the adapter.
+    // Retry once with a fresh session so user gets an actual response.
+    if (chunkCount === 0 && opts.sessionId) {
+      await opts.onEvent({ event_type: 'progress', payload: { message: `resumed session produced no output (stopReason=${stopReason}); retrying with fresh session` } });
+      try {
+        const fresh = await conn.newSession({ cwd: opts.cwd || process.cwd(), mcpServers: [] } as any);
+        activeSessionId = fresh.sessionId;
+        if (opts.onSession) await opts.onSession(fresh.sessionId);
+        res = await runPrompt();
+        stopReason = (res as any).stopReason;
+      } catch (e) {
+        await opts.onEvent({ event_type: 'error', payload: { message: `retry with fresh session failed: ${String(e)}` } });
+      }
+    }
+
+    if (chunkCount === 0) {
+      await opts.onEvent({ event_type: 'error', payload: { message: `agent produced no output (stopReason=${stopReason})` } });
+    }
 
-    await opts.onEvent({ event_type: 'result', payload: { stopReason: (res as any).stopReason } });
-    return { stopReason: (res as any).stopReason, sessionId: activeSessionId! };
+    await opts.onEvent({ event_type: 'result', payload: { stopReason } });
+    return { stopReason, sessionId: activeSessionId! };
   } finally {
     try { child.kill(); } catch {}
   }
@@ -140,11 +166,12 @@ export async function runAcp(opts: AcpRunOpts): Promise<{ stopReason: string; se
       case 'agent_message_chunk':
       case 'agent_thought_chunk': {
         const text = extractText(u.content);
-        if (text) await o.onEvent({ event_type: 'assistant_text', payload: { text } });
+        if (text) { chunkCount++; await o.onEvent({ event_type: 'assistant_text', payload: { text } }); }
         break;
       }
       case 'tool_call':
       case 'tool_call_update': {
+        chunkCount++;
         await o.onEvent({ event_type: 'tool_call', payload: {
           id: u.toolCallId || u.id, tool: u.title || u.toolName || 'tool', kind: u.kind, status: u.status, input: u.rawInput, locations: u.locations,
         }});

package/src/client.ts

@@ -38,9 +38,9 @@ async function request<T>(url: string, options?: RequestInit): Promise<ApiRespon
 
 export const apiClient = {
   get: <T = unknown>(url: string) => request<T>(url),
-  post: <T = unknown>(url: string, body: unknown) =>
-    request<T>(url, { method: 'POST', body: JSON.stringify(body) }),
-  patch: <T = unknown>(url: string, body: unknown) =>
-    request<T>(url, { method: 'PATCH', body: JSON.stringify(body) }),
+  post: <T = unknown>(url: string, body: unknown, opts?: { headers?: Record<string, string> }) =>
+    request<T>(url, { method: 'POST', body: JSON.stringify(body), headers: opts?.headers }),
+  patch: <T = unknown>(url: string, body: unknown, opts?: { headers?: Record<string, string> }) =>
+    request<T>(url, { method: 'PATCH', body: JSON.stringify(body), headers: opts?.headers }),
   delete: <T = unknown>(url: string) => request<T>(url, { method: 'DELETE' }),
 };

package/src/index.ts

@@ -17,7 +17,7 @@ const LOG_PATH = join(MULTI_DIR, 'logs', 'agent.log');
 const SKILLS_DIR = join(MULTI_DIR, 'skills');
 const STOP_PATH = join(MULTI_DIR, 'stop.flag');
 const TASKS_DB_PATH = join(MULTI_DIR, 'tasks.db');
-const VERSION = '0.6.7';
+const VERSION = '0.7.0';
 
 const COMMANDS = {
   setup: 'Register this device with a workspace',
@@ -257,6 +257,29 @@ async function cmdConnect(apiUrl: string, config: Config) {
   let workerWake: (() => void) | null = null;
   const notifyWorker = () => { try { workerWake?.(); workerWake = null; } catch {} };
 
+  // Agents linked to this device (refreshed periodically). Used to short-circuit
+  // server dispatch when an agent-created child issue is assigned to an agent
+  // running on the same runtime.
+  const localAgentIds = new Set<string>();
+  const refreshLocalAgents = async () => {
+    try {
+      const res = await apiClient.get<any>(`${apiUrl}/api/devices/${config.deviceId}/agents`);
+      const rows = res.data?.results || res.data || [];
+      if (Array.isArray(rows)) {
+        localAgentIds.clear();
+        for (const a of rows) if (a?.id) localAgentIds.add(a.id);
+      }
+    } catch {}
+  };
+  await refreshLocalAgents();
+
+  const enqueueLocal = (task: any) => {
+    const taskId = task?.issue_id ? `${task.issue_id}-${Date.now()}` : crypto.randomUUID();
+    db.run('INSERT INTO tasks (id, status, payload) VALUES (?, ?, ?)', [taskId, 'pending', JSON.stringify(task)]);
+    notifyWorker();
+    return taskId;
+  };
+
   // Local HTTP server on a free port
   const port = await pickFreePort();
   const expectedAuth = `Bearer ${config.dispatchSecret}`;
@@ -328,7 +351,7 @@ async function cmdConnect(apiUrl: string, config: Config) {
       db.run("UPDATE tasks SET status = 'running', started_at = unixepoch(), attempts = attempts + 1 WHERE id = ?", [row.id]);
       try {
         const task = JSON.parse(row.payload);
-        await handleRunTask(apiUrl, config.deviceId!, task, detected);
+        await handleRunTask(apiUrl, config.deviceId!, task, detected, { localAgentIds, enqueueLocal, refreshLocalAgents });
         db.run("UPDATE tasks SET status = 'done', finished_at = unixepoch() WHERE id = ?", [row.id]);
       } catch (e) {
         log(`task ${row.id} error: ${String(e)}`);
@@ -406,7 +429,13 @@ async function parseTunnelUrl(stream: ReadableStream<Uint8Array>): Promise<strin
   return null;
 }
 
-async function handleRunTask(apiUrl: string, deviceId: string, task: any, detected: { type: string; path: string }[]) {
+interface RuntimeCtx {
+  localAgentIds: Set<string>;
+  enqueueLocal: (task: any) => string;
+  refreshLocalAgents: () => Promise<void>;
+}
+
+async function handleRunTask(apiUrl: string, deviceId: string, task: any, detected: { type: string; path: string }[], ctx?: RuntimeCtx) {
   const issueId = task.issue_id;
   const isFollowup = !!task.followup;
   const workingDir = task.working_dir && existsSync(task.working_dir) ? task.working_dir : undefined;
@@ -658,6 +687,8 @@ async function handleRunTask(apiUrl: string, deviceId: string, task: any, detect
         log(`preamble fetch failed: ${String(e)}`);
       }
 
+      preamble += await buildPlanningPreamble(apiUrl, task);
+
       const prompt = preamble ? `${preamble}\n---\n\n${userPart}` : userPart;
 
       // Pick adapter for the agent's declared type if we have it, else first ACP-capable
@@ -699,6 +730,7 @@ async function handleRunTask(apiUrl: string, deviceId: string, task: any, detect
           }
         }
       } catch {}
+      preamble += await buildPlanningPreamble(apiUrl, task);
       const base = `${task.title}\n\n${task.description || ''}`.trim();
       let userPart: string;
       if (task.followup) {
@@ -733,6 +765,25 @@ async function handleRunTask(apiUrl: string, deviceId: string, task: any, detect
       if (n > 0) log(`  📎 uploaded ${n} output file(s)`);
     }
 
+    // Post-turn: scan agent text for `multi-plan` fenced blocks and execute mutations.
+    if (ctx) {
+      const fullText = turn.blocks.filter(b => b.kind === 'text').map(b => (b as any).text).join('\n');
+      const actions = extractPlanActions(fullText);
+      if (actions.length) {
+        const summary = await executePlanActions(apiUrl, task, actions, ctx);
+        if (summary) {
+          try { await apiClient.post(`${apiUrl}/api/issues/${issueId}/comments`, { author_type: 'agent', author_id: task.agent_id, author_name: 'agent', body: summary }); } catch {}
+        }
+      }
+    }
+
+    // Visible fallback: agent ran but emitted nothing user-facing
+    if (!hasAssistantText && !hadError) {
+      const stopReason = turn.result?.stopReason || 'unknown';
+      await postComment(`⚠️ Agent returned no output (stopReason=${stopReason}). Adapter may be stuck on a stale session — try starting a new issue or clearing session_id.`);
+      log(`  ⚠ ${task.key} produced no assistant output (stopReason=${stopReason})`);
+    }
+
     if (hadError) { await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {}); log(`  ✗ ${task.key} failed`); }
     else { await apiClient.post(`${apiUrl}/api/issues/${issueId}/complete`, {}); log(`  ✓ ${task.key} complete`); }
   } catch (e) {
@@ -743,6 +794,164 @@ async function handleRunTask(apiUrl: string, deviceId: string, task: any, detect
   }
 }
 
+// Appended to agent prompt. Teaches the agent how to emit planning actions the
+// daemon will execute after the turn: create sub-issues, update any issue in
+// the project, or delegate to other agents.
+async function buildPlanningPreamble(apiUrl: string, task: any): Promise<string> {
+  const depth = typeof task.planning_depth === 'number' ? task.planning_depth : 0;
+  if (depth >= 1) {
+    return `# Planning (sub-task context)
+
+You are acting on a sub-issue spawned by another agent. You MAY emit a \`multi-plan\` block to update your own issue's status (e.g. mark done/failed) but CANNOT create child issues or delegate further.
+
+\`\`\`multi-plan
+{"actions":[{"type":"update","id":"<this issue id>","status":"done"}]}
+\`\`\`
+
+`;
+  }
+  let projectId = '';
+  let agentsBlock = '';
+  try {
+    const issueRes = await apiClient.get<any>(`${apiUrl}/api/issues/${task.issue_id}`);
+    projectId = issueRes.data?.project_id || '';
+    const agentRes = await apiClient.get<any>(`${apiUrl}/api/agents/${task.agent_id}`);
+    const workspaceId = agentRes.data?.workspace_id;
+    if (workspaceId) {
+      const ag = await apiClient.get<any[]>(`${apiUrl}/api/agents?workspace_id=${workspaceId}`);
+      const list = Array.isArray(ag.data) ? ag.data : [];
+      const others = list.filter(a => a.id !== task.agent_id);
+      if (others.length) {
+        agentsBlock = others.map(a => `- \`${a.id}\` (${a.name}${a.type ? `, ${a.type}` : ''})`).join('\n');
+      }
+    }
+  } catch {}
+
+  return `# Planning & delegation
+
+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.
+
+Syntax:
+
+\`\`\`multi-plan
+{"actions":[
+  {"type":"create","title":"...","description":"...","assignee_type":"agent","assignee_id":"<agent id>"},
+  {"type":"update","id":"<issue id>","status":"done"},
+  {"type":"delegate","id":"<issue id>","assignee_id":"<agent id>"}
+]}
+\`\`\`
+
+Rules:
+- Omit the block entirely if no actions are needed.
+- Max 10 actions per turn; additional actions are dropped.
+- Sub-issues spawned from your plan run one-shot: they cannot themselves spawn further children (only \`update\` allowed there).
+- \`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'}).
+
+${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 };
+
+// Extract JSON action blocks fenced as ```multi-plan ... ```
+function extractPlanActions(text: string): PlanAction[] {
+  const out: PlanAction[] = [];
+  if (!text) return out;
+  const re = /```multi-plan\s*\n([\s\S]*?)\n```/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    try {
+      const parsed = JSON.parse(m[1]);
+      const actions = Array.isArray(parsed?.actions) ? parsed.actions : Array.isArray(parsed) ? parsed : [parsed];
+      for (const a of actions) if (a && typeof a === 'object' && typeof a.type === 'string') out.push(a as PlanAction);
+    } catch {}
+  }
+  return out;
+}
+
+const PLAN_ACTION_LIMIT = 10;
+
+async function executePlanActions(apiUrl: string, parentTask: any, actions: PlanAction[], ctx: RuntimeCtx): Promise<string> {
+  const lines: string[] = [];
+  let truncated = false;
+  if (actions.length > PLAN_ACTION_LIMIT) {
+    truncated = true;
+    actions = actions.slice(0, PLAN_ACTION_LIMIT);
+  }
+  // Prevent agent recursion: a child turn's plan cannot itself spawn more children.
+  // `planning_depth` is propagated from parent task; depth >= 1 blocks create/delegate.
+  const depth = typeof parentTask.planning_depth === 'number' ? parentTask.planning_depth : 0;
+  if (depth >= 1) {
+    const blocked = actions.filter(a => a.type === 'create' || a.type === 'delegate').length;
+    actions = actions.filter(a => a.type === 'update');
+    if (blocked) lines.push(`- ⚠ ${blocked} create/delegate action(s) blocked (planning depth limit)`);
+  }
+  const parentId = parentTask.issue_id;
+  const parentProjectId = await (async () => {
+    try {
+      const r = await apiClient.get<any>(`${apiUrl}/api/issues/${parentId}`);
+      return r.data?.project_id;
+    } catch { return null; }
+  })();
+  const headers = { 'x-agent-id': parentTask.agent_id };
+
+  // Refresh the set of agents linked to this device once per plan execution.
+  await ctx.refreshLocalAgents();
+
+  for (const a of actions) {
+    try {
+      if (a.type === 'create') {
+        const body = {
+          action: 'create' as const,
+          project_id: a.project_id || parentProjectId,
+          title: a.title, description: a.description,
+          priority: a.priority, assignee_type: a.assignee_type, assignee_id: a.assignee_id,
+          parent_id: a.parent_id || parentId,
+        };
+        const res = await apiClient.post<any>(`${apiUrl}/api/issues/agent/mutate`, body, { headers });
+        if (!res.success) { lines.push(`- ❌ create "${a.title}": ${res.error || res.status}`); continue; }
+        const created = res.data;
+        lines.push(`- ✓ created **${created.key}** — ${created.title}${created.assignee_id ? ` → @${created.assignee_id}` : ''}`);
+        // Same-runtime shortcut: if new issue's agent is linked locally, enqueue directly.
+        if (created.assignee_type === 'agent' && created.assignee_id && ctx.localAgentIds.has(created.assignee_id)) {
+          ctx.enqueueLocal({
+            issue_id: created.id, key: created.key, title: created.title, description: created.description,
+            agent_id: created.assignee_id, session_id: null, working_dir: parentTask.working_dir || null,
+            planning_depth: depth + 1,
+          });
+          lines.push(`  ↳ dispatched locally (same runtime)`);
+        }
+      } else if (a.type === 'update') {
+        const res = await apiClient.post<any>(`${apiUrl}/api/issues/agent/mutate`, { action: 'update', ...a }, { headers });
+        if (!res.success) { lines.push(`- ❌ update ${a.id}: ${res.error || res.status}`); continue; }
+        lines.push(`- ✓ updated ${res.data.key}`);
+      } else if (a.type === 'delegate') {
+        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}`);
+        if (ctx.localAgentIds.has(a.assignee_id)) {
+          ctx.enqueueLocal({
+            issue_id: res.data.id, key: res.data.key, title: res.data.title, description: res.data.description,
+            agent_id: a.assignee_id, session_id: res.data.session_id || null, working_dir: parentTask.working_dir || null,
+            planning_depth: depth + 1,
+          });
+          lines.push(`  ↳ dispatched locally (same runtime)`);
+        }
+      }
+    } catch (e) {
+      lines.push(`- ❌ ${a.type} failed: ${String(e)}`);
+    }
+  }
+  if (truncated) lines.push(`- ⚠ action list truncated at ${PLAN_ACTION_LIMIT}`);
+  if (!lines.length) return '';
+  return `**Planning actions**\n\n${lines.join('\n')}`;
+}
+
 function stripMd(s: string): string {
   return s.replace(/[`*_]/g, '').trim();
 }