@bermudi/pi-delegate 0.1.0

package/timer.ts

@@ -0,0 +1,46 @@
+// Node clamps timer delays larger than the signed 32-bit limit (~24.8 days)
+// to ~1ms. Long waits are therefore scheduled against an absolute deadline in
+// safe-sized chunks, so an intentionally patient timeout or inactivity window
+// cannot be collapsed into an immediate fire.
+
+/** Maximum delay a single `setTimeout` can represent before Node clamps it to
+ *  ~1ms (the signed 32-bit millisecond limit). */
+export const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+
+/**
+ * Invoke `onDeadline` at the absolute `deadline` timestamp, re-arming the timer
+ * in sub-`MAX_TIMER_DELAY_MS` chunks so Node's clamp cannot turn a long wait
+ * into an immediate fire.
+ *
+ * Returns a `clear()` that cancels the pending timer. `clear()` is idempotent
+ * and also suppresses a callback already dequeued but not yet run, so a deadline
+ * firing after cancellation is a no-op rather than a spurious action — callers
+ * therefore do not need their own "already settled / already aborted" re-check
+ * inside the terminal callback.
+ */
+export function scheduleDeadline(
+  deadline: number,
+  onDeadline: () => void,
+): () => void {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let cleared = false;
+  const arm = (): void => {
+    if (cleared) return;
+    const remaining = deadline - Date.now();
+    const delay = Math.min(Math.max(remaining, 0), MAX_TIMER_DELAY_MS);
+    timer = setTimeout(() => {
+      if (cleared) return;
+      if (Date.now() < deadline) {
+        arm();
+      } else {
+        onDeadline();
+      }
+    }, delay);
+  };
+  arm();
+  return () => {
+    cleared = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  };
+}

package/tools.ts

@@ -0,0 +1,41 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import {
+  createBashTool,
+  createEditTool,
+  createFindTool,
+  createGrepTool,
+  createLsTool,
+  createReadTool,
+  createWriteTool,
+} from "@earendil-works/pi-coding-agent";
+import { DEFAULT_TOOLS, READONLY_TOOLS } from "./constants.ts";
+
+/** Shorthand → concrete tool list. `*` = full agent (bash subsumes search);
+ *  `ro` = read-only scout (search without shell). */
+const TOOL_GROUPS: Record<string, string[]> = {
+  "*": DEFAULT_TOOLS,
+  ro: READONLY_TOOLS,
+};
+
+export const TOOL_FACTORIES: Record<string, (cwd: string) => AgentTool<any>> = {
+  read: createReadTool,
+  write: createWriteTool,
+  edit: createEditTool,
+  bash: createBashTool,
+  grep: createGrepTool,
+  find: createFindTool,
+  ls: createLsTool,
+};
+
+/** Expand tool-group shorthands (`*`, `ro`) into concrete tool lists.
+ *  Unknown names pass through unchanged for the caller to validate.
+ *  Returns a deduped list. */
+export function resolveToolGroups(tools: string[]): string[] {
+  const resolved: string[] = [];
+  for (const t of tools) {
+    const group = TOOL_GROUPS[t];
+    if (group) resolved.push(...group);
+    else resolved.push(t);
+  }
+  return [...new Set(resolved)];
+}

package/types.ts

@@ -0,0 +1,243 @@
+import type {
+  ThinkingLevel,
+  AgentToolResult,
+  AgentToolUpdateCallback,
+} from "@earendil-works/pi-agent-core";
+import type { Api, Model, Usage } from "@earendil-works/pi-ai";
+import type {
+  AgentSession,
+  ModelRegistry,
+  SessionManager,
+  SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import type { Static } from "@sinclair/typebox";
+import type { delegateArgumentsSchema } from "./schema.ts";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  model?: string;
+  thinking: ThinkingLevel;
+  tools: string[];
+  systemPrompt: string;
+  /** Origin of the profile. `claude` denotes imported .claude/agents files. */
+  scope?: "project" | "global" | "claude";
+}
+
+// ── Tool parameter types — derived from the TypeBox schema ────────────────
+// `delegateArgumentsSchema` in schema.ts is the single source of truth; these are
+// projections of it, so schema and types cannot drift. Field semantics live
+// in the schema's `description`s (which the calling model also sees).
+// The import is type-only, so the schema.ts ↔ types.ts cycle is erased at
+// compile time.
+
+export type DelegateArguments = Static<typeof delegateArgumentsSchema>;
+export type TaskDef = NonNullable<DelegateArguments["tasks"]>[number];
+/** Top-level async ticket action: "poll" | "cancel" | "wait". */
+export type DelegateAction = NonNullable<DelegateArguments["action"]>;
+/** Per-task session action: "prompt" | "close" | "list". */
+export type SessionAction = NonNullable<TaskDef["action"]>;
+
+// ── Async Ticket Types ─────────────────────────────────────────────────────
+
+export interface TicketWaiter {
+  signal?: AbortSignal;
+  onUpdate?: AgentToolUpdateCallback<DelegateDetails>;
+  resolve: (result: AgentToolResult<DelegateDetails>) => void;
+  reject: (reason: unknown) => void;
+  clearDeadline?: () => void;
+  settled: boolean;
+}
+
+export interface AsyncTicket {
+  id: string;
+  created: number;
+  completedAt?: number;
+  tasks: TaskDef[];
+  resolved: ResolvedTask[];
+  status: "running" | "cancelling" | "done" | "failed" | "cancelled";
+  results: (TaskResult | undefined)[];
+  progress: TaskProgress[];
+  controller: AbortController;
+  error?: string;
+  parentModelId?: string;
+  /** Active blocking waiters. Resolved by terminal delivery or timeout/abort. */
+  waiters?: TicketWaiter[];
+}
+
+export interface ReuseIntent {
+  /** Explicit model requested by this call/profile; omitted means use frozen. */
+  model?: Model<Api>;
+  /** Explicit base prompt requested by this call/profile; omitted means frozen. */
+  systemPrompt?: string;
+}
+
+export interface ResolvedTask {
+  prompt: string;
+  agent?: string;
+  model: Model<Api>;
+  tools: string[];
+  thinking: ThinkingLevel;
+  systemPrompt: string;
+  cwd: string;
+  context?: "fresh" | "with-parent-transcript";
+  sessionId?: string;
+  action?: SessionAction;
+  resumeFrom?: string;
+  agentName: string;
+  warnings: string[];
+  /** Explicit settings that must match a live pooled session on reuse. */
+  reuseIntent?: ReuseIntent;
+}
+
+export interface ToolActivity {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+  result?: {
+    content: Array<{ type: string; text?: string }>;
+    isError: boolean;
+  };
+  startTime: number;
+  endTime?: number;
+  /** Live stdout/stderr preview from tool_execution_update events. */
+  liveOutput?: string;
+}
+
+/** Stable machine-readable reason for a task failure.
+ *  - `stalled`: inactivity watchdog fired; the prompt was cooperatively aborted.
+ *  - `model_error`: the failure is attributable to the resolved model/provider
+ *    (account usage limit, quota exhausted, auth lost) — not transient for that
+ *    model, so same-model retry is pointless. The parent should resume with a
+ *    different `model` (see `resumeFrom` + `model`). */
+export type TaskFailureKind = "stalled" | "model_error";
+
+export interface TaskProgress {
+  index: number;
+  agent: string;
+  task: string;
+  status: "pending" | "running" | "done" | "failed";
+  durationMs: number;
+  tokens: number;
+  toolUses: number;
+  error?: string;
+  failureKind?: TaskFailureKind;
+  model?: string;
+  lastActivityAt?: number;
+  activities: ToolActivity[];
+  /** Human-facing notices (e.g. unknown tools ignored). Surfaced in the TUI
+   *  under the task; the LLM gets the same text in `content` already. */
+  warnings?: string[];
+}
+
+export interface DelegateDetails {
+  tasks: TaskDef[];
+  results: (TaskResult | { error: string })[];
+  progress: TaskProgress[];
+  parentModel?: string;
+  ticketId?: string;
+  /** Terminal/live ticket status when this result comes from an async ticket. */
+  status?: AsyncTicket["status"];
+}
+
+export interface TaskResult {
+  agent: string;
+  output: string;
+  error?: string;
+  /** Stable machine-readable failure reason; error remains human-facing. */
+  failureKind?: TaskFailureKind;
+  durationMs: number;
+  /** Display token count for the task, derived from the compaction-inclusive
+   *  session-stat delta. This matches `usage.totalTokens`; the usage object
+   *  additionally preserves the provider breakdown and cost. */
+  tokens: number;
+  /** Full provider Usage consumed by this task, including compacted-away
+   *  history. Always present (`emptyUsage()` on no-op/early-failure paths) so a
+   *  sync delegate call can fold subagent spend into the parent's session
+   *  total. Aggregate `cost.total` is accurate; the per-component cost fields
+   *  stay 0 because `getSessionStats()` exposes only the aggregate cost — and
+   *  Pi sums `cost.total` for nested usage anyway. */
+  usage: Usage;
+  sessionFile?: string;
+  touchedFiles: string[];
+}
+
+/** Single source of truth for a subagent's runtime configuration.
+ *  Passed to `createAgentSession` as `model` / `thinkingLevel` / `tools` / `cwd`. */
+export interface AgentRunConfig {
+  systemPrompt: string;
+  model: Model<Api>;
+  thinking: ThinkingLevel;
+  tools: string[];
+  cwd: string;
+}
+
+export interface AgentProgressUpdate {
+  tokens: number;
+  toolUses: number;
+  durationMs: number;
+  lastActivityAt?: number;
+  activities: ToolActivity[];
+  /** Set as soon as a terminal condition is detected, before cleanup settles. */
+  failureKind?: TaskFailureKind;
+}
+
+export interface TaskRunEnv {
+  /** Abort signal — parent's for sync, ticket's for async. May be undefined when no parent signal is available. */
+  signal: AbortSignal | undefined;
+  modelRegistry: ModelRegistry;
+  /** Parent session manager — used to link subagent sessions for /resume. */
+  parentSessionManager: { getSessionFile?(): string | undefined } | undefined;
+  /** Ticket id for busy-guard self-checks. undefined for sync. */
+  ticketId?: string;
+  /** When the delegate started. Used for close/list progress (elapsed time). */
+  delegateStartedAt: number;
+  /** Called for every progress update from runAgentSession. */
+  onProgress: (p: TaskProgress, u: AgentProgressUpdate) => void;
+  /** Called after every TaskProgress mutation (early-returns, completion). Sync uses this to fire onUpdate. */
+  onStatusChange?: () => void;
+}
+
+/** Structural subset of Pi's `ExtensionContext` used by delegate's
+ *  task-resolution and dispatch modules. Kept loose so the orchestrator can
+ *  pass the real ctx through without re-typing every Pi field. The
+ *  `sessionManager` mirrors Pi's `ReadonlySessionManager` (not re-exported
+ *  from the package index) — only the members delegate actually touches are
+ *  listed. */
+export interface DelegateToolCtx {
+  cwd: string;
+  model: Model<Api> | undefined;
+  modelRegistry: ModelRegistry;
+  sessionManager:
+    | {
+        getEntries(): SessionEntry[];
+        getLeafId(): string | null;
+        getSessionFile?(): string | undefined;
+      }
+    | undefined;
+  /** Optional hook Pi exposes for extensions to read the live system prompt. */
+  getSystemPrompt?: () => string | undefined;
+}
+
+/** Shape returned by the delegate tool's `execute`. Mirrors Pi's
+ *  `AgentToolResult<DelegateDetails>` without depending on the generic.
+ *  `usage` (sync dispatch only) is the aggregate subagent spend; Pi 0.81+
+ *  persists it on the tool result and folds it into the parent's
+ *  session/footer totals. Older hosts ignore it. Async tickets can't attach
+ *  usage — their results arrive via a follow-up message with no usage slot. */
+export interface DelegateToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: DelegateDetails;
+  /** Aggregate subagent usage for sync dispatch. Pi reads this for session
+   *  totals on 0.81+; harmless on older versions. */
+  usage?: Usage;
+}
+
+export interface AcquiredSession {
+  /** The live AgentSession — constructed once and reused across prompts (pool hits). */
+  session: AgentSession;
+  sessionManager: SessionManager | undefined;
+  sessionFile: string | undefined;
+  /** Fresh/resumed sessions are lifecycle-owned until a successful pool commit. */
+  lifecycleOwnsSession: boolean;
+}

package/usage.ts

@@ -0,0 +1,121 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { Usage } from "@earendil-works/pi-ai";
+
+/** Snapshot of the cumulative session usage fields we read for delta accounting. */
+export interface SessionUsageSnapshot {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+}
+
+/** Return a zero-valued Usage suitable for an action that made no model call. */
+export function emptyUsage(): Usage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: 0,
+    },
+  };
+}
+
+/**
+ * Read cumulative provider usage from a live AgentSession.
+ *
+ * `getSessionStats()` covers history that has been compacted away (and, on
+ * newer Pi hosts, compaction/branch-summary calls), so this is the right
+ * snapshot for pooled or resumed sessions — reading `session.messages` alone
+ * would under-count once a compaction boundary is crossed.
+ */
+export function snapshotSessionUsage(
+  session: Pick<AgentSession, "getSessionStats">,
+): SessionUsageSnapshot {
+  const stats = session.getSessionStats();
+  return {
+    input: stats.tokens.input,
+    output: stats.tokens.output,
+    cacheRead: stats.tokens.cacheRead,
+    cacheWrite: stats.tokens.cacheWrite,
+    cost: stats.cost,
+  };
+}
+
+function delta(after: number, before: number): number {
+  // A session can be replaced/branched by host code. Never report a negative
+  // billable amount if cumulative stats move backwards between snapshots.
+  return Math.max(0, after - before);
+}
+
+/** Convert a cumulative-snapshot delta into Pi's nested-tool Usage shape. */
+export function usageDelta(
+  before: SessionUsageSnapshot,
+  after: SessionUsageSnapshot,
+): Usage {
+  const input = delta(after.input, before.input);
+  const output = delta(after.output, before.output);
+  const cacheRead = delta(after.cacheRead, before.cacheRead);
+  const cacheWrite = delta(after.cacheWrite, before.cacheWrite);
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    totalTokens: input + output + cacheRead + cacheWrite,
+    // SessionStats exposes the aggregate cost only; Pi's session/footer
+    // accounting reads cost.total for nested tool usage. The component fields
+    // stay zero rather than inventing a provider-specific split.
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: delta(after.cost, before.cost),
+    },
+  };
+}
+
+/** Add two Usage values, preserving optional provider breakdowns when present. */
+export function addUsage(left: Usage, right: Usage): Usage {
+  const cacheWrite1h =
+    left.cacheWrite1h !== undefined || right.cacheWrite1h !== undefined
+      ? (left.cacheWrite1h ?? 0) + (right.cacheWrite1h ?? 0)
+      : undefined;
+  const reasoning =
+    left.reasoning !== undefined || right.reasoning !== undefined
+      ? (left.reasoning ?? 0) + (right.reasoning ?? 0)
+      : undefined;
+
+  return {
+    input: left.input + right.input,
+    output: left.output + right.output,
+    cacheRead: left.cacheRead + right.cacheRead,
+    cacheWrite: left.cacheWrite + right.cacheWrite,
+    ...(cacheWrite1h === undefined ? {} : { cacheWrite1h }),
+    ...(reasoning === undefined ? {} : { reasoning }),
+    totalTokens: left.totalTokens + right.totalTokens,
+    cost: {
+      input: left.cost.input + right.cost.input,
+      output: left.cost.output + right.cost.output,
+      cacheRead: left.cost.cacheRead + right.cost.cacheRead,
+      cacheWrite: left.cost.cacheWrite + right.cost.cacheWrite,
+      total: left.cost.total + right.cost.total,
+    },
+  };
+}
+
+/** Sum optional per-task usage without making callers manufacture zero values. */
+export function sumUsage(usages: readonly (Usage | undefined)[]): Usage {
+  return usages.reduce<Usage>(
+    (total, usage) => (usage ? addUsage(total, usage) : total),
+    emptyUsage(),
+  );
+}

package/utils.ts

@@ -0,0 +1,131 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+/** Resolve a path relative to the caller's working directory. Tilde paths and
+ * absolute paths intentionally ignore `baseCwd`. */
+export function resolveCwd(cwd: string, baseCwd = process.cwd()): string {
+  const expanded = cwd.startsWith("~")
+    ? path.join(os.homedir(), cwd.slice(1))
+    : cwd;
+  return path.isAbsolute(expanded)
+    ? path.resolve(expanded)
+    : path.resolve(baseCwd, expanded);
+}
+
+/** Validate the absolute `.jsonl` path accepted by `resumeFrom`. */
+export function validateResumeFromPath(resumeFrom: string): string | undefined {
+  if (!resumeFrom.trim()) {
+    return "expected an absolute .jsonl session file path copied from delegate retry output";
+  }
+
+  if (!resumeFrom.endsWith(".jsonl")) {
+    return "expected an absolute .jsonl session file path copied from delegate retry output";
+  }
+
+  const expanded = resumeFrom.startsWith("~")
+    ? path.join(os.homedir(), resumeFrom.slice(1))
+    : resumeFrom;
+  if (!path.isAbsolute(expanded)) {
+    return "expected an absolute .jsonl session file path copied from delegate retry output";
+  }
+
+  return undefined;
+}
+
+/** Extract text content from a partial tool result (tool_execution_update). */
+export function extractTextFromPartialResult(
+  partialResult: unknown,
+): string | undefined {
+  if (
+    !partialResult ||
+    typeof partialResult !== "object" ||
+    !("content" in partialResult)
+  )
+    return undefined;
+  const content = (partialResult as { content?: unknown }).content;
+  if (!Array.isArray(content)) return undefined;
+  const text = content
+    .filter(
+      (c): c is { type: string; text?: string } =>
+        c && typeof c === "object" && "type" in c && c.type === "text",
+    )
+    .map((c) => c.text)
+    .filter((t): t is string => typeof t === "string")
+    .join("\n");
+  return text || undefined;
+}
+
+/** Strip ANSI escape sequences from text. */
+export function stripAnsi(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+}
+
+/** Resolve carriage-return progress bars to their final line state. */
+export function resolveCarriageReturn(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => {
+      const parts = line.split("\r");
+      return parts[parts.length - 1] ?? "";
+    })
+    .join("\n");
+}
+
+/** Concatenate text blocks from assistant messages in a session slice. */
+export function extractOutput(messages: AgentMessage[]): string {
+  const parts: string[] = [];
+  for (const msg of messages) {
+    if (msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (block.type === "text" && block.text) parts.push(block.text);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+interface UsageLike {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  total?: number;
+  totalTokens?: number;
+}
+
+function isUsageLike(u: unknown): u is UsageLike {
+  if (u === null || typeof u !== "object") return false;
+  const r = u as Record<string, unknown>;
+  const numericKeys: (keyof UsageLike)[] = [
+    "input",
+    "output",
+    "cacheRead",
+    "total",
+    "totalTokens",
+  ];
+  let hasNumeric = false;
+  for (const k of numericKeys) {
+    const v = r[k as string];
+    if (v !== undefined) {
+      if (typeof v !== "number" || !Number.isFinite(v)) return false;
+      hasNumeric = true;
+    }
+  }
+  return hasNumeric;
+}
+
+/** Sum finite usage fields from assistant messages. */
+export function extractUsage(messages: AgentMessage[]) {
+  const usage = { input: 0, output: 0, cacheRead: 0, total: 0 };
+  for (const msg of messages) {
+    if (msg.role !== "assistant") continue;
+    const rawUsage: unknown = msg.usage;
+    if (!isUsageLike(rawUsage)) continue;
+    const u = rawUsage;
+    usage.input += u.input ?? 0;
+    usage.output += u.output ?? 0;
+    usage.cacheRead += u.cacheRead ?? 0;
+    usage.total += u.total ?? u.totalTokens ?? (u.input ?? 0) + (u.output ?? 0);
+  }
+  return usage;
+}