@maxiaochao/pi-toolkit 0.9.3 → 0.9.4

package/{extensions → packages}/codex-edit/codex-edit-explainer.html

@@ -135,20 +135,20 @@ footer { max-width: 1180px; margin: 0 auto; padding: 0 26px 54px; color: var(--m
   <div class="topbar-inner">
     <div class="brand">Pi <span>apply_patch</span> 方案说明</div>
     <nav class="nav" aria-label="页面导航">
-      <a href="#answer">结论</a><a href="#architecture">架构</a><a href="#config">配置</a><a href="#principle">原理</a><a href="#evidence">数据</a>
+      <a href="#answer">结论</a><a href="#install">安装</a><a href="#architecture">架构</a><a href="#config">配置</a><a href="#principle">原理</a><a href="#evidence">数据</a>
     </nav>
   </div>
 </header>
 <main>
   <section class="hero-grid" id="answer">
     <div>
-      <div class="eyebrow">GPT-5.6 / Pi / Codex-style editing</div>
+      <div class="eyebrow">GPT-5.6 / Pi / Codex harness apply_patch</div>
       <h1>它变好了，但改善主要在“第一次编辑能不能正确开始”。</h1>
-      <p class="lede">公平对照下，apply_patch 没有提升最终正确率，却把 GPT-5.6 的首次编辑成功率从 85% 提到 95%，并消除了观察到的编辑协议失败。它适合作为 GPT/Codex 模型的候选工具，不应无条件替代所有模型的 edit。</p>
+      <p class="lede">这个扩展让选中的 GPT 模型在 Pi 中使用与 Codex harness 相同的 apply_patch 协议；其他模型仍使用 Pi 原生 edit。公平对照下，GPT-5.6 的首次编辑成功率从 85% 提到 95%，并消除了观察到的编辑协议失败。</p>
     </div>
     <aside class="signal">
-      <strong>当前包状态：可安装，按模型路由</strong>
-      <p>这个 npm 包包含真正的 apply_patch extension。安装后，GPT/Codex 模型按配置使用 apply_patch，其他模型继续使用 edit。</p>
+      <strong>当前状态：根包内置，也可单独安装</strong>
+      <p><code>@maxiaochao/pi-toolkit</code> 默认包含本扩展；只需要 apply_patch 时可安装 <code>@maxiaochao/pi-codex-edit</code>。两种方式使用同一份实现。</p>
     </aside>
   </section>
 
@@ -161,6 +161,26 @@ footer { max-width: 1180px; margin: 0 auto; padding: 0 26px 54px; color: var(--m
     </div>
   </section>
 
+  <section class="section" id="install">
+    <div class="section-head"><div><div class="eyebrow">Distribution</div><h2>完整工具包与独立子包二选一</h2></div><p class="section-note">同时安装没有额外收益，还可能重复注册 <code>apply_patch</code>。</p></div>
+    <div class="explain">
+      <article class="panel">
+        <span class="badge green">完整工具包</span>
+        <h3 style="margin-top:16px">随 pi-toolkit 默认加载</h3>
+        <div class="code-wrap"><button class="copy" data-copy="toolkit-install">复制</button><pre id="toolkit-install">pi install npm:@maxiaochao/pi-toolkit
+pi update npm:@maxiaochao/pi-toolkit</pre></div>
+        <p>根 manifest 直接加载 <code>packages/codex-edit/extensions/codex-edit.ts</code>。只有发布了新的 toolkit 版本，根包用户才会收到 Codex Edit 更新。</p>
+      </article>
+      <article class="panel">
+        <span class="badge amber">独立子包</span>
+        <h3 style="margin-top:16px">只安装 Codex Edit</h3>
+        <div class="code-wrap"><button class="copy" data-copy="child-install">复制</button><pre id="child-install">pi install npm:@maxiaochao/pi-codex-edit
+pi update npm:@maxiaochao/pi-codex-edit</pre></div>
+        <p>子包拥有独立版本和发布流程。只发布子包不会更新已安装的 toolkit；实现或配置变更需要分别发布两个 npm 包。</p>
+      </article>
+    </div>
+  </section>
+
   <section class="section">
     <div class="section-head"><div><div class="eyebrow">先解释指标</div><h2>“编辑协议失败：1 → 0”到底是什么？</h2></div><p class="section-note">这是本次 benchmark 自定义的分类名，不是 HTTP、Responses API 或 custom tool 协议错误。</p></div>
     <div class="explain">
@@ -187,7 +207,7 @@ footer { max-width: 1180px; margin: 0 auto; padding: 0 26px 54px; color: var(--m
       <div class="arch-row">
         <div class="arch-node"><small>01 · Model state</small><strong>当前模型配置</strong><p>ctx.model.provider、api、id、compat 能力标记。</p></div>
         <div class="arch-arrow">→</div>
-        <div class="arch-node"><small>02 · Routing</small><strong>syncEditorTools()</strong><p>命中的 GPT/Codex 模型启用 apply_patch；其他模型启用 edit。</p></div>
+        <div class="arch-node"><small>02 · Routing</small><strong>syncEditorTools()</strong><p>ID glob 和 Responses API 均命中时启用 apply_patch；其他模型启用 Pi edit。</p></div>
         <div class="arch-arrow">→</div>
         <div class="arch-node"><small>03 · Provider</small><strong>Responses serializer</strong><p>Grammar 支持时序列化为 type=custom + Lark definition，否则回退为普通 function tool。</p></div>
         <div class="arch-arrow">→</div>
@@ -210,51 +230,52 @@ footer { max-width: 1180px; margin: 0 auto; padding: 0 26px 54px; color: var(--m
   </section>
 
   <section class="section" id="config">
-    <div class="section-head"><div><div class="eyebrow">Configuration</div><h2>当前配置与可选扩展</h2></div><p class="section-note">默认只为已稳定验证的 Sol High 启用；Luna 的性能结果存在长尾波动，需要显式 opt-in。</p></div>
+    <div class="section-head"><div><div class="eyebrow">Configuration</div><h2>当前模型路由</h2></div><p class="section-note">默认覆盖 Responses API 上的全部 <code>gpt-5.6-*</code> 变体；provider 不参与匹配。</p></div>
     <div class="tabs" role="tablist" aria-label="配置视图">
       <button class="tab" role="tab" aria-selected="true" aria-controls="config-current" id="tab-current">当前实际配置</button>
-      <button class="tab" role="tab" aria-selected="false" aria-controls="config-recommended" id="tab-recommended">Luna 显式启用</button>
+      <button class="tab" role="tab" aria-selected="false" aria-controls="config-recommended" id="tab-recommended">添加模型</button>
       <button class="tab" role="tab" aria-selected="false" aria-controls="config-route" id="tab-route">路由规则</button>
     </div>
     <div class="tab-panel active" id="config-current" role="tabpanel" aria-labelledby="tab-current">
       <div class="code-wrap"><button class="copy" data-copy="current-config">复制</button><pre id="current-config">{
   "enabled": true,
   "models": [
-    { "provider": "pudu-openai-proxy", "model": "gpt-5.6-sol" }
+    "gpt-5.6-*"
   ]
 }</pre></div>
-      <div class="callout">models.json 中的 provider API key 不在页面展示。建议使用环境变量或 Pi auth 存储，并轮换已经出现在配置文件中的 key。</div>
+      <div class="callout">路由还要求 <code>model.api</code> 为 <code>openai-responses</code> 或 <code>openai-codex-responses</code>。grammar 不可用时 Pi 回退为普通 function tool。</div>
     </div>
     <div class="tab-panel" id="config-recommended" role="tabpanel" aria-labelledby="tab-recommended">
       <div class="code-wrap"><button class="copy" data-copy="recommended-config">复制</button><pre id="recommended-config">{
   "enabled": true,
   "models": [
-    { "provider": "pudu-openai-proxy", "model": "gpt-5.6-sol" },
-    { "provider": "pudu-openai-proxy", "model": "gpt-5.6-luna" }
+    "gpt-5.6-*",
+    "gpt-5.7-*",
+    "my-codex-model"
   ]
 }</pre></div>
-      <p>Luna High 的有效重测中，两组都 20/20 正常结束，最终正确率都是 18/20；首次编辑成功率为 edit 90%、apply_patch 100%。按 17 个两组都正确的配对样本，apply_patch 中位总耗时多 2.3s；按全部 20 个配对样本，中位多 1.2s，9 例更快、11 例更慢。因此 Luna 有协议适配收益，但没有稳定的总耗时优势，当前不默认启用。</p>
+      <p>每项按完整 <code>model.id</code> 做区分大小写的匹配，<code>*</code> 是通配符。精确 ID 也可以直接作为规则。添加规则只改变路由，不代表模型已经通过协议验证；未命中规则的模型继续使用 Pi 原生 <code>edit</code>。</p>
     </div>
     <div class="tab-panel" id="config-route" role="tabpanel" aria-labelledby="tab-route">
       <div class="code-wrap"><button class="copy" data-copy="route-rule">复制</button><pre id="route-rule">model = ctx.model
 
 if enabled
 and model.api in ["openai-responses", "openai-codex-responses"]
-and provider/model matches allowlist:
+and model.id matches any models glob:
     active = ["apply_patch"]
 else:
     active = ["edit"]
 
 # Preserve all unrelated active tools.
 # Register both tools permanently for session replay.</pre></div>
-      <p>切换发生在 <code>session_start</code> 和 <code>model_select</code>。不重新定义同名工具，只改变 active tool 集合。</p>
+      <p><code>provider</code> 不参与匹配；即使 ID 命中，其他 API 上的模型仍使用 Pi <code>edit</code>。切换发生在 <code>session_start</code> 和 <code>model_select</code>。独立包修改 <code>config.json</code>，完整 toolkit 修改 <code>packages/codex-edit/config.json</code>，但包更新可能覆盖本地配置。</p>
     </div>
   </section>
 
   <section class="section" id="principle">
     <div class="section-head"><div><div class="eyebrow">Design principles</div><h2>这个工具的三个核心原则</h2></div></div>
     <div class="principles">
-      <article class="principle"><h3>模型协议对齐</h3><p>GPT/Codex 模型不再被要求适应 Pi 自定义的 <code>oldText/newText</code> JSON；它看到原生的 <code>apply_patch</code> 名称和 patch grammar。</p></article>
+      <article class="principle"><h3>模型协议对齐</h3><p>选中的 GPT 模型不再被要求适应 Pi 自定义的 <code>oldText/newText</code> JSON；它看到与 Codex harness 相同的 <code>apply_patch</code> 名称和 patch grammar。</p></article>
       <article class="principle"><h3>执行端独立防护</h3><p>grammar 不是安全策略。执行端仍要做 workspace 边界、符号链接、目录、覆盖冲突、权限和取消检查。</p></article>
       <article class="principle"><h3>按能力选择，不靠 AGENTS 对抗</h3><p>不在 AGENTS 中要求模型“不要使用 apply_patch”。扩展只让模型看到适合自己的一个编辑工具，避免两套协议同时暴露。</p></article>
     </div>
@@ -276,7 +297,7 @@ else:
       </tbody>
     </table>
     <div class="panel" style="margin-top:18px">
-      <div class="status"><i></i>最终判断：候选实现保留，默认自动启用暂不打开</div>
+      <div class="status"><i></i>最终判断：已投入使用，但只对 allowlist 中的 GPT/Codex 模型路由 apply_patch</div>
       <p>本页的耗时比较优先使用同一 fixture 的配对差值，避免两组成功样本构成不同造成中位数偏差。runner 的 180s 进程上限是删失边界，不是 API timeout；本次有效 Luna 重测没有触发该上限。</p>
     </div>
   </section>
@@ -284,9 +305,9 @@ else:
   <section class="section">
     <div class="section-head"><div><div class="eyebrow">Files</div><h2>实现位置</h2></div></div>
     <div class="panel">
-      <p><code>extensions/codex-edit/index.ts</code>：工具注册、执行、防护、renderer 和模型路由。</p>
-      <p><code>extensions/codex-edit/parser.ts</code>：patch grammar 对应的 parser、hunk matcher 和 workspace path resolver。</p>
-      <p><code>extensions/codex-edit/tests/parser.test.mjs</code>：6 个纯函数/文件操作测试，当前全部通过。</p>
+      <p><code>packages/codex-edit/extensions/codex-edit.ts</code>：工具注册、执行、防护、renderer 和模型路由。</p>
+      <p><code>packages/codex-edit/src/parser.ts</code>：patch grammar 对应的 parser、hunk matcher 和 workspace path resolver。</p>
+      <p><code>packages/codex-edit/tests/parser.test.mjs</code>：12 个 parser、matcher、路径与结构重构测试，当前全部通过。</p>
       <p><code>/home/maxiaochao/.pi/agent/evaluations/gpt-edit-benchmark/report-final.md</code>：最终 benchmark 报告。</p>
     </div>
   </section>

package/{extensions/codex-edit/index.ts → packages/codex-edit/extensions/codex-edit.ts}

@@ -13,11 +13,11 @@ import {
   applyUpdate,
   parsePatch,
   resolveWorkspacePath,
-} from "./parser.ts";
-import { modelIsAllowed } from "./model-routing.ts";
+} from "../src/parser.ts";
+import { modelIsAllowed } from "../src/model-routing.ts";
 
 const editorToolNames = new Set(["edit", "apply_patch"]);
-const settingsUrl = new URL("./config.json", import.meta.url);
+const settingsUrl = new URL("../config.json", import.meta.url);
 
 async function loadSettings() {
   try {

package/packages/codex-edit/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@maxiaochao/pi-codex-edit",
+  "version": "0.1.7",
+  "description": "Pi extension that exposes Codex-style apply_patch for GPT/Codex models with model-aware edit fallback.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "codex",
+    "gpt-5",
+    "apply-patch"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "docs",
+    "config.json",
+    "summary.md",
+    "codex-edit-explainer.html",
+    "README.md",
+    "TESTING.md",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
+    "directory": "packages/codex-edit"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/codex-edit.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/*.test.mjs",
+    "load-test": "pi -ne -e ./extensions/codex-edit.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/{extensions/codex-edit → packages/codex-edit/src}/parser.ts

@@ -115,8 +115,7 @@ function locate(lines, pattern, start, eof, label) {
   ];
   for (const compare of comparisons) {
     const candidates = findCandidates(lines, pattern, start, eof, compare);
-    if (candidates.length === 1) return candidates[0];
-    if (candidates.length > 1) throw new Error(`Ambiguous ${label || "patch"} match: ${candidates.length} regions found`);
+    if (candidates.length > 0) return candidates[0];
   }
   throw new Error(`Failed to find expected lines${label ? ` in ${label}` : ""}: ${pattern.join("\\n")}`);
 }

package/{extensions → packages}/codex-edit/summary.md

@@ -51,6 +51,6 @@ The probe conditions above reflect v0.1.5, when the route still required grammar
 
 ## Decision
 
-No-go for universal enablement in the original benchmark environment. The evidence did not justify routing every model through `apply_patch` or making it the default editor for the whole Pi workflow. The shipped route is therefore a model-ID allowlist (`gpt-5.6-*` plus an `openai-responses`/`openai-codex-responses` API check) that keeps `edit` as the fallback everywhere else. The implementation now ships inside `@maxiaochao/pi-toolkit` instead of as a standalone opt-in package, but the allowlist — not the packaging — is what bounds the change: for a non-allowlisted model the extension only re-syncs an already-active editor tool and otherwise returns early.
+No-go for universal routing in the original benchmark environment. The evidence did not justify routing every model through `apply_patch` or making it the default editor for the whole Pi workflow. Ship the extension both with `@maxiaochao/pi-toolkit` and as the standalone `@maxiaochao/pi-codex-edit` child package, while bounding activation with a model-ID allowlist (`gpt-5.6-*` plus an `openai-responses`/`openai-codex-responses` API check) and keeping `edit` as the fallback everywhere else.
 
 The production route was validated with `pudu-openai-proxy/gpt-5.6-sol:high` and `pudu-openai-proxy/gpt-5.6-luna:high`. Sol's 20-case fair run improved first editor-call success from 85% to 95% with equal final correctness. A corrected Luna rerun used the fully qualified `pudu-openai-proxy/gpt-5.6-luna:high` in both arms, with 20/20 normally completed runs in each arm: both reached 18/20 final correctness, while first editor-call success was 18/20 for `edit` and 20/20 for `apply_patch`. Among the 17 cases correct in both arms, the paired median total-duration delta was +2.3s for `apply_patch`, with 8 cases faster and 9 slower; across all 20 paired runs, the median delta was +1.2s, with 9 cases faster and 11 slower. The measured tradeoff justified validating Sol first; the shipped `gpt-5.6-*` glob additionally enables Luna and Terra, whose gap is protocol adaptation rather than a stable duration win.

package/{extensions → packages}/codex-edit/tests/package.test.mjs

@@ -2,21 +2,23 @@ import assert from "node:assert/strict";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import test from "node:test";
-import { modelIsAllowed } from "../model-routing.ts";
+import { modelIsAllowed } from "../src/model-routing.ts";
 
-const extensionDir = dirname(dirname(new URL(import.meta.url).pathname));
+const packageDir = dirname(dirname(new URL(import.meta.url).pathname));
 
-test("config is next to the extension entry file", async () => {
-  const source = await readFile(join(extensionDir, "index.ts"), "utf8");
-  assert.match(source, /new URL\("\.\/config\.json", import\.meta\.url\)/);
+test("package points Pi at the extension and config is reachable from it", async () => {
+  const manifest = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
+  assert.deepEqual(manifest.pi.extensions, ["./extensions/codex-edit.ts"]);
+  const source = await readFile(join(packageDir, "extensions/codex-edit.ts"), "utf8");
+  assert.match(source, /new URL\("\.\.\/config\.json", import\.meta\.url\)/);
   assert.match(source, /model-routing\.ts/);
-  const config = JSON.parse(await readFile(join(extensionDir, "config.json"), "utf8"));
+  const config = JSON.parse(await readFile(join(packageDir, "config.json"), "utf8"));
   assert.equal(config.enabled, true);
   assert.deepEqual(config.models, ["gpt-5.6-*"]);
 });
 
 test("matches allowed model IDs with globs independently of provider and grammar support", () => {
-  const settings = { enabled: true, models: ["gpt-5.6-*"] };
+  const settings = { enabled: true, models: ["gpt-5.6-*", "my-codex-model"] };
   const baseModel = {
     id: "gpt-5.6-terra",
     api: "openai-codex-responses",
@@ -34,5 +36,8 @@ test("matches allowed model IDs with globs independently of provider and grammar
   );
   assert.equal(modelIsAllowed({ ...baseModel, api: "openai-completions" }, settings), false);
   assert.equal(modelIsAllowed({ ...baseModel, id: "gpt-5.5" }, settings), false);
+  assert.equal(modelIsAllowed({ ...baseModel, id: "my-codex-model" }, settings), true);
+  assert.equal(modelIsAllowed({ ...baseModel, id: "my-codex-model-v2" }, settings), false);
+  assert.equal(modelIsAllowed({ ...baseModel, id: "GPT-5.6-terra" }, settings), false);
   assert.equal(modelIsAllowed(baseModel, { enabled: false, models: ["gpt-5.6-*"] }), false);
 });

package/{extensions → packages}/codex-edit/tests/parser.test.mjs

@@ -3,7 +3,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { applyUpdate, parsePatch, resolveWorkspacePath } from "../parser.ts";
+import { applyUpdate, parsePatch, resolveWorkspacePath } from "../src/parser.ts";
 
 test("parses add, delete, update, and move operations", () => {
   const operations = parsePatch(`*** Begin Patch
@@ -58,14 +58,111 @@ test("supports insertion chunks and EOF matching", () => {
   assert.equal(applyUpdate("", operations[0].chunks, "file.txt"), "first\n");
 });
 
-test("rejects ambiguous matches and workspace escapes", () => {
+test("uses the first matching region at or after the cursor", () => {
   const operations = parsePatch(`*** Begin Patch
 *** Update File: file.txt
 @@
 -value
 +changed
 *** End Patch`);
-  assert.throws(() => applyUpdate("value\nvalue\n", operations[0].chunks, "file.txt"), /Ambiguous/);
+  assert.equal(applyUpdate("value\nvalue\n", operations[0].chunks, "file.txt"), "changed\nvalue\n");
+});
+
+test("uses earlier hunks to advance the cursor through repeated HTML regions", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: page.html
+@@
+-old
++new
+@@
+ </section>
++<section id="inserted"></section>
+ <section>
+*** End Patch`);
+  const before = `<header>
+old
+</header>
+<section>first</section>
+</section>
+<section>
+one
+</section>
+<section>
+two
+</section>
+`;
+  const after = `<header>
+new
+</header>
+<section>first</section>
+</section>
+<section id="inserted"></section>
+<section>
+one
+</section>
+<section>
+two
+</section>
+`;
+  assert.equal(applyUpdate(before, operations[0].chunks, "page.html"), after);
+});
+
+test("applies a hunk at the first repeated Markdown separator after its cursor", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: SKILL.md
+@@
+-description: old
++description: new
+@@
+ ---
++Inserted after frontmatter.
+*** End Patch`);
+  const before = `---
+name: demo
+description: old
+---
+
+# Demo
+
+---
+Footer
+`;
+  const after = `---
+name: demo
+description: new
+---
+Inserted after frontmatter.
+
+# Demo
+
+---
+Footer
+`;
+  assert.equal(applyUpdate(before, operations[0].chunks, "SKILL.md"), after);
+});
+
+test("parses multiple file operations used by structural refactors", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: extensions/tool.ts
+*** Move to: packages/tool/extensions/tool.ts
+@@
+-export const value = 1;
++export const value = 2;
+*** Add File: extensions/tool-wrapper.ts
++export { value } from "../packages/tool/extensions/tool.ts";
+*** Delete File: extensions/tool.test.ts
+*** End Patch`);
+  assert.deepEqual(
+    operations.map(({ action, path, moveTo }) => ({ action, path, moveTo })),
+    [
+      { action: "update", path: "extensions/tool.ts", moveTo: "packages/tool/extensions/tool.ts" },
+      { action: "add", path: "extensions/tool-wrapper.ts", moveTo: undefined },
+      { action: "delete", path: "extensions/tool.test.ts", moveTo: undefined },
+    ],
+  );
+});
+
+test("rejects workspace escapes", () => {
   assert.equal(resolveWorkspacePath("/tmp/project", "/tmp/project/src/a.js"), "/tmp/project/src/a.js");
   assert.throws(() => resolveWorkspacePath("/tmp/project", "/tmp/other/a.js"), /escapes/);
 });

package/packages/tiny-subagent/CHANGELOG.md

@@ -0,0 +1,12 @@
+## 2026-09-30 - v0.1.1
+
+- Add standalone testing documentation and real production-runner screenshot/demo media.
+- Align the package manifest and root bundle with the shared workspace source.
+
+## 2026-09-01 - v0.1.0
+
+- Add the `tiny_subagents` Pi tool for one focused prompt in a fresh child Pi context.
+- Add package-local `worker.md` personas with model and built-in tool selection.
+- Return structured process, Pi protocol, stderr, stop-reason, exit, signal, and cancellation diagnostics.
+- Preserve oversized stdout, stderr, and final assistant output in private temporary artifacts.
+- Stream child event activity to the TUI and expose persona, prompt, and transcript details when expanded.

package/packages/tiny-subagent/README.md

@@ -0,0 +1,128 @@
+# @maxiaochao/pi-tiny-subagent
+
+A small Pi extension that runs one fresh Pi child process for one focused prompt. It does not use the `pi-subagents` package and does not inherit the parent conversation or extensions.
+
+![Tiny Subagent production runner screenshot](docs/screenshot.png)
+
+## Why this package exists
+
+This is the toolkit's deliberately small subagent model: one persona, one focused prompt, one isolated child context. It avoids a general orchestration framework and keeps child transcript noise out of the parent context while preserving process and protocol diagnostics.
+
+## Demo
+
+![Tiny Subagent demo](docs/demo.gif)
+
+```text
+tiny_subagents({ action: "list" })
+tiny_subagents({
+  agent: "worker",
+  prompt: "Inspect the authentication flow and summarize the risks"
+})
+```
+
+The child receives package-local persona instructions, selected built-in tools, and a fresh context; the parent receives the focused result or structured failure details.
+
+## Install
+
+```bash
+pi install npm:@maxiaochao/pi-tiny-subagent
+```
+
+The full `@maxiaochao/pi-toolkit` package also bundles this extension. Install the full toolkit or this standalone child package, not both.
+
+Update the distribution you installed:
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit       # bundled copy
+pi update npm:@maxiaochao/pi-tiny-subagent # standalone child
+```
+
+The versions are independent. Publishing the child does not update an already published toolkit version.
+
+The package registers one tool: `tiny_subagents`.
+
+## Personas
+
+The default `agents/worker.md` has this shape:
+
+```md
+---
+name: worker
+description: General-purpose worker for one focused task
+tools: read, bash, edit, write, grep, find, ls
+---
+
+You are a focused worker subagent.
+```
+
+The supported frontmatter fields are:
+
+- `name` (required): Persona name passed in the `agent` field.
+- `description` (required): Short description returned by `action: "list"` so the parent model can choose a persona.
+- `model` (optional): Default child model, such as `provider/model:high`. A call-level `model` overrides it; if both are absent, the child inherits the current parent-session model.
+- `tools` (optional): Comma-separated allowlist of Pi built-in tools. Supported values are `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, and `powershell` on Windows. Extension tools such as `contact_supervisor` are not allowed. If omitted, the child uses Pi's default built-in tools.
+
+For example, a read-only reviewer persona can restrict its tools and select a default model:
+
+```md
+---
+name: reviewer
+description: Review code and report correctness risks without modifying files
+model: provider/model:high
+tools: read, grep, find, ls
+---
+
+Review the assigned code. Do not edit files.
+```
+
+Persona files are loaded only from this package's `agents/*.md`; they do not share configuration with `pi-subagents`.
+
+Before execution, the parent model should discover the package-local personas:
+
+```text
+tiny_subagents({ action: "list" })
+```
+
+It can then match the task to a persona by name or description and execute without `action`:
+
+```text
+tiny_subagents({
+  agent: "worker",
+  prompt: "Inspect the authentication flow and summarize the risks"
+})
+```
+
+## Execution
+
+The child is started in the current working directory with a fresh context:
+
+```text
+pi --mode json --print --no-session --no-extensions --no-skills
+```
+
+The selected persona body is passed as an additional system prompt. Only built-in Pi tools can be enabled by `tools` in the persona file.
+
+## Live output
+
+`tiny_subagents` sends a TUI update when the child starts and after each child `message_end` or `tool_result_end` event. While the child is running, the collapsed row shows the latest activity.
+
+Press Pi's `Ctrl+O` tool-output expansion key to inspect the current child execution. The expanded `tiny_subagents` view shows:
+
+- selected persona name and description
+- selected model
+- the task prompt
+- the persona system prompt
+- child assistant tool calls, tool results, and assistant text
+- the final output and errors
+
+This uses Pi's standard tool-output expansion state, so `Ctrl+O` also changes the expanded/collapsed display state of other tool rows. The added content and event tracking are local to `tiny_subagents`; they do not change other tools or the parent model context.
+
+## Errors and large output
+
+Successful calls return the final assistant text. Failures return the Pi error message, stop reason, exit code, signal, stderr, protocol errors, and output produced before failure. Inline output is limited to 16 KiB. If stdout, stderr, or the final answer exceeds that size, the complete files are retained in a private temporary artifact directory and its path, byte counts, and `cleanup: "remove directory when no longer needed"` instruction are returned. Small-result temporary directories are removed automatically.
+
+The child uses the same Pi installation, provider configuration, model catalog, and authentication environment as the parent process. The package only selects the model; it does not define providers or credentials.
+
+## Development and tests
+
+The authoritative implementation is under `extensions/` and `src/`. See [TESTING.md](TESTING.md) for the test strategy, fixture cases, and latest baseline.

package/packages/tiny-subagent/TESTING.md

@@ -0,0 +1,20 @@
+# Tiny Subagent test strategy
+
+## Flow
+
+1. `npm --prefix packages/tiny-subagent test` runs deterministic process and persona tests.
+2. `pi -ne -ns --no-session -e ./packages/tiny-subagent/extensions/tiny-subagent.ts` verifies extension loading.
+3. `npm pack ./packages/tiny-subagent --dry-run` verifies package contents.
+4. Verify the README example and the production-runner media `docs/screenshot.png` and `docs/demo.gif` are present in the tarball.
+
+## Cases
+
+- Resolve package-local personas and validate frontmatter.
+- Start an isolated child Pi process with selected model and tools.
+- Stream child activity while keeping it outside the parent conversation.
+- Preserve detailed process/protocol failures and oversized artifacts.
+- Render collapsed and expanded tool output.
+
+## Latest baseline
+
+All deterministic child-process and persona cases pass. Release validation also requires the extension load check.

package/packages/tiny-subagent/agents/worker.md

@@ -0,0 +1,9 @@
+---
+name: worker
+description: General-purpose worker for one focused task
+tools: read, bash, edit, write, grep, find, ls
+---
+
+You are a focused worker subagent.
+
+Work only on the task in the user prompt. Inspect the current project before making claims. Use the available built-in tools when needed. Do not delegate to another agent. Finish with a concise result, including changes made, validation performed, and any remaining risks.