pi-pier 0.3.0 → 0.4.1

package/src/subagent-port.ts

@@ -1,27 +0,0 @@
-/**
- * Subagent outbound port (composition root → plugin).
- *
- * Why: index used to pass a bag of independently-nullable callbacks that the
- * plugin mutated field-by-field. A missing bag crashed at mount
- * (`Cannot set properties of undefined (setting 'applyReplySession')`).
- * Binding one `current` object is atomic: all methods or none.
- */
-export interface RunningSub {
-  paneId: string;
-  description: string;
-}
-
-export interface SubagentPort {
-  applyReplySession(paneId: string, sessionFile: string | null): void;
-  reconcileOnReply(paneId: string): string[];
-  listRunningSubs(): RunningSub[];
-  settleStatLine(paneId: string): Promise<string | null>;
-}
-
-export interface SubagentPortBox {
-  current: SubagentPort | null;
-}
-
-export function emptySubagentPortBox(): SubagentPortBox {
-  return { current: null };
-}

package/src/subagent-ready.ts

@@ -1,89 +0,0 @@
-/**
- * A14: spawn readiness had a single 30 s ping window and reported failures as one bare line
- * ("subagent pane wD:pJ pipe not ready within 30000ms"), even when the child process had already
- * died with a stack trace on its screen. With 3–4 concurrent isolated workers (each running heavy
- * commands) that window was hit repeatedly, and the diagnosis cost far more than the retry would.
- *
- * This module is the pure half: how long to wait, how to back off, when to give up early
- * (the pane is gone — no point in waiting for a pipe that cannot appear) and how to word the
- * failure so the model and the human can act on it.
- */
-
-/** Ping cadence: quick first probes, then exponential backoff capped at `READY_MAX_INTERVAL_MS`. */
-export const READY_BASE_INTERVAL_MS = 500;
-export const READY_MAX_INTERVAL_MS = 4000;
-
-/** Wait this long between two samples of the child pane's liveness (pane.list + pane read). */
-export const READY_LIVENESS_SAMPLE_MS = 2500;
-
-export interface ReadyProbe {
-  /** The pane still exists in pane.list (unknown shells count as alive). */
-  readonly paneAlive: boolean;
-  /** Tail of the pane's screen, used only to explain a failure. */
-  readonly tail?: string | null;
-}
-
-export type ReadyAttemptPlan =
-  | { readonly kind: 'ready' }
-  | { readonly kind: 'retry'; readonly delayMs: number }
-  | { readonly kind: 'give-up'; readonly reason: 'pane-gone' | 'timeout' };
-
-/**
- * Decide one readiness attempt.
- * `alive` is tri-state on purpose: an unavailable liveness probe (`null`) must not be read as death,
- * otherwise a slow herdr socket would fail spawns that are merely slow to boot.
- */
-export function planReadyAttempt(opts: {
-  elapsedMs: number;
-  attempt: number;
-  timeoutMs: number;
-  alive: boolean | null;
-  ready: boolean;
-}): ReadyAttemptPlan {
-  if (opts.ready) return { kind: 'ready' };
-  if (opts.alive === false) return { kind: 'give-up', reason: 'pane-gone' };
-  if (opts.elapsedMs >= opts.timeoutMs) return { kind: 'give-up', reason: 'timeout' };
-  return { kind: 'retry', delayMs: readyBackoffMs(opts.attempt) };
-}
-
-/** Exponential backoff with a cap: 500ms, 1s, 2s, 4s, 4s, … */
-export function readyBackoffMs(attempt: number, baseMs = READY_BASE_INTERVAL_MS, capMs = READY_MAX_INTERVAL_MS): number {
-  const n = Math.max(0, Math.floor(attempt));
-  return Math.min(capMs, baseMs * 2 ** n);
-}
-
-/** How many characters of pane tail to attach to a failure (enough for a stack trace head). */
-export const READY_TAIL_CHARS = 1200;
-
-export interface ReadyFailure {
-  readonly paneId: string;
-  readonly reason: 'pane-gone' | 'timeout';
-  readonly elapsedMs: number;
-  readonly timeoutMs: number;
-  /** Some agent states the wait observed (working/idle/…), for the "agent never reported" case. */
-  readonly lastStatus?: string | null;
-  readonly tail?: string | null;
-  /** True when the child process exited (pane gone) rather than never starting to report. */
-  readonly hint?: string | null;
-}
-
-/**
- * Failure text for the model. The three cases it must distinguish:
- *  1. the pane died (usually the child crashed — the tail carries the reason, cf. A13's stack trace);
- *  2. the pane is alive but never opened its pipe (extension failed to load, wrong pane env);
- *  3. the pane is alive and its agent is working, just slower than the timeout (retry is safe).
- */
-export function readyFailureText(failure: ReadyFailure): string {
-  const seconds = Math.round(failure.elapsedMs / 1000);
-  const head = failure.reason === 'pane-gone'
-    ? `subagent pane ${failure.paneId} exited before its pipe became ready (waited ${seconds}s)`
-    : `subagent pane ${failure.paneId} pipe not ready within ${seconds}s (limit ${Math.round(failure.timeoutMs / 1000)}s)`;
-  const why = failure.reason === 'pane-gone'
-    ? 'The child process is gone — its last output below usually carries the reason.'
-    : failure.lastStatus === 'working'
-      ? 'The pane is alive and working, so the prompt may simply be slow to boot; retrying the same call is safe.'
-      : 'The pane is alive but never registered its pipe — the child pi process may still be starting, or it failed to load the pier extension.';
-  const tail = failure.tail ? `\nlast output of ${failure.paneId}:\n${failure.tail}` : '';
-  const hint = failure.hint ? `\n${failure.hint}` : '';
-  return `${head}\n${why}${hint}${tail}`;
-}

package/src/subagent-registry.ts

@@ -1,70 +0,0 @@
-import type { HerdrClientLike } from './herdr-client.ts';
-import { foldSubsRegistry, makeRegistry, SUBS_CUSTOM_TYPE, type SubEntry } from './subagent-core.ts';
-import { swallow } from './swallow.ts';
-
-export interface SubagentRegistryHost {
-  pi: { appendEntry?: (customType: string, data: unknown) => void };
-  client: HerdrClientLike;
-  subs: Map<string, SubEntry>;
-  writeHistory: (entry: SubEntry, patch?: { status?: SubEntry['status']; closedAt?: number }, via?: string) => void;
-}
-
-export interface SubagentRegistry {
-  /** Append the registry snapshot to the session branch; duplicate snapshots are skipped (O1). */
-  persist(): void;
-  /** Replay `pi-herdr.subs` entries from the session branch into the live map. */
-  rebuild(eventCtx: unknown): void;
-  /** B6: close running rows whose pane herdr no longer lists. */
-  sweepZombieRunning(): Promise<void>;
-}
-
-/** Owns durable registry projection and startup recovery, separate from tool actions. */
-export function createSubagentRegistry(host: SubagentRegistryHost): SubagentRegistry {
-  let lastSnapshot = '';
-
-  function persist(): void {
-    try {
-      const registry = makeRegistry([...host.subs.values()]);
-      const snapshot = JSON.stringify(registry);
-      if (snapshot === lastSnapshot) return;
-      lastSnapshot = snapshot;
-      host.pi.appendEntry?.(SUBS_CUSTOM_TYPE, registry);
-    } catch (err) {
-      // Best-effort: session logging must not break delegation, but a ghost running subagent is the
-      // symptom when this fails silently, so keep the reason queryable (B9).
-      swallow('subagent.persist-subs', err);
-    }
-  }
-
-  function rebuild(eventCtx: unknown): void {
-    try {
-      const entries = (eventCtx as { sessionManager?: { getBranch?: () => readonly unknown[] } })
-        ?.sessionManager?.getBranch?.() ?? [];
-      const registry = foldSubsRegistry(entries as Parameters<typeof foldSubsRegistry>[0]);
-      for (const entry of registry.subs) host.subs.set(entry.paneId, entry);
-      lastSnapshot = ''; // Branch replay replaced live state; force the next persist.
-    } catch {
-      /* Registry recovery failure must not block the live session. */
-    }
-  }
-
-  async function sweepZombieRunning(): Promise<void> {
-    if (!host.client.available || host.subs.size === 0) return;
-    let livePaneIds: ReadonlySet<string>;
-    try {
-      livePaneIds = new Set((await host.client.listPanes()).map((pane) => pane.paneId));
-    } catch {
-      return; // Do not close agents when the liveness lookup itself failed.
-    }
-    let changed = false;
-    for (const [paneId, entry] of host.subs) {
-      if (entry.status !== 'running' || livePaneIds.has(paneId)) continue;
-      entry.status = 'closed';
-      host.writeHistory(entry, { status: 'closed', closedAt: Date.now() }, 'zombie-sweep');
-      changed = true;
-    }
-    if (changed) persist();
-  }
-
-  return { persist, rebuild, sweepZombieRunning };
-}

package/src/subagent-resolution.ts

@@ -1,41 +0,0 @@
-/**
- * Subagent task-id lookup rules.
- *
- * Kept separate from the Cordis plugin so prefix resolution remains usable without mounting the
- * master tree and can be verified independently from pane lifecycle code.
- */
-
-export type TaskIdResolutionResult =
-  | { kind: 'resolved'; taskId: string }
-  | { kind: 'ambiguous'; query: string; candidates: string[] }
-  | { kind: 'too_short'; query: string }
-  | { kind: 'not_found'; query: string };
-
-/**
- * Resolve a full or short task ID against known candidates.
- *
- * Exact matches are accepted regardless of length. Prefix matching requires four characters and
- * rejects ambiguity with a sorted candidate list.
- */
-export function resolveTaskIdPrefix(
-  query: string,
-  candidates: Iterable<string>,
-): TaskIdResolutionResult {
-  const trimmed = query.trim();
-  if (!trimmed) return { kind: 'not_found', query: trimmed };
-
-  const unique = Array.from(new Set(candidates));
-  const exact = unique.find((candidate) => candidate === trimmed);
-  if (exact) return { kind: 'resolved', taskId: exact };
-
-  if (trimmed.length < 4) return { kind: 'too_short', query: trimmed };
-
-  const lower = trimmed.toLowerCase();
-  const matches = unique.filter((candidate) => candidate.toLowerCase().startsWith(lower));
-  if (matches.length === 1) return { kind: 'resolved', taskId: matches[0]! };
-  if (matches.length > 1) {
-    matches.sort();
-    return { kind: 'ambiguous', query: trimmed, candidates: matches };
-  }
-  return { kind: 'not_found', query: trimmed };
-}

package/src/subagent-scope.ts

@@ -1,41 +0,0 @@
-/**
- * One Cordis fiber per subagent in the master process.
- * pipe / poller / history cleanup uses ctx.effect (LIFO dispose).
- * C3: workers must not import this module.
- */
-import { Context } from '@deepseek-ai/cordis';
-
-export interface ScopeHooks {
-  onDispose?: () => void;
-}
-
-export function createSessionRoot(hooks: ScopeHooks = {}): Context {
-  const root = new Context();
-  if (hooks.onDispose) {
-    root.effect(() => () => { hooks.onDispose?.(); }, 'session-root');
-  }
-  return root;
-}
-
-export async function mountSubagentScope(
-  root: Context,
-  paneId: string,
-  hooks: ScopeHooks = {},
-) {
-  // Why no second argument: the pinned cordis version takes only the plugin object here; the pane id
-  // already identifies the scope through the plugin name and the effect label.
-  return root.plugin({
-    name: `subagent:${paneId}`,
-    apply(ctx: Context) {
-      ctx.effect(() => () => { hooks.onDispose?.(); }, `subagent:${paneId}`);
-    },
-  });
-}
-
-export async function disposeSessionRoot(root: Context): Promise<void> {
-  try {
-    await root.fiber.dispose();
-  } catch {
-    /* second dispose is a no-op */
-  }
-}

package/src/subagent-session-io.ts

@@ -1,230 +0,0 @@
-/**
- * Child-session JSONL I/O: path resolution, settlement text, liveness probes.
- *
- * Why: pollLoop, foreground wait, and revive all shared the same candidate
- * order (reported path/id before recent-file fallback, excluding the parent
- * session). Keeping it in one adapter prevents settlement text from crossing sessions.
- */
-import { accessSync, constants, statSync } from 'node:fs';
-import type { HerdrClientLike } from './herdr-client.ts';
-import {
-  deriveSubSessionState,
-  lastAssistantText,
-  listSessionFiles,
-  readSessionFile,
-  sessionFileById,
-  type SessionEntryLike,
-  type SubSessionState,
-} from './session-tail.ts';
-import type { AliveProbe } from './subagent-core.ts';
-
-export interface SessionIoHost {
-  client: HerdrClientLike;
-  getSessionId: () => string;
-  sessionsDir: () => string;
-}
-
-export interface SessionIo {
-  resolveSessionFileCandidates(paneId: string, cwd: string): Promise<string[]>;
-  resolveSessionFile(paneId: string, cwd: string): Promise<string | null>;
-  collectFinalText(paneId: string, cwd: string, sinceTs: number, attempts?: number): Promise<string | null>;
-  readAskFlag(paneId: string): Promise<string | null>;
-  probeAlive(paneId: string, cwd: string): Promise<AliveProbe>;
-  subSessionState(paneId: string, cwd: string, sinceTs: number): Promise<SubSessionState>;
-}
-
-/** Cheap change fingerprint of a session file; null when it does not exist. */
-interface FileStamp {
-  size: number;
-  mtimeMs: number;
-}
-
-function stampOf(file: string): FileStamp | null {
-  try {
-    const s = statSync(file);
-    return { size: s.size, mtimeMs: s.mtimeMs };
-  } catch {
-    return null;
-  }
-}
-
-/** Readable regular file check: parsing the file would read it in full (up to MBs). */
-function isReadableFile(file: string): boolean {
-  try {
-    if (!statSync(file).isFile()) return false;
-    accessSync(file, constants.R_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Memo of values derived from a session file, keyed by path and invalidated by (size, mtime).
- *
- * Why: worker sessions grow to tens of MB, and the poll loop re-derives the same idle state every
- * tick (collectFinalText re-derives up to `attempts` times). Measured on a 31.6MB session:
- * file read + JSON.parse + derive ≈ 227ms, so an unchanged file must not be parsed twice.
- * An append-only JSONL changes size on every write, so (size, mtime) is a sound fingerprint.
- */
-class DerivedCache<T> {
-  private readonly entries = new Map<string, { stamp: FileStamp; sinceTs: number; value: T }>();
-  private readonly limit: number;
-
-  constructor(limit = 32) {
-    this.limit = limit;
-  }
-
-  get(file: string, stamp: FileStamp, sinceTs: number): T | undefined {
-    const hit = this.entries.get(file);
-    if (!hit || hit.stamp.size !== stamp.size || hit.stamp.mtimeMs !== stamp.mtimeMs || hit.sinceTs !== sinceTs) {
-      return undefined;
-    }
-    return hit.value;
-  }
-
-  set(file: string, stamp: FileStamp, sinceTs: number, value: T): void {
-    this.entries.delete(file);
-    this.entries.set(file, { stamp, sinceTs, value });
-    while (this.entries.size > this.limit) {
-      const oldest = this.entries.keys().next().value;
-      if (oldest === undefined) break;
-      this.entries.delete(oldest);
-    }
-  }
-}
-
-export function createSessionIo(h: SessionIoHost): SessionIo {
-  const stateCache = new DerivedCache<SubSessionState>();
-  const finalTextCache = new DerivedCache<string | null>();
-
-  async function resolveSessionFileCandidates(paneId: string, cwd: string): Promise<string[]> {
-    const out: string[] = [];
-    try {
-      const reported = await h.client.getAgentSessionPath(paneId);
-      if (reported) {
-        if (/\.jsonl$/.test(reported)) out.push(reported);
-        else {
-          const byId = sessionFileById(cwd, h.sessionsDir(), reported);
-          if (byId) out.push(byId);
-        }
-      }
-    } catch {
-      /* Reports may be unavailable during startup. */
-    }
-    const ownSession = h.getSessionId();
-    for (const f of listSessionFiles(cwd, h.sessionsDir(), 4)) {
-      if (f !== ownSession && !out.includes(f)) out.push(f);
-    }
-    return out;
-  }
-
-  async function resolveSessionFile(paneId: string, cwd: string): Promise<string | null> {
-    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
-      if (isReadableFile(file)) return file;
-    }
-    return null;
-  }
-
-  async function collectFinalText(
-    paneId: string,
-    cwd: string,
-    sinceTs: number,
-    attempts = 12,
-  ): Promise<string | null> {
-    for (let i = 0; i < attempts; i++) {
-      for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
-        const stamp = stampOf(file);
-        if (!stamp) continue;
-        const cached = finalTextCache.get(file, stamp, sinceTs);
-        if (cached !== undefined) {
-          if (cached) return cached;
-          continue;
-        }
-        const entries: SessionEntryLike[] | null = readSessionFile(file);
-        if (!entries) continue;
-        const text = lastAssistantText(entries, { sinceTs })?.text ?? null;
-        finalTextCache.set(file, stamp, sinceTs, text);
-        if (text) return text;
-      }
-      const wait = Promise.withResolvers<void>();
-      setTimeout(wait.resolve, 500);
-      await wait.promise;
-    }
-    return null;
-  }
-
-  async function readAskFlag(paneId: string): Promise<string | null> {
-    try {
-      const a = (await h.client.listAgents()).find((x) => x.paneId === paneId);
-      const v = a?.tokens?.['pi-ask'];
-      return typeof v === 'string' && v ? v : null;
-    } catch {
-      return null;
-    }
-  }
-
-  async function probeAlive(paneId: string, cwd: string): Promise<AliveProbe> {
-    const probe: AliveProbe = { paneExists: false, agentStatus: null, lastActivityMs: null };
-    let listed = false;
-    try {
-      const pane = (await h.client.listPanes()).find((p) => p.paneId === paneId);
-      listed = true;
-      probe.paneExists = pane != null;
-      probe.agentStatus = pane?.agentStatus ?? null;
-      if (pane?.foregroundCwd) probe.foregroundCwd = pane.foregroundCwd;
-    } catch {
-      /* pane.list unavailable — agent.list is a degraded fallback, not a death signal */
-    }
-    try {
-      const a = (await h.client.listAgents()).find((x) => x.paneId === paneId);
-      if (a) {
-        if (!listed) probe.paneExists = true;
-        probe.agentStatus = a.status ?? probe.agentStatus;
-        if (a.foregroundCwd) probe.foregroundCwd = a.foregroundCwd;
-      }
-    } catch {
-      /* agent.list is status-only; absence is not death */
-    }
-    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
-      const stamp = stampOf(file);
-      // Session files can disappear during candidate scanning; a vanished file has no activity.
-      if (!stamp) continue;
-      if (probe.lastActivityMs == null || stamp.mtimeMs > probe.lastActivityMs) probe.lastActivityMs = stamp.mtimeMs;
-    }
-    return probe;
-  }
-
-  async function subSessionState(
-    paneId: string,
-    cwd: string,
-    sinceTs: number,
-  ): Promise<SubSessionState> {
-    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
-      const stamp = stampOf(file);
-      // A missing or vanished path is skipped: herdr often reports a .jsonl path before the worker
-      // creates the file, and waitAgent(idle) returns immediately, which used to throw
-      // `Cannot read properties of null (reading 'length')` (session 01a055c5).
-      if (!stamp) continue;
-      const cached = stateCache.get(file, stamp, sinceTs);
-      if (cached) return cached;
-      const entries = readSessionFile(file);
-      // An empty/unparsable file has no state to cache; the next candidate may still have one.
-      if (!entries?.length) continue;
-      const state = deriveSubSessionState(entries, sinceTs);
-      stateCache.set(file, stamp, sinceTs, state);
-      return state;
-    }
-    return { text: null, pendingTool: false, activity: false, turnEnded: false };
-  }
-
-  return {
-    resolveSessionFileCandidates,
-    resolveSessionFile,
-    collectFinalText,
-    readAskFlag,
-    probeAlive,
-    subSessionState,
-  };
-}
-