@evandu/super-pi 0.1.57 → 0.1.59

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

@@ -43,6 +43,11 @@ export const TASK_ROSTER_ENV = "SUPER_PI_TASK_ROSTER";
 export const TASK_CONVERSATION_ENV = "SUPER_PI_TASK_CONVERSATION";
 export const TASK_DEPTH_ENV = "SUPER_PI_TASK_DEPTH";
 
+/** The independent background-command tool. NOT a sub-agent dispatch: a shell command run asynchronously. */
+export const RUN_ASYNC_TOOL_NAME = "run_async";
+/** Capability env name reused for `run_async` - same per-turn credential, same wire, same server check. */
+export const RUN_ASYNC_CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
+
 /**
  * The `todowrite` extension's half of the same environment contract, declared here for the reason the
  * four above are. `src/server/task-tool.ts` is the other end; `scripts/todo-tool.test.mjs` asserts they
@@ -72,6 +77,43 @@ export type TodoEntry = { content: string; status: "pending" | "in_progress" | "
 /** The three statuses Super Pi renders, as the model writes them. */
 const TODO_STATUSES = new Set(["pending", "in_progress", "completed"]);
 
+/** Parameters for the `run_async` tool. Plain shell command, no subagent plumbing. */
+export type RunAsyncParams = { command: string; description?: string };
+
+/**
+ * The model-facing description for the `run_async` tool.
+ *
+ * THIS IS A SHELL COMMAND, NOT A SUB-AGENT. The tool runs the command via the platform's shell
+ * (bash on Unix, PowerShell on Windows) in the conversation's workspace, returns immediately with
+ * state="running", and delivers stdout, stderr and exit code as a follow-up turn when the command
+ * settles. Use it whenever the user says "in the background", "async", "without blocking me",
+ * "run this and tell me later", or "kick off a build" - any work measured in seconds to minutes
+ * that they would otherwise be waiting on.
+ *
+ * Do NOT use `task` with `background: true` for this: `task` dispatches a sub-agent, and a
+ * sub-agent for a one-shot shell command is minutes of process startup to do what `run_async`
+ * does in tens of milliseconds.
+ */
+export const RUN_ASYNC_DESCRIPTION = `Run a shell command asynchronously in the current workspace and deliver its output as a follow-up message when it finishes.
+
+When to use this:
+- The user says "in the background", "async", "kick off", "start a build and tell me when it's done", or anything else that means "do not block me on this".
+- A command is expected to take seconds to minutes (a long build, a test suite, a download, a file watcher).
+- You want to start several independent commands and let them all run in parallel.
+
+How it works:
+1. The command runs in the conversation's workspace under the platform's shell (bash on Linux/macOS, PowerShell on Windows).
+2. The call returns immediately. You will see <task id state="running"> in the result.
+3. When the command finishes, its stdout, stderr and exit code arrive in a new turn wrapped in a <task> envelope.
+
+Usage notes:
+1. The "command" field is the shell command verbatim - do not wrap it in JSON.
+2. "description" is optional and only labels the row in the right-rail "background tasks" panel.
+3. Do NOT poll, sleep, or call this tool repeatedly to check on the same command. The result arrives on its own.
+4. For commands that should run in the FOREGROUND and whose output you need before the next step, use the bash tool instead.
+5. For delegating a multi-step task to a specialist sub-agent, use the task tool. This tool is for plain shell commands.
+6. The result envelope looks like <task id="..." state="completed|error"><task_result>stdout</task_result></task> or with <task_error> for failures. Read it the same way you would read a sub-agent's result.`;
+
 /** The parameters, exactly OpenCode's (`tool/task.ts:43-52`) minus the ones this step does not do. */
 export type TaskParams = {
   description: string;
@@ -143,8 +185,9 @@ Usage notes:
 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 only for work that does not depend on anything and that you will not need before this turn ends. The result arrives later as a follow-up message; you are not told anything at call time. Do NOT sleep, poll, or ask for status.
-10. 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.`;
+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.`;
 
 /**
  * The roster block, OpenCode's `describeTask()` reduced to its two jobs: the ids that are legal, and
@@ -259,10 +302,9 @@ export function refuseTask(config: TaskToolConfig, params: TaskParams): string |
   if (!config.endpoint) return `The task tool is not available in this session: ${TASK_ENDPOINT_ENV} is not set, so there is no Super Pi server to dispatch to. Do the work yourself with your other tools.`;
   if (!config.conversationId) return `The task tool is not available in this session: ${TASK_CONVERSATION_ENV} is not set, so this run cannot be attributed to a conversation. Do the work yourself with your other tools.`;
   if (!config.roster.length) return "This install has no dispatchable sub-agents (no agents/*.md with `mode: subagent`), so there is nobody to delegate to. Do the work yourself with your other tools.";
-  if (!params.subagent_type.trim()) return `subagent_type is required. Available: ${config.roster.map((entry) => entry.id).join(", ")}.`;
+  if (!params.subagent_type.trim()) return `subagent_type is required. Available: ${config.roster.map((entry) => entry.id).join(", ")}. If you wanted to run a SHELL COMMAND in the background instead of dispatching a sub-agent, use the run_async tool.`;
   if (!config.roster.some((entry) => entry.id === params.subagent_type)) return `${JSON.stringify(params.subagent_type)} is not a dispatchable subagent_type. Available: ${config.roster.map((entry) => entry.id).join(", ")}. Pick one of those, or do the work yourself.`;
   if (!params.prompt.trim()) return "prompt is required and must not be empty: the sub-agent starts with a fresh context and your prompt is everything it will know.";
-  if (params.background === true && !config.execEndpoint) return `Background tasks are not available: ${TASK_EXEC_ENDPOINT_ENV} is not set. Do the work yourself with your other tools.`;
   return undefined;
 }
 
@@ -289,36 +331,6 @@ export async function executeTask(
   const refusal = refuseTask(config, params);
   if (refusal) return text(renderTaskResult({ id: "refused", state: "error", text: refusal }), true);
 
-  // Background: true uses the lightweight exec endpoint instead of the subagent dispatcher.
-  // This avoids spawning a full Pi agent process for a plain shell command.
-  if (params.background === true && config.execEndpoint) {
-    const send = deps.fetch ?? globalFetch;
-    let response: Awaited<ReturnType<TaskFetch>>;
-    try {
-      response = await send(config.execEndpoint, {
-        method: "POST",
-        headers: { "content-type": "application/json", ...(config.token ? { authorization: `Bearer ${config.token}` } : {}) },
-        body: JSON.stringify({
-          cmd: params.prompt,
-          cwd: context.cwd,
-          conversationId: config.conversationId,
-          capability: config.capability,
-        }),
-        ...(deps.signal ? { signal: deps.signal } : {}),
-      });
-    } catch (error) {
-      return text(renderTaskResult({ id: "unreachable", state: "error", text: `Could not reach the Super Pi server at ${config.execEndpoint}: ${error instanceof Error ? error.message : "unknown error"}` }), true);
-    }
-    let payload: { sessionId?: string; status?: string; error?: string };
-    try { payload = JSON.parse(await response.text()) as typeof payload; }
-    catch { return text(renderTaskResult({ id: "unreadable", state: "error", text: `The exec endpoint answered ${response.status} with something that is not JSON.` }), true); }
-    const id = payload.sessionId ?? "refused";
-    if (payload.status === "running") {
-      return text(`<task id="${id}" state="running">\n<summary>${params.description.trim() || params.prompt.slice(0, 60)}</summary>\n<task_result>The command is running in the background. You will be notified automatically when it finishes. Do not sleep, poll for progress, or duplicate this work. Continue with non-overlapping work.</task_result>\n</task>`);
-    }
-    return text(renderTaskResult({ id, state: "error", text: payload.error ?? `Exec endpoint returned status ${payload.status}` }), true);
-  }
-
   const send = deps.fetch ?? globalFetch;
   let response: Awaited<ReturnType<TaskFetch>>;
   try {
@@ -503,6 +515,65 @@ export function refuseTodo(config: TodoToolConfig, params: TodoParams): string |
   return undefined;
 }
 
+/**
+ * Refuses a `run_async` call that cannot work.
+ *
+ * Two checks, for the same three-case shape `refuseTask` and `refuseTodo` use: the call must reach the
+ * server, and the server must be able to attribute it to a conversation. The roster is not consulted
+ * because this tool is not a dispatch.
+ */
+export function refuseRunAsync(config: TaskToolConfig, params: RunAsyncParams): string | undefined {
+  if (!config.execEndpoint) return `The run_async tool is not available in this session: ${TASK_EXEC_ENDPOINT_ENV} is not set, so there is no Super Pi server to run commands on. Do the work yourself with your other tools.`;
+  if (!config.conversationId) return `The run_async tool is not available in this session: ${TASK_CONVERSATION_ENV} is not set, so this run cannot be attributed to a conversation. Do the work yourself with your other tools.`;
+  if (typeof params.command !== "string" || !params.command.trim()) return "command is required and must not be empty.";
+  return undefined;
+}
+
+/**
+ * Runs one shell command asynchronously and returns the envelope the model reads.
+ *
+ * Independent of `executeTask` even though both post JSON to the same server: the model reaches for
+ * `run_async` when the user wants a background shell command, and reaches for `task` when they want
+ * a sub-agent. Routing them through one function would mean sharing a refuse-list, a description,
+ * and a wire that a model can never get wrong by accident.
+ */
+export async function executeAsync(
+  params: RunAsyncParams,
+  context: TaskToolContext,
+  config: TaskToolConfig,
+  deps: { signal?: AbortSignal; fetch?: TaskFetch } = {},
+): Promise<TaskToolResult> {
+  const text = (body: string, isError?: boolean): TaskToolResult => ({ content: [{ type: "text", text: body }], details: undefined, ...(isError ? { isError: true } : {}) });
+  const refusal = refuseRunAsync(config, params);
+  if (refusal) return text(renderTaskResult({ id: "refused", state: "error", text: refusal }), true);
+
+  const send = deps.fetch ?? globalFetch;
+  let response: Awaited<ReturnType<TaskFetch>>;
+  try {
+    response = await send(config.execEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...(config.token ? { authorization: `Bearer ${config.token}` } : {}) },
+      body: JSON.stringify({
+        cmd: params.command,
+        cwd: context.cwd,
+        conversationId: config.conversationId,
+        capability: config.capability,
+      }),
+      ...(deps.signal ? { signal: deps.signal } : {}),
+    });
+  } catch (error) {
+    return text(renderTaskResult({ id: "unreachable", state: "error", text: `Could not reach the Super Pi server at ${config.execEndpoint}: ${error instanceof Error ? error.message : "unknown error"}` }), true);
+  }
+  let payload: { sessionId?: string; status?: string; error?: string };
+  try { payload = JSON.parse(await response.text()) as typeof payload; }
+  catch { return text(renderTaskResult({ id: "unreadable", state: "error", text: `The exec endpoint answered ${response.status} with something that is not JSON.` }), true); }
+  const id = payload.sessionId ?? "refused";
+  if (payload.status === "running") {
+    return text(`<task id="${id}" state="running">\n<summary>${(params.description ?? "").trim() || params.command.slice(0, 60)}</summary>\n<task_result>The command is running in the background. You will be notified automatically when it finishes. Do not sleep, poll for progress, or duplicate this work. Continue with non-overlapping work.</task_result>\n</task>`);
+  }
+  return text(renderTaskResult({ id, state: "error", text: payload.error ?? `Exec endpoint returned status ${payload.status}` }), true);
+}
+
 /** One HTTP seam, injected so a test can drive the tool without a socket and production uses global fetch. */
 export type TodoFetch = (url: string, init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
 

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

@@ -21,6 +21,12 @@ import {
   readTodoConfig,
   type TodoParams,
 } from "./core.ts";
+import {
+  RUN_ASYNC_DESCRIPTION,
+  RUN_ASYNC_TOOL_NAME,
+  executeAsync,
+  type RunAsyncParams,
+} from "./core.ts";
 
 /**
  * The Pi adapter for the `task` and `todowrite` tools. Everything with a decision in it is in
@@ -225,6 +231,31 @@ const extension = (pi: ExtensionApi): void => {
     execute: async (_toolCallId, params, signal) =>
       await executeWorkflow(params as WorkflowParams, workflowConfig, { signal: signal ?? undefined }),
   });
+
+  /**
+   * `run_async` - asynchronous shell command execution. NOT a sub-agent dispatch.
+   *
+   * Registered LAST so a model scanning the tool list reads `task` (the more powerful delegation
+   * primitive) before the more specialised background-command tool. A model reaching for the wrong
+   * one is the failure this ordering tries to prevent.
+   *
+   * SHARES THE EXEC ENDPOINT with `task` when it had `background: true`, but is its OWN tool so the
+   * description can say "shell command" rather than "sub-agent with a flag" and refuse-task does not
+   * have to make the subagent_type optional in a way that confused a model reading the description.
+   */
+  const RunAsyncParameters = Type.Object({
+    command: Type.String({ description: "The shell command to run in the workspace. Runs under bash on Linux/macOS and PowerShell on Windows." }),
+    description: Type.Optional(Type.String({ description: "3-5 word label shown in the background tasks panel." })),
+  });
+  pi.registerTool({
+    name: RUN_ASYNC_TOOL_NAME,
+    label: "Run Async",
+    description: RUN_ASYNC_DESCRIPTION,
+    promptSnippet: "run a shell command in the background and deliver its output as a follow-up message",
+    parameters: RunAsyncParameters,
+    execute: async (_toolCallId, params, signal, _onUpdate, context) =>
+      await executeAsync(params as RunAsyncParams, context, config, { signal: signal ?? undefined }),
+  });
 };
 
 export default extension;

package/dist/server/http-server.js

@@ -201,13 +201,19 @@ export function createHttpServer(options) {
                 return;
             }
             response.writeHead(202, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ status: "updating" }));
-            const command = process.platform === "win32" ? "pi.cmd" : "pi";
-            const child = spawn(command, ["update", "npm:@evandu/super-pi"], { cwd: rootDir, detached: true, stdio: "ignore", shell: process.platform === "win32", env: process.env });
+            // Use npm directly instead of `pi update` to avoid Windows detached+shell exit timing issues.
+            // npm's exit code correctly reflects whether the update succeeded.
+            const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+            const child = spawn(npmCmd, ["install", "-g", "@evandu/super-pi"], { stdio: "ignore", shell: process.platform === "win32", env: process.env });
             child.on("close", (code) => {
-                if (code !== 0)
-                    return;
-                const restart = spawn(process.execPath, [join(rootDir, "scripts", "restart-server.mjs")], { cwd: rootDir, detached: true, stdio: "ignore", env: process.env });
-                restart.unref();
+                if (code === 0 || code === null) {
+                    console.log("Super Pi: npm install completed, triggering restart.");
+                    const restart = spawn(process.execPath, [join(rootDir, "scripts", "restart-server.mjs")], { cwd: rootDir, detached: true, stdio: "ignore", env: process.env });
+                    restart.unref();
+                }
+                else {
+                    console.error(`Super Pi: npm install failed with code ${code}`);
+                }
             });
             child.on("error", (error) => { console.warn(`Super Pi: update spawn failed: ${error instanceof Error ? error.message : "unknown error"}`); });
             child.unref();
@@ -220,7 +226,12 @@ export function createHttpServer(options) {
             }
             try {
                 const current = checkDiskVersion(rootDir);
-                const remoteVersion = await fetch("https://pi.dev/api/latest-version").then(result => result.ok ? result.json() : Promise.reject(new Error(`HTTP ${result.status}`)));
+                // Query the npm registry for the latest @evandu/super-pi version.
+                const remoteVersion = await fetch("https://registry.npmjs.org/@evandu/super-pi/latest").then(async (result) => {
+                    if (!result.ok)
+                        throw new Error(`npm registry HTTP ${result.status}`);
+                    return result.json();
+                });
                 const latestVersion = typeof remoteVersion.version === "string" ? remoteVersion.version : undefined;
                 response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ ...current, latestVersion, updateAvailable: Boolean(latestVersion && latestVersion !== current.diskVersion) }));
             }
@@ -371,10 +382,14 @@ export function createHttpServer(options) {
                 json(403, { error: result.message });
                 return;
             }
-            // Validate cwd is a known workspace
-            const workspace = store.snapshot().workspaces.find((w) => w.path === cwd);
+            // Validate cwd is a known workspace. Path comparison is normalized so Windows case
+            // differences or trailing separators do not produce a false "unknown workspace" failure
+            // when the extension hands back the same directory the server handed to it at spawn.
+            const normalized = (value) => value.replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
+            const normalizedCwd = normalized(cwd);
+            const workspace = store.snapshot().workspaces.find((w) => normalized(w.path) === normalizedCwd);
             if (!workspace) {
-                json(400, { error: "cwd is not a known workspace" });
+                json(400, { error: `cwd is not a known workspace: ${cwd} (known: ${store.snapshot().workspaces.map((w) => w.path).join(" | ")})` });
                 return;
             }
             // Set up the background task record BEFORE spawning, so the UI shows it immediately

package/dist/server/runtime.js

@@ -6,7 +6,7 @@ import { resolve, join } from "node:path";
 import { agentSpawnArgs, readAgents } from "./agents.js";
 import { TASK_CAPABILITY_ENV, mintCapability, releaseCapability } from "./capability.js";
 import { resolvePiCommand, shellQuote } from "./pi-command.js";
-import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, rosterPayload, } from "./task-tool.js";
+import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, rosterPayload, } from "./task-tool.js";
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
 import { describeToolCall, describeToolCallArgs, describeToolCallInProgress, extractPartialResultText, extractToolResultText, readQuestionCall } from "./tool-calls.js";
@@ -766,7 +766,7 @@ export class PiRpcRuntime {
         // other. They also share the extension's existence - `extensionArgs` is non-empty exactly when
         // `index.ts` is on disk and an endpoint was configured - so there is no case where one is mounted and
         // the other is not.
-        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, "question"] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : [])] });
+        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, "question"] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : [])] });
         // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
         // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
         if (!this.pi.found)

package/dist/server/task-tool.d.ts

@@ -25,6 +25,15 @@ import type { AgentDefinition, TodoItem } from "./types.js";
  */
 /** The name the model calls. Also the key Pi's tool allowlist matches on, and the deny key in `tools:`. */
 export declare const TASK_TOOL_NAME = "task";
+/**
+ * The independent background-command tool. NOT a sub-agent dispatch.
+ *
+ * Mirrored from `agents/super-pi-task/core.ts` for the same reason `TASK_TOOL_NAME` is: a tool name
+ * is a wire between two files Pi's module loader cannot cross, and `scripts/task-tool.test.mjs`
+ * asserts the two copies agree. Renaming on one side alone would fail at registerTool time with a
+ * message nobody reads.
+ */
+export declare const RUN_ASYNC_TOOL_NAME = "run_async";
 /**
  * How many task hops are allowed below a primary agent.
  *

package/dist/server/task-tool.js

@@ -24,6 +24,15 @@
  */
 /** The name the model calls. Also the key Pi's tool allowlist matches on, and the deny key in `tools:`. */
 export const TASK_TOOL_NAME = "task";
+/**
+ * The independent background-command tool. NOT a sub-agent dispatch.
+ *
+ * Mirrored from `agents/super-pi-task/core.ts` for the same reason `TASK_TOOL_NAME` is: a tool name
+ * is a wire between two files Pi's module loader cannot cross, and `scripts/task-tool.test.mjs`
+ * asserts the two copies agree. Renaming on one side alone would fail at registerTool time with a
+ * message nobody reads.
+ */
+export const RUN_ASYNC_TOOL_NAME = "run_async";
 /**
  * How many task hops are allowed below a primary agent.
  *

package/package.json

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