@ssk_dev/pi-subagents-lean 0.16.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kunkun9527
+
+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/README.md

@@ -0,0 +1,87 @@
+# @ssk_dev/pi-subagents-lean
+
+> **Lean Pi subagent plugin, same functionality — 268 initialization tokens, 81% fewer than the original.**
+> [See my full setup for Pi](https://github.com/kunkun9527/my-lean-pi-setup)
+
+[简体中文](README.zh-CN.md)
+
+A token-lean Pi facade over [`@tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents). It keeps the complete upstream subagent runtime and routes its provider-facing operations through one compact schema.
+
+## What it keeps
+
+- Upstream subagent discovery, spawning, background execution, result retrieval, steering, rendering, and lifecycle behavior.
+- The upstream `Agent`, `get_subagent_result`, and `steer_subagent` operations behind one `subagent` facade.
+- Full advanced parameters through on-demand `help` and JSON input.
+
+This package does **not** replace the upstream runtime with a minimal implementation. It only reduces the persistent model-facing tool surface.
+
+## Install
+
+```bash
+pi install npm:@ssk_dev/pi-subagents-lean
+```
+
+Do not load it together with another `pi-subagents` wrapper, or subagent tools may be registered twice.
+
+## Use
+
+The model sees one tool:
+
+```text
+subagent
+```
+
+Supported operations are `run`, `result`, `steer`, and `help`.
+
+```json
+{
+  "op": "run",
+  "prompt": "Find the implementation of the cache key.",
+  "description": "Locate cache key",
+  "subagent_type": "Explore",
+  "run_in_background": true
+}
+```
+
+Use `result` with `agent_id` to inspect a completed run and `steer` with `agent_id` plus `message` to redirect a running agent. Use `help` for advanced upstream parameters.
+
+## Important: review your agent definitions
+
+The upstream runtime can discover built-in agents and custom agents from global, workspace, and project Pi locations. This repository does not ship your private agents, sessions, or memory, but it intentionally preserves that upstream discovery behavior.
+
+After installation:
+
+1. Inspect every discovered agent definition and set its `model` to a provider/model available in your Pi environment.
+2. Delete agent types you do not want.
+3. Rename or modify agent types, prompts, tools, and extension lists to match your workflow.
+4. Check duplicate names: a custom agent with the same name may override a built-in type depending on upstream discovery precedence.
+
+The upstream package includes built-in `general-purpose`, `Explore`, and `Plan` definitions; your installation may expose additional custom types.
+
+## Measured initialization footprint
+
+With only this extension enabled, its recurring model-facing initialization contribution is:
+
+| Model-facing tool | Lean | Upstream `@tintinweb/pi-subagents@0.16.1` |
+| --- | ---: | ---: |
+| Facade / `Agent` | `subagent`: 268 | `Agent`: 1,111 |
+| Result retrieval | Included in facade | `get_subagent_result`: 149 |
+| Steering | Included in facade | `steer_subagent`: 156 |
+| **Total** | **268** | **1,416** |
+
+That is **1,148 fewer tokens (81.1%)** than the pinned upstream extension. The measurement used Pi 0.84.4 and `pi-context-view@0.4.3` in a fresh isolated session, excluding Pi built-in tools, skills, context files, messages, and unrelated extensions. Context View estimates text as `ceil(characters / 4)`, so these are reproducible context-footprint estimates rather than exact GPT tokenizer counts. Runtime-only UI and slash commands are not included because they are not sent to the model.
+
+## Versions
+
+The upstream runtime is pinned to `@tintinweb/pi-subagents@0.16.1`.
+
+## Development
+
+```bash
+npm ci
+npm run check
+```
+
+## License and upstream
+
+MIT. This project wraps the MIT-licensed [`@tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).

package/README.zh-CN.md

@@ -0,0 +1,87 @@
+# @ssk_dev/pi-subagents-lean
+
+> **Lean Pi subagent 插件，功能相同：268 个初始化 tokens，较原插件减少 81%。**
+> **整套配置：** [查看 Pi Lean Setup](https://github.com/kunkun9527/my-lean-pi-setup)
+
+[English](README.md)
+
+[`@tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) 的 token 精简版 Pi facade。它保留完整的上游 subagent 运行时，并通过一个紧凑 schema 路由面向模型的操作。
+
+## 保留的能力
+
+- 上游的 subagent 发现、启动、后台执行、结果获取、steering、渲染和生命周期行为。
+- 通过一个 `subagent` facade 提供上游 `Agent`、`get_subagent_result` 和 `steer_subagent` 操作。
+- 通过按需 `help` 和 JSON input 使用完整高级参数。
+
+本包**不会**用最小化实现替换上游运行时，只减少长期存在的模型可见工具表面。
+
+## 安装
+
+```bash
+pi install npm:@ssk_dev/pi-subagents-lean
+```
+
+不要同时加载另一个 `pi-subagents` 包装层，否则 subagent 工具可能被重复注册。
+
+## 使用
+
+模型只看到一个工具：
+
+```text
+subagent
+```
+
+支持的操作为 `run`、`result`、`steer` 和 `help`。
+
+```json
+{
+  "op": "run",
+  "prompt": "Find the implementation of the cache key.",
+  "description": "Locate cache key",
+  "subagent_type": "Explore",
+  "run_in_background": true
+}
+```
+
+使用带 `agent_id` 的 `result` 查看已完成任务；使用带 `agent_id` 和 `message` 的 `steer` 调整运行中的 agent。高级上游参数通过 `help` 查看。
+
+## 重要：检查你的 agent 定义
+
+上游运行时可以从全局、workspace 和项目 Pi 位置发现内置及自定义 agents。本仓库不会携带你的私有 agents、sessions 或 memory，但会有意保留这种上游发现行为。
+
+安装后：
+
+1. 检查每个被发现的 agent 定义，将其 `model` 设置为你的 Pi 环境中可用的供应商/模型。
+2. 删除你不需要的 agent 类型。
+3. 按工作流重命名或修改 agent 类型、提示词、工具和扩展列表。
+4. 检查重名：根据上游发现优先级，同名自定义 agent 可能覆盖内置类型。
+
+上游包包含内置 `general-purpose`、`Explore` 和 `Plan` 定义；你的安装还可能暴露其他自定义类型。
+
+## 实测初始化上下文占用
+
+仅启用本扩展时，它持续贡献给模型的初始化上下文为：
+
+| 模型可见工具 | Lean | 上游 `@tintinweb/pi-subagents@0.16.1` |
+| --- | ---: | ---: |
+| Facade / `Agent` | `subagent`：268 | `Agent`：1,111 |
+| 结果获取 | 已包含在 facade 中 | `get_subagent_result`：149 |
+| Steering | 已包含在 facade 中 | `steer_subagent`：156 |
+| **合计** | **268** | **1,416** |
+
+相比固定版本的上游扩展，减少 **1,148 tokens（81.1%）**。测量使用 Pi 0.84.4 和 `pi-context-view@0.4.3`，在全新隔离会话中只启用目标扩展，并排除 Pi 内置工具、skills、context files、消息及无关扩展。Context View 按 `ceil(字符数 / 4)` 估算，因此这些是可复现的上下文占用估值，不是 GPT tokenizer 的精确计数。未计入不会发送给模型的纯运行时 UI 和 slash commands。
+
+## 版本
+
+上游运行时固定为 `@tintinweb/pi-subagents@0.16.1`。
+
+## 开发
+
+```bash
+npm ci
+npm run check
+```
+
+## 许可证与上游
+
+MIT。本项目包装了采用 MIT 许可证的 [`@tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents)。

package/index.ts

@@ -0,0 +1,161 @@
+// pi-subagents-lean: one provider-facing facade over the full subagents runtime.
+// Complete operation schemas stay local and are disclosed through help on demand.
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import subagents from "@tintinweb/pi-subagents/src/index.ts";
+import { Text } from "@earendil-works/pi-tui";
+
+type CapturedTool = ToolDefinition<any, any, any>;
+type UpstreamExtension = (pi: ExtensionAPI) => void;
+type FacadeOperation = "run" | "result" | "steer" | "help";
+
+const FACADE_PARAMETERS = Type.Object({
+  op: Type.Unsafe<FacadeOperation>({
+    type: "string",
+    enum: ["run", "result", "steer", "help"],
+  }),
+  prompt: Type.Optional(Type.String({ description: "Task for run." })),
+  description: Type.Optional(Type.String({ description: "3-5 word UI label for run." })),
+  subagent_type: Type.Optional(
+    Type.String({ description: "general-purpose, Explore, Plan, or a custom agent type." }),
+  ),
+  run_in_background: Type.Optional(Type.Boolean()),
+  agent_id: Type.Optional(Type.String()),
+  message: Type.Optional(Type.String()),
+  input: Type.Optional(Type.String({ description: "JSON object string for advanced parameters." })),
+});
+
+function capturePi(pi: ExtensionAPI, tools: Map<string, CapturedTool>): ExtensionAPI {
+  return new Proxy(pi, {
+    get(target, property, receiver) {
+      if (property === "registerTool") {
+        return (tool: CapturedTool) => {
+          tools.set(tool.name, tool);
+        };
+      }
+      const value = Reflect.get(target, property, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+function renderParams(params: Record<string, unknown>): Record<string, unknown> {
+  const { op: _op, input, ...common } = params;
+  if (typeof input !== "string" || !input) return common;
+  try {
+    const parsed = JSON.parse(input) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? { ...(parsed as Record<string, unknown>), ...common }
+      : common;
+  } catch {
+    return common;
+  }
+}
+
+export function createSubagentsFacade(
+  upstream: UpstreamExtension = subagents,
+): (pi: ExtensionAPI) => void {
+  return (pi: ExtensionAPI): void => {
+    const tools = new Map<string, CapturedTool>();
+    upstream(capturePi(pi, tools));
+
+    const facadeTool: ToolDefinition<typeof FACADE_PARAMETERS, any, any> = {
+      name: "subagent",
+      label: "Subagent",
+      description: "Launch, inspect, or steer a subagent. Use help for advanced parameters.",
+      parameters: FACADE_PARAMETERS,
+      promptGuidelines: [
+        "run requires prompt, description (3-5 words), and subagent_type; use a matching agent for broad work, and direct tools when the target is known.",
+        "Put advanced options in input as a JSON object; direct fields override duplicate JSON keys. result uses agent_id; steer uses agent_id and message. Use help only when advanced parameters are unclear.",
+        "Background completion is notified; never poll or sleep. Summarize results and verify claimed code changes.",
+      ],
+      renderCall(args, theme, context) {
+        const routed = renderParams(args);
+        const toolName = args.op === "result"
+          ? "get_subagent_result"
+          : args.op === "steer"
+            ? "steer_subagent"
+            : "Agent";
+        const target = tools.get(toolName);
+        if (target?.renderCall) {
+          return target.renderCall(routed, theme, { ...context, args: routed });
+        }
+        return new Text(theme.fg("toolTitle", `subagent ${args.op}`), 0, 0);
+      },
+      renderResult(result, options, theme, context) {
+        const facadeArgs = context.args;
+        const routed = renderParams(facadeArgs);
+        const toolName = facadeArgs.op === "result"
+          ? "get_subagent_result"
+          : facadeArgs.op === "steer"
+            ? "steer_subagent"
+            : "Agent";
+        const target = tools.get(toolName);
+        if (target?.renderResult) {
+          return target.renderResult(result, options, theme, { ...context, args: routed });
+        }
+        const text = result.content
+          .filter((entry): entry is { type: "text"; text: string } => entry.type === "text")
+          .map((entry) => entry.text)
+          .join("\n");
+        return new Text(text, 0, 0);
+      },
+      async execute(callId, params, signal, onUpdate, ctx) {
+        if (params.op === "help") {
+          const requested = params.input?.trim();
+          const helpToolName = requested === "run"
+            ? "Agent"
+            : requested === "result"
+              ? "get_subagent_result"
+              : requested === "steer"
+                ? "steer_subagent"
+                : undefined;
+          const helpTool = helpToolName ? tools.get(helpToolName) : undefined;
+          const text = helpTool
+            ? `${requested} -> ${helpToolName}\n\n${helpTool.description ?? ""}\n\nParameters:\n${JSON.stringify(helpTool.parameters, null, 2)}`
+            : "Subagent operations: run, result, steer. Use op=help with input set to one operation for its complete parameters.";
+          return { content: [{ type: "text", text }], details: {} };
+        }
+        const toolName = params.op === "result"
+          ? "get_subagent_result"
+          : params.op === "steer"
+            ? "steer_subagent"
+            : "Agent";
+        const target = tools.get(toolName);
+        if (!target) {
+          return {
+            content: [{ type: "text", text: `subagent operation is unavailable: ${params.op}` }],
+            details: {},
+          };
+        }
+        const { op: _op, input, ...common } = params;
+        let advanced: Record<string, unknown> = {};
+        if (input) {
+          try {
+            const parsed = JSON.parse(input) as unknown;
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+              throw new Error("expected a JSON object");
+            }
+            advanced = parsed as Record<string, unknown>;
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`subagent input is invalid JSON: ${message}`);
+          }
+        }
+        const routedParams = { ...advanced, ...common };
+        const validationErrors = [...Value.Errors(target.parameters, routedParams)];
+        if (validationErrors.length > 0) {
+          const summary = validationErrors
+            .map((error) => `${error.path || "/"}: ${error.message}`)
+            .join("; ");
+          throw new Error(`subagent ${params.op} parameters are invalid: ${summary}`);
+        }
+        return target.execute(callId, routedParams, signal, onUpdate, ctx);
+      },
+    };
+    pi.registerTool(facadeTool);
+  };
+}
+
+export default createSubagentsFacade();

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ssk_dev/pi-subagents-lean",
+  "version": "0.16.1",
+  "type": "module",
+  "description": "Lean Pi subagent plugin, same functionality — 268 initialization tokens, 81% fewer than the original.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "kunkun9527",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kunkun9527/pi-subagents-lean.git"
+  },
+  "homepage": "https://github.com/kunkun9527/pi-subagents-lean#readme",
+  "bugs": {
+    "url": "https://github.com/kunkun9527/pi-subagents-lean/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "subagents",
+    "multi-agent",
+    "token-efficient"
+  ],
+  "files": [
+    "index.ts",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "check": "npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.52",
+    "@tintinweb/pi-subagents": "0.16.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.1 <1.0.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.1 <1.0.0",
+    "@earendil-works/pi-tui": ">=0.84.1 <1.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.3",
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-tui": "0.84.3",
+    "jiti": "2.7.0",
+    "typescript": "5.9.3"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}