pi-pier 0.2.7 → 0.3.1

package/src/todos-service.ts

@@ -1,13 +1,6 @@
-/** Why: Preserve the established compatibility and safety behavior (D65, D75). */
+/** Single owner of todo state; every mutation path (tool, human edit, M17 reconcile, archive) lands here (D65, D75). */
 import { EventEmitter } from 'node:events';
-import {
-  applyTodoEdits,
-  foldLatestTodosMeta,
-  listsEqual,
-  type TodoEdit,
-  type TodoItem,
-} from './todo-core.ts';
-import { countCompletedTransitions } from './progress-core.ts';
+import { applyTodoEdits, completionTransitions, foldLatestTodosMeta, listsEqual, type TodoEdit, type TodoItem } from './todo-core.ts';
 import type { RuntimeRoleManifest } from './tool-gate.ts';
 
 export interface TodosConfig {
@@ -15,15 +8,15 @@ export interface TodosConfig {
   allowParallelInProgress: boolean;
 }
 
+export type TodoCompletionSource = 'tool' | 'reconcile' | 'human' | 'archive';
+
 export class TodosService extends EventEmitter {
   private _items: TodoItem[] = [];
-  /**
-   * Live list (read-only). Mutations must go through replace/applyEdits/rebuild.
-   */
+  /** Live list (read-only). Mutations must go through replace/applyEdits/rebuild. */
   get items(): readonly TodoItem[] {
     return this._items;
   }
-  /** Why: Preserve the established compatibility and safety behavior. */
+  /** Clock anchor for staleness/archiving; null until the first write. */
   lastWriteAt: number | null = null;
   readonly config: TodosConfig;
 
@@ -32,56 +25,55 @@ export class TodosService extends EventEmitter {
     this.config = config;
   }
 
-  /** Why: Preserve the established compatibility and safety behavior (D75). */
+  /** D75: subagents are strict (one in_progress); the role manifest may force parallel mode. */
   static configFromRuntime(manifest: RuntimeRoleManifest | null, isSubagent: boolean): TodosConfig {
     const strict = isSubagent;
     const mode = manifest?.services?.todos?.mode;
-    const allowParallelInProgress = mode === 'parallel' || mode === 'serial' ? mode === 'parallel' : !strict;
-    return { strict, allowParallelInProgress };
-  }
-
-  /** Defensive copy for callers that must not mutate service state. */
-  getSnapshot(): TodoItem[] {
-    return this._items.map((it) => ({ ...it }));
+    return {
+      strict,
+      allowParallelInProgress: mode === 'parallel' || mode === 'serial' ? mode === 'parallel' : !strict,
+    };
   }
 
-  replace(items: readonly TodoItem[]): { changed: boolean } {
+  replace(items: readonly TodoItem[], opts?: { source?: TodoCompletionSource }): { changed: boolean } {
     const next = items.map((it) => ({ ...it }));
     if (listsEqual(this._items, next)) return { changed: false };
     const before = this._items;
     this._items = next;
     this.lastWriteAt = Date.now();
-    this.emitCompletedTransitions(before, this._items);
+    this.emitCompletedTransitions(before, this._items, opts?.source ?? 'tool');
     this.emit('todo.updated', { items: this._items });
     return { changed: true };
   }
 
-  applyEdits(edits: readonly TodoEdit[]): { changed: boolean } {
+  applyEdits(edits: readonly TodoEdit[], opts?: { source?: TodoCompletionSource }): { changed: boolean } {
     const before = this._items;
     const next = applyTodoEdits(this._items, edits);
     if (listsEqual(before, next)) return { changed: false };
     this._items = next;
     this.lastWriteAt = Date.now();
-    this.emitCompletedTransitions(before, this._items);
+    this.emitCompletedTransitions(before, this._items, opts?.source ?? 'reconcile');
     this.emit('todo.edited', { edits, items: this._items });
     this.emit('todo.updated', { items: this._items });
     return { changed: true };
   }
 
-  /** Why: Preserve the established compatibility and safety behavior (M16). */
-  private emitCompletedTransitions(before: readonly TodoItem[], after: readonly TodoItem[]): void {
-    const count = countCompletedTransitions(before, after);
-    if (count > 0) this.emit('todo.completed', { count, at: Date.now() });
+  /** M16: ETA and compaction boundaries feed off this single completion diff (same rule as the tool's D36 report). */
+  private emitCompletedTransitions(
+    before: readonly TodoItem[],
+    after: readonly TodoItem[],
+    source: TodoCompletionSource = 'tool',
+  ): void {
+    const count = completionTransitions(before, after).length;
+    if (count > 0) this.emit('todo.completed', { count, at: Date.now(), source });
   }
 
+  /** Branch replay: fold the JSONL to the authoritative list. A branch with no snapshot (/new, or /tree
+   *  back before the first todo_write) has no list, so the previous session's items must not survive. */
   rebuild(entries: readonly unknown[]): void {
-    // Why: Preserve the established compatibility and safety behavior.
-    // Why: Preserve the established compatibility and safety behavior.
     const folded = foldLatestTodosMeta(entries as Parameters<typeof foldLatestTodosMeta>[0]);
-    if (folded) {
-      this._items = folded.items;
-      this.lastWriteAt = folded.writtenAt;
-    }
+    this._items = folded ? folded.items : [];
+    this.lastWriteAt = folded ? folded.writtenAt : null;
     this.emit('todo.updated', { items: this._items, reason: 'rebuild' });
   }
 }

package/src/tool-error.ts

@@ -0,0 +1,19 @@
+/**
+ * pi only marks a tool result as failed when `execute()` throws; returning a value never sets the
+ * error flag (pi docs/extensions.md, "Signaling errors"). Every hard failure goes through
+ * `toolError()`, while deliberate non-failures (empty result set, "no match within Xms", a pane that
+ * has not produced output yet) stay normal results.
+ *
+ * The leading "Error: " text is stripped: the provider's tool-result error channel and pi's red
+ * rendering already mark it, and keeping it would double the prefix once pi formats a thrown error.
+ */
+export class ToolError extends Error {
+  constructor(message: string) {
+    super(String(message).replace(/^Error:\s*/, ''));
+    this.name = 'ToolError';
+  }
+}
+
+export function toolError(message: string): never {
+  throw new ToolError(message);
+}

package/src/tool-gate.ts

@@ -1,31 +1,40 @@
-/** Why: Preserve the established compatibility and safety behavior (C7, D76, D77, D79, WS-D6). */
+/**
+ * Worker execution enforcement (C7, D76/D77/D82) — pure. RuntimeRoleManifest is THE runtime manifest
+ * shape; the file format lives in role-manifest.ts and the composed/persisted shapes derive from it
+ * (manifest-compose.ts, role-state.ts).
+ */
 import type { PermissionAction, UnknownToolStance } from './role-manifest.ts';
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export interface RuntimeRoleManifest {
   role: string;
   version?: string;
   tools: string[];
   permissions: Record<string, PermissionAction>;
-  /** Why: Preserve the established compatibility and safety behavior (D82). */
+  /** Stance for tools outside `tools`; 'allow' keeps user-installed extensions visible (D82). */
   unknownTools?: UnknownToolStance;
   services?: {
     todos?: {
       mode?: 'serial' | 'parallel';
     };
   };
+  /** P0 per-role guidelines (RFC §4.6): injected as a `pier-role` prompt section each turn. */
+  guidelines?: string[];
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+/** Parse the env-carried manifest; malformed input is null (fail-open: no gate) rather than a crash. */
 export function parseRuntimeManifest(envValue: string | undefined): RuntimeRoleManifest | null {
   if (!envValue) return null;
   try {
     const m = JSON.parse(envValue) as RuntimeRoleManifest;
     if (!m || typeof m.role !== 'string' || !Array.isArray(m.tools)) return null;
-    // Why: Preserve the established compatibility and safety behavior (D82).
     if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
       m.unknownTools = 'deny';
     }
+    if (m.guidelines !== undefined) {
+      m.guidelines = Array.isArray(m.guidelines)
+        ? m.guidelines.filter((g) => typeof g === 'string' && g.trim() !== '')
+        : undefined;
+    }
     return m;
   } catch {
     return null;
@@ -43,7 +52,6 @@ export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | n
   const perm = manifest.permissions[toolName] ?? manifest.permissions['*'] ?? 'allow';
   const known = manifest.tools.includes(toolName);
   const stance = manifest.unknownTools ?? 'deny';
-  // Why: Preserve the established compatibility and safety behavior (D82).
   if (perm === 'deny' || (!known && stance === 'deny')) {
     return {
       kind: 'deny',
@@ -59,27 +67,36 @@ export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | n
   return { kind: 'allow' };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D77, D82). */
-export function planActiveTools(
-  manifestTools: string[],
-  currentActive: string[],
+/**
+ * 'allow' keeps every tool but the explicit deny rules (D82 user-installed-extension axis); 'deny'
+ * intersects with the manifest. Shared by planActiveTools (visibility) and role-state's switch
+ * planning (all-tools universe).
+ */
+export function filterToolsByStance(
+  manifestTools: readonly string[],
+  universe: readonly string[],
   opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
-): { next: string[]; changed: boolean } | null {
-  if (manifestTools.length === 0 || currentActive.length === 0) return null;
+): string[] {
   if ((opts?.unknownTools ?? 'deny') === 'allow') {
     const denied = new Set(
       Object.entries(opts?.permissions ?? {})
-        .filter(([, v]) => v === 'deny')
-        .map(([k]) => k),
+        .filter(([, action]) => action === 'deny')
+        .map(([name]) => name),
     );
-    const next = currentActive.filter((t) => !denied.has(t));
-    if (next.length === 0) return null;
-    return { next, changed: next.length !== currentActive.length };
+    return universe.filter((name) => !denied.has(name));
   }
   const wanted = new Set(manifestTools);
-  const next = currentActive.filter((t) => wanted.has(t));
-  if (next.length === 0) return null;
-  const changed = next.length !== currentActive.length;
-  return { next, changed };
+  return universe.filter((name) => wanted.has(name));
 }
 
+/** Null means "keep the current active set": an empty result must never clear every tool (D77). */
+export function planActiveTools(
+  manifestTools: readonly string[],
+  currentActive: readonly string[],
+  opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
+): { next: string[]; changed: boolean } | null {
+  if (manifestTools.length === 0 || currentActive.length === 0) return null;
+  const next = filterToolsByStance(manifestTools, currentActive, opts);
+  if (next.length === 0) return null;
+  return { next, changed: next.length !== currentActive.length };
+}

package/src/vocab.ts

@@ -1,20 +1,17 @@
 /**
- * pi-herdr bridge vocabulary (M22: title is the board).
- *
- * DESIGN.md §4.2: no new transport. Wire = herdr NDJSON; todo authority = pi
- * session JSONL; display = pane.report_metadata title / state_labels.
+ * pi-herdr bridge vocabulary. DESIGN.md §4.2: no new transport — wire = herdr NDJSON, todo authority
+ * = pi session JSONL, display = pane.report_metadata title / state_labels.
  */
 
-/** Todo five-state (D34: three-state + blocked/abandoned, aligned with OMP). */
+/** Five states (D34): three-state + blocked/abandoned, aligned with OMP. */
 export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'abandoned';
 
 export const TODO_STATUSES: readonly TodoStatus[] = ['pending', 'in_progress', 'completed', 'blocked', 'abandoned'];
 
-/** Todo item: content + status; optional blocker (blocked only) and phase (D43). No stable id (last-write-wins). */
+/** Todo item: content + status; blocker only when blocked; optional phase groups (D43). No id (last-write-wins). */
 export interface TodoItem {
   content: string;
   status: TodoStatus;
-  /** Non-empty string only when status==='blocked' (D34). */
   blocker?: string;
   /** Optional group name (D43); non-empty, ≤30 chars. */
   phase?: string;
@@ -27,55 +24,88 @@ export interface TodoSnapshot {
   items: TodoItem[];
 }
 
-/** Snapshot counts (confirmation copy and title projection). */
 export interface TodoCounts {
   pending: number;
   inProgress: number;
   completed: number;
-  /** D91: blocked as its own column (title quartet ▶○■✓). */
+  /** D91: blocked is its own column (title quartet ▶○■✓). */
   blocked: number;
 }
 
 /** Source name for pane.report-agent. */
 export const REPORT_AGENT_SOURCE = 'pi-herdr';
 
-/** First-upgrade key used to clear the old 16-key chunked tokens (M13b leftover). */
+/** First-upgrade key used to clear the old 16-key chunked tokens (M13b). */
 export const PI_HERDR_META_KEY = 'pi-herdr';
 
-/** Model-facing todo tool name (DSH-compatible). */
 export const TODO_TOOL_NAME = 'todo_write';
 
 /** Snapshot key in tool-result details (persisted in session JSONL). */
 export const TODO_DETAILS_KEY = 'pi-herdr.todo';
 
 /** Confirmation copy (byte-aligned with DSH so model vocab transfers). */
-export function formatTodoConfirmation(items: TodoItem[]): string {
+export function formatTodoConfirmation(items: readonly TodoItem[]): string {
   const c = countTodos(items);
-  return `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
+  const base = `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
+  // Append blocked only when non-zero — the model must not read "nothing pending" while items sit
+  // blocked on a human. Zero keeps the DSH-aligned wording intact.
+  return c.blocked > 0 ? `${base.slice(0, -1)}, ${c.blocked} blocked.` : base;
 }
 
-export function countTodos(items: TodoItem[]): TodoCounts {
-  let pending = 0;
-  let inProgress = 0;
-  let completed = 0;
-  let blocked = 0;
+/** Every status the todo model knows; anything else in a snapshot is corrupt data (D34). */
+const STATUS_LOOKUP: Readonly<Record<TodoStatus, true>> = {
+  pending: true,
+  in_progress: true,
+  completed: true,
+  blocked: true,
+  abandoned: true,
+};
+
+/**
+ * Corrupt snapshots carry arbitrary JSON as `status` (`extractSnapshotFromDetails` does not validate),
+ * so every table lookup keyed by status must pass through this first — `TODO_MARKS['constructor']`
+ * would otherwise render a function, and `groups['constructor'].push` would throw.
+ */
+export const isTodoStatus = (value: unknown): value is TodoStatus =>
+  typeof value === 'string' && Object.hasOwn(STATUS_LOOKUP, value);
+
+const COUNTED_STATUSES = {
+  pending: 'pending',
+  in_progress: 'inProgress',
+  completed: 'completed',
+  blocked: 'blocked',
+} as const satisfies Partial<Record<TodoStatus, keyof TodoCounts>>;
+
+/** The four states that occupy a count column (`abandoned` is terminal and deliberately uncounted). */
+const isCountedStatus = (status: TodoStatus): status is keyof typeof COUNTED_STATUSES =>
+  Object.hasOwn(COUNTED_STATUSES, status);
+
+export function countTodos(items: readonly TodoItem[]): TodoCounts {
+  const counts: TodoCounts = { pending: 0, inProgress: 0, completed: 0, blocked: 0 };
   for (const it of items) {
-    if (it.status === 'pending') pending++;
-    else if (it.status === 'in_progress') inProgress++;
-    else if (it.status === 'completed') completed++;
-    else if (it.status === 'blocked') blocked++;
-    // abandoned is omitted (D34); blocked is its own column (D91)
+    const status = it?.status;
+    if (isTodoStatus(status) && isCountedStatus(status)) counts[COUNTED_STATUSES[status]] += 1;
   }
-  return { pending, inProgress, completed, blocked };
+  return counts;
 }
 
+/** Why a settlement carried no closing text (p24-class mis-attribution vs a truly silent worker). */
+export type SettlementNullReason = 'silent' | 'attribution-suspect' | 'extraction-failed';
+
+const NULL_CLOSING_SENTENCE: Record<SettlementNullReason, string> = {
+  'attribution-suspect': 'Its closing message could NOT be read — the session attribution is suspect (a wrong transcript may have been read). Check `subagent action output` / the ledger sessionFile before assuming it produced nothing; its work may be complete.',
+  'extraction-failed': 'It appears to have ended with a final report, but the closing text could not be extracted — read it from the session transcript.',
+  silent: 'It left no closing message.',
+};
+
 /** Subagent settlement notice (aligned with DSH). */
 export function formatSettlementNotice(
   agentId: string,
   closingMessage: string | null,
+  nullReason: SettlementNullReason = 'silent',
 ): string {
   const head = `Background subagent ${agentId} finished and will do no further work unless you send it more.`;
   return closingMessage
     ? `${head} Its closing message: ${closingMessage}`
-    : `${head} It left no closing message.`;
+    : `${head} ${NULL_CLOSING_SENTENCE[nullReason]}`;
 }