@bermudi/pi-delegate 0.1.0

package/schema.ts

@@ -0,0 +1,289 @@
+import { Type, type SchemaOptions } from "@sinclair/typebox";
+import { VALID_THINKING_LEVELS } from "./constants.ts";
+import type { DelegateArguments } from "./types.ts";
+
+// JSON Schema string enum that keeps the literal union in `Static<>`.
+// `Type.String({ enum })` validates identically but widens to `string`;
+// `Type.Union([Type.Literal…])` keeps the literals but serializes as `anyOf`,
+// which some providers handle poorly. `Type.Unsafe` gives both: the wire
+// format stays `{ type: "string", enum: [...] }` and the type stays narrow.
+function StringEnum<const T extends readonly string[]>(
+  values: T,
+  options?: SchemaOptions,
+) {
+  return Type.Unsafe<T[number]>({
+    ...options,
+    type: "string",
+    enum: [...values],
+  });
+}
+
+export const delegateTaskSchema = Type.Object({
+  prompt: Type.Optional(
+    Type.String({
+      description: "Task prompt; omit only for close, list, or resumeFrom.",
+    }),
+  ),
+  agent: Type.Optional(
+    Type.String({
+      description: "Named agent profile; omit for an ad-hoc subagent.",
+    }),
+  ),
+  cwd: Type.Optional(
+    Type.String({
+      description: "Subagent directory; relative paths use parent cwd.",
+    }),
+  ),
+  systemPrompt: Type.Optional(
+    Type.String({
+      description: "Base system prompt; AgentSession adds project resources.",
+    }),
+  ),
+  context: Type.Optional(
+    StringEnum(["fresh", "with-parent-transcript"], {
+      description:
+        "fresh omits parent transcript; with-parent-transcript copies it (token-expensive).",
+      default: "fresh",
+    }),
+  ),
+  model: Type.Optional(
+    Type.String({
+      description: "Model override; omit to inherit parent.",
+    }),
+  ),
+  tools: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Omit to inherit; `*`=read/write/edit/bash (mutating); `ro`=read/grep/find/ls (read-only).",
+    }),
+  ),
+  thinking: Type.Optional(
+    StringEnum(VALID_THINKING_LEVELS, {
+      description:
+        "Thinking: off/minimal/low/medium/high/xhigh/max; defaults to agent/off.",
+    }),
+  ),
+  sessionId: Type.Optional(
+    Type.String({
+      description:
+        "Optional live pool key for multi-turn reuse; omit for one-shot tasks.",
+    }),
+  ),
+  action: Type.Optional(
+    StringEnum(["prompt", "close", "list"], {
+      description:
+        "Session action; close needs sessionId; list shows active pooled sessions.",
+      default: "prompt",
+    }),
+  ),
+  resumeFrom: Type.Optional(
+    Type.String({
+      description:
+        "Exact absolute .jsonl session path from retry output; never a ticket ID.",
+    }),
+  ),
+});
+
+// Single source of truth for registration, generated help, and the
+// DelegateArguments/TaskDef projections in types.ts.
+export const delegateArgumentsSchema = Type.Object({
+  action: Type.Optional(
+    StringEnum(["poll", "cancel", "wait"], {
+      description:
+        "Ticket control: poll, cancel, or wait. Prefer wait; do not cancel for time.",
+    }),
+  ),
+  async: Type.Optional(
+    Type.Boolean({
+      description:
+        "Detach work and return a ticket; results auto-deliver. Wait only when blocked.",
+      default: false,
+    }),
+  ),
+  ticket: Type.Optional(
+    Type.String({
+      description: "Ticket ID; omit only when polling all tickets.",
+    }),
+  ),
+  force: Type.Optional(
+    Type.Boolean({
+      description:
+        "True cancels after preview; completed writes/commands remain.",
+      default: false,
+    }),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Number({
+      minimum: 0,
+      description:
+        "How long wait blocks (ms); timeout does not cancel the ticket.",
+    }),
+  ),
+  tasks: Type.Optional(
+    Type.Array(delegateTaskSchema, {
+      minItems: 0,
+      description:
+        "Fields in entries; tasks run concurrently; separate dependent/shared-file work. []=help.",
+    }),
+  ),
+});
+
+/** Validate the three operation modes after compatibility reshaping. */
+export function validateDelegateOperation(
+  params: DelegateArguments,
+): string | undefined {
+  const tasks = params.tasks ?? [];
+  const isTicketControl = params.action !== undefined;
+
+  if (isTicketControl) {
+    if (params.tasks !== undefined || params.async === true) {
+      return "ticket control cannot include tasks or async; call it separately.";
+    }
+    if (params.action !== "poll" && !params.ticket) {
+      return `action '${params.action}' requires ticket.`;
+    }
+    if (params.action !== "cancel" && params.force === true) {
+      return "force is valid only with action 'cancel'.";
+    }
+    if (params.action !== "wait" && params.timeoutMs !== undefined) {
+      return "timeoutMs is valid only with action 'wait'.";
+    }
+    return undefined;
+  }
+
+  if (params.ticket !== undefined) {
+    return "ticket requires action 'poll', 'cancel', or 'wait'.";
+  }
+  if (params.force === true) return "force is valid only with action 'cancel'.";
+  if (params.timeoutMs !== undefined) {
+    return "timeoutMs is valid only with action 'wait'.";
+  }
+  if (!tasks.length) {
+    return params.async === true
+      ? "async dispatch requires at least one task."
+      : undefined; // Intentional help request.
+  }
+
+  for (const [index, task] of tasks.entries()) {
+    if (task.action === "close") {
+      if (!task.sessionId) {
+        return `task ${index + 1}: action 'close' requires sessionId.`;
+      }
+      const extras = Object.keys(task).filter(
+        (key) => key !== "action" && key !== "sessionId",
+      );
+      if (extras.length) {
+        return `task ${index + 1}: action 'close' accepts only action and sessionId.`;
+      }
+    }
+    if (task.action === "list") {
+      const extras = Object.keys(task).filter((key) => key !== "action");
+      if (extras.length) {
+        return `task ${index + 1}: action 'list' accepts only action.`;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/** Fields that belong to a task entry. Models sometimes place these at the
+ * top level of the arguments; the shim folds them back into a single task. */
+const TASK_FIELD_NAMES = [
+  "prompt",
+  "agent",
+  "cwd",
+  "systemPrompt",
+  "context",
+  "model",
+  "tools",
+  "thinking",
+  "sessionId",
+  "resumeFrom",
+] as const;
+
+/** Actions that are only valid at task level. The top-level `action` is
+ * ticket-scoped (poll/cancel/wait), so a flat close/list/prompt belongs to
+ * the wrapped task. */
+const TASK_ACTIONS = new Set(["prompt", "close", "list"]);
+
+function parseStringifiedArray(value: string): unknown[] | undefined {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Recover `tools` given as a string: a JSON array string, or a bare group
+ * token like "*" / "ro" wrapped into a single-element array. Anything else
+ * is left for schema validation to reject. */
+function normalizeToolsField(value: string): unknown {
+  const parsed = parseStringifiedArray(value);
+  if (parsed) return parsed;
+  const trimmed = value.trim();
+  return trimmed && !/[\s,]/.test(trimmed) ? [trimmed] : value;
+}
+
+/** Compatibility shim run by pi before schema validation. Recovers the
+ * malformed shapes weaker models emit, instead of letting them silently
+ * degrade to the help response (an empty `tasks` returns the manual, which
+ * models then misread as "the tool is broken"):
+ * - `tasks` as a JSON string instead of an array;
+ * - task fields (`prompt`, `systemPrompt`, `tools`, ...) placed at the top
+ *   level instead of inside a `tasks` entry — wrapped into a single task;
+ * - `tools` as a JSON string (or bare token) inside a task entry.
+ * Skipped when a ticket action is in play. All other invalid input is left
+ * for normal schema validation to reject loudly.
+ *
+ * Silent by design: these rewrites are lossless re-shaping, so unlike the
+ * model-suffix warning in task-resolution (which fires because thinking
+ * intent is discarded), recovery warrants no signal. */
+export function normalizeDelegateArguments(args: unknown): DelegateArguments {
+  if (!args || typeof args !== "object") return args as DelegateArguments;
+  const record: Record<string, unknown> = {
+    ...(args as Record<string, unknown>),
+  };
+
+  // Stringified `tasks` array → real array.
+  if (typeof record.tasks === "string") {
+    const parsed = parseStringifiedArray(record.tasks);
+    if (parsed) record.tasks = parsed;
+  }
+
+  // Flat task fields at the top level → wrap into a single task. Only fires
+  // when there is no usable tasks array and no ticket action (`ticket`,
+  // poll/cancel/wait) — those calls are legitimately taskless.
+  const hasTasks = Array.isArray(record.tasks) && record.tasks.length > 0;
+  const isTicketAction =
+    record.action === "poll" ||
+    record.action === "cancel" ||
+    record.action === "wait";
+  if (!hasTasks && !isTicketAction && record.ticket === undefined) {
+    const task: Record<string, unknown> = {};
+    for (const key of TASK_FIELD_NAMES) {
+      if (record[key] !== undefined) {
+        task[key] = record[key];
+        delete record[key];
+      }
+    }
+    if (typeof record.action === "string" && TASK_ACTIONS.has(record.action)) {
+      task.action = record.action;
+      delete record.action;
+    }
+    if (Object.keys(task).length > 0) record.tasks = [task];
+  }
+
+  // Stringified (or bare-token) `tools` inside task entries → real arrays.
+  if (Array.isArray(record.tasks)) {
+    record.tasks = record.tasks.map((entry: unknown) => {
+      if (!entry || typeof entry !== "object") return entry;
+      const e = entry as Record<string, unknown>;
+      if (typeof e.tools !== "string") return entry;
+      return { ...e, tools: normalizeToolsField(e.tools) };
+    });
+  }
+
+  return record as DelegateArguments;
+}

package/sessions.ts

@@ -0,0 +1,102 @@
+import * as fs from "node:fs";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+/** Link a subagent session to its parent and persist the header when possible. */
+export function setParentSession(sm: SessionManager, parentPath: string): void {
+  const inner = sm as unknown as {
+    fileEntries: Array<{ type: string; parentSession?: string }>;
+    getSessionFile?: () => string | undefined;
+    _rewriteFile?: () => void;
+  };
+  const header = inner.fileEntries[0];
+  if (header && header.type === "session") {
+    header.parentSession = parentPath;
+    // For a *resumed* session the file already exists on disk and the manager
+    // is flushed (SessionManager.open/setSessionFile sets flushed=true). The
+    // in-memory header mutation above is otherwise lost: upstream _persist()
+    // only *appends* new entries once flushed — it never rewrites the header.
+    // So a resumeFrom session would never surface as a child in /resume despite
+    // the link being set in memory. Rewrite the whole file (header + entries)
+    // so the parentSession field is actually persisted. Fresh sessions skip
+    // this (file doesn't exist yet); their first _persist() writes the mutated
+    // header along with the rest, and rewriting early would trip the
+    // duplicate-header bug in _persist()'s not-yet-flushed path.
+    const file = inner.getSessionFile?.();
+    if (file && fs.existsSync(file)) {
+      try {
+        inner._rewriteFile?.();
+      } catch {
+        /* best effort — link stays in-memory; not fatal */
+      }
+    }
+  }
+}
+
+/**
+ * Create a session manager for a subagent run.
+ *
+ * Always creates a standalone session file in the target cwd.
+ * Sets `parentSession` in the header so subagent work is discoverable
+ * as a child of the parent session in `/resume`.
+ *
+ * Returns the concrete `SessionManager` (ready to hand to `createAgentSession`)
+ * and its file path (for result reporting + pool bookkeeping).
+ */
+export function createSubagentSessionManager(
+  parentSessionManager: unknown,
+  cwd: string,
+): { manager: SessionManager; file: string } | undefined {
+  // Resolve parent session file path for linking.
+  const parentFile = (
+    parentSessionManager as
+      { getSessionFile?(): string | undefined } | undefined
+  )?.getSessionFile?.();
+
+  // Always persist subagent work so the main agent can search it later.
+  const sm = SessionManager.create(cwd);
+  const sessionFile = sm.getSessionFile();
+  if (!sessionFile) return undefined;
+
+  // Link to parent session so subagent appears as a child in /resume.
+  if (parentFile) {
+    setParentSession(sm, parentFile);
+  }
+
+  return { manager: sm, file: sessionFile };
+}
+
+/**
+ * Force-flush a session's header (and any buffered entries) to disk.
+ *
+ * pi-coding-agent's SessionManager intentionally does not write the `.jsonl`
+ * until the first assistant message lands (its `_persist()` gates the first
+ * write behind an "assistant message exists" check — a documented contract).
+ * When a subagent's *first* model call dies before producing one — e.g. a
+ * Cloudflare 524 gateway timeout — no file is ever created, yet the planned
+ * path is already recorded. That leaves delegate reporting a sessionFile that
+ * doesn't exist, which in turn leads the parent to attempt (and fail) a
+ * `resumeFrom` against a nonexistent file.
+ *
+ * This flushes via the upstream `_rewriteFile()` seam — the same private method
+ * upstream itself calls to recover from empty/corrupt session files — so the
+ * reported path becomes real and resumable. Idempotent: no-op when the file
+ * already exists or the session manager has no `sessionFile`.
+ *
+ * Returns true when a resumable file exists on return (whether this call wrote
+ * it or it pre-existed), false otherwise.
+ */
+export function persistSessionHeader(sm: unknown): boolean {
+  const inner = sm as {
+    getSessionFile?: () => string | undefined;
+    _rewriteFile?: () => void;
+  };
+  const file = inner.getSessionFile?.();
+  if (!file) return false;
+  if (fs.existsSync(file)) return true;
+  try {
+    inner._rewriteFile?.();
+  } catch {
+    /* best effort — caller falls back to reporting no sessionFile */
+  }
+  return fs.existsSync(file);
+}

package/settings.ts

@@ -0,0 +1,78 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface DelegateSettings {
+  agentOverrides?: Record<
+    string,
+    { model?: string; thinking?: string; tools?: string[]; skills?: string[] }
+  >;
+}
+
+/** Read and validate a JSON settings object, returning null on I/O or parse errors. */
+export function readDelegateSettingsFile(
+  filePath: string,
+): Record<string, unknown> | null {
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function getDelegateSettings(filePath: string): DelegateSettings | null {
+  const settings = readDelegateSettingsFile(filePath);
+  if (
+    !settings?.delegate ||
+    typeof settings.delegate !== "object" ||
+    Array.isArray(settings.delegate)
+  )
+    return null;
+  return settings.delegate as DelegateSettings;
+}
+
+const delegateSettingsCache = new Map<string, DelegateSettings | null>();
+
+/** Load merged delegate settings: project overrides user.
+ * Result is cached per cwd for the lifetime of the delegate call. */
+export function loadDelegateSettings(cwd: string): DelegateSettings | null {
+  const key = path.resolve(cwd);
+  const cached = delegateSettingsCache.get(key);
+  if (cached !== undefined) return cached;
+
+  const userPath = path.join(os.homedir(), ".pi", "agent", "settings.json");
+  // Look for project root by finding .pi/ directory, not just .pi/agents/
+  let projectPath: string | null = null;
+  let dir = key;
+  const root = path.resolve("/");
+  while (true) {
+    if (fs.existsSync(path.join(dir, ".pi"))) {
+      projectPath = path.join(dir, ".pi", "settings.json");
+      break;
+    }
+    if (dir === root) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  const user = getDelegateSettings(userPath);
+  const project = projectPath ? getDelegateSettings(projectPath) : null;
+
+  if (!user && !project) {
+    delegateSettingsCache.set(key, null);
+    return null;
+  }
+  const result: DelegateSettings = {
+    agentOverrides: {
+      ...(user?.agentOverrides ?? {}),
+      ...(project?.agentOverrides ?? {}),
+    },
+  };
+  delegateSettingsCache.set(key, result);
+  return result;
+}

package/spill.ts

@@ -0,0 +1,161 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getOutputSpillTail, getOutputSpillThreshold } from "./config.ts";
+
+// ── Spill: keep subagent final-output bloat out of the LLM context ───────
+//
+// Two audiences share one source of truth (`result.output`):
+//   - the human's expanded TUI view (always the full output, via
+//     render-branches.ts `new Markdown(r.output)`)
+//   - the LLM-facing `content` string (bounded here — tail kept, head spilled)
+//
+// The spill is a greppable plain-text `.md` projection of the *final output*
+// only. The full transcript already lives in the session `.jsonl`; this does
+// not duplicate it. Design: lossless always — if the spill write fails, we
+// degrade to today's behavior (full output in context) rather than hard-truncate.
+
+/** Decision over an output string: spill or not, and what stays in-context. */
+export interface SpillDecision {
+  /** True when the output exceeds the threshold and should be spilled. */
+  spill: boolean;
+  /** The text to keep in-context — full output when not spilling, the tail when spilling. */
+  inContext: string;
+  /** Length of the full output (chars). */
+  fullChars: number;
+}
+
+/**
+ * Pure decision: given an output string and bounds, decide whether to spill
+ * and what tail to keep in-context. Testable without any filesystem.
+ *
+ * - Output at or under the threshold → passthrough (no spill).
+ * - Over the threshold → keep the suffix of length `tailChars`.
+ * - The tail is the *suffix*, not the prefix: a subagent's verdict is at the
+ *   end; the preamble is usually regurgitated tool output.
+ *
+ * The tail slice is surrogate-pair-aware: if the cut lands on a trailing
+ * surrogate, it advances one so the in-context string never begins with a
+ * lone (replacement-char-rendering) half of an astral character.
+ */
+export function decideSpill(
+  output: string,
+  opts: { thresholdChars: number; tailChars: number },
+): SpillDecision {
+  const fullChars = output.length;
+  if (fullChars <= opts.thresholdChars) {
+    return { spill: false, inContext: output, fullChars };
+  }
+  return { spill: true, inContext: tailOf(output, opts.tailChars), fullChars };
+}
+
+/**
+ * Write the full output to a temp `.md` file and return its path, or `null`
+ * on failure. Never throws — callers rely on the lossless-degrade guarantee.
+ *
+ * Path shape: `os.tmpdir()/delegate-output-<sanitized-label>-<6hex>.md`,
+ * mode 0o600. The label is sanitized (subagent precedent) so agent names
+ * can't escape the filename. `suffix` (and `dir`) are injectable so tests get
+ * deterministic, collision-free names and can point at an unwritable dir to
+ * exercise the failure path without mocking.
+ */
+export function spillToTempFile(
+  output: string,
+  label: string,
+  suffix: string = randomBytes(3).toString("hex"),
+  dir: string = os.tmpdir(),
+): string | null {
+  const safeLabel = label.replace(/[^\w.-]+/g, "_");
+  const filePath = path.join(dir, `delegate-output-${safeLabel}-${suffix}.md`);
+  try {
+    fs.writeFileSync(filePath, output, { mode: 0o600 });
+    return filePath;
+  } catch (e) {
+    console.warn(
+      `[delegate] spill write failed (${filePath}): ${e instanceof Error ? e.message : String(e)}`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Render a subagent's final output for the LLM-facing `content` string.
+ *
+ * What the callers use. Behavior:
+ *   - under threshold (or empty/placeholder) → output unchanged
+ *   - over threshold + write ok → tail + pointer to the spill file
+ *   - over threshold + write fail → output unchanged (degrade), warn-logged
+ *
+ * `opts` lets tests inject small thresholds (and a `dir` to force write
+ * failures) without touching the config singleton (there are no config
+ * mutators — `delegate.json` is the only write path). Production callers omit
+ * it and pick up `delegate.json` defaults.
+ */
+export function renderOutputForLLM(
+  output: string,
+  label: string,
+  opts?: { thresholdChars?: number; tailChars?: number; dir?: string },
+): string {
+  // Skip empty / placeholder — nothing to spill, nothing to bound.
+  if (!output || !output.trim() || output === "(no output)") return output;
+
+  const thresholdChars = opts?.thresholdChars ?? getOutputSpillThreshold();
+  const tailChars = opts?.tailChars ?? getOutputSpillTail();
+
+  const decision = decideSpill(output, { thresholdChars, tailChars });
+  if (!decision.spill) return output;
+
+  const filePath = spillToTempFile(output, label, undefined, opts?.dir);
+  // Lossless degrade: write failed → return full output, never hard-truncate.
+  if (!filePath) return output;
+
+  return spillPointer(decision.inContext, filePath, decision.fullChars);
+}
+
+/**
+ * Render output for the running-ticket poll view: **tail only, no file.**
+ *
+ * The output is a moving target mid-flight (a done task's full spill lands at
+ * ticket completion via `formatCompletedTask`); writing a file per poll would
+ * churn paths and confuse the LLM. So the poll stays bounded with a tail and
+ * a note pointing to the eventual spill. Under the tail budget → unchanged.
+ */
+export function renderOutputForPoll(
+  output: string,
+  opts?: { tailChars?: number },
+): string {
+  if (!output || !output.trim() || output === "(no output)") return output;
+  const tailChars = opts?.tailChars ?? getOutputSpillTail();
+  if (output.length <= tailChars) return output;
+  const tail = tailOf(output, tailChars);
+  return `…${tail}\n[truncated — full output is spilled to a file when the ticket completes]`;
+}
+
+/** Assemble the tail + pointer block emitted on a successful spill. */
+function spillPointer(
+  tail: string,
+  filePath: string,
+  fullChars: number,
+): string {
+  return `…${tail}\n\n[full output (${humanSize(fullChars)}) spilled to ${filePath} —\n \`read\`/\`grep\` it if completeness matters here; above is the tail]`;
+}
+
+/**
+ * Suffix of `s` at most `n` chars long, surrogate-pair-aware. If the cut
+ * would land on a trailing surrogate, advance one so the result never starts
+ * with a lone half of an astral character.
+ */
+function tailOf(s: string, n: number): string {
+  if (s.length <= n) return s;
+  let start = s.length - n;
+  if (start > 0 && (s.charCodeAt(start) & 0xfc00) === 0xdc00) start++;
+  return s.slice(start);
+}
+
+/** Compact human-readable size from a char count (≈ bytes for ASCII). */
+function humanSize(chars: number): string {
+  if (chars < 1024) return `${chars} B`;
+  if (chars < 1024 * 1024) return `${Math.round(chars / 1024)} KB`;
+  return `${(chars / (1024 * 1024)).toFixed(1)} MB`;
+}