@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/history/query-scope.ts

@@ -0,0 +1,278 @@
+import { Type, Check } from "../shared/native-typebox.ts";
+import {
+  HistoryIndexError,
+  type HistoryVersion,
+  type HistoryPageInput,
+  type HistoryConfiguration,
+} from "./types.ts";
+import { hash, integer, hasText } from "./text.ts";
+import type { HistoryStore } from "./store.ts";
+import {
+  type SourceRow,
+  type Row,
+  type IndexInput,
+  number,
+  nullableText,
+  nullableNumber,
+  text,
+} from "./rows.ts";
+import { parseObject } from "./values.ts";
+
+const cursorSchema = Type.Object({
+  generation: Type.String(),
+  owner: Type.String(),
+  version: Type.Number(),
+  query: Type.String(),
+  keys: Type.Array(Type.Union([Type.Number(), Type.String()]), { maxItems: 8 }),
+  offset: Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+});
+export interface Cursor {
+  readonly generation: string;
+  readonly owner: string;
+  readonly version: number;
+  readonly query: string;
+  readonly keys: readonly (string | number)[];
+  readonly offset: number;
+}
+export interface Boundary {
+  readonly clauses: readonly string[];
+  readonly params: readonly IndexInput[];
+  readonly terminalSequence?: number;
+}
+function configurationValues(
+  facts: Row,
+  leaf: string | null | undefined,
+  strict: boolean,
+): HistoryConfiguration {
+  const count = number(facts, "count");
+  if (count === 0 && hasText(leaf) && strict) {
+    throw new HistoryIndexError(
+      "BOUNDARY_UNAVAILABLE",
+      "Selected configuration leaf is not available in the indexed generation.",
+    );
+  }
+  if (count > 0 && number(facts, "rooted") === 0) {
+    if (!strict) {
+      return {};
+    }
+    throw new HistoryIndexError(
+      "MALFORMED_ANCESTRY",
+      "Selected native configuration has cyclic ancestry.",
+    );
+  }
+  const model = nullableText(facts, "model");
+  const thinking = nullableText(facts, "thinking");
+  return {
+    ...(model === null
+      ? {}
+      : { model, modelRecordedAt: nullableNumber(facts, "recorded_at") ?? undefined }),
+    ...(thinking === null ? {} : { thinking }),
+  };
+}
+function configurationKey(
+  source: SourceRow,
+  input: Pick<HistoryPageInput, "terminalEntryId" | "endedAt" | "leaf">,
+  strict: boolean,
+): string {
+  const terminal = hasText(input.terminalEntryId);
+  return JSON.stringify([
+    source.id,
+    source.generation,
+    source.cursor,
+    source.stamp,
+    terminal ? input.terminalEntryId : null,
+    terminal ? null : (input.endedAt ?? null),
+    input.leaf === undefined ? null : [typeof input.leaf, input.leaf],
+    strict,
+  ]);
+}
+export class QueryScope {
+  readonly store: Readonly<HistoryStore>;
+  readonly info: () => HistoryVersion;
+  private readonly configurations = new Map<string, HistoryConfiguration>();
+  constructor(store: Readonly<HistoryStore>, info: () => HistoryVersion) {
+    this.store = store;
+    this.info = info;
+  }
+  sourcesRemoved(): void {
+    this.configurations.clear();
+  }
+  key(parts: readonly unknown[]): string {
+    return hash(JSON.stringify(parts));
+  }
+  cursor(query: string, keys: readonly (string | number)[], offset: number): string {
+    return Buffer.from(
+      JSON.stringify({
+        generation: this.store.generation,
+        owner: this.store.owner,
+        version: this.info().version,
+        query,
+        keys,
+        offset,
+      } satisfies Cursor),
+    ).toString("base64url");
+  }
+  parseCursor(value: string | undefined, query: string): Cursor | undefined {
+    if (value === undefined) {
+      return;
+    }
+    let cursor: Cursor;
+    try {
+      if (value.length > 4096) {
+        throw new Error("Cursor exceeds budget.");
+      }
+      const parsed = parseObject(Buffer.from(value, "base64url").toString("utf8"));
+      if (!Check(cursorSchema, parsed)) {
+        throw new Error("Invalid cursor fields.");
+      }
+      cursor = parsed;
+    } catch {
+      throw new HistoryIndexError("INVALID_CURSOR", "Invalid history cursor.");
+    }
+    if (
+      cursor.generation !== this.store.generation ||
+      cursor.owner !== this.store.owner ||
+      cursor.query !== query ||
+      cursor.version !== this.info().version
+    ) {
+      throw new HistoryIndexError(
+        "STALE_CURSOR",
+        "History changed or this cursor belongs to a different query/source; restart paging.",
+      );
+    }
+    return cursor;
+  }
+  child(runId: string, index: number): { readonly source?: SourceRow; readonly agent: string } {
+    integer(index, 0);
+    const child = this.store.get(
+      "SELECT * FROM children WHERE run_id=? AND child_index=?",
+      runId,
+      index,
+    );
+    if (!child) {
+      throw new HistoryIndexError(
+        "OWNERSHIP",
+        "Run/child is not in the current owner's admitted handles.",
+      );
+    }
+    const sourceId = nullableText(child, "source_id");
+    return {
+      source: sourceId === null ? undefined : this.store.source(sourceId),
+      agent: text(child, "agent"),
+    };
+  }
+  boundary(
+    source: SourceRow,
+    input: Pick<HistoryPageInput, "terminalEntryId" | "endedAt">,
+    alias: "" | "e" = "",
+  ): Boundary {
+    const column = alias.length > 0 ? `${alias}.` : "";
+    const clauses = [`${column}source_id=?`, `${column}generation=?`, `${column}published=1`];
+    const params: IndexInput[] = [source.id, source.generation];
+    let terminalSequence: number | undefined;
+    if (input.terminalEntryId !== undefined && input.terminalEntryId.length > 0) {
+      const terminal = this.store.get(
+        "SELECT start FROM entries WHERE source_id=? AND generation=? AND id=? AND published=1",
+        source.id,
+        source.generation,
+        input.terminalEntryId,
+      );
+      if (!terminal) {
+        throw new HistoryIndexError(
+          "BOUNDARY_UNAVAILABLE",
+          "Saved terminal entry is not available in the current indexed generation.",
+        );
+      }
+      terminalSequence = number(terminal, "start");
+      clauses.push(`${column}start<=?`);
+      params.push(terminalSequence);
+    } else if (input.endedAt !== undefined) {
+      clauses.push(`${column}timestamp<=?`);
+      params.push(integer(input.endedAt, 0));
+    }
+    return { clauses, params, terminalSequence };
+  }
+  private configurationFacts(
+    source: SourceRow,
+    input: Pick<HistoryPageInput, "terminalEntryId" | "endedAt" | "leaf">,
+  ): ReturnType<HistoryStore["get"]> {
+    const boundary = this.boundary(source, input);
+    const latest = this.store.get(
+      `SELECT id FROM entries WHERE ${boundary.clauses.join(" AND ")} ORDER BY start DESC LIMIT 1`,
+      ...boundary.params,
+    );
+    const leaf = input.leaf ?? (latest ? text(latest, "id") : undefined);
+    if (leaf === undefined || leaf.length === 0) {
+      return;
+    }
+    // Resolve each child's parent by its indexed ID, not a transcript rescan at every step.
+    const ancestry = `WITH RECURSIVE eligible AS (SELECT rowid,id,parent_id,start,timestamp,configuration_model,configuration_thinking FROM entries WHERE ${boundary.clauses.join(" AND ")}), branch AS (SELECT * FROM eligible WHERE id=? UNION SELECT parent.* FROM branch child CROSS JOIN eligible parent WHERE parent.id=child.parent_id)`;
+    return this.store.require(
+      `${ancestry} SELECT
+      (SELECT COUNT(*) FROM branch) AS count,
+      EXISTS(SELECT 1 FROM branch child WHERE parent_id IS NULL OR NOT EXISTS(SELECT 1 FROM eligible parent WHERE parent.id=child.parent_id)) AS rooted,
+      (SELECT configuration_model FROM branch WHERE configuration_model IS NOT NULL ORDER BY start DESC LIMIT 1) AS model,
+      (SELECT timestamp FROM branch WHERE configuration_model IS NOT NULL ORDER BY start DESC LIMIT 1) AS recorded_at,
+      (SELECT configuration_thinking FROM branch WHERE configuration_thinking IS NOT NULL ORDER BY start DESC LIMIT 1) AS thinking`,
+      ...boundary.params,
+      leaf,
+    );
+  }
+  configuration(
+    source: SourceRow,
+    input: Pick<HistoryPageInput, "terminalEntryId" | "endedAt" | "leaf">,
+    strict = true,
+  ): HistoryConfiguration {
+    if (input.leaf === null) {
+      return {};
+    }
+    try {
+      // Validate boundaries before reuse. Only committed source changes invalidate ancestry.
+      this.boundary(source, input);
+      const key = configurationKey(source, input, strict);
+      const cached = this.configurations.get(key);
+      if (cached) {
+        return { ...cached };
+      }
+      const facts = this.configurationFacts(source, input);
+      if (!facts) {
+        return {};
+      }
+      const configuration = configurationValues(facts, input.leaf, strict);
+      this.cacheConfiguration(key, configuration);
+      return { ...configuration };
+    } catch (error) {
+      if (!strict && error instanceof HistoryIndexError && error.code === "BOUNDARY_UNAVAILABLE") {
+        return {};
+      }
+      throw error;
+    }
+  }
+  private cacheConfiguration(key: string, configuration: HistoryConfiguration): void {
+    if (this.configurations.size >= 128) {
+      const oldest = this.configurations.keys().next().value;
+      if (oldest !== undefined) {
+        this.configurations.delete(oldest);
+      }
+    }
+    this.configurations.set(key, configuration);
+  }
+  finalResultId(
+    input: Pick<HistoryPageInput, "runId" | "index" | "terminalEntryId" | "endedAt">,
+    digest: string,
+    preferredRange?: readonly [number, number],
+  ): string | undefined {
+    const { source } = this.child(input.runId, input.index);
+    if (!source) {
+      return;
+    }
+    const boundary = this.boundary(source, input, "e");
+    const row = this.store.get(
+      `SELECT a.item_id FROM answers a JOIN entries e ON e.rowid=a.entry_rowid WHERE a.digest=? AND ${boundary.clauses.join(" AND ")} ORDER BY ${preferredRange ? "(e.start BETWEEN ? AND ?) DESC," : ""}e.start DESC LIMIT 1`,
+      digest,
+      ...boundary.params,
+      ...(preferredRange ?? []),
+    );
+    return row ? text(row, "item_id") : undefined;
+  }
+}

package/src/history/rows.ts

@@ -0,0 +1,118 @@
+import { isRecord } from "../shared/unknown.ts";
+import { HistoryIndexError } from "./types.ts";
+
+export type IndexInput = string | number | bigint | null;
+export type Row = Readonly<Record<string, string | number | null>>;
+export function indexRow(input: unknown): Row {
+  if (!isRecord(input)) {
+    throw new HistoryIndexError("CORRUPT", "Invalid index row.");
+  }
+  const row: Record<string, string | number | null> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== null && typeof value !== "string" && typeof value !== "number") {
+      throw new HistoryIndexError("CORRUPT", `Unsupported index column ${key}.`);
+    }
+    row[key] = value;
+  }
+  return row;
+}
+export function text(row: Row, key: string): string {
+  const value = row[key];
+  if (typeof value !== "string") {
+    throw new HistoryIndexError("CORRUPT", `Invalid index text column ${key}.`);
+  }
+  return value;
+}
+export function number(row: Row, key: string): number {
+  const value = row[key];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new HistoryIndexError("CORRUPT", `Invalid index numeric column ${key}.`);
+  }
+  return value;
+}
+export function nullableText(row: Row, key: string): string | null {
+  return row[key] === null ? null : text(row, key);
+}
+export function nullableNumber(row: Row, key: string): number | null {
+  return row[key] === null ? null : number(row, key);
+}
+export interface SourceRow {
+  readonly id: string;
+  readonly path: string;
+  readonly generation: number;
+  readonly identity: string | null;
+  readonly stamp: string | null;
+  readonly session_id: string | null;
+  readonly header_digest: string | null;
+  readonly cursor: number;
+  readonly prefix_digest: string | null;
+  readonly state: string;
+  readonly error: string | null;
+  readonly malformed: number;
+  readonly complexity: number;
+  readonly checked_at: number | null;
+  readonly format_version: number | null;
+}
+export interface EntryRow {
+  readonly rowid: number;
+  readonly source_id: string;
+  readonly generation: number;
+  readonly id: string;
+  readonly native_id: string | null;
+  readonly parent_id: string | null;
+  readonly start: number;
+  readonly end: number;
+  readonly digest: string;
+  readonly timestamp: number | null;
+  readonly type: string;
+  readonly preview: string;
+  readonly published: number;
+  readonly role: string | null;
+  readonly assistant_text: number;
+  readonly visible_id: string | null;
+  readonly human_id: string | null;
+  readonly configuration_model: string | null;
+  readonly configuration_thinking: string | null;
+}
+export function sourceRow(row: Row): SourceRow {
+  return {
+    id: text(row, "id"),
+    path: text(row, "path"),
+    generation: number(row, "generation"),
+    identity: nullableText(row, "identity"),
+    stamp: nullableText(row, "stamp"),
+    session_id: nullableText(row, "session_id"),
+    header_digest: nullableText(row, "header_digest"),
+    cursor: number(row, "cursor"),
+    prefix_digest: nullableText(row, "prefix_digest"),
+    state: text(row, "state"),
+    error: nullableText(row, "error"),
+    malformed: number(row, "malformed"),
+    complexity: number(row, "complexity"),
+    checked_at: nullableNumber(row, "checked_at"),
+    format_version: nullableNumber(row, "format_version"),
+  };
+}
+export function entryRow(row: Row): EntryRow {
+  return {
+    rowid: number(row, "rowid"),
+    source_id: text(row, "source_id"),
+    generation: number(row, "generation"),
+    id: text(row, "id"),
+    native_id: nullableText(row, "native_id"),
+    parent_id: nullableText(row, "parent_id"),
+    start: number(row, "start"),
+    end: number(row, "end"),
+    digest: text(row, "digest"),
+    timestamp: nullableNumber(row, "timestamp"),
+    type: text(row, "type"),
+    preview: text(row, "preview"),
+    published: number(row, "published"),
+    role: nullableText(row, "role"),
+    assistant_text: number(row, "assistant_text"),
+    visible_id: nullableText(row, "visible_id"),
+    human_id: nullableText(row, "human_id"),
+    configuration_model: nullableText(row, "configuration_model"),
+    configuration_thinking: nullableText(row, "configuration_thinking"),
+  };
+}

package/src/history/run-projection.ts

@@ -0,0 +1,164 @@
+import { ownedRunView } from "../runs/shared/run-records.ts";
+import { acceptanceHumanAction } from "../runs/shared/acceptance-evaluation.ts";
+import {
+  getRunMetadataDir,
+  listRunQuestions,
+  summarizeSupervisorQuestion,
+} from "../runs/shared/supervisor-questions.ts";
+import type { HistoryRunRow, OwnedRun, ReadonlyForegroundResumeRun } from "./types.ts";
+import type { OwnedRunReadState } from "../runs/shared/owned-run-read-state.ts";
+import { safeText } from "./text.ts";
+
+type Child = HistoryRunRow["children"][number];
+function compactResult(result: Child["result"]): Child["result"] {
+  if (!result) {
+    return;
+  }
+  return {
+    agent: result.agent,
+    task: safeText(result.task),
+    exitCode: result.exitCode,
+    usage: {
+      input: result.usage.input,
+      output: result.usage.output,
+      cacheRead: result.usage.cacheRead,
+      cacheWrite: result.usage.cacheWrite,
+      cost: result.usage.cost,
+      turns: result.usage.turns,
+    },
+    finalOutput: safeText(result.finalOutput, 1024),
+    error: result.error === undefined ? undefined : safeText(result.error),
+    sessionFile: result.sessionFile,
+    terminalEntryId: result.terminalEntryId,
+    terminalLeafId: result.terminalLeafId,
+    detached: result.detached,
+    interrupted: result.interrupted,
+    timedOut: result.timedOut,
+    nativeSessionId: result.nativeSessionId,
+    accounting: result.accounting,
+    agentProcessExit: result.agentProcessExit,
+    model: result.model,
+    fullOutputPath: result.fullOutputPath,
+  };
+}
+function compactActivity(activity: Child["activity"]): Child["activity"] {
+  if (!activity) {
+    return;
+  }
+  return {
+    status: activity.status,
+    currentTool: activity.currentTool,
+    currentToolArgs:
+      activity.currentToolArgs === undefined ? undefined : safeText(activity.currentToolArgs, 256),
+    currentPath: activity.currentPath,
+    streamingText:
+      activity.streamingText === undefined
+        ? undefined
+        : safeText(activity.streamingText.slice(-2048), 2048),
+    lastActivityAt: activity.lastActivityAt,
+    recentOutput: activity.recentOutput?.slice(-4).map((line) => safeText(line, 256)),
+  };
+}
+function compactChild(child: Child): Child {
+  return {
+    agent: child.agent,
+    index: child.index,
+    workflowNodeId: child.workflowNodeId,
+    sessionFile: child.sessionFile,
+    task: child.task === undefined ? undefined : safeText(child.task),
+    label: child.label === undefined ? undefined : safeText(child.label, 256),
+    state: child.state,
+    configuration: child.configuration,
+    missingSession: child.missingSession,
+    identityUnavailable: child.identityUnavailable,
+    modelSelection: child.modelSelection,
+    savedConfiguration: child.launch && {
+      model: child.launch.model,
+      thinking: child.launch.thinking,
+      modelRecordedAt: child.launch.modelRecordedAt,
+    },
+    humanAction:
+      child.result?.acceptance && safeText(acceptanceHumanAction(child.result.acceptance), 2048),
+    acceptanceStatus: child.result?.acceptance?.status,
+    activity: compactActivity(child.activity),
+    result: compactResult(child.result),
+  };
+}
+function compactQuestion(
+  question: NonNullable<HistoryRunRow["questions"]>[number],
+): NonNullable<HistoryRunRow["questions"]>[number] {
+  const summary = summarizeSupervisorQuestion(question);
+  return {
+    ...summary,
+    message: safeText(question.message, 2048),
+    answer: summary.answer && {
+      ...summary.answer,
+      message: safeText(question.answer?.message, 2048),
+    },
+  };
+}
+export function unknownRun(
+  run: OwnedRun,
+  diagnosis = "Run summary is awaiting background canonical projection.",
+): HistoryRunRow {
+  return {
+    ...run,
+    state: "unknown",
+    updatedAt: run.startedAt,
+    attention: ["unknown"],
+    canInterrupt: false,
+    continuations: [],
+    children: run.children.map((child) => ({
+      ...child,
+      state: "unknown",
+      configuration: "legacy-partial",
+    })),
+    diagnosis,
+  };
+}
+export function compactView(view: HistoryRunRow): HistoryRunRow {
+  return {
+    ...view,
+    task: safeText(view.task, 2048),
+    error: view.error === undefined ? undefined : safeText(view.error),
+    diagnosis: view.diagnosis === undefined ? undefined : safeText(view.diagnosis),
+    recoveryError: view.recoveryError === undefined ? undefined : safeText(view.recoveryError),
+    review: view.review && {
+      ...view.review,
+      message: view.review.message === undefined ? undefined : safeText(view.review.message),
+    },
+    continuations: [],
+    questions: view.questions?.map(compactQuestion),
+    children: view.children.map(compactChild),
+    summary: safeText(
+      view.children
+        .map((child) => child.result?.finalOutput ?? child.result?.error ?? "")
+        .filter((text) => text.length > 0)
+        .join(" | "),
+      1024,
+    ),
+  };
+}
+/** Canonical owner/filesystem projection. Native transcript presence never establishes completion. */
+export function projectRun(
+  run: OwnedRun,
+  ownerSessionId: string,
+  runs: Readonly<ReadonlyMap<string, OwnedRun>>,
+  foreground: Readonly<ReadonlyMap<string, ReadonlyForegroundResumeRun>>,
+): HistoryRunRow {
+  const state: OwnedRunReadState = { ownedRuns: runs, foregroundRuns: foreground };
+  const questions = listRunQuestions(getRunMetadataDir(run.runId)).filter(
+    (question) =>
+      question.ownerSessionId === ownerSessionId &&
+      ["awaiting_input", "answer_pending"].includes(question.state),
+  );
+  return {
+    ...ownedRunView(run, state, {
+      pendingInput: questions.length > 0,
+      includeContinuations: false,
+      readConfiguration: false,
+      reconcile: false,
+    }),
+    questions,
+  };
+}