pi-pier 0.3.1 → 0.4.1

package/README.md

@@ -43,8 +43,8 @@ The installer also verifies node / pi / herdr versions.
 | 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`, `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 |
+| `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 records the toolset change as a transcript delta, so it applies on the worker's next request and survives resume). Every spawned task gets a stable slug: outputs print `slug@paneId`, and `agentId` accepts the slug, the pane id, or the combined form |
+| `report_progress` | Worker panes only: send the delegating master a short checkpoint update without ending the task. Arrives in the master's context as a display-less custom message (no turn, no chat flood), rendered as a `⤴ progress` card |
 | `terminal` | Persistent interactive shells in dedicated herdr panes. Actions: `open`, `send`, `read`, `signal`, `close`, `list` |
 
 ### Commands
@@ -52,13 +52,16 @@ The installer also verifies node / pi / herdr versions.
 | Command | Purpose |
 |---|---|
 | `/todos` | Show the todo list, or edit it: `/todos done|drop|rm|unblock <fuzzy match>` |
+| `/dashboard [overlay]` | Ops dashboard. Default opens the shared Pier **popup** on its `Dashboard` tab (90% × 80%, singleton); `overlay` opens the same view as an independent full-window pane. Non-Herdr falls back to an in-pane text view. |
+| `/pier-tree [overlay]` | Master only: the full delegation tree — your complete todo list plus every running subagent's full list (live-pushed over the pipe) and settled nodes with ages. Default opens the same shared popup on its `Tree` tab (the snapshot refreshes on every todo/worker push; `1`/`2`/`Tab` switch views inside the popup); `overlay` opens an independent full-window pane; bare pi / a missing plugin falls back to the in-pane notify view. The resident widget stays one line per agent and hides entirely once the self list is fully completed (D113/D114) |
 | `/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-role` | Show the current role + available role names, or switch mid-session: `/pier-role <name>` (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
+- **Delegation identity**: the worker knows who delegated it — spawn env (`PI_HERDR_DELEGATION`) replays through the worker marker and the session's own first-frame entry; its system prompt carries a `pier-delegation` section (identity + delivery contract), the transcript opens with an "⟵ delegated by master …" card, the pane title gets an `↳` prefix, and `pi-parent`/`pi-task` tokens feed the workbench dashboard tree and blocked-alert attribution
 - **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
@@ -105,8 +108,8 @@ pi overwrites tools/commands by name; event listeners stack.
 ## Requirements
 
 - Node ≥ 22
-- 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
+- pi ≥ 1.3.0 (`@earendil-works/pi-coding-agent`) — `before_agent_start.messageType` and resumed-session active tools
+- **herdr ≥ 0.9.5** — required for subagents / pane integration / notifications (see the IMPORTANT note above); native `pane.focused`, self-reported resume, and shutdown-safe session saves restore subagent panes after a server restart
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.3.1",
+  "version": "0.4.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",
@@ -49,11 +49,11 @@
     "@deepseek-ai/cordis-plugin-loader": "^1.0.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=1.3.0",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.86.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
     "typebox": "~1.3.7",
     "typescript": "~5.9.3"
   }

package/src/bootstrap.ts

@@ -12,6 +12,7 @@ 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';
+import { cordisProvide } from './cordis-services.ts';
 import { pierOption } from './pier-options.ts';
 
 export interface BootstrapHooks {
@@ -37,7 +38,7 @@ export async function createCordisApp(hooks: BootstrapHooks = {}): Promise<Cordi
   const root = new Context();
   const ledger = new DisposeLedger();
   // Inject the ledger through Cordis DI because loader transforms entry config and cannot carry live instances.
-  root.provide('pi-herdr.ledger', ledger);
+  cordisProvide(root, 'pi-herdr.ledger', ledger);
   if (hooks.onDispose) {
     root.effect(() => () => { hooks.onDispose?.(); }, 'session-root');
   }

package/src/compact-coordinator.ts

@@ -227,8 +227,9 @@ export class CompactCoordinator {
       return;
     }
 
-    // P1-3 backoff: after a failed summarization (token-cap class), skip compact decisions for a
-    // bounded window — each attempt aborts an in-flight turn, so a doomed retry burns turns.
+    // P1-3 backoff: after a failed summarization, skip compact decisions for a bounded window —
+    // each attempt aborts an in-flight turn, so a doomed retry burns turns. (The token-cap failure
+    // class is gone since pi 1.4.0 uncapped summary output; transient timeouts/aborts remain.)
     if (this.state.compactBackoffTurnEnds > 0) {
       this.state.compactBackoffTurnEnds--;
       if (opts.config.logEnabled) {

package/src/cordis-services.ts

@@ -0,0 +1,64 @@
+/**
+ * Closed set of cordis services this process provides on the root.
+ *
+ * `ctx.get`/`ctx.provide` also accept an arbitrary string and return `any`, so a raw call plus `as`
+ * neither rejects a mistyped key nor a dropped bag field (fe99252). Mounts and plugins go through
+ * the helpers below. Instances stay on the root: a plugin-fiber Service would unload them on HMR.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { DisposeLedger } from './ledger.ts';
+import type { PiSurface } from './pi-surface.ts';
+import type { TerminalDeps } from './plugins/terminal.ts';
+import type { TodoDeps, TodoUiSlot } from './plugins/todo.ts';
+import type { TodosService } from './todos-service.ts';
+import type { SubagentDeps } from './plugins/subagent.ts';
+
+export interface PierCordisServices {
+  'pi-herdr.ledger': DisposeLedger;
+  'pi-herdr.surface': PiSurface<object>;
+  'pi-herdr.terminal-deps': TerminalDeps;
+  'pi-herdr.todo-deps': TodoDeps;
+  'pi-herdr.subagent-deps': SubagentDeps;
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context extends PierCordisServices {}
+}
+
+export function cordisProvide<K extends keyof PierCordisServices>(
+  ctx: Context,
+  key: K,
+  value: PierCordisServices[K],
+): void {
+  ctx.provide(key, value);
+}
+
+/** Throws when the root has not provided `key`. `ctx.get` itself returns `T | undefined`. */
+export function cordisGet<K extends keyof PierCordisServices>(ctx: Context, key: K): PierCordisServices[K] {
+  const value = ctx.get(key) as PierCordisServices[K] | undefined;
+  if (value === undefined) throw new Error(`[pi-herdr] cordis service missing: ${key}`);
+  return value;
+}
+
+/** The six required 'pi-herdr.todo-deps' fields both mounts assemble identically (maxItems mirrors
+ * the tool prompt's "at most 15 entries"); masters and workers spread their own optional seams —
+ * getWorkers/getBlockedDepth/stopReminder — on top of this base. */
+export function baseTodoDeps(m: {
+  pi: unknown;
+  todos: TodosService;
+  todoUi: TodoUiSlot;
+  mirrorTodos: () => void;
+}): Pick<TodoDeps, 'todos' | 'allowParallelInProgress' | 'maxItems' | 'mirrorTodos' | 'appendEntry' | 'state'> {
+  return {
+    todos: m.todos,
+    allowParallelInProgress: m.todos.config.allowParallelInProgress,
+    maxItems: 15,
+    mirrorTodos: m.mirrorTodos,
+    appendEntry: (customType: string, data: unknown) => {
+      // Unchecked cast: pi's ExtensionAPI type omits this optional runtime entry-append seam.
+      const pi = m.pi as { appendEntry?: (t: string, d: unknown) => void };
+      pi.appendEntry?.(customType, data);
+    },
+    state: m.todoUi,
+  };
+}

package/src/dashboard-command.ts

@@ -1,4 +1,5 @@
 import type { HerdrClientLike, HerdrEnv } from './herdr-client.ts';
+import { openPierPanel } from './panel-open.ts';
 import { isTodoStatus, type TodoItem, type TodoStatus } from './vocab.ts';
 
 export interface DashboardCommandDeps {
@@ -9,6 +10,8 @@ export interface DashboardCommandDeps {
   env: HerdrEnv | null;
   getTodoItems?: () => readonly TodoItem[];
   getHeldLocks?: () => readonly string[];
+  /** Publishes the current delegation tree and returns its snapshot path (panel Tree tab). */
+  prepareTree?: () => string | null;
 }
 
 /** SUMMARY_ORDER fixes the summary-line order; LIVE_ROWS adds the detail line below it.
@@ -74,26 +77,48 @@ export function formatStandaloneDashboard(opts: {
 
 export function installDashboardCommand(deps: DashboardCommandDeps): void {
   deps.pi.registerCommand('dashboard', {
-    description: 'Open the Pier Ops Dashboard (modal popup in Herdr 0.9.1, tab fallback, or local TUI view)',
-    handler: async (_args, ctx) => {
+    description: 'Open the Pier Ops Dashboard (modal popup by default; `/dashboard overlay` = independent full-window pane)',
+    handler: async (args, ctx) => {
       const ui = (ctx as { ui?: { notify?: (text: string, level?: string) => void } }).ui;
+      const overlay = typeof args === 'string' && args.trim().toLowerCase() === 'overlay';
 
       if (deps.client.available && deps.env) {
-        try {
-          const res = await deps.client.openPluginPane({
-            pluginId: 'pier.workbench',
-            entrypoint: 'dashboard',
-            placement: 'popup',
-            width: '80%',
-            height: '80%',
-            focus: true,
-          });
-          if (res.mode === 'fallback_tab') {
+        if (overlay) {
+          // Escape hatch: a real full-window pane instead of the singleton popup.
+          const treeFile = deps.prepareTree?.() ?? null;
+          try {
+            const res = await deps.client.openPluginPane({
+              pluginId: 'pier.workbench',
+              entrypoint: 'dashboard',
+              placement: 'overlay',
+              focus: true,
+              env: {
+                PIER_PANEL: 'dashboard',
+                ...(treeFile ? { PIER_TREE_FILE: treeFile } : {}),
+              },
+            });
+            if (res.mode === 'fallback_tab') {
+              ui?.notify?.('Herdr < 0.9.1: Pier Dashboard opened in new tab', 'info');
+            }
+            return;
+          } catch {
+            // Fall through to the local view.
+          }
+        } else {
+          const res = await openPierPanel(
+            { client: deps.client, env: deps.env },
+            { panel: 'dashboard', treeFile: deps.prepareTree?.() ?? null },
+          );
+          if (res === 'popup') return;
+          if (res === 'tab') {
             ui?.notify?.('Herdr < 0.9.1: Pier Dashboard opened in new tab', 'info');
+            return;
+          }
+          if (res === 'busy') {
+            ui?.notify?.('Another popup is already open — close it and run /dashboard again.', 'warning');
+            return;
           }
-          return;
-        } catch {
-          // Plugin missing or socket error: fall through to the Level 3 local view.
+          // 'unavailable' → Level 3 local view.
         }
       }
 

package/src/delegation-core.ts

@@ -0,0 +1,115 @@
+/**
+ * Delegation identity (RFC docs/rfc-delegation-identity.md Phase 1): a worker pane knows who
+ * delegated it, for what task, and shows that on every surface it already touches — system prompt
+ * section, session custom entry (first-frame card), herdr sidebar tokens, and the pane title.
+ * Pure builders only; the composition root owns the side effects.
+ */
+
+/** Contract env handed to the worker process by the master (PI_HERDR_ prefix per naming rule). */
+export const DELEGATION_ENV = 'PI_HERDR_DELEGATION';
+/** Worker-session custom entry written once at first boot; replayed on resume. */
+export const DELEGATION_CUSTOM_TYPE = 'pi-herdr.delegation';
+/** herdr sidebar tokens (pane.report_metadata): parent pane + delegated task. */
+export const DELEGATION_PARENT_TOKEN = 'pi-parent';
+export const DELEGATION_TASK_TOKEN = 'pi-task';
+/** herdr truncates title/token values at 80 chars; clip locally to keep glyphs whole. */
+const TOKEN_MAX = 80;
+
+export interface DelegationContext {
+  /** Master pane that spawned this worker; '' when the master pane is unknown (tests, RPC). */
+  readonly parentPaneId: string;
+  /** Master pi session id (cross-locate the parent transcript via /resume). */
+  readonly parentSessionId: string;
+  /** SubEntry.taskId — stable across revives. */
+  readonly taskId: string;
+  /** Task short label (SubEntry.description). */
+  readonly description: string;
+  /** Role manifest name active at spawn. */
+  readonly role: string;
+  /** Phase 2: the master's pipe name — report_progress dials it directly (D49 reply-address
+   * semantics, precomputed because the worker cannot derive the master's session cwd). */
+  readonly parentPipe?: string;
+}
+
+function str(v: unknown): string | null {
+  return typeof v === 'string' ? v : null;
+}
+
+/** Validate a parsed delegation record (env JSON, marker JSON or custom-entry data); null when malformed. */
+export function delegationFromRecord(parsed: unknown): DelegationContext | null {
+  if (!parsed || typeof parsed !== 'object') return null;
+  const rec = parsed as Record<string, unknown>; // shape-checked field by field below
+  const parentPipe = str(rec.parentPipe);
+  const taskId = str(rec.taskId);
+  const description = str(rec.description);
+  if (!taskId || !description) return null;
+  return {
+    parentPaneId: str(rec.parentPaneId) ?? '',
+    parentSessionId: str(rec.parentSessionId) ?? '',
+    taskId,
+    description,
+    role: str(rec.role) ?? 'worker-default',
+    ...(parentPipe ? { parentPipe } : {}),
+  };
+}
+
+/** Parse the spawn env; null when absent or structurally invalid (taskId/description mandatory). */
+export function parseDelegationContext(raw: string | undefined | null): DelegationContext | null {
+  if (!raw || typeof raw !== 'string') return null;
+  try {
+    return delegationFromRecord(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+/** env map for spawnPaneInTaskTab/createTab; JSON like the role manifest next to it. */
+export function delegationEnv(ctx: DelegationContext): Record<string, string> {
+  return { [DELEGATION_ENV]: JSON.stringify(ctx) };
+}
+
+/** Fold `pi-herdr.delegation` branch entries (last one wins) — the /resume replay source. */
+export function foldDelegation(
+  entries: ReadonlyArray<{ type?: string; customType?: string; data?: unknown }>,
+): DelegationContext | null {
+  let found: DelegationContext | null = null;
+  for (const entry of entries) {
+    if (entry.type !== 'custom' || entry.customType !== DELEGATION_CUSTOM_TYPE) continue;
+    const next = delegationFromRecord(entry.data);
+    if (next) found = next;
+  }
+  return found;
+}
+
+/**
+ * System-prompt section text: identity + delivery contract in one stable wording, so the master
+ * model does not have to restate it in every spawn prompt (pi-subagent-manager idea A+F).
+ */
+export function buildDelegationSection(ctx: DelegationContext, ownPaneId: string): string {
+  const parent = ctx.parentPaneId || 'unknown pane';
+  const session = ctx.parentSessionId || 'unknown session';
+  const self = ownPaneId ? ` You are pane ${ownPaneId} (agentId "${ownPaneId}") — cite it when asking questions or reporting errors.`
+    : '';
+  return [
+    `You are a delegated subagent of the master pane ${parent} (session ${session}); you were not started by a human.`,
+    `Task: ${ctx.description}. Role: ${ctx.role}.${self}`,
+    'Contract: when finished, state your final answer plainly — the master collects it from this pane\'s settlement; do not ask who requested the work. If you cannot finish, say exactly what blocks you instead of stopping silently.',
+  ].join('\n');
+}
+
+/** Sidebar token patch; empty (no request) when there is no parent pane to attribute. */
+export function delegationSidebarTokens(ctx: DelegationContext): Record<string, string> {
+  if (!ctx.parentPaneId) return {};
+  return {
+    [DELEGATION_PARENT_TOKEN]: ctx.parentPaneId.slice(0, TOKEN_MAX),
+    [DELEGATION_TASK_TOKEN]: ctx.description.slice(0, TOKEN_MAX),
+  };
+}
+
+/** Worker pane title marker: `↳ <todo title>`, or `↳ <task>` alone before the first todo_write. */
+export function applyWorkerTag(title: string | null, delegatedTask: string | null): string | null {
+  if (!delegatedTask) return title;
+  const base = title ?? delegatedTask;
+  return `↳ ${base.slice(0, TOKEN_MAX - 2)}`;
+}
+

package/src/efficiency-config-core.ts

@@ -9,6 +9,7 @@
  * top-level key disables every mechanism).
  */
 
+import { isPlainObject } from './guards.ts';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -86,10 +87,6 @@ export const DEFAULT_EFFICIENCY_CONFIG: EfficiencyConfig = Object.freeze({
   jev: Object.freeze({ enabled: false, logEnabled: false, model: 'jev-1.13.0', timeoutMs: 2000, minConfidence: 0.6 }),
 });
 
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-
 type FieldKind = 'bool' | 'int' | 'number' | 'ratio' | 'string' | 'optionalString';
 
 interface FieldSpec {

package/src/efficiency-store.ts

@@ -58,7 +58,7 @@ export function reducerObjectPath(root: string, sha256: string): string {
 
 export function efficiencyLogPath(
   root: string,
-  mechanism: 'compact' | 'observation' | 'reducer' | 'jev' | 'routing',
+  mechanism: 'compact' | 'observation' | 'reducer' | 'jev' | 'routing' | 'tools',
   customPath?: string,
 ): string {
   if (customPath && typeof customPath === 'string') return resolve(customPath);

package/src/guards.ts

@@ -0,0 +1,6 @@
+/** Shared structural guards used by the *-core validators. */
+
+/** Plain JSON object: not null, not an array. */
+export function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}