@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.10

package/src/ui/fleet-state.ts

@@ -0,0 +1,154 @@
+/** Session-journal authority for bounded fleet alerts and settled disclosure choices. */
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+
+export const FLEET_STATE_ENTRY = "subagents:fleet-state";
+export const FLEET_STATE_VERSION = 1;
+export const MAX_FLEET_ALERT_DETAILS = 128;
+export const MAX_COMPACT_ALERT_COUNT = 99;
+export const MAX_ALERT_ID_LENGTH = 160;
+export const MAX_ALERT_TYPE_LENGTH = 80;
+export const MAX_ALERT_DESCRIPTION_LENGTH = 240;
+const ALERT_FIELD_COUNT = 5;
+
+export type FailureKind = "error" | "aborted" | "failed" | "killed";
+/** No AgentRecord, result, session, promise or usage references may cross this boundary. */
+export interface FleetAlert {
+  id: string;
+  type: string;
+  description: string;
+  state: FailureKind;
+  timestamp: number;
+}
+export interface FleetSnapshot {
+  version: typeof FLEET_STATE_VERSION;
+  collapsed: boolean;
+  alerts: FleetAlert[];
+  overflow: Record<FailureKind, number>;
+  /** Identity history lives in the existing journal, not an unbounded UI set. */
+  transition?: { alert: FleetAlert; acknowledged: boolean };
+}
+export interface FleetJournalEntry { type: string; customType?: string; data?: unknown }
+const KINDS: readonly FailureKind[] = ["error", "aborted", "failed", "killed"];
+const emptyOverflow = (): Record<FailureKind, number> => ({ error: 0, aborted: 0, failed: 0, killed: 0 });
+
+/** Validate whole checkpoints; corrupt/unknown entries cannot partially replace valid state. */
+function snapshot(data: unknown): FleetSnapshot | undefined {
+  if (!data || typeof data !== "object") return undefined;
+  const value = data as FleetSnapshot;
+  if (value.version !== FLEET_STATE_VERSION || typeof value.collapsed !== "boolean") return undefined;
+  // Earlier disclosure-only entries are valid empty checkpoints.
+  if (value.alerts === undefined && value.overflow === undefined) return { version: FLEET_STATE_VERSION, collapsed: value.collapsed, alerts: [], overflow: emptyOverflow() };
+  if (!Array.isArray(value.alerts) || value.alerts.length > MAX_FLEET_ALERT_DETAILS || !value.alerts.every(validAlert)
+    || new Set(value.alerts.map(alert => alert.id)).size !== value.alerts.length
+    || !value.overflow || !KINDS.every(kind => Number.isSafeInteger(value.overflow[kind]) && value.overflow[kind] >= 0)
+    || (value.transition !== undefined && (!value.transition || !validAlert(value.transition.alert) || typeof value.transition.acknowledged !== "boolean"))) return undefined;
+  return value;
+}
+
+function validAlert(value: unknown): value is FleetAlert {
+  if (!value || typeof value !== "object") return false;
+  const alert = value as FleetAlert;
+  return typeof alert.id === "string" && alert.id.length > 0 && alert.id.length <= MAX_ALERT_ID_LENGTH
+    && typeof alert.type === "string" && alert.type.length <= MAX_ALERT_TYPE_LENGTH
+    && typeof alert.description === "string" && alert.description.length <= MAX_ALERT_DESCRIPTION_LENGTH
+    && Object.keys(alert).length === ALERT_FIELD_COUNT
+    && KINDS.includes(alert.state) && Number.isFinite(alert.timestamp);
+}
+
+/** Bounded strings and plain values only, including when a detached spool supplied the input. */
+export function fleetAlert(value: unknown): FleetAlert | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const record = value as { id?: unknown; type?: unknown; description?: unknown; status?: unknown; completedAt?: unknown; startedAt?: unknown };
+  if (typeof record.id !== "string" || !record.id || record.id.length > MAX_ALERT_ID_LENGTH || typeof record.type !== "string"
+    || typeof record.description !== "string" || !KINDS.includes(record.status as FailureKind)) return undefined;
+  const timestamp = record.completedAt ?? record.startedAt;
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) return undefined;
+  const clean = (text: string, limit: number) => stripTerminalSequences(text).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, limit);
+  return { id: record.id, type: clean(record.type, MAX_ALERT_TYPE_LENGTH), description: clean(record.description, MAX_ALERT_DESCRIPTION_LENGTH), state: record.status as FailureKind, timestamp };
+}
+
+/**
+ * At most N detailed alerts plus four exact overflow counters in RAM. Each transition
+ * checkpoints bounded state. For an overflow id, scan the active branch backwards for
+ * its last transition (O(journal length) time, O(1) extra space). The host already owns
+ * that journal; no extra id/ack set, file, or global registry is retained here.
+ */
+export class FleetJournal {
+  collapsed = true;
+  private readonly details = new Map<string, FleetAlert>();
+  private overflow = emptyOverflow();
+  private entries: () => readonly FleetJournalEntry[] = () => [];
+  private append: ((state: FleetSnapshot) => void) | undefined;
+  private settledCollapsed = true;
+
+  restore(entries: () => readonly FleetJournalEntry[], append: (state: FleetSnapshot) => void): void {
+    this.entries = entries;
+    this.append = append;
+    this.details.clear();
+    this.overflow = emptyOverflow();
+    this.collapsed = true;
+    const branch = entries();
+    for (let i = branch.length - 1; i >= 0; i--) {
+      const entry = branch[i];
+      if (entry.type !== "custom" || entry.customType !== FLEET_STATE_ENTRY) continue;
+      const state = snapshot(entry.data);
+      if (!state) continue;
+      this.collapsed = state.collapsed;
+      this.overflow = { ...state.overflow };
+      for (const alert of state.alerts) this.details.set(alert.id, { ...alert });
+      break;
+    }
+    this.settledCollapsed = this.collapsed;
+  }
+
+  get alerts(): readonly FleetAlert[] { return [...this.details.values()]; }
+  get overflowCount(): number { return KINDS.reduce((sum, kind) => sum + this.overflow[kind], 0); }
+  get count(): number { return this.details.size + this.overflowCount; }
+
+  /** Duplicate notices and polling are not new failures; acknowledged ids stay read. */
+  report(alert: FleetAlert): void {
+    const detail = this.details.get(alert.id);
+    const previous = detail ? { alert: detail, acknowledged: false } : this.previous(alert.id);
+    if (previous && previous.alert.timestamp >= alert.timestamp) return;
+    // A resumed agent keeps its id. Replace its unread attempt, or reopen an
+    // acknowledged identity only for a newer failure, never for a stale notice.
+    if (previous && !previous.acknowledged) {
+      if (detail) this.details.set(alert.id, alert);
+      else { this.overflow[previous.alert.state]--; this.overflow[alert.state]++; }
+    } else if (this.details.size < MAX_FLEET_ALERT_DETAILS) this.details.set(alert.id, alert);
+    else this.overflow[alert.state]++;
+    this.write({ alert, acknowledged: false });
+  }
+
+  acknowledge(id: string): void {
+    const detail = this.details.get(id);
+    const previous = detail ? { alert: detail, acknowledged: false } : this.previous(id);
+    if (!previous || previous.acknowledged) return;
+    if (!this.details.delete(id)) this.overflow[previous.alert.state]--;
+    this.write({ alert: previous.alert, acknowledged: true });
+  }
+
+  /** Debounced by the controller; a net-no-change burst writes nothing. */
+  flushDisclosure(): void {
+    if (this.collapsed !== this.settledCollapsed) this.write();
+  }
+
+  private previous(id: string): FleetSnapshot["transition"] {
+    const branch = this.entries();
+    for (let i = branch.length - 1; i >= 0; i--) {
+      const entry = branch[i];
+      if (entry.type !== "custom" || entry.customType !== FLEET_STATE_ENTRY) continue;
+      const data = entry.data as FleetSnapshot | undefined;
+      if (data?.version === FLEET_STATE_VERSION && data.transition?.alert?.id === id) {
+        const valid = snapshot(data);
+        if (valid) return valid.transition;
+      }
+    }
+    return undefined;
+  }
+
+  private write(transition?: FleetSnapshot["transition"]): void {
+    this.append?.({ version: FLEET_STATE_VERSION, collapsed: this.collapsed, alerts: [...this.details.values()], overflow: { ...this.overflow }, ...(transition ? { transition } : {}) });
+    this.settledCollapsed = this.collapsed;
+  }
+}

package/src/ui/notification-view.ts

@@ -0,0 +1,139 @@
+/**
+ * notification-view.ts -- the `subagent-notification` message renderer.
+ *
+ * Core gives a custom message with a registered renderer a ▸/▾ gutter, collapses
+ * it to the renderer's first line, and toggles it on click. So the first line is
+ * the whole collapsed notice and no marker is drawn here:
+ *
+ *   ✓ audit the RPC path · 12 tools · 33.8k token · ~$0.0042 · 41.2s
+ *   3 agents finished · ✓ a, ✓ b, ✗ c
+ *
+ * Expanded adds the stats, the result preview and the transcript as a link.
+ */
+
+import { pathToFileURL } from "node:url";
+import { type Component, hyperlink, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { NotificationDetails } from "../types.js";
+import { formatCost, formatMs, formatTokens, formatTurns, type Theme } from "./agent-widget.js";
+import { fallbackFlag, fallbackFlagText, hasFallback } from "./fallback-flag.js";
+
+/** Lines of the result preview shown when expanded. */
+const EXPANDED_PREVIEW_LINES = 30;
+
+const FAILED = new Set(["error", "stopped", "aborted"]);
+
+function icon(d: NotificationDetails, theme: Theme): string {
+  return FAILED.has(d.status) ? theme.fg("error", "✗") : theme.fg("success", "✓");
+}
+
+/** The parts after the description: tools, tokens, cost, duration. */
+function statParts(d: NotificationDetails, showCost: boolean): string[] {
+  const parts: string[] = [];
+  if (d.toolUses > 0) parts.push(`${d.toolUses} tool${d.toolUses === 1 ? "" : "s"}`);
+  if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
+  if (showCost) {
+    const cost = formatCost(d.totalCost ?? 0);
+    if (cost) parts.push(cost);
+  }
+  if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
+  return parts;
+}
+
+/** `✓ desc · 12 tools · 33.8k token · ~$0.0042 · 41.2s`. */
+export function noticeSummary(d: NotificationDetails, theme: Theme, showCost: boolean): string {
+  const dot = ` ${theme.fg("dim", "·")} `;
+  // Leading, before the unbounded description: the collapsed line is truncated
+  // from the right, and a substituted model must not be what gets cut.
+  const flag = fallbackFlag(theme, d) ? `${fallbackFlag(theme, d)} ` : "";
+  const head = `${icon(d, theme)} ${flag}${theme.bold(d.description)}`;
+  // Ahead of the stats for the same reason: truncation must not cut it.
+  const resume = d.resumeHint ? [theme.fg("warning", `resume ${d.id} to continue`)] : [];
+  const stats = statParts(d, showCost).map(p => theme.fg("dim", p));
+  return [head, ...resume, ...stats].join(dot);
+}
+
+/** `3 agents finished · ✓ a, ✓ b, ✗ c`. */
+export function groupSummary(all: NotificationDetails[], theme: Theme): string {
+  const names = all.map(d => `${icon(d, theme)} ${d.description}`).join(theme.fg("dim", ", "));
+  // In the heading, ahead of the member list that truncation eats from the end,
+  // so a fallback member listed last is still counted.
+  const groups = new Map<string, { carrier: NotificationDetails; count: number }>();
+  for (const carrier of all.filter(d => d.modelTier !== undefined || hasFallback(d))) {
+    const key = `${hasFallback(carrier)}:${fallbackFlagText(1, carrier)}`;
+    const group = groups.get(key);
+    if (group) group.count++;
+    else groups.set(key, { carrier, count: 1 });
+  }
+  const flags = [...groups.values()].map(({ carrier, count }) => fallbackFlag(theme, carrier, count)).join(" ");
+  const flag = flags ? ` ${flags}` : "";
+  return `${theme.bold(`${all.length} agents finished`)}${flag} ${theme.fg("dim", "·")} ${names}`;
+}
+
+/** The transcript as an OSC 8 hyperlink, so a click opens it. */
+function transcriptLine(path: string, theme: Theme): string {
+  return `${hyperlink("transcript ↗", pathToFileURL(path).href)} ${theme.fg("dim", path)}`;
+}
+
+/** Detail lines for one agent, shown only when expanded. */
+function detailLines(d: NotificationDetails, theme: Theme, showCost: boolean, indent: string): string[] {
+  const lines: string[] = [];
+  const stats: string[] = [];
+  if (d.status !== "completed") {
+    stats.push(d.status === "steered" ? "completed (steered)" : d.status);
+  }
+  if (d.turnCount > 0) stats.push(formatTurns(d.turnCount, d.maxTurns));
+  stats.push(...statParts(d, showCost));
+  if (stats.length > 0) lines.push(indent + theme.fg("dim", stats.join(" · ")));
+  if (d.error) lines.push(indent + theme.fg("error", d.error));
+  if (d.resumeHint) lines.push(indent + theme.fg("warning", d.resumeHint));
+  if (d.modelNote) lines.push(indent + theme.fg("warning", d.modelNote));
+  for (const line of d.resultPreview.split("\n").slice(0, EXPANDED_PREVIEW_LINES)) {
+    lines.push(indent + theme.fg("dim", line));
+  }
+  if (d.outputFile) lines.push(indent + transcriptLine(d.outputFile, theme));
+  return lines;
+}
+
+/** First line truncated (core folds on it), the rest wrapped. */
+class NoticeView implements Component {
+  constructor(
+    private readonly first: string,
+    private readonly rest: string[],
+  ) {}
+
+  render(width: number): string[] {
+    return [truncateToWidth(this.first, width), ...this.rest.flatMap(line => wrapTextWithAnsi(line, width))];
+  }
+
+  invalidate(): void { /* static */ }
+}
+
+export function renderNotification(
+  details: NotificationDetails,
+  expanded: boolean,
+  theme: Theme,
+  showCost: boolean,
+): Component {
+  const all = [details, ...(details.others ?? [])];
+  if (all.length === 1) {
+    return new NoticeView(
+      noticeSummary(details, theme, showCost),
+      expanded ? detailLines(details, theme, showCost, "  ") : [],
+    );
+  }
+  const rest: string[] = [];
+  if (expanded) {
+    for (const d of all) {
+      rest.push(noticeSummary(d, theme, showCost));
+      rest.push(...detailLines(d, theme, showCost, "  "));
+    }
+    if (showCost) {
+      const total = formatCost(all.reduce((sum, a) => sum + (a.totalCost ?? 0), 0));
+      if (total) {
+        const tokens = all.reduce((sum, a) => sum + a.totalTokens, 0);
+        rest.push(theme.fg("dim", `${formatTokens(tokens)} · ${total} in total`));
+      }
+    }
+  }
+  return new NoticeView(groupSummary(all, theme), rest);
+}

package/src/ui/schedule-menu.ts

@@ -0,0 +1,105 @@
+/**
+ * schedule-menu.ts — `/agents → Scheduled jobs` submenu.
+ *
+ * Minimal v1 surface: list scheduled jobs, select one to inspect details +
+ * confirm cancellation. No create wizard (the `Agent` tool's `schedule` param
+ * is the canonical creation path), no toggle/cleanup (cancel is enough for
+ * "I scheduled something dumb, get rid of it"). Add management surfaces here
+ * if real demand emerges.
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { SubagentScheduler } from "../schedule.js";
+import type { ScheduledSubagent } from "../types.js";
+import { selectItem } from "./select-item.js";
+
+/** Format an ISO timestamp as relative time ("in 4h", "2d ago", "—"). */
+function relTime(iso: string | undefined, now = Date.now()): string {
+  if (!iso) return "—";
+  const t = new Date(iso).getTime();
+  if (Number.isNaN(t)) return "—";
+  const diff = t - now;
+  const abs = Math.abs(diff);
+  const future = diff > 0;
+  if (abs < 60_000) return future ? "in <1m" : "<1m ago";
+  const m = Math.round(abs / 60_000);
+  if (m < 60) return future ? `in ${m}m` : `${m}m ago`;
+  const h = Math.round(abs / 3_600_000);
+  if (h < 24) return future ? `in ${h}h` : `${h}h ago`;
+  const d = Math.round(abs / 86_400_000);
+  return future ? `in ${d}d` : `${d}d ago`;
+}
+
+/** One-line status icon. */
+function statusIcon(j: ScheduledSubagent): string {
+  if (!j.enabled) return "✗";
+  if (j.lastStatus === "error") return "!";
+  if (j.lastStatus === "running") return "⋯";
+  return "✓";
+}
+
+/** Compact selectable row — name, schedule, agent type, next/last run, count. */
+function formatJob(j: ScheduledSubagent, scheduler: SubagentScheduler): string {
+  const next = scheduler.getNextRun(j.id);
+  return [
+    statusIcon(j),
+    j.name.padEnd(18).slice(0, 18),
+    j.schedule.padEnd(14).slice(0, 14),
+    `[${j.subagent_type}]`,
+    `next ${relTime(next)}`,
+    `last ${relTime(j.lastRun)}`,
+    `runs ${j.runCount}`,
+  ].join("  ");
+}
+
+/** Multi-line details block for the cancel confirm. */
+function formatDetails(j: ScheduledSubagent, scheduler: SubagentScheduler): string {
+  const next = scheduler.getNextRun(j.id) ?? "—";
+  return [
+    `name:      ${j.name}`,
+    `schedule:  ${j.schedule} (${j.scheduleType})`,
+    `agent:     ${j.subagent_type}`,
+    `prompt:    ${j.prompt.slice(0, 200)}${j.prompt.length > 200 ? "…" : ""}`,
+    `created:   ${j.createdAt}`,
+    `last run:  ${j.lastRun ?? "—"} (${j.lastStatus ?? "—"})`,
+    `next run:  ${next}`,
+    `runs:      ${j.runCount}`,
+  ].join("\n");
+}
+
+/**
+ * List scheduled jobs; selecting one opens a cancel-confirm with details.
+ * Returns when the user backs out or after a cancellation.
+ */
+export async function showSchedulesMenu(
+  ctx: ExtensionCommandContext,
+  scheduler: SubagentScheduler,
+): Promise<void> {
+  if (!scheduler.isActive()) {
+    ctx.ui.notify("Scheduler is not active in this session.", "warning");
+    return;
+  }
+
+  const jobs = scheduler.list();
+  if (jobs.length === 0) {
+    ctx.ui.notify("No scheduled jobs.", "info");
+    return;
+  }
+
+  // Numbered + item-paired: two jobs whose names agree in the first 18
+  // characters format identically, and matching the returned string back
+  // against a parallel label array cancelled whichever came first.
+  const job = await selectItem(
+    ctx.ui,
+    `Scheduled jobs (${jobs.length}) — select to cancel`,
+    jobs,
+    j => formatJob(j, scheduler),
+  );
+  if (!job) return;
+
+  const ok = await ctx.ui.confirm(`Cancel "${job.name}"?`, formatDetails(job, scheduler));
+  if (!ok) return;
+
+  scheduler.removeJob(job.id);
+  ctx.ui.notify(`Cancelled "${job.name}".`, "info");
+}

package/src/ui/select-item.ts

@@ -0,0 +1,45 @@
+/**
+ * select-item.ts — pick an item from a list via `ctx.ui.select`, safely.
+ *
+ * Pi's dialog API is `select(title, options: string[]) => Promise<string | undefined>`:
+ * strings in, string out, with no index or value form. Callers therefore have to
+ * map the returned string back to the item it came from, and the obvious way —
+ * `labels.indexOf(choice)` over a parallel array — silently resolves to the
+ * FIRST match whenever two rows format identically. Row formatters here truncate
+ * (job names to 18 chars, agent descriptions to whatever fits), and the text they
+ * truncate is LLM-authored, so collisions are ordinary rather than exotic.
+ *
+ * This numbers every row, which makes the labels unique by construction — no
+ * data-dependent branch that only executes in the case nobody exercises — and
+ * keeps each label paired with its item so a later edit that sorts or filters
+ * between building and resolving cannot desync them.
+ */
+
+/** Minimal shape of the `ctx.ui` surface this needs. */
+export interface SelectUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+}
+
+/**
+ * Show a numbered picker and return the chosen item (not its label).
+ *
+ * Returns undefined when the user escapes, or when the returned string is not
+ * one we offered.
+ */
+export async function selectItem<T>(
+  ui: SelectUI,
+  title: string,
+  items: readonly T[],
+  format: (item: T, index: number) => string,
+): Promise<T | undefined> {
+  // Pad the number so a 10+ item list keeps its columns aligned.
+  const width = String(items.length).length;
+  const rows = items.map((item, i) => ({
+    item,
+    label: `${String(i + 1).padStart(width)}. ${format(item, i)}`,
+  }));
+
+  const choice = await ui.select(title, rows.map(r => r.label));
+  if (!choice) return undefined;
+  return rows.find(r => r.label === choice)?.item;
+}

package/src/ui/viewer-keys.ts

@@ -0,0 +1,39 @@
+/**
+ * viewer-keys.ts — Scroll key matchers for the conversation viewer.
+ *
+ * Resolves `tui.select.*` through the user's keybindings when pi provides a
+ * manager, falling back to the previous hardcoded keys otherwise. The viewer's
+ * k/j and shift+arrow aliases always work alongside whatever is bound.
+ */
+
+import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+
+/** The `tui.select.*` keybinding ids the viewer resolves. */
+export type ViewerScrollKeybinding =
+  | "tui.select.up"
+  | "tui.select.down"
+  | "tui.select.pageUp"
+  | "tui.select.pageDown";
+
+/** Structural subset of pi-tui's `KeybindingsManager` (which satisfies it). */
+export interface ViewerKeybindings {
+  matches(data: string, keybinding: ViewerScrollKeybinding): boolean;
+}
+
+export interface ViewerKeys {
+  scrollUp(data: string): boolean;
+  scrollDown(data: string): boolean;
+  pageUp(data: string): boolean;
+  pageDown(data: string): boolean;
+}
+
+export function createViewerKeys(keybindings?: ViewerKeybindings): ViewerKeys {
+  const matches = (data: string, id: ViewerScrollKeybinding, fallback: KeyId): boolean =>
+    keybindings ? keybindings.matches(data, id) : matchesKey(data, fallback);
+  return {
+    scrollUp: (data) => matches(data, "tui.select.up", "up") || matchesKey(data, "k"),
+    scrollDown: (data) => matches(data, "tui.select.down", "down") || matchesKey(data, "j"),
+    pageUp: (data) => matches(data, "tui.select.pageUp", "pageUp") || matchesKey(data, "shift+up"),
+    pageDown: (data) => matches(data, "tui.select.pageDown", "pageDown") || matchesKey(data, "shift+down"),
+  };
+}