pi-pier 0.3.0 → 0.3.1

package/src/subagent-launch.ts

@@ -1,114 +0,0 @@
-/**
- * Subagent `execute` planners (validation + foreground wait).
- *
- * Why: execute mixed param checks, isolate git I/O, spawn, and wait-loop
- * decisions. The decisions are pure and must stay testable without a pane.
- */
-import { normalizeEntryKind } from './history-store.ts';
-
-export const FOREGROUND_POLL_MS = 2_000;
-
-export type LaunchParams = {
-  description?: unknown;
-  prompt?: unknown;
-  run_in_background?: unknown;
-  cwd?: unknown;
-  isolate?: unknown;
-  role?: unknown;
-  allowed_tools?: unknown;
-  tab?: unknown;
-};
-
-import type { SubagentSpec } from './subagent-core.ts';
-
-export type LaunchValidation =
-  | { kind: 'error'; text: string }
-  | {
-      kind: 'ok';
-      spec: SubagentSpec;
-      background: boolean;
-      isolate: boolean;
-      cwdParam: string | null;
-      roleKind: string;
-      suggested: string[];
-      tab: string | null;
-      /** Role manifest supplied by the caller (drives tool gating); null when unset. */
-      manifestRole: string | null;
-    };
-
-export function planLaunchValidation(
-  params: LaunchParams | null | undefined,
-  herdrAvailable: boolean,
-): LaunchValidation {
-  if (!herdrAvailable) {
-    return {
-      kind: 'error',
-      text: 'Error: subagent requires pi to run inside a herdr-managed pane (HERDR_ENV not set).',
-    };
-  }
-  const spec: SubagentSpec = {
-    description: String(params?.description ?? 'subagent'),
-    prompt: String(params?.prompt ?? ''),
-  };
-  if (!spec.prompt.trim()) {
-    return { kind: 'error', text: 'Error: `prompt` must be a non-empty string' };
-  }
-  const cwdParam = typeof params?.cwd === 'string' && params.cwd.trim() ? params.cwd.trim() : null;
-  const isolate = params?.isolate === true;
-  if (isolate && cwdParam) {
-    return {
-      kind: 'error',
-      text: 'Error: `isolate` and `cwd` are mutually exclusive — isolate creates a new worktree, cwd delegates into an existing one',
-    };
-  }
-  const suggested = Array.isArray(params?.allowed_tools)
-    ? params.allowed_tools.filter((t): t is string => typeof t === 'string' && t.trim() !== '')
-    : [];
-  const manifestRole =
-    typeof params?.role === 'string' && params.role.trim() ? params.role.trim() : 'worker-default';
-  const tab = typeof params?.tab === 'string' ? params.tab : null;
-  return {
-    kind: 'ok',
-    spec,
-    background: params?.run_in_background === true,
-    isolate,
-    cwdParam,
-    roleKind: normalizeEntryKind(typeof params?.role === 'string' ? params.role.trim() : undefined),
-    suggested,
-    manifestRole,
-    tab,
-  };
-}
-
-export function planIsolateRepoGuard(baseSha: string | null): { kind: 'error'; text: string } | { kind: 'ok'; sha: string } {
-  if (!baseSha) {
-    return { kind: 'error', text: 'Error: isolate requires a git repository with at least one commit' };
-  }
-  return { kind: 'ok', sha: baseSha };
-}
-
-export type ForegroundTickPlan =
-  | { kind: 'blocked' }
-  | { kind: 'settled'; text: string }
-  | { kind: 'wait'; delayMs: number }
-  | { kind: 'collect-final' }
-  | { kind: 'continue' };
-
-export function planForegroundTick(input: {
-  state: string | null;
-  session: { text: string | null; pendingTool: boolean; activity: boolean };
-}): ForegroundTickPlan {
-  if (input.state === 'blocked') return { kind: 'blocked' };
-  if (input.state === 'idle' || input.state === 'done') {
-    if (input.session.text) return { kind: 'settled', text: input.session.text };
-    if (input.session.pendingTool || !input.session.activity) {
-      return { kind: 'wait', delayMs: FOREGROUND_POLL_MS };
-    }
-    return { kind: 'collect-final' };
-  }
-  return { kind: 'continue' };
-}
-
-export function planPatienceExpiry(alive: boolean): 'move-to-background' | 'timeout' {
-  return alive ? 'move-to-background' : 'timeout';
-}

package/src/subagent-list-action.ts

@@ -1,69 +0,0 @@
-import { basename } from 'node:path';
-import { agoText, type AliveProbe, type SubEntry } from './subagent-core.ts';
-
-export interface ListActionResult {
-  content: Array<{ type: 'text'; text: string }>;
-  details: Record<string, unknown>;
-}
-
-export interface ListActionDeps {
-  subs: () => Iterable<SubEntry>;
-  probeAlive: (paneId: string, cwd: string) => Promise<AliveProbe>;
-  readAskFlag: (paneId: string) => Promise<string | null>;
-  now?: () => number;
-}
-
-/** Render the live background registry without coupling it to Cordis or the tool registration. */
-export async function executeSubagentList(deps: ListActionDeps): Promise<ListActionResult> {
-  const listed = [...deps.subs()].filter((sub) => sub.background);
-  if (listed.length === 0) {
-    return {
-      content: [{ type: 'text', text: 'No background subagents started (from this session branch).' }],
-      details: {},
-    };
-  }
-
-  const byTask = new Map<string, SubEntry>();
-  for (const sub of listed) {
-    const previous = byTask.get(sub.taskId);
-    if (!previous || sub.createdAt >= previous.createdAt) byTask.set(sub.taskId, sub);
-  }
-
-  const probes = new Map<string, AliveProbe>();
-  await Promise.all([...byTask.values()].map(async (sub) => {
-    if (sub.status === 'closed') return;
-    try {
-      probes.set(sub.paneId, await deps.probeAlive(sub.paneId, sub.cwd));
-    } catch {
-      /* Best effort for display. */
-    }
-  }));
-
-  const now = deps.now ?? Date.now;
-  const lines: string[] = [];
-  for (const sub of byTask.values()) {
-    const tabTag = sub.tabName ? ` [tab: ${sub.tabName}]` : '';
-    const wtTag = sub.isolate ? ` [wt: ${sub.isolate.branch}]` : '';
-    if (sub.status === 'closed') {
-      lines.push(`${sub.taskId.slice(0, 8)} [idle] (${sub.kind}, closed; action send revives)${tabTag}${wtTag} ${sub.description}`);
-      continue;
-    }
-
-    const state = sub.status === 'settled' ? 'idle' : 'running';
-    const takeoverMark = sub.userTakeover ? ', user-controlled' : '';
-    const probe = probes.get(sub.paneId);
-    const statusTag = probe?.agentStatus ? ` ${probe.agentStatus}` : '';
-    const activityTag = probe?.lastActivityMs != null ? `, active ${agoText(probe.lastActivityMs, now())}` : '';
-    let gateTag = '';
-    if (probe?.agentStatus === 'blocked') {
-      const question = await deps.readAskFlag(sub.paneId);
-      gateTag = question ? ` — AWAITING HUMAN: "${question}"` : ' — AWAITING HUMAN decision';
-    }
-    const cwdTag = probe?.foregroundCwd && probe.foregroundCwd !== sub.cwd
-      ? ` [cwd: ${basename(probe.foregroundCwd) || probe.foregroundCwd}]`
-      : '';
-    lines.push(`${sub.paneId} [${state}${takeoverMark}${statusTag}${activityTag}${gateTag}] (${sub.kind})${tabTag}${wtTag}${cwdTag} ${sub.description}`);
-  }
-
-  return { content: [{ type: 'text', text: lines.join('\n') }], details: {} };
-}

package/src/subagent-output-action.ts

@@ -1,104 +0,0 @@
-import type { HerdrAgentState, HerdrClientLike } from './herdr-client.ts';
-import type { SubEntry } from './subagent-core.ts';
-import {
-  computeSubagentOutputDelta,
-  formatSubagentOutput,
-  resolveSubagentStatus,
-  type SubagentOutputCursor,
-} from './subagent-output-core.ts';
-import { readSubagentOutput } from './subagent-output-adapter.ts';
-import { toolError } from './tool-error.ts';
-
-export interface OutputActionParams {
-  agentId?: unknown;
-  taskId?: unknown;
-  max_chars?: unknown;
-  maxChars?: unknown;
-}
-
-export interface OutputActionResult {
-  content: Array<{ type: 'text'; text: string }>;
-  details: Record<string, unknown>;
-}
-
-export interface OutputActionDeps {
-  client: HerdrClientLike;
-  resolveEntry: (rawId: string, cwd: string) => { entry: SubEntry } | { error: string };
-  readAskFlag: (paneId: string) => Promise<string | null>;
-  outputCursors: Map<string, SubagentOutputCursor>;
-  getCwd: (toolCtx: unknown) => string;
-}
-
-export async function executeSubagentOutput(
-  params: OutputActionParams | undefined,
-  toolCtx: unknown,
-  deps: OutputActionDeps,
-): Promise<OutputActionResult> {
-  const rawId = String(params?.agentId ?? params?.taskId ?? '').trim();
-  if (!rawId) return toolError('Error: missing agentId for output (see action list)') as OutputActionResult;
-
-  const cwd = deps.getCwd(toolCtx);
-  const resolved = deps.resolveEntry(rawId, cwd);
-  if ('error' in resolved) return toolError(resolved.error) as OutputActionResult;
-
-  const entry = resolved.entry;
-  let agentState: HerdrAgentState | null = null;
-  let askFlag: string | null = null;
-  try {
-    const agents = await deps.client.listAgents();
-    const agent = agents.find((candidate) => candidate.paneId === entry.paneId);
-    agentState = agent?.status ?? null;
-    askFlag = agent?.tokens?.['pi-ask'] ?? null;
-  } catch {
-    /* Best effort: output remains useful without live status. */
-  }
-  if (!askFlag && agentState === 'blocked') {
-    try {
-      askFlag = await deps.readAskFlag(entry.paneId);
-    } catch {
-      /* Best effort. */
-    }
-  }
-
-  const status = resolveSubagentStatus({
-    localStatus: entry.status,
-    herdrStatus: agentState,
-    hasAskFlag: Boolean(askFlag),
-  });
-
-  let rawRead: { text: string; revision: number; truncated: boolean };
-  try {
-    rawRead = await readSubagentOutput(deps.client, entry.paneId);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return toolError(`Error: failed to read output for subagent ${entry.paneId}: ${message}`) as OutputActionResult;
-  }
-
-  const prevCursor = deps.outputCursors.get(entry.paneId);
-  const maxChars = typeof params?.max_chars === 'number'
-    ? params.max_chars
-    : typeof params?.maxChars === 'number' ? params.maxChars : undefined;
-  const deltaResult = computeSubagentOutputDelta(prevCursor, rawRead.text, { maxChars });
-  deps.outputCursors.set(entry.paneId, deltaResult.nextCursor);
-
-  const formatted = formatSubagentOutput({
-    paneId: entry.paneId,
-    status,
-    revision: rawRead.revision,
-    bufferTruncated: rawRead.truncated,
-    deltaResult,
-    askQuestion: askFlag,
-  });
-
-  return {
-    content: [{ type: 'text', text: formatted }],
-    details: {
-      paneId: entry.paneId,
-      status,
-      revision: rawRead.revision,
-      truncated: rawRead.truncated || deltaResult.truncated,
-      restart: deltaResult.restart,
-      deltaLength: deltaResult.delta.length,
-    },
-  };
-}

package/src/subagent-output-adapter.ts

@@ -1,27 +0,0 @@
-/**
- * Herdr output-read adapter for subagents.
- *
- * Newer herdr exposes agent.read; older versions only expose pane.read. Prefer the semantic agent
- * endpoint and fall back to the pane endpoint so output observation stays version-compatible.
- */
-import type { HerdrClientLike } from './herdr-client.ts';
-
-export interface SubagentOutputRead {
-  text: string;
-  revision: number;
-  truncated: boolean;
-}
-
-export async function readSubagentOutput(
-  client: HerdrClientLike,
-  paneId: string,
-): Promise<SubagentOutputRead> {
-  if (typeof client.readAgent === 'function') {
-    try {
-      return await client.readAgent(paneId, { source: 'recent', stripAnsi: true });
-    } catch {
-      return await client.readPane(paneId, { source: 'recent', stripAnsi: true });
-    }
-  }
-  return await client.readPane(paneId, { source: 'recent', stripAnsi: true });
-}

package/src/subagent-output-core.ts

@@ -1,263 +0,0 @@
-/**
- * subagent-output-core.ts
- *
- * Pure functions for subagent incremental output extraction:
- *  - Cursor management (in-memory per-pane tail tracking)
- *  - Longest common suffix/prefix delta computation
- *  - Boundary handling for scrolling, clear-screen, repeated text (graceful degradation with restart: true)
- *  - Bounded character budgeting and metadata formatting
- */
-import type { HerdrAgentState } from './herdr-client.ts';
-import type { SubEntry } from './subagent-core.ts';
-
-export const OUTPUT_DEFAULT_MAX_CHARS = 6000;
-export const OUTPUT_HARD_CAP_CHARS = 16000;
-export const OUTPUT_MIN_OVERLAP = 16;
-export const OUTPUT_TAIL_CHARS = 500;
-
-export type SubagentStatus = 'running' | 'idle' | 'blocked' | 'settled';
-
-export interface SubagentOutputCursor {
-  /** Suffix of previous full text used for boundary matching */
-  tail: string;
-  /** Length of previous full text */
-  fullLength: number;
-}
-
-export interface SubagentOutputDeltaOptions {
-  /** Max characters of delta to return (default: 6000) */
-  maxChars?: number;
-  /** Minimum overlap length required for partial scroll matching (default: 16) */
-  minOverlap?: number;
-  /** Length of tail to retain in cursor (default: 500) */
-  tailChars?: number;
-}
-
-export interface SubagentOutputDeltaResult {
-  /** The new output text (or full bounded text on initial/restart) */
-  delta: string;
-  /** Whether the increment could not be determined reliably (scrolled away, cleared, ambiguous repeat) */
-  restart: boolean;
-  /** Whether delta was truncated to maxChars */
-  truncated: boolean;
-  /** New cursor to save for next call */
-  nextCursor: SubagentOutputCursor;
-}
-
-/**
- * Extract tail characters from a text buffer for cursor matching.
- */
-export function extractTail(text: string, tailChars = OUTPUT_TAIL_CHARS): string {
-  if (text.length <= tailChars) return text;
-  return text.slice(text.length - tailChars);
-}
-
-/**
- * Bound text to a maximum character budget, retaining the tail (most recent output).
- */
-export function boundText(text: string, maxChars: number): { text: string; truncated: boolean } {
-  if (text.length <= maxChars) {
-    return { text, truncated: false };
-  }
-  return {
-    text: text.slice(text.length - maxChars),
-    truncated: true,
-  };
-}
-
-/**
- * Pure function: Given previous cursor (tail + fullLength) and current full buffer text,
- * compute the incremental delta since last read.
- *
- * Boundary handling:
- *  1. Initial read (prevCursor is null/empty): returns full bounded text, restart=false.
- *  2. No change: fullLength and tail match, delta is empty, restart=false.
- *  3. Normal append: prevTail appears uniquely in currText -> delta is text after prevTail.
- *  4. Repeated text: prevTail appears multiple times -> ambiguous, returns full bounded text with restart=true.
- *  5. Partial buffer scroll: prevTail partially scrolled off top -> longest suffix of prevTail
- *     matching prefix of currText (>= minOverlap) identifies boundary.
- *  6. Full scroll / clear screen: no valid overlap found -> returns full bounded text with restart=true.
- */
-export function computeSubagentOutputDelta(
-  prevCursor: SubagentOutputCursor | null | undefined,
-  currText: string,
-  options?: SubagentOutputDeltaOptions,
-): SubagentOutputDeltaResult {
-  const rawMaxChars = options?.maxChars ?? OUTPUT_DEFAULT_MAX_CHARS;
-  const maxChars = Math.max(1, Math.min(rawMaxChars, OUTPUT_HARD_CAP_CHARS));
-  const minOverlap = options?.minOverlap ?? OUTPUT_MIN_OVERLAP;
-  const tailChars = options?.tailChars ?? OUTPUT_TAIL_CHARS;
-
-  // Case 1: First call (no previous cursor)
-  if (!prevCursor || !prevCursor.tail) {
-    const bounded = boundText(currText, maxChars);
-    return {
-      delta: bounded.text,
-      restart: false,
-      truncated: bounded.truncated,
-      nextCursor: {
-        tail: extractTail(currText, tailChars),
-        fullLength: currText.length,
-      },
-    };
-  }
-
-  const prevTail = prevCursor.tail;
-
-  // Case 2: Exact same content (no new output)
-  if (currText.length === prevCursor.fullLength && currText.endsWith(prevTail)) {
-    return {
-      delta: '',
-      restart: false,
-      truncated: false,
-      nextCursor: prevCursor,
-    };
-  }
-
-  // Case 3: prevTail appears in currText
-  const firstIdx = currText.indexOf(prevTail);
-  const lastIdx = currText.lastIndexOf(prevTail);
-
-  if (firstIdx !== -1) {
-    // 3a: Ambiguous duplicate occurrences in current text
-    if (firstIdx !== lastIdx) {
-      const bounded = boundText(currText, maxChars);
-      return {
-        delta: bounded.text,
-        restart: true,
-        truncated: bounded.truncated,
-        nextCursor: {
-          tail: extractTail(currText, tailChars),
-          fullLength: currText.length,
-        },
-      };
-    }
-
-    // 3b: Unique match
-    const rawDelta = currText.slice(firstIdx + prevTail.length);
-    if (rawDelta.length === 0) {
-      return {
-        delta: '',
-        restart: false,
-        truncated: false,
-        nextCursor: prevCursor,
-      };
-    }
-
-    const bounded = boundText(rawDelta, maxChars);
-    return {
-      delta: bounded.text,
-      restart: false,
-      truncated: bounded.truncated,
-      nextCursor: {
-        tail: extractTail(currText, tailChars),
-        fullLength: currText.length,
-      },
-    };
-  }
-
-  // Case 4: prevTail is not found in full. Check if a suffix of prevTail matches a prefix of currText
-  // (terminal buffer scrolled lines off the top).
-  let longestOverlap = 0;
-  const maxPossibleOverlap = Math.min(prevTail.length - 1, currText.length);
-  const effectiveMinOverlap = Math.min(minOverlap, prevTail.length);
-
-  for (let k = maxPossibleOverlap; k >= effectiveMinOverlap; k--) {
-    const suffix = prevTail.slice(prevTail.length - k);
-    if (currText.startsWith(suffix)) {
-      longestOverlap = k;
-      break;
-    }
-  }
-
-  if (longestOverlap >= effectiveMinOverlap) {
-    const rawDelta = currText.slice(longestOverlap);
-    const bounded = boundText(rawDelta, maxChars);
-    return {
-      delta: bounded.text,
-      restart: false,
-      truncated: bounded.truncated,
-      nextCursor: {
-        tail: extractTail(currText, tailChars),
-        fullLength: currText.length,
-      },
-    };
-  }
-
-  // Case 5: Clear screen or full scroll out -> degraded reset
-  const bounded = boundText(currText, maxChars);
-  return {
-    delta: bounded.text,
-    restart: true,
-    truncated: bounded.truncated,
-    nextCursor: {
-      tail: extractTail(currText, tailChars),
-      fullLength: currText.length,
-    },
-  };
-}
-
-/**
- * Resolve subagent semantic status from local subs registry and herdr agent state.
- */
-export function resolveSubagentStatus(opts: {
-  localStatus: SubEntry['status'];
-  herdrStatus?: HerdrAgentState | null;
-  hasAskFlag?: boolean;
-}): SubagentStatus {
-  if (opts.hasAskFlag || opts.herdrStatus === 'blocked') {
-    return 'blocked';
-  }
-  if (opts.herdrStatus === 'working') {
-    return 'running';
-  }
-  if (opts.localStatus === 'settled' || opts.localStatus === 'closed' || opts.herdrStatus === 'done') {
-    return 'settled';
-  }
-  if (opts.herdrStatus === 'idle') {
-    return 'idle';
-  }
-  if (opts.localStatus === 'running') {
-    return 'running';
-  }
-  return 'running';
-}
-
-export interface FormatSubagentOutputOpts {
-  paneId: string;
-  status: SubagentStatus;
-  revision: number;
-  bufferTruncated: boolean;
-  deltaResult: SubagentOutputDeltaResult;
-  askQuestion?: string | null;
-}
-
-/**
- * Format subagent output for display to the master model.
- */
-export function formatSubagentOutput(opts: FormatSubagentOutputOpts): string {
-  const parts: string[] = [];
-  const metaItems: string[] = [
-    `pane: ${opts.paneId}`,
-    `status: ${opts.status}${opts.status === 'blocked' && opts.askQuestion ? ` (question: "${opts.askQuestion}")` : ''}`,
-    `revision: ${opts.revision}`,
-  ];
-
-  if (opts.deltaResult.restart) {
-    metaItems.push('restart: true (buffer reset or scrolled)');
-  }
-  if (opts.bufferTruncated || opts.deltaResult.truncated) {
-    metaItems.push('truncated: true');
-  }
-
-  const header = `[Subagent Output | ${metaItems.join(' | ')}]`;
-  parts.push(header);
-
-  if (opts.deltaResult.delta.length === 0) {
-    parts.push('(no new output since last read)');
-  } else {
-    parts.push(opts.deltaResult.delta);
-  }
-
-  return parts.join('\n');
-}