@signalridge/pi-subagents 1.5.0 → 1.7.0

package/src/supervisor.ts

@@ -0,0 +1,115 @@
+/**
+ * supervisor.ts — `contact_supervisor`, the child→parent direction.
+ *
+ * `steer_subagent` sends guidance downward. Nothing sent anything upward: a
+ * subagent that hit a genuine fork in the road could only guess, finish wrong,
+ * and have the guess discovered later in its result.
+ *
+ * The answer comes from the HUMAN, not from a supervising model. Our subagents
+ * share the parent's `ExtensionContext`, so the parent's UI is directly
+ * reachable — asking the person who is sitting there is both cheaper and more
+ * correct than delegating the judgement to another model, and it is the same
+ * reason this package has no LLM arbitrator anywhere else.
+ *
+ * That reachability is also why this is ~80 lines rather than a filesystem
+ * channel with a poller on each end: in-process, the question is one promise.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { sanitizeDisplayText, truncateCodePoints } from "./ui/safe-text.js";
+
+/** Longest question a child may put to the parent, in characters. */
+const MAX_QUESTION = 2_000;
+/** Longest option label offered in a choice prompt. */
+const MAX_OPTION = 200;
+/** Most options a child may offer, so the picker stays usable. */
+const MAX_OPTIONS = 8;
+
+export interface SupervisorAsk {
+  /** Prompt the human with a free-text question; undefined = dismissed. */
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+  /** Prompt the human to pick one option; undefined = dismissed. */
+  select(title: string, options: string[]): Promise<string | undefined>;
+}
+
+export interface SupervisorToolContext {
+  /** The parent's UI. Omitted when there is no human to ask. */
+  ask?: SupervisorAsk;
+  /** Display name of the asking agent, for the prompt title. */
+  agentLabel: string;
+}
+
+function textResult(text: string, isError = false) {
+  return { content: [{ type: "text" as const, text }], isError, details: {} };
+}
+
+/**
+ * Build the `contact_supervisor` tool, or nothing when no human can answer.
+ *
+ * Returning an empty array rather than a tool that always fails is deliberate,
+ * and matches how nested tools are handled: injecting a tool whose every call
+ * is an error spends context to teach the model an affordance it does not have.
+ * Headless and RPC sessions therefore see no such tool at all.
+ */
+export function createSupervisorTool(context: SupervisorToolContext) {
+  if (!context.ask) return [];
+  const ask = context.ask;
+
+  return [
+    defineTool({
+      name: "contact_supervisor",
+      label: "Ask Supervisor",
+      description:
+        "Ask the human who started you a question and wait for their answer. Use ONLY for a decision you cannot make yourself and cannot defer: an ambiguous requirement where the readings lead to materially different work, a destructive step that needs confirmation, or missing information nothing available to you can supply. It interrupts a person, so prefer stating an assumption and continuing. Returns their answer, or tells you they declined — in which case proceed on your best judgement and say what you assumed.",
+      parameters: Type.Object({
+        question: Type.String({
+          description: "The question, self-contained. The human cannot see your conversation.",
+          maxLength: MAX_QUESTION,
+        }),
+        options: Type.Optional(
+          Type.Array(Type.String({ maxLength: MAX_OPTION }), {
+            description: `Offer up to ${MAX_OPTIONS} concrete choices instead of free text. Prefer this when the answers are known.`,
+            maxItems: MAX_OPTIONS,
+          }),
+        ),
+      }),
+      execute: async (_toolCallId, params) => {
+        // Both the question and any option labels are model-authored text about
+        // to be drawn into the user's terminal, so they are sanitized and
+        // bounded here — the same treatment any other child-supplied string
+        // gets before it reaches a UI surface.
+        const question = truncateCodePoints(sanitizeDisplayText(params.question), MAX_QUESTION, "…").trim();
+        if (!question) return textResult("Ask a non-empty question.", true);
+
+        const title = `${context.agentLabel} asks`;
+        const options = (params.options ?? [])
+          .map((option) => truncateCodePoints(sanitizeDisplayText(option), MAX_OPTION, "…").trim())
+          .filter((option) => option.length > 0)
+          .slice(0, MAX_OPTIONS);
+
+        let answer: string | undefined;
+        try {
+          answer =
+            options.length > 0
+              ? await ask.select(`${title}: ${question}`, options)
+              : await ask.input(title, question);
+        } catch (error: unknown) {
+          // A dialog that cannot open must not fail the child's whole run; it
+          // is told nobody answered and carries on under its own judgement.
+          return textResult(
+            `Could not reach the supervisor (${error instanceof Error ? error.message : String(error)}). Proceed on your best judgement and state the assumption you made.`,
+          );
+        }
+
+        const reply = answer?.trim();
+        if (!reply) {
+          return textResult(
+            "The supervisor did not answer. Proceed on your best judgement and state the assumption you made.",
+          );
+        }
+        return textResult(`Supervisor answered: ${reply}`);
+      },
+    }),
+  ];
+}

package/src/types.ts

@@ -30,13 +30,32 @@ export const DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as con
 /** Memory scope for persistent agent memory. */
 export type MemoryScope = "user" | "project" | "local";
 
-/** Isolation mode for agent execution. */
-export type IsolationMode = "worktree";
+/** Isolation mode for agent execution. "off" explicitly opts out of worktree isolation. */
+export type IsolationMode = "worktree" | "off";
 
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig {
   name: string;
   displayName?: string;
+  /**
+   * Badge colour for this agent, as a Claude Code palette name or `#RRGGBB`.
+   * Anything else renders without a badge rather than failing the load — a
+   * colour typo must not cost the user their agent.
+   */
+  color?: string;
+  /**
+   * Tools whose every call needs the user to agree first (`ask_tools:`). The
+   * third answer between `tools:` and `disallowed_tools:`, for tools that are
+   * usually fine and occasionally not. Approval comes from the human, never
+   * from a model — see `ask-tools.ts`.
+   */
+  askTools?: string[];
+  /**
+   * Shell command run by the HOST after this agent finishes, whose pass/fail is
+   * appended to its result (`gate:`). The one acceptance signal the agent
+   * cannot author — see `gate.ts`.
+   */
+  gate?: string;
   description: string;
   builtinToolNames?: string[];
   /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
@@ -69,6 +88,14 @@ export interface AgentConfig {
   /** Programmatic-only, for the same reason as `model` above. */
   thinking?: ThinkingLevel;
   maxTurns?: number;
+  /**
+   * Token budget for one run of this agent (`max_tokens`). `0`/omitted =
+   * unlimited, matching `maxTurns`. Bounds what a single turn can spend, which
+   * a turn count cannot: one turn can burn an arbitrary number of tokens.
+   */
+  maxTokens?: number;
+  /** Tool-call budget for one run of this agent (`max_tool_calls`). `0`/omitted = unlimited. */
+  maxToolCalls?: number;
   /** Persist this subagent as a normal pi session instead of keeping it in memory only. */
   persistSession?: boolean;
   /** Write the subagent's .output transcript. Defaults to true; false suppresses only that transcript. */
@@ -133,6 +160,17 @@ export interface AgentRecord {
   outputFile?: string;
   /** Cleanup function for the output file stream subscription. */
   outputCleanup?: () => void;
+  /**
+   * Session file path when the agent's conversation is persisted to disk
+   * (session_file in the agent definition or pi's session persistence). Set at
+   * spawn so an evicted record can be reopened as a resumable entry.
+   */
+  sessionFile?: string;
+  /**
+   * Resumable mention handle, when the agent was addressable by `@handle`.
+   * Only top-level agents carry one.
+   */
+  handle?: string;
   /**
    * Lifetime usage breakdown, accumulated via `message_end` events. Survives
    * compaction. Total = input + output + cacheWrite (cacheRead deliberately
@@ -179,6 +217,25 @@ export interface AgentRecord {
   detached?: boolean;
 }
 
+/**
+ * What survives a record's eviction so `@handle` keeps working. The live record
+ * is discarded after the cleanup timer, but the pi session it wrote is still on
+ * disk, and this is the little that is needed to find and describe it again.
+ *
+ * Named `ResumableAgentEntry` (not "tombstone") because this codebase already
+ * uses `ManagedSpawnTombstone` for the managed-spawn idempotency record — two
+ * different concepts must not share a name.
+ */
+export interface ResumableAgentEntry {
+  handle: string;
+  id: string;
+  type: SubagentType;
+  description: string;
+  /** Always set — a record with no session file is never indexed. */
+  sessionFile: string;
+  completedAt: number;
+}
+
 export interface AgentInvocation {
   /** Short display name, e.g. "haiku" — only set when different from parent. */
   modelName?: string;

package/src/ui/agent-mention.ts

@@ -0,0 +1,163 @@
+/**
+ * agent-mention.ts — what `@` can address, and the suggestions pi renders for it.
+ *
+ * A subagent is addressable whether or not it is currently running: a live
+ * record is messaged or resumed, an evicted one whose session is still on disk
+ * is reopened, and an agent *type* with no instance at all is started. That is
+ * the point of the handle — `@explore` means the Explore agent, not "the
+ * Explore process that happens to exist right now" — so the roster below unions
+ * all three, and the dispatcher and the popup read the same list.
+ *
+ * pi's `CombinedAutocompleteProvider` already owns `@`, where it means "attach a
+ * file". Extensions can wrap it (`ctx.ui.addAutocompleteProvider`), so this
+ * provider answers the `@` tokens that name an agent and delegates every other
+ * one — including all of `applyCompletion`, whose `@`-branch already inserts
+ * `item.value` plus a trailing space, which is exactly what a handle needs.
+ *
+ * Matching is case-insensitive prefix (not fuzzy), and when any agent matches,
+ * files are dropped from the list rather than mixed in — an `@name` that names
+ * an agent is never also a path.
+ *
+ * Every string that reaches a row passes through `sanitizeDisplayText` first:
+ * an agent description comes from a `.pi/agents/*.md` file that may not be
+ * trustworthy, and the popup draws into the user's terminal.
+ */
+
+import type { AutocompleteItem, AutocompleteProvider, AutocompleteSuggestions } from "@earendil-works/pi-tui";
+import type { AgentManager } from "../agent-manager.js";
+import { handleBase, MENTION_TRIGGER } from "../mention.js";
+import type { AgentRecordSnapshot, ResumableAgentEntry } from "../types.js";
+import { sanitizeDisplayText, truncateCodePoints } from "./safe-text.js";
+
+/**
+ * One thing `@` can address, and what sending to it will do. `typeLabel` is the
+ * agent's `display_name`, resolved by the caller: this module stays independent
+ * of the type registry, but the popup must agree with FleetView and the widget,
+ * which both render the label rather than the raw type.
+ */
+export type MentionTarget =
+  | { kind: "record"; handle: string; record: AgentRecordSnapshot; typeLabel: string }
+  | { kind: "resumable"; handle: string; entry: ResumableAgentEntry; typeLabel: string }
+  | { kind: "type"; handle: string; type: string; description: string };
+
+/** The registry facts the roster needs, so it stays independent of agent-types. */
+export type TypeInfo = { name: string; description: string };
+
+/**
+ * Everything `@` can reach, in the order the popup lists it: steerable agents
+ * first, then the other live ones earliest-launched, then evicted conversations
+ * that can be reopened, then agent types with no live instance. A type whose
+ * handle a record already holds is omitted — that name addresses the existing
+ * agent, which is what makes `@explore` mean "message the one that's running"
+ * and only otherwise "start one".
+ */
+export function mentionRoster(
+  manager: AgentManager,
+  types: readonly TypeInfo[],
+  // Identity by default: a caller with no registry to consult gets the raw
+  // type, which is also what the config lookup falls back to when no label is set.
+  displayNameOf: (type: string) => string = (type) => type,
+): MentionTarget[] {
+  const isLive = (r: AgentRecordSnapshot) => r.status === "running" || r.status === "queued";
+  const records = manager
+    .listAgents()
+    .filter((r) => r.handle !== undefined && r.parentAgentId === undefined)
+    .sort((a, b) => Number(isLive(b)) - Number(isLive(a)) || a.startedAt - b.startedAt);
+
+  const taken = new Set<string>();
+  const targets: MentionTarget[] = [];
+
+  for (const record of records) {
+    const handle = record.handle as string;
+    taken.add(handle.toLowerCase());
+    targets.push({ kind: "record", handle, record, typeLabel: displayNameOf(record.type) });
+  }
+
+  // Then agents that are gone but whose conversation can be reopened. After the
+  // live ones: a running agent is the likelier target, and this keeps the
+  // ordering "what exists now, then what can be brought back, then what can be
+  // started".
+  for (const entry of manager.listResumable()) {
+    if (taken.has(entry.handle.toLowerCase())) continue;
+    taken.add(entry.handle.toLowerCase());
+    targets.push({ kind: "resumable", handle: entry.handle, entry, typeLabel: displayNameOf(entry.type) });
+  }
+
+  for (const type of types) {
+    const handle = handleBase(type.name);
+    if (taken.has(handle)) continue;
+    taken.add(handle);
+    targets.push({ kind: "type", handle, type: type.name, description: type.description });
+  }
+  return targets;
+}
+
+export function createMentionProvider(
+  current: AutocompleteProvider,
+  roster: () => MentionTarget[],
+  isEnabled: () => boolean,
+): AutocompleteProvider {
+  return {
+    // Only `@` — the contract is "characters that should naturally trigger THIS
+    // provider", and pi unions each wrapper's own set onto the outermost one
+    // itself, so re-declaring the wrapped provider's characters here would both
+    // misreport us and duplicate that.
+    triggerCharacters: ["@"],
+
+    async getSuggestions(lines, cursorLine, cursorCol, options): Promise<AutocompleteSuggestions | null> {
+      const items = isEnabled() ? mentionItems(roster(), lines[cursorLine] ?? "", cursorCol) : null;
+      if (items) return items;
+      return current.getSuggestions(lines, cursorLine, cursorCol, options);
+    },
+
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}
+
+/** Suggestions for the `@…` token under the cursor, or null when it names no agent. */
+export function mentionItems(
+  roster: readonly MentionTarget[],
+  line: string,
+  cursorCol: number,
+): AutocompleteSuggestions | null {
+  const match = MENTION_TRIGGER.exec(line.slice(0, cursorCol));
+  if (!match) return null;
+
+  const typed = match[2].toLowerCase();
+  const items: AutocompleteItem[] = [];
+  for (const target of roster) {
+    if (!target.handle.toLowerCase().startsWith(typed)) continue;
+    items.push({ value: `@${target.handle}`, label: `@${target.handle}`, description: describeTarget(target) });
+  }
+  return items.length > 0 ? { items, prefix: `@${match[2]}` } : null;
+}
+
+/** Name the action that will actually happen, so the list never mispromises. */
+function describeTarget(target: MentionTarget): string {
+  if (target.kind === "type") return `start agent · ${summarize(target.description)}`;
+  if (target.kind === "resumable") {
+    // No status: the record is gone, and "completed" would imply one is still
+    // being tracked. The type carries the identity the handle may not.
+    return `resume · ${sanitizeDisplayText(target.typeLabel)} · ${summarize(target.entry.description)}`;
+  }
+  const { status, description } = target.record;
+  const action = status === "running" || status === "queued" ? "send message" : "resume";
+  return `${action} · ${status} · ${summarize(description)}`;
+}
+
+/**
+ * First sentence of a description, sanitized then clipped — agent descriptions
+ * run to paragraphs, and they come from files this extension did not write.
+ * Sanitize BEFORE truncating: cutting first can sever an escape sequence and
+ * leave a live introducer behind.
+ */
+function summarize(description: string): string {
+  const first = (description.match(/^.*?[.!?](?=\s|$)/s)?.[0] ?? description).replace(/\s+/g, " ").trim();
+  return truncateCodePoints(sanitizeDisplayText(first), 60, "…");
+}

package/src/ui/conversation-viewer.ts

@@ -7,11 +7,12 @@
 
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { type Component, Input, matchesKey, type TUI, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { renderAgentName } from "../agent-color.js";
 import { extractText } from "../context.js";
 import type { AgentRecordSnapshot } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { Theme } from "./agent-display.js";
-import { type AgentActivity, buildInvocationTags, describeActivity, fgPreservingNestedStyles, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-display.js";
+import { type AgentActivity, buildInvocationTags, describeActivity, fgPreservingNestedStyles, formatDuration, formatSessionTokens, getPromptModeLabel } from "./agent-display.js";
 import { PREVIEW_SCAN_LIMIT, safeTerminalText, sanitizeDisplayText, truncateCodePoints } from "./safe-text.js";
 import { getAgentStatusColor, getAgentStatusLabel, getAgentStatusMark } from "./status-label.js";
 import { createViewerKeys, type ViewerKeybindings, type ViewerKeys } from "./viewer-keys.js";
@@ -182,12 +183,12 @@ export class ConversationViewer implements Component {
     // agent's conversation ends and the parent's resumes. An inner rule would be
     // a third horizontal line competing with the two that mark the boundary, and
     // a four-sided box would cost two columns on every row for the same job.
-    const rule = () => th.fg("border", "─".repeat(Math.max(0, width)));
+    const rule = () => th.fg("borderAccent", "─".repeat(Math.max(0, width)));
     const hrMid = row("");
 
     lines.push(rule());
     lines.push(row(th.bold("Agent conversation")));
-    const name = getDisplayName(this.record.type);
+    const name = renderAgentName(this.record.type, th, { bold: true });
     const modeLabel = getPromptModeLabel(this.record.type);
     const modeTag = modeLabel ? th.fg("dim", `mode ${modeLabel}`) : undefined;
     const statusText = getAgentStatusLabel(this.record.status);
@@ -205,7 +206,7 @@ export class ConversationViewer implements Component {
 
     const headerParts = [
       th.fg(statusColor, `${getAgentStatusMark(this.record.status)} ${statusText}`),
-      th.bold(name),
+      name,
       modeTag,
       th.fg("muted", sanitizeDisplayText(this.record.description)),
       fgPreservingNestedStyles(th, "dim", headerStats.join(" · ")),

package/src/ui/fleet-list.ts

@@ -12,10 +12,12 @@
  */
 
 import { Editor, isKeyRelease, Key, matchesKey, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { borderedComponent } from "@signalridge/pi-ui";
+import { renderAgentName } from "../agent-color.js";
 import type { AgentManager } from "../agent-manager.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal } from "../usage.js";
-import { type AgentActivity, getDisplayName, type Theme } from "./agent-display.js";
+import { type AgentActivity, type Theme } from "./agent-display.js";
 import { ConversationViewer, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
 import { sanitizeDisplayText } from "./safe-text.js";
 import { getAgentStatusColor, getAgentStatusLabel, getAgentStatusMark } from "./status-label.js";
@@ -301,7 +303,7 @@ export class FleetList {
     void this.ui.custom<undefined>(
       (tui, theme, keybindings, done) => {
         this.viewerClose = () => done(undefined);
-        return new ConversationViewer(
+        return borderedComponent(new ConversationViewer(
           tui,
           session,
           record,
@@ -314,7 +316,7 @@ export class FleetList {
           keybindings,
           (message: string) => this.manager.steer(record.id, message),
           () => this.manager.getRecord?.(record.id),
-        );
+        ), (text) => theme.fg("borderAccent", text));
       },
       {
         overlay: true,
@@ -379,11 +381,11 @@ export class FleetList {
 
   private renderAgentRow(rosterIndex: number, sel: number, record: AgentRecord, width: number, theme: Theme): string {
     const selected = rosterIndex === sel;
-    const name = getDisplayName(record.type);
     const status = getAgentStatusLabel(record.status);
-    const nameText = selected
-      ? theme.bold(theme.fg("accent", name))
-      : theme.fg("muted", name);
+    const nameText = renderAgentName(record.type, theme, {
+      fallbackColor: selected ? "accent" : "muted",
+      bold: selected,
+    });
     const description = sanitizeDisplayText(record.description);
     const descriptionText = selected ? theme.fg("accent", description) : description;
     const semanticStatusColor = getAgentStatusColor(record.status);