@huseynsnmz/pi-suite 0.2.3 → 0.2.5

package/packages/subagent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hüseyin Sönmez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/subagent/README.md

@@ -0,0 +1,17 @@
+# pi-subagent
+
+Part of [pi-suite](../../README.md). Turn it off with `/suite off subagent`.
+
+One tool, `agent`, that hands a task to a fresh copy of Pi and gives back its final answer as text. Wide searches, heavy reading and independent reviews happen in their context rather than yours. There's nothing to set up, and no agents to define.
+
+| `type` | What it can do |
+| --- | --- |
+| `explore` (the default) | Only `read`, `grep`, `find` and `ls`. Also allowed in `plan` and `read-only` |
+| `general` | Everything, under your permission rules. Blocked in `plan` and `read-only` |
+
+- **Parallel:** several calls in one message run at once.
+- **Model:** it uses the session's model and reasoning. With `router/auto`, that's the `subagent` role in `/router`, so a cheaper model can do the reading.
+- **Permissions:** a child's asks come to your session, and `auto` carries over to it.
+- **Limits:** a child can't start its own agents, its answer is cut at 30,000 characters, it isn't saved as a session, and it starts as fast as Pi does. For long work in the background, use [pi-board](../board/README.md).
+
+If you have `pi-subagents` installed, remove it, or the model has two tools for the same job.

package/packages/subagent/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@huseynsnmz/pi-subagent",
+  "version": "0.1.0",
+  "description": "One simple tool for handing a task to a fresh agent.",
+  "type": "module",
+  "license": "MIT",
+  "private": true,
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test test/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.0",
+    "@types/node": "26.6.6",
+    "typescript": "7.0.2",
+    "typebox": "1.4.3"
+  }
+}

package/packages/subagent/src/index.ts

@@ -0,0 +1,85 @@
+/** One tool, `agent`: hands a task to a fresh copy of Pi, and gives back its final answer as text. */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const READ_ONLY_TOOLS = ["read", "grep", "find", "ls"];
+const ANSWER_CHARS = 30_000;
+const ERROR_CHARS = 500;
+
+export interface ChildOptions {
+  type: "explore" | "general";
+  model?: string;
+  thinking?: string;
+}
+
+/** The prompt goes in on stdin, so it can't be taken for a flag and doesn't show in the process list. */
+export function childArgs({ type, model, thinking }: ChildOptions): string[] {
+  return ["-p", "--no-session", ...(model === undefined ? [] : ["--model", model]), ...(thinking === undefined ? [] : ["--thinking", thinking]), ...(type === "explore" ? ["--tools", READ_ONLY_TOOLS.join(",")] : [])];
+}
+
+/** The mode a child runs in. Plan's only way out is a person, so its explore agents just read, and yolo has to be asked for. */
+function childMode(mode: string): string {
+  if (mode === "plan") return "read-only";
+  return mode === "yolo" ? "normal" : mode;
+}
+
+/** How the permission system and pi-router know this is a child, and pi-modes knows its mode. */
+export function childEnv(base: NodeJS.ProcessEnv, parentSession: string, mode: string | undefined): NodeJS.ProcessEnv {
+  return { ...base, PI_SUBAGENT_CHILD: "1", PI_SUBAGENT_PARENT_SESSION: parentSession, ...(mode === undefined ? {} : { PI_MODES_START: childMode(mode) }) };
+}
+
+export function trimAnswer(answer: string): string {
+  const text = answer.trim();
+  return text.length > ANSWER_CHARS ? `${text.slice(0, ANSWER_CHARS)}\n[The answer was cut at ${ANSWER_CHARS} characters.]` : text;
+}
+
+export function runChild(cwd: string, command: string[], env: NodeJS.ProcessEnv, prompt: string, signal: AbortSignal | undefined): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, command, { cwd, env, stdio: ["pipe", "pipe", "pipe"], signal });
+    let out = "";
+    let err = "";
+    // A character can be split across two chunks.
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (data) => (out += data));
+    child.stderr.on("data", (data) => (err = (err + data).slice(-ERROR_CHARS)));
+    child.stdin.on("error", () => {}); // It can exit before reading. Its exit code says why.
+    child.on("error", (error) => reject(signal?.aborted ? new Error("The agent was stopped.") : error));
+    child.on("close", (code) => {
+      if (code !== 0) return reject(new Error(`The agent failed: ${err.trim() || `exit code ${code}`}`));
+      if (out.trim() === "") return reject(new Error("The agent gave no answer."));
+      resolve(trimAnswer(out));
+    });
+    child.stdin.end(prompt);
+  });
+}
+
+export default function piSubagent(pi: ExtensionAPI): void {
+  // A child's job is its own task. Agents starting agents is how a small task gets a big bill.
+  if (process.env.PI_SUBAGENT_CHILD === "1") return;
+
+  pi.registerTool({
+    name: "agent",
+    label: "Agent",
+    description:
+      "Hand a task to a fresh agent, and get back its final answer as text. It starts with none of this conversation, so the prompt must say everything it needs, and what to report. Use it for wide searches, for reading a lot, and for an independent review, so all that doesn't fill this context. Several calls in one message run at once. Don't use it for what a direct tool call or two can answer.",
+    parameters: Type.Object({
+      description: Type.String({ description: "What it's doing, in 3 to 5 words" }),
+      prompt: Type.String({ description: "The whole task, standing on its own" }),
+      type: Type.Optional(Type.Union([Type.Literal("explore"), Type.Literal("general")], { description: "explore (the default) can only read. general can also edit and run commands, under the same permission rules" })),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const probe: { mode?: string } = {};
+      pi.events.emit("pi-modes:mode", probe);
+      const model = ctx.model === undefined ? undefined : `${ctx.model.provider}/${ctx.model.id}`;
+      const args = childArgs({ type: params.type ?? "explore", model, thinking: pi.getThinkingLevel() });
+      // Pi may run from a compiled binary, with no script to name.
+      const script = process.argv[1];
+      const command = script !== undefined && existsSync(script) ? [script, ...args] : args;
+      const answer = await runChild(ctx.cwd, command, childEnv(process.env, ctx.sessionManager.getSessionId(), probe.mode), params.prompt, signal);
+      return { content: [{ type: "text" as const, text: answer }], details: {} };
+    },
+  });
+}

package/packages/web/README.md

@@ -9,7 +9,7 @@ A web page can hold instructions aimed at the AI reading it. So a separate model
 ## Install
 
 ```bash
-pi install npm:@huseynsnmz/pi-suite@0.2.3
+pi install npm:@huseynsnmz/pi-suite@0.2.5
 ```
 
 `web_fetch` works straight away. It reads pages with the session's model, unless you set `readerModel` or use [pi-router](https://github.com/huseynsnmz/pi-suite/tree/main/packages/router), which can choose the reader. `web_search` stays off until you choose where searches go.

package/src/index.ts

@@ -1,4 +1,4 @@
-// One package, seven parts. A part that's off isn't even imported, so it adds no tools, prompts or start-up time.
+// One package, many parts. A part that's off isn't even imported, so it adds no tools, prompts or start-up time.
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";

package/src/settings.ts

@@ -11,6 +11,7 @@ export const PARTS = {
   frame: "The start card, framed editor, tool boxes, footer and todo list",
   board: "The board of agent sessions",
   commands: "/clear and /security-review",
+  subagent: "The agent tool: hand a task to a fresh agent, and get its answer back",
   subscription: "Claude models on your Claude login, asking before anything is billed as extra usage",
 } as const;