pi-pier 0.2.7 → 0.3.1

package/README.md

@@ -1,7 +1,7 @@
 # pi-pier
 
 > [!IMPORTANT]
-> **This npm package is only the pi-extension half of pier.** pier is a two-half system — this extension plus a **herdr plugin** (`pier.workbench`). Without the herdr side you still get `todo_write` / `ask_user_question`; `subagent` / `terminal` are not registered. Pane integration, notifications, and workspace bootstrap all require herdr. See [Install the herdr half](#install-the-herdr-half-companion-plugin) below.
+> **This npm package is only the pi-extension half of pier.** pier is a two-half system — this extension plus a **herdr plugin** (`pier.workbench`). Without the herdr side you still get `todo_write` / `ask_user_question`; `subagent` / `terminal` are not registered. Pane integration and notifications require herdr. See [Install the herdr half](#install-the-herdr-half-companion-plugin) below.
 
 **pier** = **pi** × h**erdr** — a [pi](https://pi.dev/) extension that fuses coding agent sessions with the [herdr](https://herdr.dev/) pane/tab orchestrator.
 
@@ -21,7 +21,7 @@ pi install git:github.com/July24/pier
 
 ## Install the herdr half (companion plugin)
 
-The herdr plugin `pier.workbench` provides the other half: main-tab bootstrap (auto-start a pi master session per workspace), blocked-gate notifications (system notifications when a subagent waits for a human), and the focus-heat layout (focused pane grows in place). Install it from the same repo:
+The herdr plugin `pier.workbench` provides the other half: blocked-gate notifications (system notifications when a subagent waits for a human), the focus-heat layout (focused pane grows in place), and the ops dashboard / sidebar agent view. Install it from the same repo:
 
 ```sh
 herdr plugin install July24/pier/packages/pier-workbench --yes
@@ -31,10 +31,10 @@ Or install **both halves at once** with the one-shot installer from the monorepo
 
 ```sh
 git clone https://github.com/July24/pier && cd pier
-node install.mjs        # user mode: installs both halves + generates local bootstrap config
+node install.mjs        # user mode: installs both halves
 ```
 
-The installer also verifies node / pi / herdr versions, probes local paths, and writes the workbench bootstrap config (`boot-config.json`) into herdr's plugin config dir.
+The installer also verifies node / pi / herdr versions.
 
 ## What you get
 
@@ -43,15 +43,27 @@ The installer also verifies node / pi / herdr versions, probes local paths, and
 | 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. Actions: `spawn` (default; foreground / parallel / background), `list`, `send`, `interrupt`, `resume` |
+| `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane. Actions: `spawn` (default; foreground / parallel / background), `list`, `send`, `interrupt`, `resume`, `output` (incremental preview of a running subagent's pane output), `role` (switch that worker's role profile mid-session — pi 0.86 records the toolset change as a transcript delta, so it applies on the worker's next request and survives resume) |
+| `ask_user_question` | Human gate: 2-5 authored options plus a trailing free-text row (`allowOther: false` for pure choice); multiple related questions per call. TUI renders single- and multi-select through one picker dialog (multi adds checkboxes: space toggles, `a` all, live count; `recommended` seeds the cursor and pre-checks in multi); pane shows blocked in herdr while waiting |
 | `terminal` | Persistent interactive shells in dedicated herdr panes. Actions: `open`, `send`, `read`, `signal`, `close`, `list` |
-| `ask_user_question` | Human gate: structured options plus Other; pane shows blocked in herdr while waiting |
+
+### Commands
+
+| Command | Purpose |
+|---|---|
+| `/todos` | Show the todo list, or edit it: `/todos done|drop|rm|unblock <fuzzy match>` |
+| `/locks` | Show write locks held by this pane and by live panes — the **human/operator view** of the write-lock beacons (herdr only). Agents see the holders inside their own write warnings; the raw tokens are readable via `herdr agent list` |
+| `/pier-role` | Show the current role + available role names, or switch mid-session: `/pier-role <name>` (pi ≥ 0.86; widening beyond the current toolset asks for confirmation; the switch lands as a transcript tool delta) |
+| `/pier-config` | Read-only configuration guide over four planes: bare call = index + hands a guided change to the agent; `show [plane\|all]` = effective value + source (`env > workspace > user > default`); `check` = validate all planes; `doc [path]` = write a report |
 
 ### 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
+- **Blocking dialogs block the pane**: pi's `ui_prompt_start` / `ui_prompt_end` events cover the inherently blocking `ctx.ui` dialogs (`select` / `confirm` / `input` / `editor`), so a dialog from any extension (not only pier's own ask tool) reports the pane as blocked and emits the `herdr:blocked` edge; nested gates are coalesced. `custom` is excluded because pi also routes resident overlays through it (pier's slim-frame overlay never calls `done()`, and a resident overlay keeps pi's prompt span open anyway)
+- **Role gate stops early**: a tool call denied by the role manifest returns `terminate`, so a batch whose results are all terminating ends without another model round trip
+- **Readable transcript**: pier's own session entries (todo edits, subagent/terminal registries, role manifests, soft approvals) and its reminder messages render as compact cards instead of raw JSON
+- **Soft locks**: write paths register per-pane beacons; conflicts warn (default) or block (`PI_HERDR_WRITE_LOCK=1`) instead of racing silently. Warnings name **every** holder — the audience split is: agent reads its own tool-result warning, human reads `/locks` (or `herdr agent list` for the raw token table). `write`/`edit` only — `bash` writes are not covered
+- **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. A role manifest may carry `guidelines` (behavior constraints a toolset cannot express); they ride the system prompt as a `pier-role` section each turn. Masters can switch a worker's role remotely via `subagent action:"role"`; humans can switch the pane they are in via `/pier-role`
 - **Settlement notices folded**: background subagent completions inject between turns (max 3 shown, rest collapsed) instead of flood-filling at run end
 
 ## Scope & degradation
@@ -61,10 +73,12 @@ This extension mutates the pi session even outside herdr. After `pi install npm:
 | Surface | Bare `pi` (no `HERDR_ENV`) | Inside herdr |
 |---|---|---|
 | `todo_write`, `/todos`, widget, anti-freeze, stop reminder | live | live |
-| `ask_user_question` | live (TUI select/input) | live + blocked marker |
+| `ask_user_question` | live (TUI picker for single and multi; host select dialog / typed prompts as RPC fallback) | live + blocked marker |
+| Blocked reporting for blocking `ctx.ui` dialogs (`ui_prompt_start/end`, `select`/`confirm`/`input`/`editor`) | live | live + blocked marker |
 | Hidden inject (`before_agent_start` todo-read; settle reminder) | live | live |
 | `subagent`, `terminal` | **not registered** | live |
 | `/locks`, write-lock on `write`/`edit` | not installed | live |
+| `/pier-config` (read-only config guide over 4 planes) | live | live |
 | slim-frame overlay, pane title, pipe, isolate worktree | off | live |
 | `setActiveTools` role visible layer | off | on (herdr master) |
 
@@ -91,15 +105,15 @@ pi overwrites tools/commands by name; event listeners stack.
 ## Requirements
 
 - Node ≥ 22
-- pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
-- **herdr ≥ 0.8.0** — required for subagents / pane integration / notifications (see the IMPORTANT note above); without it only the todo loop and `ask_user_question` load
+- pi ≥ 0.86.0 (`@earendil-works/pi-coding-agent`) — dynamic toolset (transcript-backed `setActiveTools` deltas) and role switching require it
+- **herdr ≥ 0.9.0** — required for subagents / pane integration / notifications (see the IMPORTANT note above); without it only the todo loop and `ask_user_question` load
 
 ## Development
 
 ```sh
 git clone https://github.com/July24/pier && cd pier
 npm install --ignore-scripts
-npm test   # node --test, ~250 unit tests
+npm test   # node --test, ~590 unit tests
 ```
 
 See the [monorepo README](https://github.com/July24/pier) for design principles, the herdr-plugin half, and the one-shot installer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "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",
@@ -39,6 +39,10 @@
       "./skills/pi-herdr-workflow"
     ]
   },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test \"test/*.test.ts\""
+  },
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.1",
     "@deepseek-ai/cordis-plugin-group": "^1.0.1",
@@ -49,7 +53,8 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "typebox": "~1.3.7"
+    "@earendil-works/pi-coding-agent": "0.86.0",
+    "typebox": "~1.3.7",
+    "typescript": "~5.9.3"
   }
 }

package/schemas/efficiency-config.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://herdr-pi.local/schemas/efficiency-config.schema.json",
+  "title": "pier efficiency configuration (D100-D103)",
+  "type": "object",
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "onlineContextCompact": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "是否启用待办驱动的在线上下文压缩" },
+        "logEnabled": { "type": "boolean", "default": false, "description": "是否记录在线压缩的决策与节省量日志" },
+        "cacheWriteReadRatio": {
+          "oneOf": [
+            { "type": "number", "minimum": 0 },
+            { "type": "string", "enum": ["auto"] }
+          ],
+          "default": "auto",
+          "description": "KV 缓存写入与读取成本比。auto 表示从 ctx.model.cost 自动推导"
+        },
+        "firstCompactionRequestScale": { "type": "number", "default": 2.0, "minimum": 1.0 },
+        "subsequentCompactionMargin": { "type": "number", "default": 1.5, "minimum": 1.0 },
+        "keepRecentTokens": {
+          "type": "integer",
+          "default": 20000,
+          "minimum": 1000,
+          "description": "原生压缩保留区大小（同时用于 archiveTokens 估算与 nativeCompactionFeasible 预检）。缺省自动继承 pi 的 compaction.keepRecentTokens 设置（默认 20000）。"
+        }
+      },
+      "additionalProperties": false
+    },
+    "observationPack": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "是否启用大工具输出冷热分级打包" },
+        "logEnabled": { "type": "boolean", "default": false, "description": "是否记录观察结果打包与召回日志" },
+        "thresholdBytes": { "type": "integer", "default": 10240, "minimum": 1024 },
+        "fullSends": { "type": "integer", "default": 2, "minimum": 1 },
+        "recallChunkBytes": { "type": "integer", "default": 16384, "minimum": 1024 },
+        "excerptBytes": { "type": "integer", "default": 1024, "minimum": 128 }
+      },
+      "additionalProperties": false
+    },
+    "evidencePreservingReducer": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "是否启用长测试日志保真提炼" },
+        "logEnabled": { "type": "boolean", "default": false, "description": "是否记录提炼比对、耗时与回退日志" },
+        "model": {
+          "type": "string",
+          "description": "专用的轻量 Reducer 模型 (provider/model)。缺省使用当前模型并在日志中提示经济性"
+        },
+        "minBytes": { "type": "integer", "default": 4096, "minimum": 512 },
+        "maxChars": { "type": "integer", "default": 600000 },
+        "maxOutputTokens": { "type": "integer", "default": 2048 },
+        "timeoutMs": { "type": "integer", "default": 5000, "description": "同步拦截超时上限，默认 5 秒避免阻塞" },
+        "localOnly": { "type": "boolean", "default": false, "description": "仅本地归档长日志并跳过模型提炼" }
+      },
+      "additionalProperties": false
+    },
+    "jev": {
+      "type": "object",
+      "description": "jev 决策层（RFC docs/rfc-jev-integration.md）：可选的 System One 分类调用，逐点 fail-open",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "是否启用 jev 决策层（还需配置 apiKey 才会真正发起调用）" },
+        "logEnabled": { "type": "boolean", "default": false, "description": "是否写 efficiency-logs/jev.jsonl（不记录请求/响应 body）" },
+        "baseUrl": { "type": "string", "description": "API 根地址覆盖（中转/网关）；缺省 https://api.typesafe.ai" },
+        "model": { "type": "string", "default": "jev-1.13.0", "description": "钉住的版本化模型 id；别名会静默漂移导致校准阈值失真" },
+        "timeoutMs": { "type": "integer", "default": 2000, "minimum": 500, "description": "单次调用总预算（AbortController 硬杀，SDK 无总预算模式）" },
+        "minConfidence": { "type": "number", "default": 0.6, "minimum": 0, "maximum": 1, "description": "Choice/Score 答案被采纳的最低置信度，低于则按未回答处理" },
+        "apiKey": { "type": "string", "description": "API key。解析优先级：PIER_JEV_API_KEY 环境变量 > 此处 > TYPESAFE_API_KEY 环境变量" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/role-manifest.schema.json

@@ -8,7 +8,13 @@
     "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" },
+    "guidelines": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "P0 per-role 行为约束（RFC §4.6）：工具集表达不了的“怎么用”约束，每轮作为 pier-role prompt section 注入；空数组请省略"
+    },
     "manifest": {
       "type": "object",
       "properties": {

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

@@ -88,6 +88,17 @@ The ledger is an append-only JSONL file at `~/.pi/agent/herdr-pi/history/<flatte
 
 Call: `subagent(action: "resume", taskId: "<uuid>")`
 
+## 2.5 Configuration questions
+
+When the user asks about pier/pi configuration (or asks to change it), start from the read-only
+guide instead of guessing: `/pier-config show all` reports every knob's **effective value and
+source** (`env > workspace > user > default`), `check` validates all four planes (efficiency
+D100–D103, roles, pi settings, `PIER_*`/`PI_HERDR_*` env), and `doc` writes a report
+into `<repo>/.pi-herdr/config-report.md`. Bare `/pier-config` injects the full guided-change
+workflow. Key rules: an untrusted project's workspace layer is ignored (report it, never edit
+blindly); pi-owned settings go through pi's own `/settings`; change one plane at a time and show a
+diff before writing. Overview: `docs/configuration.md`.
+
 ## 3. Human gate
 
 - For a human decision (approval, tradeoff, direction), use `ask_user_question` (this plugin). Prefer 2-5 options with short labels and tradeoffs in `description`. Do **not** author an "Other" option — the UI appends "Other (type your own)". Use `recommended` (0-based) for the default and `questions` to batch related decisions (max 4). While waiting, your pane is **blocked** in herdr so the human can see and intervene. The answer comes back as the tool result, then you continue.

package/src/ansi-text.ts

@@ -0,0 +1,134 @@
+/**
+ * ANSI-aware text measurement and clipping for pier's TUI surfaces.
+ *
+ * Local implementation: the todo widget, the pinned pane title and the ask_user_question multi-select
+ * all need width-correct clipping, but importing `visibleWidth`/`truncateToWidth` from pi-tui would
+ * make those paths depend on a package that may be absent in stripped installs. The table below only
+ * has to be right for ASCII plus the CJK/emoji ranges that actually appear in user content.
+ */
+
+const SGR = /\x1b\[[0-9;]*m/y;
+
+export function charWidth(cp: number): number {
+  if (cp < 32) return 0;
+  if (cp >= 0x7f && cp < 0xa0) return 0;
+  if (cp >= 0x0300 && cp <= 0x036f) return 0; // combining marks
+  if (
+    (cp >= 0x1100 && cp <= 0x115f)
+    || (cp >= 0x2e80 && cp <= 0x303e)
+    || (cp >= 0x3041 && cp <= 0x33ff)
+    || (cp >= 0x3400 && cp <= 0x4dbf)
+    || (cp >= 0x4e00 && cp <= 0x9fff)
+    || (cp >= 0xa000 && cp <= 0xa4cf)
+    || (cp >= 0xac00 && cp <= 0xd7a3)
+    || (cp >= 0xf900 && cp <= 0xfaff)
+    || (cp >= 0xfe30 && cp <= 0xfe6f)
+    || (cp >= 0xff00 && cp <= 0xff60)
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+    || (cp >= 0x1f300 && cp <= 0x1f9ff)
+    || (cp >= 0x20000 && cp <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+/** Rendered cell width; SGR sequences count as zero cells. */
+export function styledWidth(line: string): number {
+  let width = 0;
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    width += charWidth(cp);
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return width;
+}
+
+/** Cut to `width` cells without breaking escape sequences; wide glyphs count as two cells. */
+export function truncateStyled(line: string, width: number): string {
+  if (width <= 0) return '';
+  if (styledWidth(line) <= width) return line;
+  const keep = Math.max(0, width - 1); // reserve one cell for the ellipsis
+  let out = '';
+  let used = 0;
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      out += m[0];
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    const w = charWidth(cp);
+    if (used + w > keep) break;
+    out += cp > 0xffff ? line.slice(i, i + 2) : line[i]!;
+    used += w;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return `${out}\x1b[0m…`;
+}
+
+/**
+ * Wrap to `width` cells, preferring space breaks and never splitting a wide glyph or an escape
+ * sequence. Open SGR codes are re-emitted at continuation starts so a style spanning the break (a
+ * dim description) survives; emitted lines end with a reset when a style is open.
+ */
+export function wrapStyled(line: string, width: number): string[] {
+  if (width <= 0) return [''];
+  const out: string[] = [];
+  let current = '';
+  let used = 0;
+  let spaceAt = -1; // index in `current` of the last breakable space
+  let open = '';    // SGR codes active at the scan position
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      current += m[0];
+      open = m[0] === '\x1b[0m' ? '' : open + m[0];
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    const w = charWidth(cp);
+    const chunk = cp > 0xffff ? line.slice(i, i + 2) : line[i]!;
+    if (used + w > width && used > 0) {
+      // A space that overflows breaks there; otherwise rewind to the last space so words stay whole.
+      const atSpace = chunk === ' ';
+      const head = !atSpace && spaceAt > 0 ? current.slice(0, spaceAt) : current;
+      const tail = !atSpace && spaceAt > 0 ? current.slice(spaceAt + 1) : '';
+      out.push(head.replace(/ +$/, '') + (open ? '\x1b[0m' : ''));
+      current = open + tail;
+      used = styledWidth(tail);
+      const tailSpace = tail.lastIndexOf(' ');
+      spaceAt = tailSpace > 0 ? open.length + tailSpace : -1;
+      if (atSpace) i += 1; // the breaking space is consumed, not re-processed
+      continue; // re-evaluate the pending char on the fresh line
+    }
+    if (used + w > width) {
+      // A glyph wider than the whole line (width 1): emit it alone.
+      out.push(current + chunk + (open ? '\x1b[0m' : ''));
+      current = open;
+      used = 0;
+      spaceAt = -1;
+      i += cp > 0xffff ? 2 : 1;
+      continue;
+    }
+    current += chunk;
+    used += w;
+    if (chunk === ' ') spaceAt = current.length - 1;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  if (current || out.length === 0) out.push(current);
+  return out;
+}