pi-pier 0.3.1 → 0.4.2

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;
+  /** The master's pipe name — the worker's `todo_sync` push 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,10 +9,15 @@
  * 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';
 
+/** pi's thinking levels in ascending order, plus `inherit` (summarize at the session's own level). */
+export const SUMMARY_THINKING_LEVELS = ['inherit', 'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+export type SummaryThinkingLevel = (typeof SUMMARY_THINKING_LEVELS)[number];
+
 export interface OnlineContextCompactConfig {
   enabled: boolean;
   logEnabled: boolean;
@@ -20,6 +25,8 @@ export interface OnlineContextCompactConfig {
   keepRecentTokens?: number;
   firstCompactionRequestScale: number;
   subsequentCompactionMargin: number;
+  /** Cap on the summary request's thinking level (never raised above the session's). */
+  summaryThinkingLevel: SummaryThinkingLevel;
 }
 
 export interface ObservationPackConfig {
@@ -73,7 +80,7 @@ export const DEFAULT_EFFICIENCY_CONFIG: EfficiencyConfig = Object.freeze({
   version: 1,
   onlineContextCompact: Object.freeze({
     enabled: false, logEnabled: false, cacheWriteReadRatio: 'auto', keepRecentTokens: 20000,
-    firstCompactionRequestScale: 2.0, subsequentCompactionMargin: 1.5,
+    firstCompactionRequestScale: 2.0, subsequentCompactionMargin: 1.5, summaryThinkingLevel: 'low',
   }),
   observationPack: Object.freeze({
     enabled: false, logEnabled: false, thresholdBytes: 10240, fullSends: 2,
@@ -86,11 +93,7 @@ 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';
+type FieldKind = 'bool' | 'int' | 'number' | 'ratio' | 'string' | 'optionalString' | 'enum';
 
 interface FieldSpec {
   readonly key: string;
@@ -100,6 +103,8 @@ interface FieldSpec {
   readonly max?: number;
   /** Issue text for a bound that must not be printed as a plain JS number ("1.0"). */
   readonly minText?: string;
+  /** Accepted values for `enum`. */
+  readonly values?: readonly string[];
 }
 
 /** A section is `{enabled, ...fields}`; field order fixes the order of reported issues. */
@@ -116,6 +121,7 @@ const SECTIONS: readonly SectionSpec[] = [
     { key: 'keepRecentTokens', kind: 'int', min: 1000 },
     { key: 'firstCompactionRequestScale', kind: 'number', min: 1, minText: '1.0' },
     { key: 'subsequentCompactionMargin', kind: 'number', min: 1, minText: '1.0' },
+    { key: 'summaryThinkingLevel', kind: 'enum', values: SUMMARY_THINKING_LEVELS },
   ] },
   { name: 'observationPack', fields: [
     { key: 'enabled', kind: 'bool' },
@@ -159,6 +165,8 @@ function issueFor(section: string, field: FieldSpec): string {
         : `${path} 必须是 ${field.min} 到 ${field.max} 之间的数字`;
     case 'ratio':
       return `${path} 必须是 "auto" 或非负有限数`;
+    case 'enum':
+      return `${path} 必须是 ${(field.values ?? []).join(' | ')} 之一`;
     default:
       return `${path} 必须是非空字符串`;
   }
@@ -193,6 +201,9 @@ function applyField(target: Record<string, unknown>, field: FieldSpec, raw: unkn
       if (typeof raw !== 'string' || !raw.trim()) return false;
       target[field.key] = raw.trim();
       return true;
+    case 'enum':
+      if (typeof raw !== 'string' || !(field.values ?? []).includes(raw)) return false;
+      break;
   }
   target[field.key] = raw;
   return true;

package/src/efficiency-store.ts

@@ -5,7 +5,7 @@
  */
 
 import { constants } from 'node:fs';
-import { lstat, mkdir, open, readdir, realpath, rename, rm, stat } from 'node:fs/promises';
+import { lstat, mkdir, open, readdir, realpath, rename, rm, stat, type FileHandle } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import {
@@ -52,13 +52,28 @@ export function observationObjectPath(root: string, obsId: string): string {
   return join(root, 'observation-pack', 'objects', `${obsId}.txt`);
 }
 
+/** Cross-process idempotence probe: a resumed process has no memo but the content-addressed object
+ *  is still on disk. A wrong-sized file is treated as absent so the writer re-verifies it. */
+export async function observationObjectExists(
+  root: string,
+  obsId: string,
+  expectedBytes?: number,
+): Promise<boolean> {
+  try {
+    const stats = await lstat(observationObjectPath(root, obsId));
+    return stats.isFile() && (expectedBytes === undefined || stats.size === expectedBytes);
+  } catch {
+    return false;
+  }
+}
+
 export function reducerObjectPath(root: string, sha256: string): string {
   return join(root, 'evidence-preserving-reducer', 'objects', `${sha256}.txt`);
 }
 
 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);
@@ -202,6 +217,27 @@ export async function storeContentAddressedObject(
   };
 }
 
+const ALIGN_SCAN_BYTES = 64 * 1024;
+
+/** Advance a mid-line offset to the next line start so a recall page never opens inside a line.
+ *  A single-line tail (no newline left) keeps the requested offset: skipping to EOF would make the
+ *  rest of the object unreadable. */
+async function alignOffsetToLineStart(handle: FileHandle, offset: number, size: number): Promise<number> {
+  if (offset <= 0 || offset >= size) return offset;
+  const prev = Buffer.alloc(1);
+  const { bytesRead: prevRead } = await handle.read(prev, 0, 1, offset - 1);
+  if (prevRead === 0 || prev[0] === 0x0a) return offset;
+
+  const scan = Buffer.alloc(Math.min(ALIGN_SCAN_BYTES, size - offset));
+  for (let pos = offset; pos < size; pos += scan.length) {
+    const { bytesRead } = await handle.read(scan, 0, Math.min(scan.length, size - pos), pos);
+    if (bytesRead === 0) break;
+    const newline = scan.subarray(0, bytesRead).indexOf(0x0a);
+    if (newline !== -1) return pos + newline + 1;
+  }
+  return offset;
+}
+
 export async function readStoredObjectChunk(
   filePath: string,
   offset: number,
@@ -218,14 +254,15 @@ export async function readStoredObjectChunk(
       throw new Error(`Offset ${offset} exceeds object size ${fileStat.size}`);
     }
 
-    const available = Math.max(0, fileStat.size - offset);
+    const start = await alignOffsetToLineStart(handle, offset, fileStat.size);
+    const available = Math.max(0, fileStat.size - start);
     const buffer = Buffer.alloc(Math.min(available, limits.maxBytes + 4));
-    const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, start);
     const sliced = sliceBufferChunk(buffer.subarray(0, bytesRead), 0, limits);
     // sliceBufferChunk's nextOffset is relative to the window it was given (offset 0). Callers page
     // with the absolute file offset from the header, so add the seek back.
-    const nextOffset = offset + sliced.nextOffset;
-    return { ...sliced, nextOffset, eof: nextOffset >= fileStat.size };
+    const nextOffset = start + sliced.nextOffset;
+    return { ...sliced, offset: start, nextOffset, eof: nextOffset >= fileStat.size };
   } finally {
     await handle?.close();
   }

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);
+}