@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/tui/history-metadata.ts

@@ -0,0 +1,177 @@
+import type {
+  AssistantMessage,
+  DeferredHandle,
+  NestedToolCalls,
+  NestedToolCallRecord,
+  Usage,
+} from "@earendil-works/pi-ai";
+import { Type, Check } from "../shared/native-typebox.ts";
+import { THINKING_LEVELS } from "../shared/model-info.ts";
+import { isJson, isJsonObject } from "./history-json.ts";
+const cost = Type.Object({
+  input: Type.Number(),
+  output: Type.Number(),
+  cacheRead: Type.Number(),
+  cacheWrite: Type.Number(),
+  total: Type.Number(),
+});
+export const usageSchema = Type.Object({
+  input: Type.Number(),
+  output: Type.Number(),
+  cacheRead: Type.Number(),
+  cacheWrite: Type.Number(),
+  totalTokens: Type.Number(),
+  cost,
+  cacheWrite1h: Type.Optional(Type.Number()),
+  reasoning: Type.Optional(Type.Number()),
+});
+export function nativeUsage(value: unknown): Usage | undefined {
+  return Check(usageSchema, value) ? { ...value, cost: { ...value.cost } } : undefined;
+}
+const nestedCallFields = Type.Object({
+  id: Type.String(),
+  name: Type.String(),
+  arguments: Type.Optional(Type.Unknown()),
+  argumentsBytes: Type.Optional(Type.Number()),
+  status: Type.Union([Type.Literal("ok"), Type.Literal("error"), Type.Literal("unfinished")]),
+  durationMs: Type.Optional(Type.Number()),
+  error: Type.Optional(Type.String()),
+});
+function nestedCall(value: unknown): NestedToolCallRecord | undefined {
+  if (!Check(nestedCallFields, value)) {
+    return;
+  }
+  const { arguments: args, ...fields } = value;
+  if (args !== undefined && !isJsonObject(args)) {
+    return;
+  }
+  return { ...fields, ...("arguments" in value ? { arguments: args } : {}) };
+}
+const nestedCallsFields = Type.Object({
+  calls: Type.Array(Type.Unknown()),
+  complete: Type.Boolean(),
+});
+export function nativeNestedCalls(value: unknown): NestedToolCalls | undefined {
+  if (!Check(nestedCallsFields, value)) {
+    return;
+  }
+  const calls: NestedToolCallRecord[] = [];
+  for (const part of value.calls) {
+    const call = nestedCall(part);
+    if (!call) {
+      return;
+    }
+    calls.push(call);
+  }
+  return { calls, complete: value.complete };
+}
+const deferredFields = Type.Object({
+  provider: Type.String(),
+  modelId: Type.String(),
+  api: Type.String(),
+  id: Type.String(),
+  expiresAt: Type.Optional(Type.Number()),
+  pollAfterMs: Type.Optional(Type.Number()),
+  data: Type.Optional(Type.Unknown()),
+});
+function deferred(value: unknown): DeferredHandle | undefined {
+  if (!Check(deferredFields, value)) {
+    return;
+  }
+  const { data, ...fields } = value;
+  if (data !== undefined && !isJson(data)) {
+    return;
+  }
+  return { ...fields, ...("data" in value ? { data } : {}) };
+}
+const diagnosticFields = Type.Object({
+  type: Type.String(),
+  timestamp: Type.Number(),
+  error: Type.Optional(
+    Type.Object({
+      name: Type.Optional(Type.String()),
+      message: Type.String(),
+      stack: Type.Optional(Type.String()),
+      code: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+    }),
+  ),
+  details: Type.Optional(Type.Unknown()),
+});
+type Diagnostic = NonNullable<AssistantMessage["diagnostics"]>[number];
+function diagnostic(value: unknown): Diagnostic | undefined {
+  if (!Check(diagnosticFields, value)) {
+    return;
+  }
+  const { details, ...fields } = value;
+  if (details !== undefined && !isJsonObject(details)) {
+    return;
+  }
+  return { ...fields, ...("details" in value ? { details } : {}) };
+}
+function diagnostics(value: unknown): Diagnostic[] | undefined {
+  if (!Array.isArray(value)) {
+    return;
+  }
+  const parsed: Diagnostic[] = [];
+  for (const part of value) {
+    const item = diagnostic(part);
+    if (!item) {
+      return;
+    }
+    parsed.push(item);
+  }
+  return parsed;
+}
+const metadataFields = Type.Object({
+  responseModel: Type.Optional(Type.String()),
+  responseId: Type.Optional(Type.String()),
+  providerThinkingLevel: Type.Optional(Type.String()),
+  thinkingLevel: Type.Optional(Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)))),
+  rawStopReason: Type.Optional(Type.String()),
+  endTurn: Type.Optional(Type.Boolean()),
+});
+type Metadata = Pick<
+  AssistantMessage,
+  | "responseModel"
+  | "responseId"
+  | "providerThinkingLevel"
+  | "thinkingLevel"
+  | "rawStopReason"
+  | "endTurn"
+  | "deferred"
+  | "diagnostics"
+>;
+function scalarMetadata(value: unknown): Omit<Metadata, "deferred" | "diagnostics"> | undefined {
+  if (!Check(metadataFields, value)) {
+    return;
+  }
+  return {
+    ...("responseModel" in value ? { responseModel: value.responseModel } : {}),
+    ...("responseId" in value ? { responseId: value.responseId } : {}),
+    ...("providerThinkingLevel" in value
+      ? { providerThinkingLevel: value.providerThinkingLevel }
+      : {}),
+    ...("thinkingLevel" in value ? { thinkingLevel: value.thinkingLevel } : {}),
+    ...("rawStopReason" in value ? { rawStopReason: value.rawStopReason } : {}),
+    ...("endTurn" in value ? { endTurn: value.endTurn } : {}),
+  };
+}
+export function assistantMetadata(value: Readonly<Record<string, unknown>>): Metadata | undefined {
+  const pending = value.deferred,
+    notes = value.diagnostics;
+  const deferredValue = pending === undefined ? undefined : deferred(pending),
+    diagnosticValues = notes === undefined ? undefined : diagnostics(notes);
+  const scalars = scalarMetadata(value);
+  if (
+    (pending !== undefined && deferredValue === undefined) ||
+    (notes !== undefined && diagnosticValues === undefined) ||
+    !scalars
+  ) {
+    return;
+  }
+  return {
+    ...scalars,
+    ...("deferred" in value ? { deferred: deferredValue } : {}),
+    ...("diagnostics" in value ? { diagnostics: diagnosticValues } : {}),
+  };
+}

package/src/tui/history-record.ts

@@ -0,0 +1,321 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type {
+  AssistantMessage,
+  ToolCall,
+  ToolResultMessage,
+  TextContent,
+  ThinkingContent,
+} from "@earendil-works/pi-ai";
+import { Type, Check } from "../shared/native-typebox.ts";
+import { isRecord } from "./history-text.ts";
+import { isJson, isJsonObject } from "./history-json.ts";
+import {
+  assistantMetadata,
+  nativeUsage,
+  nativeNestedCalls,
+  usageSchema,
+} from "./history-metadata.ts";
+
+/** A native message handle, not an indexed partial observation. */
+export type HistoryNativeMessage = AgentMessage;
+export interface HistoryAssistantPreview {
+  readonly role: "assistant";
+  readonly content: readonly (TextContent | ThinkingContent | ToolCall)[];
+  readonly provider?: string;
+  readonly model?: string;
+  readonly stopReason?: string;
+  readonly errorMessage?: string;
+}
+export type DisplayEntry = { readonly id: string; readonly timestamp: string } & (
+  | {
+      readonly type: "message";
+      readonly message:
+        | HistoryNativeMessage
+        | HistoryAssistantPreview
+        | { readonly role: "user"; readonly content: unknown };
+      readonly native?: HistoryNativeMessage;
+    }
+  | {
+      readonly type: "custom_message";
+      readonly customType: string;
+      readonly content: unknown;
+      readonly details?: unknown;
+    }
+  | { readonly type: "compaction" | "branch_summary"; readonly summary: string }
+);
+const text = Type.Object({
+  type: Type.Literal("text"),
+  text: Type.String(),
+  textSignature: Type.Optional(Type.String()),
+});
+const thinking = Type.Object({
+  type: Type.Literal("thinking"),
+  thinking: Type.String(),
+  thinkingSignature: Type.Optional(Type.String()),
+  redacted: Type.Optional(Type.Boolean()),
+});
+const image = Type.Object({
+  type: Type.Literal("image"),
+  data: Type.String(),
+  mimeType: Type.String(),
+});
+const assistantFields = Type.Object({
+  role: Type.Literal("assistant"),
+  api: Type.String(),
+  provider: Type.String(),
+  model: Type.String(),
+  timestamp: Type.Number(),
+  usage: usageSchema,
+  stopReason: Type.Union(
+    ["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"].map((value) =>
+      Type.Literal(value),
+    ),
+  ),
+  errorMessage: Type.Optional(Type.String()),
+});
+
+type RecordMode = "preview" | "full";
+const toolCallFields = Type.Object({
+  type: Type.Literal("toolCall"),
+  id: Type.String(),
+  name: Type.String(),
+  arguments: Type.Unknown(),
+  thoughtSignature: Type.Optional(Type.String()),
+  namespace: Type.Optional(Type.String()),
+});
+export function toolCall(value: unknown): ToolCall | undefined {
+  if (!Check(toolCallFields, value) || !isJsonObject(value.arguments)) {
+    return;
+  }
+  return {
+    type: "toolCall",
+    id: value.id,
+    name: value.name,
+    arguments: { ...value.arguments },
+    ...("thoughtSignature" in value ? { thoughtSignature: value.thoughtSignature } : {}),
+    ...("namespace" in value ? { namespace: value.namespace } : {}),
+  };
+}
+function assistant(value: Readonly<Record<string, unknown>>): AssistantMessage | undefined {
+  const rawContent = value.content,
+    metadata = assistantMetadata(value);
+  if (!metadata || !Check(assistantFields, value) || !Array.isArray(rawContent)) {
+    return;
+  }
+  const content: AssistantMessage["content"] = [];
+  for (const part of rawContent) {
+    if (Check(text, part)) {
+      content.push({ ...part });
+    } else if (Check(thinking, part)) {
+      content.push({ ...part });
+    } else {
+      const call = toolCall(part);
+      if (!call) {
+        return;
+      }
+      content.push(call);
+    }
+  }
+  const stopReason = value.stopReason;
+  if (!isStopReason(stopReason)) {
+    return;
+  }
+  return {
+    ...metadata,
+    role: "assistant",
+    api: value.api,
+    provider: value.provider,
+    model: value.model,
+    timestamp: value.timestamp,
+    usage: { ...value.usage, cost: { ...value.usage.cost } },
+    stopReason,
+    content,
+    ...("errorMessage" in value ? { errorMessage: value.errorMessage } : {}),
+  };
+}
+function isStopReason(value: string): value is AssistantMessage["stopReason"] {
+  return (
+    value === "pending" ||
+    value === "stop" ||
+    value === "length" ||
+    value === "toolUse" ||
+    value === "error" ||
+    value === "aborted" ||
+    value === "deferred"
+  );
+}
+function toolMetadata(
+  value: Readonly<Record<string, unknown>>,
+): Pick<ToolResultMessage, "usage" | "nestedCalls"> | undefined {
+  const usage = nativeUsage(value.usage),
+    nestedCalls = nativeNestedCalls(value.nestedCalls);
+  if ((value.usage !== undefined && !usage) || (value.nestedCalls !== undefined && !nestedCalls)) {
+    return;
+  }
+  return {
+    ...("usage" in value ? { usage } : {}),
+    ...("nestedCalls" in value ? { nestedCalls } : {}),
+  };
+}
+const toolResultFields = Type.Object({
+  toolCallId: Type.String(),
+  toolName: Type.String(),
+  isError: Type.Boolean(),
+  timestamp: Type.Number(),
+});
+function toolResultContent(
+  value: unknown,
+  mode: RecordMode,
+): ToolResultMessage["content"] | undefined {
+  if (!Array.isArray(value)) {
+    return;
+  }
+  const content: ToolResultMessage["content"] = [];
+  for (const part of value) {
+    if (Check(text, part) || Check(image, part)) {
+      content.push({ ...part });
+    } else if (
+      mode === "preview" &&
+      isRecord(part) &&
+      part.type === "image" &&
+      part.data === undefined &&
+      typeof part.mimeType === "string"
+    ) {
+      // Indexed previews omit image bytes; only preview cards may use this display adapter.
+      content.push({ type: "image", data: "", mimeType: part.mimeType });
+    } else {
+      return;
+    }
+  }
+  return content;
+}
+function toolResult(
+  value: Readonly<Record<string, unknown>>,
+  mode: RecordMode,
+): ToolResultMessage | undefined {
+  const content = toolResultContent(value.content, mode),
+    details = value.details;
+  const metadata = toolMetadata(value);
+  if (!metadata) {
+    return;
+  }
+  if (!Check(toolResultFields, value)) {
+    return;
+  }
+  if (!content || (details !== undefined && !isJson(details))) {
+    return;
+  }
+  return {
+    ...metadata,
+    role: "toolResult",
+    toolCallId: value.toolCallId,
+    toolName: value.toolName,
+    isError: value.isError,
+    timestamp: value.timestamp,
+    content,
+    ...("details" in value ? { details } : {}),
+  };
+}
+function assistantPreview(
+  value: Readonly<Record<string, unknown>>,
+): HistoryAssistantPreview | undefined {
+  if (!Array.isArray(value.content)) {
+    return;
+  }
+  const content: Array<TextContent | ThinkingContent | ToolCall> = [];
+  for (const part of value.content) {
+    if (Check(text, part) || Check(thinking, part)) {
+      content.push({ ...part });
+    } else {
+      const call = toolCall(part);
+      if (call) {
+        content.push(call);
+      }
+    }
+  }
+  return {
+    role: "assistant",
+    content,
+    model: typeof value.model === "string" ? value.model : undefined,
+    provider: typeof value.provider === "string" ? value.provider : undefined,
+    stopReason: typeof value.stopReason === "string" ? value.stopReason : undefined,
+    errorMessage: typeof value.errorMessage === "string" ? value.errorMessage : undefined,
+  };
+}
+function bashMessage(
+  value: Readonly<Record<string, unknown>>,
+): Extract<HistoryNativeMessage, { role: "bashExecution" }> | undefined {
+  if (typeof value.command !== "string" || typeof value.output !== "string") {
+    return;
+  }
+  return {
+    role: "bashExecution",
+    command: value.command,
+    output: value.output,
+    exitCode: typeof value.exitCode === "number" ? value.exitCode : undefined,
+    cancelled: value.cancelled === true,
+    truncated: value.truncated === true,
+    timestamp: typeof value.timestamp === "number" ? value.timestamp : 0,
+  };
+}
+function observedMessage(
+  value: unknown,
+  mode: RecordMode,
+): Pick<Extract<DisplayEntry, { type: "message" }>, "message" | "native"> | undefined {
+  if (!isRecord(value)) {
+    return;
+  }
+  switch (value.role) {
+    case "assistant": {
+      const native = assistant(value);
+      const message = native ?? (mode === "preview" ? assistantPreview(value) : undefined);
+      return message ? { message, ...(native ? { native } : {}) } : undefined;
+    }
+    case "toolResult": {
+      const message = toolResult(value, mode);
+      return message ? { message } : undefined;
+    }
+    case "user":
+      return { message: { role: "user", content: value.content } };
+    case "bashExecution": {
+      const message = bashMessage(value);
+      return message ? { message } : undefined;
+    }
+    default:
+      return;
+  }
+}
+function messageEntry(
+  value: Readonly<Record<string, unknown>>,
+  base: { readonly id: string; readonly timestamp: string },
+  mode: RecordMode,
+): DisplayEntry | undefined {
+  const observed = observedMessage(value.message, mode);
+  return observed ? { ...base, type: "message", ...observed } : undefined;
+}
+/** Validate only display facts; an indexed observation is never invented owner/session metadata. */
+export function displayEntry(value: unknown, mode: RecordMode): DisplayEntry | undefined {
+  if (!isRecord(value) || typeof value.id !== "string" || typeof value.timestamp !== "string") {
+    return;
+  }
+  const base = { id: value.id, timestamp: value.timestamp };
+  if (value.type === "message") {
+    return messageEntry(value, base, mode);
+  }
+  if (value.type === "custom_message" && typeof value.customType === "string") {
+    return {
+      ...base,
+      type: "custom_message",
+      customType: value.customType,
+      content: value.content,
+      details: value.details,
+    };
+  }
+  if (
+    (value.type === "compaction" || value.type === "branch_summary") &&
+    typeof value.summary === "string"
+  ) {
+    return { ...base, type: value.type, summary: value.summary };
+  }
+  return;
+}

package/src/tui/history-text.ts

@@ -0,0 +1,34 @@
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+export function readableText(value: unknown): string {
+  if (typeof value === "string") {
+    return stripTerminalSequences(value);
+  }
+  // JSON.stringify can return undefined for omitted native values despite its declared string result.
+  const serialized: unknown = JSON.stringify(value, null, 2);
+  return stripTerminalSequences(typeof serialized === "string" ? serialized : "");
+}
+export function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function contentText(content: unknown): string {
+  if (!Array.isArray(content)) {
+    return readableText(content);
+  }
+  return content
+    .map((part: unknown) => {
+      if (!isRecord(part)) {
+        return "";
+      }
+      if (part.type === "text") {
+        return readableText(part.text);
+      }
+      if (part.type === "thinking") {
+        return readableText(part.thinking);
+      }
+      return part.type === "image"
+        ? `[Image: ${typeof part.mimeType === "string" ? part.mimeType : "image"}]`
+        : "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}

package/src/tui/indexed-history.ts

@@ -0,0 +1,149 @@
+import type {
+  HistoryIndexHandle,
+  HistoryEntry,
+  HistoryPage,
+  HistoryPageInput,
+} from "../shared/types.ts";
+import { displayHistory, type AgentHistory, type AgentHistoryItem } from "./history-display.ts";
+import { displayEntry, type DisplayEntry } from "./history-record.ts";
+import { isRecord } from "./history-text.ts";
+
+function inBoundary(entry: HistoryEntry, page: HistoryPage, input: HistoryPageInput): boolean {
+  return (
+    (page.terminalSequence === undefined || entry.sequence <= page.terminalSequence) &&
+    (input.endedAt === undefined || (entry.timestamp ?? Infinity) <= input.endedAt)
+  );
+}
+function toolPairs(entry: HistoryEntry): Array<{ toolCallId: string; kind: "call" | "result" }> {
+  const message = entry.entry.message;
+  if (!isRecord(message)) {
+    return [];
+  }
+  if (message.role === "toolResult" && typeof message.toolCallId === "string") {
+    return [{ toolCallId: message.toolCallId, kind: "call" }];
+  }
+  if (message.role !== "assistant" || !Array.isArray(message.content)) {
+    return [];
+  }
+  return message.content.flatMap((part: unknown) =>
+    isRecord(part) && part.type === "toolCall" && typeof part.id === "string"
+      ? [{ toolCallId: part.id, kind: "result" as const }]
+      : [],
+  );
+}
+async function pairedEntries(
+  index: HistoryIndexHandle,
+  input: HistoryPageInput,
+  page: HistoryPage,
+): Promise<Map<string, HistoryEntry>> {
+  const entries = new Map(page.entries.map((entry) => [entry.id, entry]));
+  const tools = new Map<string, { call?: HistoryEntry; result?: HistoryEntry }>();
+  for (const entry of page.entries) {
+    for (const pair of toolPairs(entry)) {
+      tools.set(pair.toolCallId, {
+        ...tools.get(pair.toolCallId),
+        [pair.kind === "call" ? "result" : "call"]: entry,
+      });
+    }
+  }
+  for (const entry of page.entries) {
+    for (const pair of toolPairs(entry)) {
+      let paired: HistoryEntry | null | undefined = tools.get(pair.toolCallId)?.[pair.kind];
+      if (!paired) {
+        // Pair page-local tools in reading order; requests share the bounded history process.
+        // oxlint-disable-next-line no-await-in-loop
+        paired = await index.entry({
+          runId: input.runId,
+          index: input.index,
+          ...pair,
+          terminalEntryId: input.terminalEntryId,
+          endedAt: input.endedAt,
+          signal: input.signal,
+        });
+      }
+      if (paired && inBoundary(paired, page, input)) {
+        entries.set(paired.id, paired);
+      }
+    }
+  }
+  return entries;
+}
+async function fullItem(
+  index: HistoryIndexHandle,
+  input: HistoryPageInput,
+  entries: Readonly<ReadonlyMap<string, HistoryEntry>>,
+  item: AgentHistoryItem,
+): Promise<AgentHistoryItem> {
+  const ids = new Set((item.entryIds ?? [item.id]).map((id) => id.split(":")[0] ?? "")),
+    full: DisplayEntry[] = [];
+  for (const id of ids) {
+    const entry = entries.get(id);
+    if (!entry) {
+      throw new Error("Selected native entry is unavailable; retry history.");
+    }
+    // Keep selected call/result records ordered and the process memory bound to one record at a time.
+    // oxlint-disable-next-line no-await-in-loop
+    const record = await index.record({
+      runId: input.runId,
+      index: input.index,
+      ref: entry.ref,
+      terminalEntryId: input.terminalEntryId,
+      endedAt: input.endedAt,
+      signal: input.signal,
+    });
+    const observed = record && displayEntry({ ...record, id }, "full");
+    if (!observed) {
+      throw new Error("Selected native entry is unavailable; retry history.");
+    }
+    full.push(observed);
+  }
+  const detail = displayHistory(full).items.find((candidate) => candidate.id === item.id);
+  if (!detail) {
+    throw new Error("Selected native entry is unavailable; retry history.");
+  }
+  return detail;
+}
+/** A page retains bounded previews; selected records are revalidated by the process. */
+export async function indexedHistory(
+  index: HistoryIndexHandle,
+  input: HistoryPageInput,
+): Promise<{ history: AgentHistory; page: HistoryPage }> {
+  const page = await index.historyPage(input);
+  if (
+    input.terminalEntryId !== undefined &&
+    input.terminalEntryId.length > 0 &&
+    page.terminalSequence === undefined
+  ) {
+    throw new Error("Saved terminal entry is unavailable; retry history.");
+  }
+  const entries = await pairedEntries(index, input, page);
+  const observed = [...entries.values()]
+    .sort((a, b) => a.sequence - b.sequence)
+    .flatMap((entry) => displayEntry(entry.entry, "preview") ?? []);
+  const history = displayHistory(observed),
+    visible = new Set(page.entries.map((entry) => entry.id));
+  const items = history.items
+    .filter((item) =>
+      (item.entryIds ?? [item.id]).some((id) => visible.has(id.split(":")[0] ?? "")),
+    )
+    .map((item) => detailLoader(item, () => fullItem(index, input, entries, item)));
+  return {
+    history: {
+      ...history,
+      items,
+      entryIds: history.entryIds.filter((id) => visible.has(id.split(":")[0] ?? "")),
+      unavailable: page.unavailable,
+      configuration: page.configuration,
+      deliveredMessages: new Map(page.deliveredMessages),
+      finalId: page.finalResultId,
+    },
+    page,
+  };
+}
+
+function detailLoader(
+  item: AgentHistoryItem,
+  load: () => Promise<AgentHistoryItem>,
+): AgentHistoryItem {
+  return { ...item, load };
+}