pi-pier 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# pi-pier
+
+**pier** = **pi** × h**erdr** — a [pi](https://pi.dev/) extension that fuses coding agent sessions with the [herdr](https://herdr.dev/) pane/tab orchestrator.
+
+`pi-pier` is the **pi extension half** of the [pier monorepo](https://github.com/July24/pier). It fills two gaps pi deliberately leaves open — the **todo list loop** and **interactive subagents** — using herdr panes/tabs as the visual and interaction substrate. It degrades gracefully outside herdr.
+
+## Install
+
+```sh
+pi install npm:pi-pier
+```
+
+Or from git:
+
+```sh
+pi install git:github.com/July24/pier
+```
+
+> The companion **herdr plugin half** (`pier.workbench`: main-tab bootstrap, blocked-gate notifications, focus-heat layout) is installed separately via `herdr plugin install July24/pier/packages/pier-workbench`, or all at once with the one-shot installer in the [repo](https://github.com/July24/pier): `node install.mjs`.
+
+## What you get
+
+### Tools
+
+| Tool | Purpose |
+|---|---|
+| `todo_write` | Full-replacement todo list. Session JSONL is the single source of truth; correct rollback on branch switches. Projected live onto the pane title (`▶i ○p ■b ✓c (N/M) · current task`). `/todos` command to view/edit/unblock |
+| `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane (separate context window). Foreground / parallel / background modes |
+| `list_agents` | Live state of background subagents (running / idle + panes) |
+| `send_message` | Follow-up work for a subagent (queued if busy, wakes if idle) |
+| `interrupt_agent` | Stop a subagent's current turn; it stays alive for more messages |
+
+### Behaviors
+
+- **Human-in-the-loop**: every subagent is a visible, interactive TUI pane — step into it anytime to talk directly (fix bugs, take over, answer its `ask_user_question`). Blocked gates raise sidebar markers + notifications
+- **Soft locks**: write paths lock per-pane; conflicts warn/block instead of racing
+- **Role profiles**: built-in `master` / `worker-default`; custom roles mount from `.pi-herdr/roles/<name>.json`. Toolsets converge per role — deny rules cannot be bypassed
+- **Settlement notices folded**: background subagent completions inject between turns (max 3 shown, rest collapsed) instead of flood-filling at run end
+
+## Scope & degradation
+
+Outside a herdr environment the extension auto-degrades: herdr reporting costs nothing, `subagent` / terminal tools return "requires a herdr-managed pane" hints, while `todo_write` / `ask_user_question` keep working (session JSONL as authority, no herdr dependency).
+
+## Requirements
+
+- Node ≥ 22
+- pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
+- herdr ≥ 0.8.0 for the full pane experience (optional)
+
+## Development
+
+```sh
+git clone https://github.com/July24/pier && cd pier
+npm install --ignore-scripts
+npm test   # node --test, ~250 unit tests
+```
+
+See the [monorepo README](https://github.com/July24/pier) for design principles, the herdr-plugin half, and the one-shot installer.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "pi-pier",
+  "version": "0.1.0",
+  "description": "pier: pi extension that fuses pi agent sessions with the herdr pane/tab orchestrator — todo_write loop closure + interactive subagents in isolated panes",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "herdr",
+    "coding-agent",
+    "subagents",
+    "todo"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/July24/pier.git",
+    "directory": "packages/pier-ext"
+  },
+  "homepage": "https://github.com/July24/pier#readme",
+  "bugs": {
+    "url": "https://github.com/July24/pier/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src",
+    "skills",
+    "schemas",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills/pi-herdr-workflow"
+    ]
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/cordis-plugin-group": "^1.0.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "typebox": "~1.3.7"
+  }
+}

package/schemas/role-manifest.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://herdr-pi.local/schemas/role-manifest.schema.json",
+  "title": "herdr-pi role manifest（D76 v2）",
+  "description": "档2 role 档案契约：version（P2 语义版本）+ roleType（P3 planner/executor/hybrid）+ 三态 rules（P1 allow/ask/deny）。运行时校验为 src/role-manifest.ts 手写零依赖实现，本文件是合同文档。",
+  "type": "object",
+  "properties": {
+    "role": { "type": "string", "pattern": "^[a-z0-9-]+$", "description": "角色名，须与文件名一致" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "语义版本 x.y.z" },
+    "model": { "type": "string", "pattern": "^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$", "description": "按角色路由模型 provider/model（WS-D10；可省略 = 进程默认）" },
+    "description": { "type": "string" },
+    "manifest": {
+      "type": "object",
+      "properties": {
+        "tools": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[a-z0-9_-]+$" },
+          "uniqueItems": true,
+          "description": "基线工具；必含 todo_write 与 ask_user_question（协调工具，运行时校验强制）"
+        },
+        "rules": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z0-9_*-]+$" },
+          "additionalProperties": { "enum": ["allow", "ask", "deny"] },
+          "description": "三态权限；* 为通配符默认；可省略 = {\"*\":\"allow\"}"
+        },
+        "unknownTools": {
+          "enum": ["allow", "deny"],
+          "description": "D82 未知工具姿态（缺省 deny）：allow = 用户安装的扩展默认可见可用（master/worker）；deny = 清单外一律不可见。与 rules 的 * 通配分属两轴（可见性 vs 强制力）"
+        }
+      },
+      "required": ["tools"],
+      "additionalProperties": false
+    },
+    "services": {
+      "type": "object",
+      "properties": {
+        "todos": {
+          "type": "object",
+          "properties": {
+            "mode": { "enum": ["serial", "parallel"] },
+            "reminderLimit": { "type": "integer", "exclusiveMinimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["role", "version", "manifest"],
+  "additionalProperties": false
+}

package/skills/pi-herdr-workflow/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: pi-herdr-workflow
+description: >-
+  How to use the pi-herdr workbench fusion: todo_write discipline, subagent
+  delegation (foreground/parallel/background), list_agents/send_message/
+  interrupt_agent, and how the human watches everything in herdr panes.
+  Load when the user asks about multi-step plans, delegating subtasks,
+  background work, or checking on running subagents.
+license: MIT
+---
+
+# pi-herdr 工作台工作流
+
+你在一个 herdr 终端工作区（pane）里运行。本 skill 教你把 `todo_write` 与
+`subagent` 工具用好；人类在 herdr 的 TUI 里实时观察：每个 pane 的窗格头
+显示 `▶x ○y ■b ✓z · 当前任务`，语义状态（working/blocked/idle）上卷到侧边栏。
+
+## 1. todo 纪律（全量替换语义）
+
+- `todo_write` 每次调用提交**完整列表**（last-wins），没有部分更新。
+- 条目 = `content`（非空、唯一、5–10 词的命令式短语，写"做什么"不写"怎么做"，**不带编号前缀**）+ `status`（pending | in_progress | completed | blocked | abandoned）。
+  - `blocked` = 在等外部条件（信息、人、别的系统），必须带 `blocker` 说明等什么；`abandoned` = 显式放弃（不删条目，保留计划痕迹）。
+  - 多阶段计划用可选 `phase` 分组（≤30 字）；单阶段就不写 phase。
+- 保持列表精简（≤15 条）：一条 = 一个有意义的交付单元，不是微步骤。
+- 正在推进的标 `in_progress`（真正并行时才允许多条）；**完成立即标 completed**。
+- **测试失败/实现不完整/有未解决错误时绝不算 completed**——保持 in_progress，或改成 blocked 并说明 blocker。
+- **绝不把 todo_write 当成一轮里的唯一工具调用**——搭着真实工作一起提交。
+- 记不清某条任务的原文时，从上一轮 todo_write 结果里找，**不许凭记忆编**（防幻影条目）。
+- **不要**把已委派给子代理的工作写进自己的 todo——那是子代理自己的职责；
+  你的列表只跟踪你自己的工作。等子代理结果回流后再验收归档。
+- 多子代理协作时在 content 里写清**文件所有权**（例如 "重构 auth 模块（只碰 src/auth/）"），
+  避免两个 agent 抢同一文件。
+- **你是被委派的工作 pane**（`PI_HERDR_SUBAGENT=1`）时，本插件自动执行严格模式：
+  你的列表任何时候**至多一条 in_progress**（多写会被归一化），全部完成会自动晋升下一条 pending。
+  你是主控 pane 时保持并行语义，纪律由本节承担。
+
+## 2. 子代理委派
+
+子代理 pane 跑的是**交互式 pi TUI**（独立会话）：人类可以随时进入该 pane
+直接与子代理对话；你的委派 prompt 会以消息形式出现在它的对话里。
+
+### 选型
+- **前台**（默认）：调用后等待结果返回。适合"下一步依赖其结果"的委派。
+- **后台**（`run_in_background: true`）：立即返回 `agentId`；子代理在独立
+  pane 常驻运行。适合长任务/并行推进。它会**持续存在**（有自己的持久会话），
+  结算时你会收到一条 "Background subagent <id> finished..." 通知消息。
+- 一条消息里的多个 subagent 调用会并行执行（上限 4 并发）。
+- 可选 `role`（如 `advisor`）只是标签：v1 不改工具面、不改生命周期，与普通 task 一样走 TTL；省略 = `task`。复活走 `resume_subagent`，不要假设 pane 会自动补回来。
+
+### 任务 tab 分组（`tab` 参数）
+- 每个委派默认开一个**以任务命名的新 tab**（名字取自 `description`）。
+- 一组相关的子任务用同一个 `tab` 名字收进同一个 tab（例如网络调研 + 现状
+  摸索都用 `tab: "调研"`），人类在 herdr 里一个 tab 内看完全部相关 pane。
+- 名字要短（≤20 字）、人类一眼能懂；tab 栏就是任务板。
+- 不要为了少开 tab 而把无关任务塞进同一个 tab；一个 tab = 一个任务目标。
+- **任务 tab 是临时的**：tab 内全部子代理结算后（默认宽限约 10 分钟）tab
+  会自动关闭——不要假设它的 pane 长期存在；需要回看/继续时用
+  `resume_subagent(taskId)` 从历史复活，而不是引用已关的 pane。
+
+### prompt 纪律
+- prompt 必须**自包含**：子代理看不到你的对话历史，只有这段 prompt。
+- 明确输入（哪些文件/事实）、明确产出（交什么）、明确边界（不碰什么）。
+- 用文件/工件传递共享上下文，不要把大段内容塞进 prompt。
+- 独立任务才委派；互相依赖的工作拆给同一子代理。
+
+### 后台子代理的后续管理
+- `list_agents`：查看全部后台子代理与状态（running/idle）。
+- `send_message(agentId, message)`：给子代理追加任务（FIFO；已结算的子代理
+  会被唤醒继续干）。
+- `interrupt_agent(agentId)`：打断子代理当前轮次（它仍驻留，可继续 send_message）。
+- 子代理结算后不要重新委派同一个 agentId 之外的新任务时，可再 send_message 唤醒。
+
+## 3. 人类闸门
+
+- 需要人类决策（审批、取舍、方向选择）时，用 `ask_user_question`（本插件提供）——
+  等待回答期间，你的 pane 在 herdr 里呈 **blocked** 状态，人类会看到并介入；
+  答案会作为工具结果回到你的上下文，然后继续工作。
+- 子代理 pane 在 herdr 里可被人类直接进入交互；你的委派描述（pane 标签）
+  要写得人类一眼能懂。
+
+## 4. 多 agent 纪律（工程实践映射）
+
+- 你是仲裁者：验收每个子代理的输出，再合入你的工作；不要把仲裁权下放。
+- 关键结论安排独立复核（换个子代理 reviewer 复核），不盲信单一子代理。
+- 同构的并行子代理会犯同样的错：给不同子代理不同的任务边界与产出格式。
+- 委派后继续做你自己的事，不要干等（前台调用除外）。

package/src/bootstrap.ts

@@ -0,0 +1,106 @@
+/**
+ * 档1 bootstrap：master 进程的 cordis 树根（D78 挂载树 / D80 生态采用 / D81 三分法）。
+ *
+ * 形态：Loader 作根插件 → builtins.group 注册（D80③ `cordis:group`）→
+ *      timer（hmr 前置依赖，D80②）→ hmr（仅开发姿态：`--expose-internals` 且
+ *      env PI_HERDR_HMR=1，缺一即跳过——生产路径零 watcher）。
+ *
+ * worker 进程不走本模块（C3/D81：短命进程手动 mount，无 loader/hmr）——
+ * 与 subagent-scope.ts 同为 master 分支动态 import。
+ *
+ * 后续：core 模块（todo/subagent/terminal/approval/reconcile 族）逐个迁为
+ * loader entry（热换面 = entry，D80③ 手动 mount 不热换）。
+ */
+import { Context } from '@deepseek-ai/cordis';
+import Loader from '@deepseek-ai/cordis-plugin-loader';
+import Group from '@deepseek-ai/cordis-plugin-group';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import { DisposeLedger } from './ledger.ts';
+
+export interface BootstrapHooks {
+  onDispose?: () => void;
+}
+
+export interface CordisApp {
+  /** 树根（subagent scope 与 lifecycle effect 都挂这里）。 */
+  root: Context;
+  /** loader service 是否就绪（false = 降级为裸树，行为同档0）。 */
+  loaderReady: boolean;
+  /** hmr 是否激活（开发姿态才有）。 */
+  hmrActive: boolean;
+  /** dispose 账本（D80⑤ hmr 补偿 + D79 反注册共用；session_shutdown 走 disposeAll）。 */
+  ledger: DisposeLedger;
+}
+
+/** node 是否带 --expose-internals（hmr 的硬前提，D80①）。 */
+export function detectExposeInternals(): boolean {
+  return process.execArgv.some((a) => a === '--expose-internals' || a.startsWith('--expose-internals='));
+}
+
+export async function createCordisApp(hooks: BootstrapHooks = {}): Promise<CordisApp> {
+  const root = new Context();
+  const ledger = new DisposeLedger();
+  // 服务注入（cordis 原生 DI）：core entry 用 ctx.get('pi-herdr.ledger') 取账本——
+  // （entry config 过不了活实例，loader 会变换 config；provide/get 是 hmr/timer 同款机制）
+  root.provide('pi-herdr.ledger', ledger);
+  if (hooks.onDispose) {
+    root.effect(() => () => { hooks.onDispose?.(); }, 'session-root');
+  }
+  // 相对名 entry（./core/...）以本文件目录解析
+  root.baseUrl = pathToFileURL(path.dirname(fileURLToPath(import.meta.url))).href + '/';
+
+  let loaderReady = false;
+  let hmrActive = false;
+  try {
+    await root.plugin(Loader);
+    const withLoader = root as Context & { loader?: { builtins: Record<string, unknown> } };
+    if (withLoader.loader) {
+      withLoader.loader.builtins.group = Group; // D80③：声明里用 cordis:group 引用
+      loaderReady = true;
+    }
+  } catch (err) {
+    console.error(`[pi-herdr] cordis loader degraded (bare tree): ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (loaderReady && detectExposeInternals() && process.env.PI_HERDR_HMR === '1') {
+    try {
+      const withLoader = root as Context & {
+        loader?: { create: (o: { name: string; config?: unknown }) => Promise<unknown> };
+      };
+      await withLoader.loader?.create({ name: '@deepseek-ai/cordis-plugin-timer' });
+      await withLoader.loader?.create({
+        name: '@deepseek-ai/cordis-plugin-hmr',
+        config: {
+          root: [path.dirname(fileURLToPath(import.meta.url))],
+          debounce: 200,
+          ignored: [],
+        },
+      });
+      hmrActive = true;
+      console.error('[pi-herdr] hmr active (dev posture: --expose-internals + PI_HERDR_HMR=1)');
+      // D80⑤（修正后）：hmr reload **会**拆旧 fiber 的 effect-disposers（registry.delete）——
+      // ctx.effect 是 core entry 主拆除机制。本 hook 补的是账本侧：pi-surface 旧世代
+      // 收割（d87 世代化：重挂后的 disposeKey 只杀登记世代及之前，新世代豁免）。
+      root.on('hmr/reload', (reloads: unknown) => {
+        try {
+          const files: string[] = [];
+          for (const r of (reloads as Map<unknown, { filename?: string }>).values()) {
+            if (typeof r?.filename === 'string') files.push(r.filename);
+          }
+          if (files.length > 0) {
+            const n = ledger.disposeKey(files);
+            if (n > 0) console.error(`[pi-herdr] ledger: compensated ${n} disposal(s) for ${files.join(', ')}`);
+          }
+        } catch {
+          /* 补偿尽力而为 */
+        }
+      });
+    } catch (err) {
+      // D80②：hmr 挂失败不致命——降级为零 watcher，树其余部分照常
+      console.error(`[pi-herdr] hmr mount failed (degraded): ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return { root, loaderReady, hmrActive, ledger };
+}

package/src/core/grid-shape.ts

@@ -0,0 +1,86 @@
+/**
+ * D91 网格形态：spawn 时挑「最大格子沿长轴分裂」，让 pane 自然铺成方格
+ * （用户愿景：股票热力图式方格；横向格更易读最新输出）。
+ *
+ * 依据 herdr 0.8.2 源码：ratio = split 节点 first child 份额（split_rect：
+ * first_w = width*ratio）；layout.apply 不能挂接既有 pane（只建新 shell），
+ * 因此网格形态只能在 spawn 增量分裂时养成，形态之外的尺寸归热力 reflow 管。
+ */
+
+export type ShapeNode =
+  | { type: 'pane'; paneId: string }
+  | { type: 'split'; direction: string; ratio: number; first: ShapeNode; second: ShapeNode };
+
+/** 容错解析 layout.export 的 root（pane 叶：{type:'pane', pane:{pane_id}}）。 */
+export function parseShapeTree(raw: unknown): ShapeNode | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const o = raw as Record<string, unknown>;
+  if (o.type === 'pane') {
+    const nested = o.pane as Record<string, unknown> | undefined;
+    const id = typeof o.pane_id === 'string'
+      ? o.pane_id
+      : typeof nested?.pane_id === 'string' ? nested.pane_id : null;
+    return id ? { type: 'pane', paneId: id } : null;
+  }
+  if (o.type === 'split') {
+    const first = parseShapeTree(o.first);
+    const second = parseShapeTree(o.second);
+    if (!first || !second) return null;
+    return {
+      type: 'split',
+      direction: String(o.direction ?? 'right'),
+      ratio: typeof o.ratio === 'number' ? o.ratio : 0.5,
+      first,
+      second,
+    };
+  }
+  return null;
+}
+
+export interface PaneCell {
+  id: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** 先序计算每个 pane 的格子（终端字符坐标；宽高仅用于比较，取典型 TUI 比例 200×50）。 */
+export function paneCells(root: ShapeNode, width = 200, height = 50): PaneCell[] {
+  const cells: PaneCell[] = [];
+  const walk = (node: ShapeNode, x: number, y: number, w: number, h: number): void => {
+    if (node.type === 'pane') {
+      cells.push({ id: node.paneId, x, y, w, h });
+      return;
+    }
+    const horizontal = node.direction === 'right' || node.direction === 'left' || node.direction === 'horizontal';
+    if (horizontal) {
+      walk(node.first, x, y, w * node.ratio, h);
+      walk(node.second, x + w * node.ratio, y, w * (1 - node.ratio), h);
+    } else {
+      walk(node.first, x, y, w, h * node.ratio);
+      walk(node.second, x, y + h * node.ratio, w, h * (1 - node.ratio));
+    }
+  };
+  walk(root, 0, 0, width, height);
+  return cells;
+}
+
+/**
+ * 挑分裂目标：面积最大的格子（并列取先序第一，稳定），沿长轴分裂——
+ * 宽 ≥ 1.3×高 → right（左右分，保格子横向可读），否则 down。
+ * exclude = 不许动的格子（board 等无 agent 常驻 shell）。
+ */
+export function pickGridSplit(
+  root: ShapeNode,
+  opts: { exclude?: ReadonlySet<string>; width?: number; height?: number } = {},
+): { targetPaneId: string; direction: 'right' | 'down' } | null {
+  const cells = paneCells(root, opts.width ?? 200, opts.height ?? 50)
+    .filter((c) => !opts.exclude?.has(c.id));
+  if (cells.length === 0) return null;
+  let best = cells[0];
+  for (const c of cells) {
+    if (c.w * c.h > best.w * best.h + 1e-9) best = c;
+  }
+  return { targetPaneId: best.id, direction: best.w > best.h * 1.3 ? 'right' : 'down' };
+}