@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/tui/conversation-frame.ts

@@ -0,0 +1,184 @@
+import { DynamicBorder, type Theme } from "@earendil-works/pi-coding-agent";
+import { Box, Container, Text, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { actionHints } from "./action-hints.ts";
+import { readableText } from "./history-text.ts";
+import { CONTINUE_HINT, CONTINUE_NOTICES, primaryKey, type AgentVisit } from "./view-model.ts";
+
+interface ControlModel {
+  readonly menu: boolean;
+  readonly detail: boolean;
+  readonly compact: boolean;
+  readonly width: number;
+  readonly primary?: string;
+  readonly actionHint: string;
+  readonly act: (action: string) => void;
+}
+export function conversationControls(model: ControlModel, theme: Theme): Component {
+  const { compact, act } = model;
+  const primary =
+    model.primary !== undefined
+      ? { text: model.actionHint, run: () => act(model.primary ?? "") }
+      : model.actionHint;
+  const actions = { text: compact ? "F2" : "F2 Actions", run: () => act("actions") };
+  const focus = { text: compact ? "Tab" : "Tab Read/write", run: () => act("focus") };
+  const reply = { text: compact ? "Alt+R" : "Alt+R Reply", run: () => act("reply") };
+  const back = { text: backLabel(model), run: () => act("back") };
+  const choose = {
+    text: `${primaryKey("tui.select.confirm")}${compact ? "" : " Choose"}`.trim(),
+    run: () => act("choose"),
+  };
+  if (model.menu) {
+    return actionHints([choose, " · ", back]);
+  }
+  const style = (text: string) => theme.fg("dim", text);
+  if (model.detail) {
+    return actionHints([reply, " · ", actions, " · ", back], style);
+  }
+  if (compact) {
+    return actionHints([actions, " · ", focus, " · ", back], style);
+  }
+  if (model.width < 60) {
+    return actionHints([actions, " · ", back, "\n", primary, " · ", focus], style);
+  }
+  return actionHints([primary, " · ", actions, " · ", focus, " · ", back], style);
+}
+function backLabel(model: ControlModel): string {
+  if (!model.menu) {
+    return model.compact ? "Esc" : "Esc Back";
+  }
+  let suffix = "";
+  if (!model.compact) {
+    suffix = model.detail ? " Back to details" : " Back to conversation";
+  }
+  return `${primaryKey("tui.select.cancel")}${suffix}`.trim();
+}
+interface FrameModel {
+  readonly width: number;
+  readonly height: number;
+  readonly title: string;
+  readonly status: string;
+  readonly unread: boolean;
+  readonly menu?: Component;
+  readonly detail: boolean;
+  readonly footer: Component;
+  readonly viewport: Component;
+  readonly editorViewport: Component;
+  readonly editorRows: number;
+  readonly composeLabel: string;
+  readonly notice: AgentVisit["notice"];
+  readonly quoteTitle?: string;
+  readonly act: (action: string) => void;
+}
+function header(model: FrameModel, theme: Theme, showStatus: boolean): Container {
+  const c = new Container(),
+    width = Math.max(1, model.width - 2);
+  c.addChild(new Text(theme.fg("accent", theme.bold(truncateToWidth(model.title, width))), 0, 0));
+  if (showStatus) {
+    c.addChild(
+      actionHints(
+        [
+          ...(model.unread
+            ? [
+                "New activity · ",
+                ...(model.menu
+                  ? []
+                  : [{ text: "Alt+L latest", run: () => model.act("latest") }, " · "]),
+              ]
+            : []),
+          model.status,
+        ],
+        (text) => theme.fg("dim", text),
+        "...",
+      ),
+    );
+  }
+  return c;
+}
+function composer(model: FrameModel, theme: Theme, compact: boolean): Container {
+  const c = new Container(),
+    width = Math.max(1, model.width - 2);
+  if (!model.detail) {
+    const notice = model.notice;
+    if (notice !== undefined) {
+      const parts =
+        typeof notice === "string"
+          ? [readableText(notice).replace(/\s+/g, " ").trim()]
+          : [
+              CONTINUE_NOTICES[notice.continue],
+              { text: CONTINUE_HINT, run: () => model.act("continue") },
+              ".",
+            ];
+      c.addChild(actionHints(parts, (text) => theme.fg("warning", text), "..."));
+    }
+    if (model.quoteTitle !== undefined) {
+      c.addChild(
+        actionHints(
+          [
+            "Quote · ",
+            { text: "Alt+Q remove", run: () => model.act("unquote") },
+            ": ",
+            model.quoteTitle,
+          ],
+          (text) => theme.fg("dim", text),
+          "...",
+        ),
+      );
+    }
+    if (!compact) {
+      c.addChild(new Text(theme.fg("accent", truncateToWidth(model.composeLabel, width)), 0, 0));
+    }
+    c.addChild(model.editorViewport);
+  }
+  c.addChild(model.footer);
+  return c;
+}
+export function conversationFrame(
+  model: FrameModel,
+  theme: Theme,
+): { component: Component; editorHeight: number; historyHeight: number } {
+  const width = Math.max(1, model.width - 2),
+    compact = model.height < 16;
+  const contentRows = model.menu
+    ? model.menu.render(width).length
+    : 1 +
+      (model.detail
+        ? 0
+        : 1 +
+          Number(!compact) +
+          Number(model.notice !== undefined) +
+          Number(model.quoteTitle !== undefined));
+  const required = 1 + model.footer.render(width).length + contentRows;
+  const showStatus = model.height > required,
+    framed = model.height >= required + Number(showStatus) + 2;
+  const root = new Container(),
+    body = new Box(1, 0, (text) => theme.bg("customMessageBg", text));
+  const title = header(model, theme, showStatus);
+  body.addChild(title);
+  let editorHeight = Infinity,
+    historyHeight = 1;
+  if (model.menu) {
+    body.addChild(model.menu);
+    body.addChild(model.footer);
+  } else {
+    const bottom = composer(model, theme, compact);
+    const space = model.height - Number(framed) * 2 - title.render(width).length;
+    const bottomRows = bottom.render(width).length;
+    if (!model.detail) {
+      editorHeight = Math.max(1, space - (bottomRows - model.editorRows) - 1);
+    }
+    const clippedRows = model.detail
+      ? bottomRows
+      : bottomRows - model.editorRows + Math.min(model.editorRows, editorHeight);
+    historyHeight = Math.max(1, space - clippedRows);
+    body.addChild(model.viewport);
+    body.addChild(bottom);
+  }
+  if (framed) {
+    root.addChild(new DynamicBorder((text) => theme.fg("borderAccent", text)));
+  }
+  root.addChild(body);
+  if (framed) {
+    root.addChild(new DynamicBorder((text) => theme.fg("borderAccent", text)));
+  }
+  return { component: root, editorHeight, historyHeight };
+}

package/src/tui/conversation-history.ts

@@ -0,0 +1,246 @@
+import { errorText } from "./text-values.ts";
+import {
+  historyStatus,
+  pageNotices,
+  taskNotices,
+  outgoingHistory,
+} from "./conversation-notices.ts";
+import type { TUI } from "@earendil-works/pi-tui";
+import type { HistoryPageInput } from "../shared/types.ts";
+import { getSingleResultOutput } from "../shared/utils.ts";
+import { withFinalResult, type AgentHistoryItem, type AgentHistory } from "./agent-history.ts";
+import { UNAVAILABLE_ASSIGNMENT, type AgentVisit } from "./view-model.ts";
+import type { ConversationController, HistorySelection } from "./view-ports.ts";
+interface PageSource {
+  readonly initialPosition: () => boolean;
+  readonly initialVisit: () => Pick<AgentVisit, "anchor" | "readThrough">;
+  readonly readSequence: (sequence: number) => void;
+  readonly clearCards: () => void;
+  readonly refresh: () => void;
+}
+
+export class ConversationHistory {
+  loadingPage = false;
+  refreshPending = false;
+  pageError?: string;
+  latestPage = true;
+  seenSource = false;
+  private pageRequest = 0;
+  private closed = false;
+  private readonly tui: TUI;
+  private readonly controller: ConversationController;
+  private readonly key: string;
+  private readonly source: PageSource;
+  constructor(tui: TUI, controller: ConversationController, key: string, source: PageSource) {
+    this.tui = tui;
+    this.controller = controller;
+    this.key = key;
+    this.source = source;
+    this.seenSource = Boolean(controller.task(key)?.page?.count);
+  }
+
+  private active(request: number): boolean {
+    return !this.closed && request === this.pageRequest;
+  }
+
+  async loadPage(
+    paging: Pick<HistoryPageInput, "before" | "after" | "cursor"> = {},
+    anchor?: string | null,
+  ): Promise<void> {
+    if (this.closed) {
+      return;
+    }
+    const request = ++this.pageRequest;
+    this.refreshPending = false;
+    this.loadingPage = true;
+    this.pageError = undefined;
+    this.controller.setHistoryLoading(this.key, true);
+    this.latestPage =
+      paging.before === undefined && paging.after === undefined && paging.cursor === undefined;
+    this.tui.requestRender();
+    try {
+      await this.resolvePage(paging, anchor, request);
+    } catch (error) {
+      if (this.active(request)) {
+        this.pageError = `History unavailable: ${errorText(error)}. F5 retries the selected run.`;
+      }
+    } finally {
+      this.finishPage(request);
+    }
+  }
+
+  private finishPage(request: number): void {
+    if (!this.active(request)) {
+      return;
+    }
+    this.loadingPage = false;
+    this.controller.setHistoryLoading(this.key, false);
+    if (this.refreshPending && this.pageError === undefined) {
+      this.refreshPending = false;
+      this.source.refresh();
+    }
+    this.tui.requestRender();
+  }
+  private async resolvePage(
+    paging: Pick<HistoryPageInput, "before" | "after" | "cursor">,
+    anchor: string | null | undefined,
+    request: number,
+  ): Promise<void> {
+    const selected = await this.controller.historyPage(this.key, paging, anchor);
+    if (!selected || !this.active(request)) {
+      return;
+    }
+    const result = await this.initialReportPage(selected, request);
+    if (!result || !this.active(request)) {
+      return;
+    }
+    const history = await this.savedReport(result, request);
+    if (history && this.active(request)) {
+      if (!result.isCurrent()) {
+        await this.loadPage(paging, anchor);
+        return;
+      }
+      if (result.readThroughSequence !== undefined) {
+        this.source.readSequence(result.readThroughSequence);
+      }
+      this.latestPage = result.latestPage;
+      this.applyPage(history, result);
+    }
+  }
+  private needsInitialReport(result: HistorySelection): boolean {
+    const task = this.controller.task(this.key),
+      visit = this.source.initialVisit();
+    if (
+      !task ||
+      !this.source.initialPosition() ||
+      visit.readThrough !== undefined ||
+      visit.anchor ||
+      task.child.state === "live"
+    ) {
+      return false;
+    }
+    const finalId = result.history.finalId;
+    return finalId !== undefined && !result.history.entryIds.includes(finalId);
+  }
+  private async initialReportPage(
+    result: HistorySelection,
+    request: number,
+  ): Promise<HistorySelection | undefined> {
+    if (!this.controller.task(this.key)) {
+      return;
+    }
+    if (!this.needsInitialReport(result)) {
+      return result;
+    }
+    const report = await this.controller.historyPage(this.key, {}, result.history.finalId);
+    if (!this.active(request) || !this.controller.task(this.key)) {
+      return;
+    }
+    return report ?? result;
+  }
+
+  private includeReport(history: AgentHistory, latestPage: boolean): boolean {
+    return (
+      this.source.initialPosition() ||
+      latestPage ||
+      (history.finalId !== undefined && history.entryIds.includes(history.finalId))
+    );
+  }
+  private async savedReport(
+    result: HistorySelection,
+    request: number,
+  ): Promise<AgentHistory | undefined> {
+    const task = this.controller.task(this.key);
+    if (!task) {
+      return;
+    }
+    const history = result.history;
+    const includeReport = this.includeReport(history, result.latestPage);
+    if (
+      !includeReport ||
+      task.child.state === "live" ||
+      !task.child.result ||
+      getSingleResultOutput(task.child.result).length === 0
+    ) {
+      return history;
+    }
+    const runId = task.run.runId;
+    const report = await this.controller.savedResult(this.key, `result:${runId}`);
+    const current = this.controller.task(this.key);
+    if (!this.active(request) || !current || current.run.runId !== runId) {
+      return;
+    }
+    return withFinalResult(history, report.text, runId, current.run.updatedAt);
+  }
+
+  private applyPage(history: AgentHistory, result: HistorySelection): void {
+    const task = this.controller.task(this.key);
+    if (!task) {
+      return;
+    }
+    const items = history.items.map((item) =>
+      item.id === `result:${task.run.runId}`
+        ? { ...item, load: () => this.controller.savedResult(this.key, item.id) }
+        : item,
+    );
+    this.seenSource ||= result.page.count > 0;
+    this.controller.applyHistoryPage(this.key, { ...history, items }, result.page, this.seenSource);
+    this.source.clearCards();
+  }
+
+  assignment(): AgentHistoryItem {
+    const task = this.controller.task(this.key);
+    if (!task) {
+      return {
+        id: "assignment",
+        kind: "notice",
+        title: "Assignment unavailable",
+        text: UNAVAILABLE_ASSIGNMENT,
+        timestamp: 0,
+      };
+    }
+    return {
+      id: "assignment",
+      kind: "notice",
+      title:
+        task.child.identityUnavailable === true
+          ? "Assignment unavailable"
+          : `Assignment · ${task.child.agent}`,
+      text:
+        task.child.identityUnavailable === true
+          ? UNAVAILABLE_ASSIGNMENT
+          : `${task.model.details}\n\n${task.child.task ?? "The original per-child assignment was not saved for this older run."}`,
+      timestamp: task.run.startedAt,
+    };
+  }
+
+  items(detail?: AgentHistoryItem): AgentHistoryItem[] {
+    const task = this.controller.task(this.key);
+    if (!task) {
+      return [
+        {
+          id: "unavailable",
+          kind: "notice",
+          title: "Agent unavailable",
+          text: "The owning session or run is no longer available.",
+          timestamp: 0,
+        },
+      ];
+    }
+    if (detail) {
+      return [detail];
+    }
+    const status = this.pageError ?? historyStatus(task.page, this.loadingPage);
+    return [
+      this.assignment(),
+      ...pageNotices(task, status, this.latestPage),
+      ...task.history,
+      ...taskNotices(task),
+      ...this.controller.visit(this.key).outbox.map(outgoingHistory),
+    ];
+  }
+  dispose(): void {
+    this.closed = true;
+    this.pageRequest++;
+  }
+}

package/src/tui/conversation-menu.ts

@@ -0,0 +1,119 @@
+import { primaryKey, activity, type AgentTask, type AgentVisit } from "./view-model.ts";
+import type { ReadonlyInput } from "../shared/types.ts";
+import { matchesKey } from "@earendil-works/pi-tui";
+interface Choice {
+  readonly value: string;
+  readonly label: string;
+}
+function taskCanControl(task: Readonly<AgentTask> | undefined): boolean {
+  return task?.child.identityUnavailable !== true && task?.child.activity?.status !== "pending";
+}
+export function conversationChoices(
+  task: Readonly<AgentTask> | undefined,
+  options: {
+    readonly expanded: boolean;
+    readonly pinned: boolean;
+    readonly quote: ReadonlyInput<AgentVisit["quote"]>;
+  },
+): Choice[] {
+  const choices = [
+    { value: "reply", label: "Reply to selected message / tool / change" },
+    { value: "details", label: "Full details / diff" },
+    { value: "expand", label: options.expanded ? "Collapse tool output" : "Expand tool output" },
+    { value: "assignment", label: "Full original assignment" },
+    { value: "changes", label: "Inspect working tree changes" },
+    { value: "latest", label: "Jump to latest activity" },
+    { value: "pin", label: options.pinned ? "Unpin this agent" : "Keep this agent visible" },
+  ];
+  if (options.quote) {
+    choices.push({ value: "unquote", label: "Remove quoted context" });
+  }
+  if (taskCanControl(task)) {
+    choices.push(
+      task?.child.state === "live" || task?.question
+        ? { value: "stop", label: "Stop this agent only" }
+        : { value: "continue", label: "Continue with this message" },
+    );
+  }
+  choices.push(
+    { value: "picker", label: "Your other agents" },
+    { value: "peers", label: "Other connected sessions" },
+    { value: "earlier", label: "Earlier history" },
+    { value: "later", label: "Later history" },
+    { value: "retry", label: "Refresh / retry selected history" },
+  );
+  return choices;
+}
+const SHORTCUTS = [
+  ["escape", "back"],
+  ["f2", "actions"],
+  ["f5", "retry"],
+  ["alt+r", "reply"],
+  ["alt+g", "changes"],
+  ["alt+l", "latest"],
+  ["alt+p", "pin"],
+  ["alt+q", "unquote"],
+  ["alt+s", "stop"],
+  ["alt+c", "continue"],
+] as const;
+export function conversationShortcut(data: string): string | undefined {
+  return SHORTCUTS.find(([key]) => matchesKey(data, key))?.[1];
+}
+export function primaryConversationAction(
+  task: Readonly<AgentTask> | undefined,
+  editor: boolean,
+): string | undefined {
+  if (!taskCanControl(task)) {
+    return;
+  }
+  if (task?.child.state !== "live" && !task?.question) {
+    return "continue";
+  }
+  return editor ? "send" : "details";
+}
+function composeLabel(task: Readonly<AgentTask> | undefined, busy: boolean): string {
+  return `${task?.question ? "Answer" : "Message"} ${task?.label ?? "agent"}${busy ? " · sending" : ""}`;
+}
+export function conversationHeading(
+  task: Readonly<AgentTask> | undefined,
+  options: {
+    readonly entrance: string;
+    readonly detail: boolean;
+    readonly following: boolean;
+    readonly busy: boolean;
+  },
+): {
+  readonly title: string;
+  readonly status: string;
+  readonly unread: boolean;
+  readonly composeLabel: string;
+} {
+  return {
+    title: `${options.entrance} › ${task?.label ?? "unavailable"}${options.detail ? " › details" : ""}`,
+    status: task
+      ? `${task.child.agent} · ${activity(task)} · ${task.model.summary}`
+      : "Unavailable",
+    unread: task?.unread === true && !options.following,
+    composeLabel: composeLabel(task, options.busy),
+  };
+}
+export function primaryConversationHint(
+  action: string | undefined,
+  width: number,
+  loading: boolean,
+  task: Readonly<AgentTask> | undefined,
+): string {
+  if (loading) {
+    return "Loading quoted context…";
+  }
+  if (task?.child.identityUnavailable === true) {
+    return "Assignment unavailable · draft kept";
+  }
+  if (task?.child.activity?.status === "pending") {
+    return "Waiting to start · draft kept";
+  }
+  if (action === "continue") {
+    return width < 60 ? "Alt+C Continue" : "Alt+C Continue with message";
+  }
+  return action === "send" ? `${primaryKey("tui.input.submit")} Send`.trim() : "Enter Details";
+}

package/src/tui/conversation-notices.ts

@@ -0,0 +1,116 @@
+import { hasText } from "./text-values.ts";
+import { acceptanceHumanAction } from "../runs/shared/acceptance.ts";
+import { formatAgentProcessExit } from "../shared/status-format.ts";
+import type { HistoryPage, ReadonlyInput } from "../shared/types.ts";
+import type { AgentHistoryItem } from "./agent-history.ts";
+import type { AgentTask, OutgoingMessage } from "./view-model.ts";
+function notice(id: string, title: string, text = "", timestamp = 0): AgentHistoryItem {
+  return { id, kind: "notice", title, text, timestamp };
+}
+export function historyStatus(page: HistoryPage | undefined, loading: boolean): string | undefined {
+  if (loading && !page) {
+    return "Loading conversation…";
+  }
+  if (page?.freshness.state === "catching-up") {
+    return "Catching up · partial history";
+  }
+  return page?.freshness.state === "degraded"
+    ? "Some saved history unavailable · F5 retry"
+    : undefined;
+}
+export function pageNotices(
+  task: Readonly<AgentTask>,
+  status: string | undefined,
+  latest: boolean,
+): AgentHistoryItem[] {
+  const items: AgentHistoryItem[] = [],
+    page = task.page;
+  if (hasText(status)) {
+    items.push(notice("history-loading", status));
+  }
+  if (page && page.count > page.entries.length) {
+    items.push(
+      notice(
+        "history-page",
+        `History · ${page.entries.length} of ${page.count} native records${latest ? " · latest" : ""}`,
+        "F2 Actions → Earlier history / Later history / Latest. Full details validates the selected native record.",
+      ),
+    );
+  }
+  if (task.child.identityUnavailable !== true && task.child.state !== "live") {
+    items.push(
+      notice(
+        "process-exit",
+        `Agent: ${task.child.state}`,
+        formatAgentProcessExit(task.child.result?.agentProcessExit),
+        task.run.updatedAt,
+      ),
+    );
+  }
+  return items;
+}
+function activityItem(task: Readonly<AgentTask>): AgentHistoryItem | undefined {
+  const activity = task.child.activity;
+  if (
+    task.child.identityUnavailable === true ||
+    task.child.state !== "live" ||
+    !hasText(activity?.streamingText)
+  ) {
+    return;
+  }
+  return {
+    id: `live:${task.run.runId}`,
+    kind: "assistant",
+    title: "Agent · writing",
+    text: activity.streamingText,
+    timestamp: activity.lastActivityAt ?? 0,
+  };
+}
+export function taskNotices(task: Readonly<AgentTask>): AgentHistoryItem[] {
+  const items: AgentHistoryItem[] = [];
+  if (task.child.identityUnavailable !== true) {
+    const action = task.child.humanAction ?? acceptanceHumanAction(task.child.result?.acceptance);
+    if (hasText(action)) {
+      items.push(
+        notice(
+          "human-action",
+          "Needs your action — acceptance incomplete",
+          action,
+          task.run.updatedAt,
+        ),
+      );
+    }
+    if (hasText(task.unavailable)) {
+      items.push(notice("unavailable", "Conversation unavailable", task.unavailable));
+    }
+  }
+  if (task.question) {
+    items.push(
+      notice(
+        `question:${task.question.questionId}`,
+        "Waiting for your answer",
+        task.question.message,
+        task.question.createdAt,
+      ),
+    );
+  }
+  const activity = activityItem(task);
+  if (activity) {
+    items.push(activity);
+  }
+  return items;
+}
+const SENT_TITLES = {
+  sending: "You · sending",
+  waiting: "You · waiting for the child / tool boundary",
+  unconfirmed: "You · delivery unconfirmed",
+} as const;
+export function outgoingHistory(sent: ReadonlyInput<OutgoingMessage>): AgentHistoryItem {
+  return {
+    id: `outgoing:${sent.id}`,
+    kind: "user",
+    title: SENT_TITLES[sent.status],
+    text: `${sent.text}${sent.quote ? `\n\nRegarding ${sent.quote.title}:\n${sent.quote.text}` : ""}${hasText(sent.reason) ? `\n\n${sent.reason}` : ""}`,
+    timestamp: sent.at,
+  };
+}