@evandu/super-pi 0.1.60 → 0.1.61

package/agents/super-pi-task/core.ts

@@ -120,7 +120,6 @@ export type TaskParams = {
   prompt: string;
   subagent_type: string;
   task_id?: string;
-  background?: boolean;
 };
 
 /** One dispatchable sub-agent, as the server read it from `agents/*.md` at spawn time. */
@@ -154,9 +153,12 @@ export function parseRoster(raw: string | undefined): RosterEntry[] {
  *
  * THE CORRECTION. OpenCode's note 1 says a dispatch "runs until it finishes", and this file used to say
  * the same - while the schema carried a `background` parameter and the code implemented it. So a mode
- * that existed was described as though it did not, and the model would never have used it. Note 2 below
- * now states that the default is blocking AND that `background` exists, because "delegate several
- * independent things at once" is exactly what this roster is shaped for and a model told it cannot.
+ * that existed was described as though it did not, and the model would never have used it. The current
+ * shape is simpler: there is no blocking mode at all. Every dispatch is asynchronous, every call returns
+ * state="running" immediately, and the answer arrives as a follow-up turn. A model that has never been
+ * told a dispatch BLOCKS until the child finishes will fire three of them in parallel and find they all
+ * read the same pre-delegation state, which is exactly the failure this default avoids. Note 2 below
+ * states the always-async contract.
  *
  * THE ADDITIONS, notes 7-9, are about COMPOSING dispatches. They were absent because there was
  * previously nothing on the other end to compose into: the model delegated, read the result, and decided
@@ -178,16 +180,14 @@ When NOT to use this tool:
 
 Usage notes:
 1. Every dispatch starts a SEPARATE agent process that runs until it finishes, so the cost of a delegation is minutes rather than seconds. Delegate work that is genuinely substantial; do not delegate a lookup you could do in one tool call.
-2. Once you have delegated work to a subagent, do not duplicate that work yourself. Continue with non-overlapping tasks, or wait for the result.
-3. When the subagent is done it returns ONE message back to you, wrapped in a <task> element. That result is not visible to the user: if it matters to the user, say so in your own reply.
-4. Each dispatch starts with a FRESH context. Your prompt is all the subagent will know, so it must contain the full task, and it must say exactly what you want back in its final message.
-5. Tell the subagent whether you expect it to WRITE CODE or only to RESEARCH (search, file reads, web fetches), and how to verify its work if it writes. It is not aware of the user's intent.
-6. If a subagent's description says it should be used proactively, use it without being asked.
-7. BY DEFAULT A DISPATCH BLOCKS: the call does not return until that subagent has finished, and its answer comes back to you in this same turn. So you CAN dispatch several in one turn and use each answer before writing the next prompt - which is the normal way to chain specialists.
-8. A LATER DISPATCH MUST CARRY THE EARLIER ONE'S ANSWER IN ITS PROMPT, because the next subagent starts with a fresh context and cannot see what the first one found. The tool does not do this for you. Write the findings you need into the next prompt yourself.
-9. Pass background: true to run this sub-agent ASYNCHRONOUSLY. The dispatch returns immediately with state="running" and the answer arrives as a follow-up turn when the sub-agent finishes. Do NOT use this for a plain shell command - use the run_async tool instead, which is much faster for a one-shot command and does not spin up an entire sub-agent.
-10. To run a SHELL COMMAND in the background (a long build, a test suite, a watcher, anything measured in seconds to minutes), use the run_async tool. Do NOT pass background: true to the task tool for this.
-11. For three or more steps where each depends on the previous one, prefer the workflow tool: it runs the chain server-side and hands each step the previous step's output without you copying it through your context.`;
+2. The dispatch is ALWAYS ASYNCHRONOUS. The call returns immediately with state="running" and the sub-agent's answer arrives as a follow-up turn when it finishes. You CAN dispatch several in one turn; each returns right away, and the answers stream back as separate follow-up turns in the order the sub-agents settle. Do NOT sleep, poll, or duplicate the dispatch.
+3. Once you have delegated work to a subagent, do not duplicate that work yourself. Continue with non-overlapping tasks.
+4. When the subagent is done it returns ONE message back to you, wrapped in a <task> element. That result is not visible to the user: if it matters to the user, say so in your own reply.
+5. Each dispatch starts with a FRESH context. Your prompt is all the subagent will know, so it must contain the full task, and it must say exactly what you want back in its final message.
+6. Tell the subagent whether you expect it to WRITE CODE or only to RESEARCH (search, file reads, web fetches), and how to verify its work if it writes. It is not aware of the user's intent.
+7. If a subagent's description says it should be used proactively, use it without being asked.
+8. To CHAIN sub-agents, write the first dispatch's expected answer INTO the second dispatch's prompt, because the next sub-agent starts with a fresh context and cannot see what the first one found. The tool does not do this for you. For three or more chained steps, prefer the workflow tool: it runs the chain server-side and hands each step the previous step's output without you copying it through your context.
+9. To run a SHELL COMMAND in the background (a long build, a test suite, a watcher, anything measured in seconds to minutes), use the run_async tool. This tool is for delegating to a specialist sub-agent, not for plain commands.`;
 
 /**
  * The roster block, OpenCode's `describeTask()` reduced to its two jobs: the ids that are legal, and
@@ -345,7 +345,10 @@ export async function executeTask(
         prompt: params.prompt,
         description: params.description,
         depth: config.depth,
-        background: false,
+        // ALWAYS ASYNCHRONOUS. The model never blocks on a sub-agent - a sub-agent takes minutes, and a
+        // dispatch that blocks would freeze the primary turn for the whole of that. The result arrives
+        // as a follow-up turn when the sub-agent finishes; the call returns state="running" immediately.
+        background: true,
         // Always sent, even when undefined, so a body that omits the field is unambiguously a caller that
         // did not have one - which the server treats as a refusal, not as a legacy request to let through.
         capability: config.capability,
@@ -366,22 +369,24 @@ export async function executeTask(
 
   // No run id means nothing ran: either the server refused before spawning, or the body was unreadable.
   // "refused" says so, where "unknown" would imply a run exists somewhere whose output is merely absent.
+  // The dispatch is ALWAYS async, so the only shape a successful response has here is state="running".
+  // A finished run that came back synchronously would mean the server ignored background:true, which is
+  // the refusal below, not a happy path.
   const id = payload.run?.id ?? "refused";
-  if (params.background === true && payload.run?.status === "running") {
+  if (payload.run?.status === "running") {
     return text(`<task id="${id}" state="running">\n<summary>${params.description.trim() || params.subagent_type}</summary>\n<task_result>The task is working in the background. You will be notified automatically when it finishes. Do not sleep, poll for progress, ask the task for status, or duplicate this task's work. Continue with non-overlapping work.</task_result>\n</task>`);
   }
-  const completed = payload.run?.status === "completed";
-  const body = completed
-    ? payload.output ?? ""
-    : payload.error ?? `The sub-agent run finished as ${JSON.stringify(payload.run?.status ?? "unknown")} without saying why.`;
+  // The server should never answer a background dispatch with a finished run, because background:true
+  // returns 202 immediately. If it does, surface the reason rather than pretending the answer is in hand.
+  const body = payload.error ?? `The sub-agent run finished as ${JSON.stringify(payload.run?.status ?? "unknown")} without saying why.`;
   return text(
     renderTaskResult({
       id,
-      state: completed ? "completed" : "error",
+      state: "error",
       summary: params.description.trim() ? `${params.description.trim()} (${params.subagent_type})` : `${params.subagent_type}`,
-      text: payload.outputTruncated && completed ? `${body}\n\n[This answer was truncated at 50 KB by the server; the full run is recorded in Super Pi.]` : body,
+      text: body,
     }),
-    !completed,
+    true,
   );
 }
 

package/agents/super-pi-task/index.ts

@@ -50,7 +50,6 @@ const Parameters = Type.Object({
   prompt: Type.String({ description: "The task for the agent to perform" }),
   subagent_type: Type.String({ description: "The type of specialized agent to use for this task" }),
   task_id: Type.Optional(Type.String({ description: "Resume a previous task when supported" })),
-  background: Type.Optional(Type.Boolean({ description: "Run asynchronously and deliver the result as a follow-up message" })),
 });
 const QuestionParameters = Type.Object({ question: Type.String(), options: Type.Array(Type.String(), { minItems: 1 }), multiple: Type.Optional(Type.Boolean()), extraNote: Type.Optional(Type.Boolean()) });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.60",
+  "version": "0.1.61",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",