@yaag/extension 0.3.0 → 0.5.0

package/src/run-record.ts

@@ -1,5 +1,6 @@
 import { initialSummary, type RunSummary } from "@yaag/runtime";
 import type { ProcessIdentity } from "./process-liveness.ts";
+import { parseRunSummary } from "./run-summary-parse.ts";
 
 /**
  * The durable state of a Run.
@@ -16,21 +17,26 @@ export type PersistedOutcome =
   | { readonly kind: "fulfilled"; readonly code: number | null; readonly result: string }
   | { readonly kind: "rejected"; readonly reason: string };
 
-/** What starting a Run said about it; enough to describe it in a later session. */
-export interface RunLaunch {
-  /**
-   * Exactly one of `file` and `script` is present: `file` for a program file,
-   * `script` for an Inline Program (ADR-0033). The pair stays a tolerant
-   * optional pair rather than a union, because a record written by an older
-   * yaag must still narrow.
-   */
-  readonly file?: string;
-  readonly script?: string;
+/** Everything a launch carries besides the program itself. */
+export interface RunLaunchContext {
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
 }
 
+/**
+ * What starting a Run said about it; enough to describe it in a later session.
+ *
+ * The program is one of exactly two kinds (ADR-0033): a program file, or an
+ * Inline Program source. The tolerance for a record an older yaag wrote without
+ * a `kind` lives in {@link parseRunRecord}, not in this type. A new record does
+ * carry `kind` on disk, which an older yaag ignores, so the format drifts in
+ * both directions without loss.
+ */
+export type RunLaunch =
+  | (RunLaunchContext & { readonly kind: "file"; readonly file: string })
+  | (RunLaunchContext & { readonly kind: "inline"; readonly script: string });
+
 /** One Run as stored on disk, at `<runs dir>/<id>.json`. */
 export interface RunRecord {
   readonly id: string;
@@ -44,22 +50,45 @@ export interface RunRecord {
 }
 
 /**
- * Narrows an untrusted parsed JSON value to a {@link RunRecord}.
+ * Parses an untrusted parsed JSON value into a {@link RunRecord}, or `null`.
  *
  * A record may have been written by an older yaag, or truncated by a crash, so
  * every field the extension reads is checked here and a record that fails is
- * dropped rather than repaired.
+ * dropped rather than repaired. The record is rebuilt from checked fields, and
+ * the launch is normalized to its tagged kind, which is why this is a parser
+ * and not a type guard. The Summary shape is checked by {@link parseRunSummary}.
  */
-export function isRunRecord(value: unknown): value is RunRecord {
-  if (typeof value !== "object" || value === null) return false;
+export function parseRunRecord(value: unknown): RunRecord | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
   const candidate: Record<string, unknown> = { ...value };
-  return (
-    typeof candidate["id"] === "string" &&
-    typeof candidate["startedAt"] === "string" &&
-    isState(candidate["state"]) &&
-    isLaunch(candidate["launch"]) &&
-    isSummary(candidate["summary"])
-  );
+  const launch = parseLaunch(candidate["launch"]);
+  const identity = parseProcess(candidate["process"]);
+  const summary = parseRunSummary(candidate["summary"]);
+  const outcome = parseOutcome(candidate["outcome"]);
+  if (
+    launch === null ||
+    identity === undefined ||
+    summary === null ||
+    outcome === undefined ||
+    typeof candidate["id"] !== "string" ||
+    typeof candidate["startedAt"] !== "string" ||
+    !isNullableString(candidate["endedAt"]) ||
+    !isState(candidate["state"])
+  ) {
+    return null;
+  }
+  // The record is rebuilt field by field, so nothing untrusted is cast: every
+  // field a consumer reads has the type this parser proved (rule 0001 §3).
+  return {
+    id: candidate["id"],
+    launch,
+    process: identity,
+    startedAt: candidate["startedAt"],
+    endedAt: candidate["endedAt"],
+    state: candidate["state"],
+    summary,
+    outcome,
+  };
 }
 
 /** A Run record for a Run that has just started. */
@@ -87,15 +116,65 @@ function isState(value: unknown): value is PersistedRunState {
   );
 }
 
-function isLaunch(value: unknown): value is RunLaunch {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (("file" in value && typeof value.file === "string") ||
-      ("script" in value && typeof value.script === "string"))
-  );
+/** Normalizes the tolerant on-disk launch shape; a record with no `kind` still parses. */
+function parseLaunch(value: unknown): RunLaunch | null {
+  if (typeof value !== "object" || value === null) return null;
+  const stored: Record<string, unknown> = { ...value };
+  const { file, script } = stored;
+  const context = launchContext(stored);
+  // Both present is the state `programTarget` refuses, so a record holding it
+  // is dropped rather than repaired, like a record holding neither.
+  if (typeof file === "string" && typeof script === "string") return null;
+  if (typeof file === "string") return { kind: "file", file, ...context };
+  if (typeof script === "string") return { kind: "inline", script, ...context };
+  return null;
+}
+
+function launchContext(stored: Record<string, unknown>): RunLaunchContext {
+  return {
+    ...(typeof stored.args === "string" ? { args: stored.args } : {}),
+    ...(typeof stored.record === "string" ? { record: stored.record } : {}),
+    ...(typeof stored.resume === "string" ? { resume: stored.resume } : {}),
+  };
+}
+
+/**
+ * `undefined` means the stored value is malformed or missing; a stored `null`
+ * is a Run whose process was never known.
+ */
+function parseProcess(value: unknown): ProcessIdentity | null | undefined {
+  if (value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return undefined;
+  const stored: Record<string, unknown> = { ...value };
+  if (typeof stored.pid !== "number" || !isNullableString(stored.startedAt)) {
+    return undefined;
+  }
+  return { pid: stored.pid, startedAt: stored.startedAt };
+}
+
+/**
+ * `undefined` means the stored value is malformed or missing; a stored `null`
+ * is a Run that has not ended.
+ */
+function parseOutcome(value: unknown): PersistedOutcome | null | undefined {
+  if (value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return undefined;
+  const stored: Record<string, unknown> = { ...value };
+  if (stored.kind === "fulfilled") {
+    if (typeof stored.result !== "string" || !isNullableNumber(stored.code)) return undefined;
+    return { kind: "fulfilled", code: stored.code, result: stored.result };
+  }
+  if (stored.kind === "rejected") {
+    if (typeof stored.reason !== "string") return undefined;
+    return { kind: "rejected", reason: stored.reason };
+  }
+  return undefined;
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
 }
 
-function isSummary(value: unknown): value is RunSummary {
-  return typeof value === "object" && value !== null && "runState" in value;
+function isNullableNumber(value: unknown): value is number | null {
+  return value === null || typeof value === "number";
 }

package/src/run-registry.ts

@@ -1,5 +1,6 @@
 import type { EndedRunSummary, RunSummary } from "@yaag/runtime";
 import type { ProcessIdentity } from "./process-liveness.ts";
+import { pickInlineResumeSource } from "./resume-source.ts";
 import { type RunLaunch, type RunRecord, startedRecord } from "./run-record.ts";
 import { restoreRecords } from "./run-restore.ts";
 import type { RunStore } from "./run-store.ts";
@@ -135,6 +136,21 @@ export class RunRegistry {
     return this.#runs.get(id) ?? { state: "unknown" };
   }
 
+  /**
+   * The Inline Program source a Checkpoint resumes, read back from the durable
+   * records (ADR-0033). Null when no record holds one, and for a memory-only
+   * registry.
+   *
+   * It waits for every queued write first: a record write is asynchronous and
+   * queued, so a resume of a Run that just settled would otherwise read the
+   * directory before its own record is there and refuse a resumable Run.
+   */
+  async inlineSourceFor(artifact: string): Promise<string | null> {
+    if (this.#store === undefined) return null;
+    await this.#store.settled();
+    return pickInlineResumeSource(await this.#store.load(), artifact);
+  }
+
   /** Reads a Run this session never started back from the store, by id. */
   async recall(id: string): Promise<RunStatus> {
     const known = this.lookup(id);

package/src/run-store.ts

@@ -1,12 +1,18 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { isRunRecord, type RunRecord } from "./run-record.ts";
+import { parseRunRecord, type RunRecord } from "./run-record.ts";
 import { resolveRunsDirectory } from "./runs-dir.ts";
 
 /** How many finished records are kept before the oldest ones are pruned. */
 export const FINISHED_RECORD_CAP = 200;
 
+/** Owner-only directory: a Run record can hold an Inline Program source (ADR-0033). */
+export const RECORD_DIRECTORY_MODE = 0o700;
+
+/** Owner-only record file, for the same reason as {@link RECORD_DIRECTORY_MODE}. */
+export const RECORD_FILE_MODE = 0o600;
+
 export interface RunStoreOptions {
   readonly directory?: string;
   readonly cap?: number;
@@ -19,6 +25,11 @@ export interface RunStoreOptions {
  * working when the state directory is read-only or full. Writes go to a temp
  * file and are renamed into place, so a reader never sees a half-written record
  * (ADR-0021).
+ *
+ * A record holds the whole Inline Program source (an inline `RunLaunch`), so the
+ * directory and each record file are private to the user who owns them
+ * ({@link RECORD_DIRECTORY_MODE}, {@link RECORD_FILE_MODE}); the source stays
+ * off argv for the same reason (ADR-0033).
  */
 export class RunStore {
   readonly #directory: string;
@@ -84,9 +95,15 @@ export class RunStore {
     const target = join(this.#directory, `${record.id}.json`);
     const temp = `${target}.${randomUUID()}.tmp`;
     try {
-      await mkdir(this.#directory, { recursive: true });
-      await writeFile(temp, JSON.stringify(record), "utf8");
+      await mkdir(this.#directory, { recursive: true, mode: RECORD_DIRECTORY_MODE });
+      await writeFile(temp, JSON.stringify(record), { encoding: "utf8", mode: RECORD_FILE_MODE });
       await rename(temp, target);
+      // A directory or a record file that an older yaag left readable is
+      // tightened here: the record can hold an Inline Program source. The two
+      // modes above already hold for what this write creates, because an
+      // explicit mode is not broadened by the umask.
+      await chmod(target, RECORD_FILE_MODE);
+      await chmod(this.#directory, RECORD_DIRECTORY_MODE);
     } catch {
       await unlink(temp).catch(() => {});
     }
@@ -95,7 +112,7 @@ export class RunStore {
   async #read(entry: string): Promise<RunRecord | null> {
     try {
       const value: unknown = JSON.parse(await readFile(join(this.#directory, entry), "utf8"));
-      return isRunRecord(value) ? value : null;
+      return parseRunRecord(value);
     } catch {
       return null;
     }

package/src/run-summary-parse.ts

@@ -0,0 +1,265 @@
+import type {
+  AgentActivity,
+  AgentInfo,
+  AgentState,
+  NodeInfo,
+  NodeState,
+  RunOutcome,
+  RunSummary,
+  TokenBreakdown,
+} from "@yaag/runtime";
+
+/**
+ * Parses the persisted Summary of a Run record, or returns `null`.
+ *
+ * The Summary is the one field of a Run record whose whole shape is read again
+ * by the renderers, so it is reconstructed field by field instead of cast: a
+ * record truncated by a crash or written by an older yaag is dropped rather
+ * than repaired (ADR-0021). Every optional field of the fold is rebuilt only
+ * when the stored value has the type the fold gives it.
+ */
+export function parseRunSummary(value: unknown): RunSummary | null {
+  const stored = asRecord(value);
+  if (stored === null) return null;
+  const base = parseBase(stored);
+  if (base === null) return null;
+  if (stored.runState === "running") {
+    if (stored.outcome !== null || stored.ok !== null) return null;
+    return { ...base, runState: "running", outcome: null, ok: null };
+  }
+  if (stored.runState !== "ended") return null;
+  const outcome = stored.outcome;
+  const lost = stored.checkpointLost;
+  if (!isOutcome(outcome) || typeof stored.ok !== "boolean") return null;
+  if (!isNullableNumber(stored.endedAt)) return null;
+  if (lost !== undefined && typeof lost !== "string") return null;
+  return {
+    ...base,
+    runState: "ended",
+    outcome,
+    ok: stored.ok,
+    endedAt: stored.endedAt,
+    ...(lost === undefined ? {} : { checkpointLost: lost }),
+  };
+}
+
+/** The accounting and identity facts every Summary state carries. */
+interface SummaryBase {
+  readonly program: string;
+  readonly startedAt: number | null;
+  readonly artifact: string | null;
+  readonly agents: Readonly<Record<string, AgentInfo>>;
+  readonly asksStarted: number;
+  readonly asksSettled: number;
+  readonly cost: number;
+  readonly tokens: TokenBreakdown | null;
+  readonly incomplete: boolean;
+  readonly durationMs: number;
+  readonly worstFrameGapMs: number;
+}
+
+function parseBase(stored: Record<string, unknown>): SummaryBase | null {
+  const agents = parseAgents(stored.agents);
+  const tokens = parseTokens(stored.tokens);
+  if (
+    agents === null ||
+    tokens === undefined ||
+    typeof stored.program !== "string" ||
+    !isNullableNumber(stored.startedAt) ||
+    !isNullableString(stored.artifact) ||
+    typeof stored.asksStarted !== "number" ||
+    typeof stored.asksSettled !== "number" ||
+    typeof stored.cost !== "number" ||
+    typeof stored.incomplete !== "boolean" ||
+    typeof stored.durationMs !== "number" ||
+    typeof stored.worstFrameGapMs !== "number"
+  ) {
+    return null;
+  }
+  return {
+    program: stored.program,
+    startedAt: stored.startedAt,
+    artifact: stored.artifact,
+    agents,
+    asksStarted: stored.asksStarted,
+    asksSettled: stored.asksSettled,
+    cost: stored.cost,
+    tokens,
+    incomplete: stored.incomplete,
+    durationMs: stored.durationMs,
+    worstFrameGapMs: stored.worstFrameGapMs,
+  };
+}
+
+function parseAgents(value: unknown): Record<string, AgentInfo> | null {
+  const stored = asRecord(value);
+  if (stored === null) return null;
+  const agents: Record<string, AgentInfo> = {};
+  for (const [name, entry] of Object.entries(stored)) {
+    const agent = parseAgent(entry);
+    if (agent === null) return null;
+    agents[name] = agent;
+  }
+  return agents;
+}
+
+function parseAgent(value: unknown): AgentInfo | null {
+  const stored = asRecord(value);
+  if (stored === null) return null;
+  const state = stored.state;
+  const nodes = parseNodes(stored.nodes);
+  const tokens = parseTokens(stored.tokens);
+  const activity = parseActivity(stored.activity);
+  if (
+    nodes === null ||
+    tokens === undefined ||
+    activity === undefined ||
+    !isAgentState(state) ||
+    !isNullableString(stored.model) ||
+    !isNullableString(stored.cwd) ||
+    !isNullableString(stored.branch) ||
+    !isNullableString(stored.sessionFile) ||
+    !isNullableNumber(stored.cost) ||
+    typeof stored.incomplete !== "boolean" ||
+    !isNullableNumber(stored.stateChangedAt) ||
+    !isNullableNumber(stored.usageUpdatedAt) ||
+    !isNullableNumber(stored.askStartedAt) ||
+    typeof stored.finishedNodesPruned !== "number"
+  ) {
+    return null;
+  }
+  const base = {
+    model: stored.model,
+    cwd: stored.cwd,
+    branch: stored.branch,
+    sessionFile: stored.sessionFile,
+    activity,
+    tokens,
+    cost: stored.cost,
+    incomplete: stored.incomplete,
+    stateChangedAt: stored.stateChangedAt,
+    usageUpdatedAt: stored.usageUpdatedAt,
+    askStartedAt: stored.askStartedAt,
+    nodes,
+    finishedNodesPruned: stored.finishedNodesPruned,
+  };
+  if (state === "asking") {
+    if (typeof stored.askIndex !== "number") return null;
+    if (typeof stored.promptGist !== "string") return null;
+    if (typeof stored.replayed !== "boolean") return null;
+    return {
+      ...base,
+      state,
+      askIndex: stored.askIndex,
+      promptGist: stored.promptGist,
+      replayed: stored.replayed,
+    };
+  }
+  if (!isNullableNumber(stored.askIndex)) return null;
+  if (!isNullableString(stored.promptGist)) return null;
+  return { ...base, state, askIndex: stored.askIndex, promptGist: stored.promptGist };
+}
+
+function parseNodes(value: unknown): NodeInfo[] | null {
+  if (!Array.isArray(value)) return null;
+  const nodes: NodeInfo[] = [];
+  for (const entry of value) {
+    const stored = asRecord(entry);
+    if (stored === null) return null;
+    const tokens = parseTokens(stored.tokens);
+    if (
+      tokens === undefined ||
+      typeof stored.path !== "string" ||
+      !isNodeState(stored.state) ||
+      !isNullableString(stored.activityGist) ||
+      !isNullableNumber(stored.cost) ||
+      !isNullableNumber(stored.updatedAt)
+    ) {
+      return null;
+    }
+    nodes.push({
+      path: stored.path,
+      state: stored.state,
+      activityGist: stored.activityGist,
+      tokens,
+      cost: stored.cost,
+      updatedAt: stored.updatedAt,
+    });
+  }
+  return nodes;
+}
+
+/**
+ * `undefined` means the stored value is malformed or missing; a stored `null`
+ * is an Agent or Node whose usage was never reported.
+ */
+function parseTokens(value: unknown): TokenBreakdown | null | undefined {
+  if (value === null) return null;
+  const stored = asRecord(value);
+  if (stored === null) return undefined;
+  const fields = ["input", "output", "cacheRead", "cacheWrite", "total"] as const;
+  if (fields.some((field) => typeof stored[field] !== "number")) return undefined;
+  return {
+    input: stored.input as number,
+    output: stored.output as number,
+    cacheRead: stored.cacheRead as number,
+    cacheWrite: stored.cacheWrite as number,
+    total: stored.total as number,
+  };
+}
+
+/**
+ * `undefined` means the stored value is malformed or missing; a stored `null`
+ * is an Agent with no current activity.
+ */
+function parseActivity(value: unknown): AgentActivity | null | undefined {
+  if (value === null) return null;
+  const stored = asRecord(value);
+  if (stored === null) return undefined;
+  const type = stored.type;
+  if (type === "thinking" || type === "writing" || type === "compacting") return { type };
+  if (type === "tool") {
+    if (typeof stored.name !== "string" || typeof stored.argsGist !== "string") {
+      return undefined;
+    }
+    return { type, name: stored.name, argsGist: stored.argsGist };
+  }
+  if (type === "retrying") {
+    if (typeof stored.attempt !== "number" || typeof stored.max !== "number") {
+      return undefined;
+    }
+    return { type, attempt: stored.attempt, max: stored.max };
+  }
+  return undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return { ...value };
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}
+
+function isNullableNumber(value: unknown): value is number | null {
+  return value === null || typeof value === "number";
+}
+
+function isAgentState(value: unknown): value is AgentState {
+  return value === "idle" || value === "asking" || value === "exited";
+}
+
+function isNodeState(value: unknown): value is NodeState {
+  return value === "running" || value === "exited" || value === "failed";
+}
+
+function isOutcome(value: unknown): value is RunOutcome {
+  return (
+    value === "completed" ||
+    value === "failed" ||
+    value === "stopped" ||
+    value === "paused" ||
+    value === "interrupted"
+  );
+}

package/src/run-tool-test-support.ts

@@ -1,16 +1,14 @@
 import { dirname, join } from "node:path";
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { stripTerminalSequences } from "@earendil-works/pi-tui";
-import { initialSummary } from "@yaag/runtime";
 import type { BackgroundStatus } from "./background-status.ts";
-import { fakeTheme } from "./fake-theme.ts";
 import { resolveBun } from "./resolve-bun.ts";
 import { resolveCliEntry } from "./resolve-cli.ts";
+import type { RunParams } from "./run-call-render.ts";
 import type { RunDetails } from "./run-details.ts";
 import { RunRegistry } from "./run-registry.ts";
 import { createRunTool, type SendMessage } from "./run-tool.ts";
 import type { RunTreeStore } from "./run-trees.ts";
-import type { RunHandle, StartRunOptions } from "./spawn-run.ts";
+import type { RunHandle } from "./spawn-run.ts";
 import { createStopTool, type StopDetails } from "./stop-tool.ts";
 import { TestExtensionContext } from "./test-extension-context.ts";
 
@@ -21,63 +19,6 @@ const ctx = new TestExtensionContext(dirname(cli));
 
 export const fixture = (name: string): string => join(dirname(cli), "fixtures", `${name}.ts`);
 
-export interface RunParams {
-  readonly file?: string;
-  readonly script?: string;
-  readonly args?: string;
-  readonly background?: boolean;
-  readonly record?: string;
-  readonly resume?: string;
-}
-
-/** Renders the tool's call line, stripped of styling, as the transcript shows it. */
-export function renderCallLabel(params: RunParams): string {
-  const tool = createRunTool({
-    bun,
-    cli,
-    registry: new RunRegistry(),
-    sendMessage: () => undefined,
-  });
-  const component = tool.renderCall?.(params, fakeTheme(), {
-    args: params,
-    toolCallId: "call-1",
-    invalidate: () => {},
-    lastComponent: undefined,
-    state: undefined,
-    cwd: process.cwd(),
-    executionStarted: false,
-    argsComplete: true,
-    isPartial: false,
-    expanded: false,
-    showImages: false,
-    isError: false,
-  });
-  return stripTerminalSequences(component?.render(80)[0] ?? "");
-}
-
-/** A start seam that never spawns: it captures its options and ends the Run at once. */
-export function fakeStart(stdout = "{}"): {
-  readonly start: (options: StartRunOptions) => RunHandle;
-  readonly seen: StartRunOptions[];
-} {
-  const seen: StartRunOptions[] = [];
-  return {
-    seen,
-    start: (options) => {
-      seen.push(options);
-      return {
-        stop: () => {},
-        outcome: Promise.resolve({
-          code: 0,
-          stdout,
-          stderr: "",
-          summary: initialSummary(),
-        }),
-      };
-    },
-  };
-}
-
 export interface Sent {
   readonly content: unknown;
   readonly details: unknown;