@yaag/runtime 0.1.0

package/src/summary-agent.ts

@@ -0,0 +1,310 @@
+import type { AgentActivity } from "./events.ts";
+import type { NodeInfo } from "./summary-nodes.ts";
+import type { TokenBreakdown, WorktreeResolution } from "./transport.ts";
+
+export type { AgentActivity } from "./events.ts";
+export type { NodeInfo } from "./summary-nodes.ts";
+
+/** The observer-facing lifecycle state of an Agent. */
+export type AgentState = "idle" | "asking" | "exited";
+
+/** Identity and accounting facts that apply in every observer Agent state. */
+interface AgentInfoBase {
+  readonly model: string | null;
+  readonly cwd: string | null;
+  readonly branch: string | null;
+  /** pi's session file for this Agent, when the spawn reported one; a Peek reads it. */
+  readonly sessionFile: string | null;
+  readonly activity: AgentActivity | null;
+  readonly tokens: TokenBreakdown | null;
+  readonly cost: number | null;
+  readonly incomplete: boolean;
+  readonly stateChangedAt: number | null;
+  /** Timestamp ordering only cumulative live accounting, never lifecycle state. */
+  readonly usageUpdatedAt: number | null;
+  readonly askStartedAt: number | null;
+  /** This Agent's bounded Nested Node table, in first-seen order (spec §3). */
+  readonly nodes: readonly NodeInfo[];
+  /** Exited Nested Nodes dropped to keep the table bounded. */
+  readonly finishedNodesPruned: number;
+}
+
+/** An Agent between Asks; its latest settled Ask identity, if any, is retained. */
+export interface IdleAgentInfo extends AgentInfoBase {
+  readonly state: "idle";
+  readonly askIndex: number | null;
+  readonly promptGist: string | null;
+}
+
+/** An Agent with one active Ask, whose identity and start timestamp are known. */
+export interface AskingAgentInfo extends AgentInfoBase {
+  readonly state: "asking";
+  readonly askIndex: number;
+  readonly promptGist: string;
+  /** Whether the active Ask is served from Cassette playback. */
+  readonly replayed: boolean;
+  /** Null only for a legacy unstamped Ask start; no timestamp is synthesized. */
+  readonly askStartedAt: number | null;
+}
+
+/** A terminal Agent observation retaining its final usage and latest Ask identity. */
+export interface ExitedAgentInfo extends AgentInfoBase {
+  readonly state: "exited";
+  readonly askIndex: number | null;
+  readonly promptGist: string | null;
+}
+
+/**
+ * The discriminated observer projection for one Agent.
+ *
+ * Transition helpers below are pure and clock-free. Stamped state events older
+ * than the folded state are ignored; unstamped legacy events use stream order.
+ */
+export type AgentInfo = IdleAgentInfo | AskingAgentInfo | ExitedAgentInfo;
+
+/** Internal fold record, deliberately identical to the public observer projection. */
+export type AgentRecord = AgentInfo;
+
+/** Cumulative assistant-completion usage observed while an Agent is still live. */
+export interface AgentUsageObservation {
+  readonly tokens: TokenBreakdown;
+  readonly cost: number;
+}
+
+/** Final usage and optional worktree identity reported when an Agent exits. */
+export interface AgentExitObservation {
+  readonly tokens: TokenBreakdown | null;
+  readonly cost: number | null;
+  readonly incomplete: boolean;
+  readonly worktree?: WorktreeResolution;
+}
+
+/** Produces an idle placeholder for lifecycle events received before a spawn. */
+function placeholderAgent(): IdleAgentInfo {
+  return {
+    model: null,
+    cwd: null,
+    branch: null,
+    sessionFile: null,
+    state: "idle",
+    askIndex: null,
+    promptGist: null,
+    activity: null,
+    tokens: null,
+    cost: null,
+    incomplete: false,
+    stateChangedAt: null,
+    usageUpdatedAt: null,
+    askStartedAt: null,
+    nodes: [],
+    finishedNodesPruned: 0,
+  };
+}
+
+/**
+ * Reconciles spawn identity without reopening a terminal Agent or losing facts
+ * learned from a prior exit. A late spawn fills only missing identity fields.
+ */
+export function spawnAgent(
+  current: AgentRecord | undefined,
+  identity: {
+    readonly model: string;
+    readonly cwd: string;
+    readonly branch?: string;
+    readonly sessionFile?: string;
+  },
+  at: number | null,
+): AgentRecord {
+  if (current === undefined) {
+    return {
+      ...placeholderAgent(),
+      model: identity.model,
+      cwd: identity.cwd,
+      branch: identity.branch ?? null,
+      sessionFile: identity.sessionFile ?? null,
+      stateChangedAt: at,
+    };
+  }
+  return {
+    ...current,
+    model: current.model ?? identity.model,
+    cwd: current.cwd ?? identity.cwd,
+    branch: current.branch ?? identity.branch ?? null,
+    sessionFile: current.sessionFile ?? identity.sessionFile ?? null,
+  };
+}
+
+/**
+ * Folds an Ask start into the asking arm when it is not older than the folded
+ * Agent state or Ask identity. Legacy unstamped events retain arrival order.
+ */
+export function startAsk(
+  current: AgentRecord | undefined,
+  ask: { readonly index: number; readonly promptGist: string; readonly replayed: boolean },
+  at: number | null,
+): AgentRecord {
+  const agent = current ?? placeholderAgent();
+  if (!canChangeAskState(agent, at) || (agent.askIndex !== null && ask.index < agent.askIndex)) {
+    return agent;
+  }
+  return {
+    ...agent,
+    state: "asking",
+    askIndex: ask.index,
+    promptGist: ask.promptGist,
+    replayed: ask.replayed,
+    activity: null,
+    stateChangedAt: at,
+    askStartedAt: at,
+  };
+}
+
+/**
+ * Folds an Ask-scoped activity only into its current asking Agent. Older stamped
+ * observations, mismatched Ask identities, and terminal states are ignored.
+ */
+export function setActivity(
+  current: AgentRecord | undefined,
+  index: number,
+  activity: AgentActivity,
+  at: number | null,
+): AgentRecord {
+  const agent = current ?? placeholderAgent();
+  if (
+    agent.state !== "asking" ||
+    agent.askIndex !== index ||
+    (at !== null && agent.stateChangedAt !== null && at < agent.stateChangedAt)
+  ) {
+    return agent;
+  }
+  return { ...agent, activity, stateChangedAt: at };
+}
+
+/**
+ * Folds an Ask settlement into the idle arm, retaining the settled Ask identity.
+ * Older stamped events are ignored and legacy unstamped events use stream order.
+ */
+export function endAsk(
+  current: AgentRecord | undefined,
+  index: number,
+  at: number | null,
+): AgentRecord {
+  const agent = current ?? placeholderAgent();
+  if (
+    !canChangeAskState(agent, at) ||
+    (agent.askIndex !== null &&
+      (index < agent.askIndex || (agent.state === "asking" && agent.askIndex !== index)))
+  ) {
+    return agent;
+  }
+  return {
+    ...agent,
+    state: "idle",
+    askIndex: index,
+    activity: null,
+    stateChangedAt: at,
+  };
+}
+
+/**
+ * Folds a cumulative usage snapshot without changing Agent lifecycle state.
+ *
+ * Terminal Agent accounting is never replaced; equal usage timestamps retain
+ * stream order while older stamped observations are ignored.
+ */
+export function setUsage(
+  current: AgentRecord | undefined,
+  observation: AgentUsageObservation,
+  at: number | null,
+): AgentRecord {
+  const agent = current ?? placeholderAgent();
+  if (
+    agent.state === "exited" ||
+    (at !== null && agent.usageUpdatedAt !== null && at < agent.usageUpdatedAt)
+  ) {
+    return agent;
+  }
+  return { ...agent, tokens: observation.tokens, cost: observation.cost, usageUpdatedAt: at };
+}
+
+/**
+ * Folds authoritative shutdown accounting into the terminal Agent state.
+ *
+ * Worktree identity is enriched even when a stale exit cannot alter state or
+ * usage, so late observations remain useful.
+ */
+export function exitAgent(
+  current: AgentRecord | undefined,
+  observation: AgentExitObservation,
+  at: number | null,
+): AgentRecord {
+  const agent = enrichWorktree(current ?? placeholderAgent(), observation.worktree);
+  if (!canReplaceExit(agent, at)) return agent;
+  return {
+    ...agent,
+    state: "exited",
+    activity: null,
+    tokens: observation.tokens,
+    cost: observation.cost,
+    incomplete: observation.incomplete || observation.cost === null,
+    stateChangedAt: at,
+  };
+}
+
+/**
+ * Computes Run-wide accounting from every Agent's newest snapshot. A live Agent
+ * without an assistant completion contributes zero; an exited Agent without
+ * final stats preserves the established unknown-accounting semantics.
+ */
+export function totalsFromAgents(agents: Readonly<Record<string, AgentRecord>>): {
+  readonly cost: number;
+  readonly tokens: TokenBreakdown | null;
+  readonly incomplete: boolean;
+} {
+  const records = Object.values(agents);
+  return {
+    cost: records.reduce((total, agent) => total + (agent.cost ?? 0), 0),
+    tokens: records.some((agent) => agent.state === "exited" && agent.tokens === null)
+      ? null
+      : records.reduce(addTokens, zeroTokens()),
+    incomplete: records.some(
+      (agent) => agent.state === "exited" && (agent.incomplete || agent.cost === null),
+    ),
+  };
+}
+
+function enrichWorktree(agent: AgentRecord, worktree: WorktreeResolution | undefined): AgentRecord {
+  if (worktree === undefined) return agent;
+  return {
+    ...agent,
+    cwd: agent.cwd ?? worktree.cwd,
+    branch: agent.branch ?? worktree.branch,
+  };
+}
+
+function canChangeAskState(agent: AgentRecord, at: number | null): boolean {
+  return (
+    agent.state !== "exited" &&
+    (at === null || agent.stateChangedAt === null || at >= agent.stateChangedAt)
+  );
+}
+
+function canReplaceExit(agent: AgentRecord, at: number | null): boolean {
+  return at === null || agent.stateChangedAt === null || at >= agent.stateChangedAt;
+}
+
+function addTokens(total: TokenBreakdown, agent: AgentRecord): TokenBreakdown {
+  const tokens = agent.tokens;
+  if (tokens === null) return total;
+  return {
+    input: total.input + tokens.input,
+    output: total.output + tokens.output,
+    cacheRead: total.cacheRead + tokens.cacheRead,
+    cacheWrite: total.cacheWrite + tokens.cacheWrite,
+    total: total.total + tokens.total,
+  };
+}
+
+function zeroTokens(): TokenBreakdown {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+}

package/src/summary-nodes.ts

@@ -0,0 +1,77 @@
+import type { LifecycleEventBody, NodeState } from "./events.ts";
+import type { AgentRecord } from "./summary-agent.ts";
+import type { TokenBreakdown } from "./transport.ts";
+import { AGENT_NODE_TABLE_MAX } from "./wire-constants.ts";
+
+/** One Nested Node's folded row in an Agent's bounded node table. */
+export interface NodeInfo {
+  readonly path: string;
+  readonly state: NodeState;
+  readonly activityGist: string | null;
+  readonly tokens: TokenBreakdown | null;
+  readonly cost: number | null;
+  readonly updatedAt: number | null;
+}
+
+type NodeUpdateEvent = Extract<LifecycleEventBody, { readonly type: "node_update" }>;
+
+/**
+ * Folds one `node_update` into an Agent's bounded node table.
+ *
+ * Rows upsert by path and keep first-seen order. A stamped update older than
+ * the folded row is ignored, mirroring `setActivity`. Past
+ * `AGENT_NODE_TABLE_MAX` rows, exited nodes prune oldest-first into
+ * `finishedNodesPruned`. Running nodes are never pruned, so the table retains
+ * at most `max(AGENT_NODE_TABLE_MAX, simultaneously running node count)` rows:
+ * the row count is unbounded if upstream concurrency is unbounded. Only each
+ * row's snapshot size is bounded (spec §3).
+ */
+export function applyNodeUpdate(
+  agent: AgentRecord,
+  event: NodeUpdateEvent,
+  at: number | null,
+): AgentRecord {
+  const index = agent.nodes.findIndex((node) => node.path === event.path);
+  const current = index === -1 ? undefined : agent.nodes[index];
+  if (
+    current !== undefined &&
+    at !== null &&
+    current.updatedAt !== null &&
+    at < current.updatedAt
+  ) {
+    return agent;
+  }
+  const node = nodeFrom(event, at);
+  const nodes =
+    current === undefined
+      ? [...agent.nodes, node]
+      : agent.nodes.map((existing, position) => (position === index ? node : existing));
+  return prune({ ...agent, nodes });
+}
+
+function nodeFrom(event: NodeUpdateEvent, at: number | null): NodeInfo {
+  return {
+    path: event.path,
+    state: event.state,
+    activityGist: event.activityGist ?? null,
+    tokens: event.usage?.tokens ?? null,
+    cost: event.usage?.cost ?? null,
+    updatedAt: at,
+  };
+}
+
+function prune(agent: AgentRecord): AgentRecord {
+  if (agent.nodes.length <= AGENT_NODE_TABLE_MAX) return agent;
+  const excess = agent.nodes.length - AGENT_NODE_TABLE_MAX;
+  const kept: NodeInfo[] = [];
+  let pruned = 0;
+  for (const node of agent.nodes) {
+    if (node.state !== "running" && pruned < excess) {
+      pruned += 1;
+      continue;
+    }
+    kept.push(node);
+  }
+  if (pruned === 0) return agent;
+  return { ...agent, nodes: kept, finishedNodesPruned: agent.finishedNodesPruned + pruned };
+}

package/src/summary.ts

@@ -0,0 +1,213 @@
+import type { LifecycleEvent, LifecycleEventBody, RunOutcome } from "./events.ts";
+import type { AgentInfo } from "./summary-agent.ts";
+import {
+  type AgentRecord,
+  endAsk,
+  exitAgent,
+  setActivity,
+  setUsage,
+  spawnAgent,
+  startAsk,
+  totalsFromAgents,
+} from "./summary-agent.ts";
+import { applyNodeUpdate } from "./summary-nodes.ts";
+import type { TokenBreakdown } from "./transport.ts";
+
+export type { NodeState, NodeUsage, RunOutcome } from "./events.ts";
+export type {
+  AgentActivity,
+  AgentInfo,
+  AgentState,
+  AskingAgentInfo,
+  ExitedAgentInfo,
+  IdleAgentInfo,
+  NodeInfo,
+} from "./summary-agent.ts";
+
+/** The observer-facing lifecycle state of a Run. */
+export type RunState = "running" | "ended";
+
+/** Accounting and identity facts shared by all Run observer states. */
+interface RunSummaryBase {
+  readonly program: string;
+  readonly startedAt: number | 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;
+}
+
+/** A Run that has not settled; it has neither outcome nor compatibility result. */
+export interface RunningRunSummary extends RunSummaryBase {
+  readonly runState: "running";
+  readonly outcome: null;
+  readonly ok: null;
+}
+
+/** A settled Run with its outcome, compatibility result, and ending event time. */
+export interface EndedRunSummary extends RunSummaryBase {
+  readonly runState: "ended";
+  readonly outcome: RunOutcome;
+  readonly ok: boolean;
+  /** The `run_end.at` event fact used to reject strictly older stamped endings. */
+  readonly endedAt: number | null;
+}
+
+/**
+ * The pure, discriminated observer fold of a Run's Lifecycle Events.
+ *
+ * It stores event facts only, reads no clock, and never synthesizes durations:
+ * `run_end.durationMs` is authoritative. Unknown events are no-ops. Stamped
+ * state events use timestamp order (ties retain stream order); legacy unstamped
+ * bodies use arrival order because no timestamp can be compared.
+ */
+export type RunSummary = RunningRunSummary | EndedRunSummary;
+
+const ZERO_TOKENS: TokenBreakdown = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  total: 0,
+};
+
+/** Returns the deterministic, running Summary for a Run that emitted nothing. */
+export function initialSummary(): RunningRunSummary {
+  return {
+    program: "",
+    runState: "running",
+    outcome: null,
+    startedAt: null,
+    agents: {},
+    asksStarted: 0,
+    asksSettled: 0,
+    cost: 0,
+    tokens: ZERO_TOKENS,
+    incomplete: false,
+    durationMs: 0,
+    worstFrameGapMs: 0,
+    ok: null,
+  };
+}
+
+/**
+ * Folds one Lifecycle Event into a fresh Summary without mutating either input.
+ *
+ * A stamped `run_end` older than the folded terminal timestamp is a no-op;
+ * equal times retain stream order. Legacy unstamped endings retain arrival order
+ * and may replace a stamped ending because no ordering fact exists. A late
+ * `run_start` enriches program/start metadata but never reopens a settled Run.
+ */
+export function applyEvent(summary: RunSummary, event: LifecycleEvent): RunSummary;
+export function applyEvent(summary: RunSummary, event: LifecycleEventBody): RunSummary;
+export function applyEvent(
+  summary: RunSummary,
+  event: LifecycleEvent | LifecycleEventBody,
+): RunSummary {
+  const at = "at" in event ? event.at : null;
+  switch (event.type) {
+    case "run_start":
+      return { ...summary, program: event.program, startedAt: at };
+    case "agent_spawn":
+      return withAgent(summary, event.agent, spawnAgent(summary.agents[event.agent], event, at));
+    case "ask_start":
+      return withAgent(
+        { ...summary, asksStarted: summary.asksStarted + 1 },
+        event.agent,
+        startAsk(summary.agents[event.agent], { ...event, replayed: event.replayed === true }, at),
+      );
+    case "ask_activity":
+      return updateActivity(summary, event, at);
+    case "node_update":
+      return updateNodes(summary, event, at);
+    case "agent_usage":
+      return withAgent(summary, event.agent, setUsage(summary.agents[event.agent], event, at));
+    case "ask_end":
+      return settleAsk(summary, event, at);
+    case "agent_exit":
+      return withAgent(summary, event.agent, exitAgent(summary.agents[event.agent], event, at));
+    case "run_end":
+      return endRun(summary, event, at);
+    default:
+      return summary;
+  }
+}
+
+function endRun(
+  summary: RunSummary,
+  event: Extract<LifecycleEventBody, { readonly type: "run_end" }>,
+  at: number | null,
+): RunSummary {
+  if (
+    summary.runState === "ended" &&
+    at !== null &&
+    summary.endedAt !== null &&
+    at < summary.endedAt
+  ) {
+    return summary;
+  }
+  return {
+    ...summary,
+    runState: "ended",
+    outcome: event.outcome,
+    ok: event.ok,
+    endedAt: at,
+    durationMs: event.durationMs,
+    worstFrameGapMs: event.worstFrameGapMs,
+  };
+}
+
+function updateActivity(
+  summary: RunSummary,
+  event: Extract<LifecycleEventBody, { readonly type: "ask_activity" }>,
+  at: number | null,
+): RunSummary {
+  const current = summary.agents[event.agent];
+  if (current === undefined) return summary;
+  const agent = setActivity(current, event.index, event.activity, at);
+  return current === agent
+    ? summary
+    : { ...summary, agents: { ...summary.agents, [event.agent]: agent } };
+}
+
+function updateNodes(
+  summary: RunSummary,
+  event: Extract<LifecycleEventBody, { readonly type: "node_update" }>,
+  at: number | null,
+): RunSummary {
+  const current = summary.agents[event.agent];
+  if (current === undefined) return summary;
+  const agent = applyNodeUpdate(current, event, at);
+  return current === agent
+    ? summary
+    : { ...summary, agents: { ...summary.agents, [event.agent]: agent } };
+}
+
+function settleAsk(
+  summary: RunSummary,
+  event: Extract<LifecycleEventBody, { readonly type: "ask_end" }>,
+  at: number | null,
+): RunSummary {
+  const next = withAgent(
+    { ...summary, asksSettled: summary.asksSettled + 1 },
+    event.agent,
+    endAsk(summary.agents[event.agent], event.index, at),
+  );
+  return {
+    ...next,
+    worstFrameGapMs:
+      event.maxFrameGapMs === undefined
+        ? next.worstFrameGapMs
+        : Math.max(next.worstFrameGapMs, event.maxFrameGapMs),
+  };
+}
+
+function withAgent(summary: RunSummary, name: string, agent: AgentRecord): RunSummary {
+  const agents = { ...summary.agents, [name]: agent };
+  const totals = totalsFromAgents(agents);
+  return { ...summary, agents, ...totals };
+}

package/src/tool-probe-extension.ts

@@ -0,0 +1,17 @@
+interface ToolProbeAPI {
+  getActiveTools(): string[];
+  on(event: "session_start", handler: (event: unknown, context: ToolProbeContext) => void): void;
+}
+
+interface ToolProbeContext {
+  readonly ui: { setStatus(key: string, text: string | undefined): void };
+}
+
+const STATUS_KEY = "yaag.tool-probe.v1";
+
+/** Reports pi's post-composition active tool names through the RPC UI channel. */
+export default function (pi: ToolProbeAPI): void {
+  pi.on("session_start", (_event, ctx) => {
+    ctx.ui.setStatus(STATUS_KEY, JSON.stringify(pi.getActiveTools()));
+  });
+}