paseo-bm-plugin 0.0.0-placeholder.0

package/server/format-check.ts

@@ -0,0 +1,352 @@
+/**
+ * `BM-FORMAT`: the sender of a block that breaks its template is told, and
+ * asked to send the whole corrected block again (delta 20260918g §4.7,
+ * REQ-061 f, owner decisions Q2 a and Q8 a).
+ *
+ * Only timeline shapes verified on a real daemon are read: a `user_message`
+ * with no `clientMessageId` is another agent's message, and an
+ * `assistant_message` is the agent's own. The raw shape of a
+ * `send_agent_prompt` tool call is not verified, so a block is checked where it
+ * ARRIVES, at the turn end of the side that received it:
+ *
+ * | Block                      | Checked at the turn end of | Sender (told)                     |
+ * |----------------------------|----------------------------|-----------------------------------|
+ * | BM-REPORT (+ BM-QUESTIONS) | the Manager                | the one Worker with that request  |
+ * | BM-ANSWERS                 | the Worker                 | its parent, when it is a Manager  |
+ * | BM-REVIEW                  | the Reviewer (its own)     | the Reviewer itself               |
+ *
+ * Rules this module must never lose:
+ * - **Never into a running turn.** `send()` on a running agent replaces its
+ *   turn (review-budget.ts); a sender that is running or initializing is left
+ *   for a later turn end. An archived or closed sender is never sent to:
+ *   `send()` would un-archive it (ADR-005).
+ * - **Only the latest block.** Each turn end of the checking side replaces the
+ *   pending notice with the verdict on the newest block it received (a valid
+ *   one clears it). At the SENDER's own turn end the checking side may not
+ *   have seen the sender's newest block yet, so there the notice goes only if
+ *   the checking side has received nothing since the block was checked (its
+ *   `lastUserMessageAt` still equals the mark); otherwise it waits for the
+ *   checking side's next turn end, which decides (design §4.7 errata).
+ * - **A later chance always comes for reports and reviews.** A pending notice is
+ *   looked at again at the next turn end of (1) the checking side, (2) the
+ *   receiving side — the Manager for reports, the Worker for answers, the
+ *   Reviewer's parent Worker for reviews — and (3) the sender itself. The
+ *   Manager is woken after every Worker turn and a Worker when its Reviewer
+ *   finishes (both `notifyOnFinish` by default). Answers have no such
+ *   guarantee: that notice may never go, and the card chip still shows.
+ * - **Bounded.** One notice per distinct block, at most `MAX_NOTICES` per
+ *   sender, request and kind. State lives in memory; a reload starts afresh
+ *   and never re-reads old blocks.
+ *
+ * Nothing here throws into an agent's turn end: a failure costs one log line.
+ */
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { checkBlocks, issueText, type BlockKind, type CheckedBlock } from "../shared/bm-format";
+import { roleOfProvider, type BmRole } from "./agent-role";
+import { sliceLastTurn } from "./collector";
+import { bmAgentsOf, requireLocation, type DashboardPaseo } from "./dashboard-rpc";
+import { FORMAT_NOTICE_MARKER, isPluginNotice } from "./notices";
+import { readRecords } from "./trace-store";
+import { requestIdOfAgent, type AgentFacts } from "./traces";
+
+/** Notices per sender, request and kind (owner decision Q8 a). */
+export const MAX_NOTICES = 2;
+/** Re-reads of a sender that still reads `running` at its own turn end, and the pause between them. */
+export const OWN_TURN_REREADS = 5;
+export const OWN_TURN_REREAD_MS = 1000;
+
+export interface FormatAgentSnapshot {
+  status?: string | null;
+  archivedAt?: string | null;
+  lastUserMessageAt?: string | null;
+}
+
+/** The SDK slice this module uses; `PaseoApi` is structurally close enough to be cast. */
+export interface FormatPaseo extends Omit<DashboardPaseo, "agents"> {
+  agents: Omit<DashboardPaseo["agents"], "ref"> & {
+    ref(agentId: string): {
+      refresh(): Promise<{ agent?: FormatAgentSnapshot | null } | null>;
+      send(text: string): Promise<void>;
+    };
+  };
+}
+
+/** What the hook hands over; the timeline is the whole conversation. */
+export interface FormatTurnEvent {
+  agent: { id: string; workspaceId: string | null; parentAgentId: string | null; provider: string };
+  turnId?: string | null;
+  timeline: readonly unknown[];
+}
+
+interface Pending {
+  key: string;
+  kind: BlockKind;
+  requestId: string | null;
+  senderId: string;
+  senderRole: BmRole;
+  /** The side that checked the block: its turn end, and its `lastUserMessageAt` mark. */
+  checkerId: string;
+  mark: string | null;
+  /** The receiving side's agent (Manager / Worker / the Reviewer's parent Worker). */
+  receiverId: string | null;
+  issues: string[];
+  hash: string;
+}
+
+export interface FormatState {
+  pending: Map<string, Pending>;
+  /** Notices sent per `sender|requestId|kind`. */
+  sent: Map<string, number>;
+  /** Hashes of blocks already notified. */
+  notifiedBlocks: Set<string>;
+  /** Keys being sent right now, so two turn ends never send one notice twice. */
+  sending: Set<string>;
+}
+
+export function createFormatState(): FormatState {
+  return { pending: new Map(), sent: new Map(), notifiedBlocks: new Set(), sending: new Set() };
+}
+
+export interface FormatDeps {
+  paseo: FormatPaseo;
+  state: FormatState;
+  log?: (message: string) => void;
+  /** Pause between own-turn re-reads; tests pass an instant one. */
+  sleep?: (ms: number) => Promise<void>;
+  homedir?: () => string;
+}
+
+export type FormatOutcome = "ignored" | "checked";
+
+/** The notice, word for word from design §4.7. */
+export function formatNotice(kind: BlockKind, requestId: string | null, issues: readonly string[]): string {
+  const last =
+    kind === "BM-REVIEW"
+      ? "Answer with the whole corrected BM-REVIEW block as your final message; do not review again."
+      : "Send the whole corrected block again, to the same agent as before, in one message. Change nothing else and do not redo any work; then carry on exactly where you were.";
+  return [
+    `${FORMAT_NOTICE_MARKER} requestId: ${requestId ?? "unknown"}`,
+    `Your last ${kind} broke the template:`,
+    ...issues.map((issue) => `- ${issue}`),
+    last,
+  ].join("\n");
+}
+
+/** djb2, enough to tell two blocks apart. */
+function hashOf(text: string): string {
+  let hash = 5381;
+  for (let index = 0; index < text.length; index += 1) hash = ((hash << 5) + hash + text.charCodeAt(index)) | 0;
+  return (hash >>> 0).toString(36);
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+interface TimelineText {
+  type: string;
+  text: string;
+  clientMessageId?: unknown;
+}
+
+function textItem(item: unknown): TimelineText | null {
+  if (item === null || typeof item !== "object") return null;
+  const { type, text } = item as { type?: unknown; text?: unknown };
+  if ((type !== "user_message" && type !== "assistant_message") || typeof text !== "string") return null;
+  return item as TimelineText;
+}
+
+/** The blocks of one message grouped as the sender sent them: a report with its questions is one unit. */
+function unitsOf(blocks: readonly CheckedBlock[]): Array<{ kind: BlockKind; requestId: string | null; issues: string[]; text: string }> {
+  const units: Array<{ kind: BlockKind; requestId: string | null; issues: string[]; text: string }> = [];
+  for (const block of blocks) {
+    const previous = units.at(-1);
+    if (block.kind === "BM-QUESTIONS" && previous?.kind === "BM-REPORT") {
+      previous.issues.push(...block.issues.map(issueText));
+      previous.text += `\n\n${block.text}`;
+      continue;
+    }
+    units.push({ kind: block.kind, requestId: block.requestId, issues: block.issues.map(issueText), text: block.text });
+  }
+  return units;
+}
+
+async function snapshotOf(paseo: FormatPaseo, agentId: string): Promise<FormatAgentSnapshot | null> {
+  const result = await paseo.agents.ref(agentId).refresh();
+  return result?.agent ?? null;
+}
+
+/** `bmAgentsOf` reads only `agents.list`; hand it exactly that. */
+function directoryOf(paseo: FormatPaseo): DashboardPaseo {
+  return { agents: { list: (options) => paseo.agents.list(options) }, workspaces: paseo.workspaces, config: paseo.config };
+}
+
+/** The Worker of the workspace that owns `requestId`, when exactly one does. */
+async function workerOf(deps: FormatDeps, workspaceId: string, requestId: string | null): Promise<AgentFacts | null> {
+  if (requestId === null) return null;
+  const directory = directoryOf(deps.paseo);
+  const workers = (await bmAgentsOf(directory)).filter((entry) => entry.workspaceId === workspaceId && entry.facts.role === "worker");
+  let records: Parameters<typeof requestIdOfAgent>[1] = [];
+  try {
+    records = readRecords(await requireLocation(directory, { homedir: deps.homedir }), workspaceId).records;
+  } catch {
+    // Without a trace store only the labels are known.
+  }
+  const matches = workers.filter(({ facts }) => (facts.requestIdLabel ?? requestIdOfAgent(facts, records).requestId) === requestId);
+  return matches.length === 1 ? matches[0]!.facts : null;
+}
+
+async function factsOfAgent(deps: FormatDeps, agentId: string | null): Promise<AgentFacts | null> {
+  if (agentId === null) return null;
+  return (await bmAgentsOf(directoryOf(deps.paseo))).find((entry) => entry.facts.id === agentId)?.facts ?? null;
+}
+
+/** Records the latest block of each sender/request/kind seen in this turn. */
+async function detect(event: FormatTurnEvent, role: BmRole, deps: FormatDeps, log: (message: string) => void): Promise<void> {
+  const items = sliceLastTurn(Array.isArray(event.timeline) ? event.timeline : [])
+    .map(textItem)
+    .filter((item): item is TimelineText => item !== null);
+  const wanted: BlockKind = role === "manager" ? "BM-REPORT" : role === "worker" ? "BM-ANSWERS" : "BM-REVIEW";
+  // Received from another agent (no clientMessageId, not the plugin's own notice) — or, for a Reviewer, its own words.
+  const sources = items.filter((item) =>
+    role === "reviewer"
+      ? item.type === "assistant_message"
+      : item.type === "user_message" && typeof item.clientMessageId !== "string" && !isPluginNotice(item.text),
+  );
+  const latest = new Map<string, { kind: BlockKind; requestId: string | null; issues: string[]; text: string }>();
+  for (const item of sources) {
+    for (const unit of unitsOf(checkBlocks(item.text))) {
+      if (unit.kind !== wanted) continue;
+      latest.set(`${unit.kind}|${unit.requestId ?? "?"}`, unit);
+    }
+  }
+  if (latest.size === 0) return;
+
+  let mark: string | null = null;
+  let markRead = false;
+  for (const unit of latest.values()) {
+    let sender: { id: string; role: BmRole } | null;
+    let receiverId: string | null;
+    if (role === "manager") {
+      const worker = event.agent.workspaceId === null ? null : await workerOf(deps, event.agent.workspaceId, unit.requestId);
+      sender = worker === null ? null : { id: worker.id, role: "worker" };
+      receiverId = event.agent.id;
+    } else if (role === "worker") {
+      const parent = await factsOfAgent(deps, event.agent.parentAgentId);
+      sender = parent?.role === "manager" ? { id: parent.id, role: "manager" } : null;
+      receiverId = event.agent.id;
+    } else {
+      sender = { id: event.agent.id, role: "reviewer" };
+      receiverId = event.agent.parentAgentId;
+    }
+    if (sender === null) {
+      if (unit.issues.length > 0) log(`[paseo-bm] a ${unit.kind} for ${unit.requestId ?? "an unknown request"} breaks the template, but its sender is not known; no BM-FORMAT sent.`);
+      continue;
+    }
+    const key = `${sender.id}|${unit.requestId ?? "?"}|${unit.kind}`;
+    if (unit.issues.length === 0) {
+      deps.state.pending.delete(key);
+      continue;
+    }
+    const hash = hashOf(unit.text);
+    if (deps.state.notifiedBlocks.has(hash)) continue;
+    if (!markRead) {
+      mark = (await snapshotOf(deps.paseo, event.agent.id))?.lastUserMessageAt ?? null;
+      markRead = true;
+    }
+    deps.state.pending.set(key, {
+      key,
+      kind: unit.kind,
+      requestId: unit.requestId,
+      senderId: sender.id,
+      senderRole: sender.role,
+      checkerId: event.agent.id,
+      mark,
+      receiverId,
+      issues: unit.issues,
+      hash,
+    });
+  }
+}
+
+/** Tries every pending notice this turn end is a chance for. */
+async function flush(endedId: string, deps: FormatDeps, log: (message: string) => void): Promise<void> {
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const chances = [...deps.state.pending.values()].filter(
+    (entry) => entry.checkerId === endedId || entry.receiverId === endedId || entry.senderId === endedId,
+  );
+  for (const entry of chances) {
+    if (deps.state.sending.has(entry.key)) continue;
+    deps.state.sending.add(entry.key);
+    try {
+      const counted = `${entry.senderId}|${entry.requestId ?? "?"}|${entry.kind}`;
+      if ((deps.state.sent.get(counted) ?? 0) >= MAX_NOTICES) {
+        deps.state.pending.delete(entry.key);
+        log(`[paseo-bm] ${entry.kind} from ${entry.senderId} still breaks the template after ${MAX_NOTICES} notices; not asking again.`);
+        continue;
+      }
+      const atSenderOnly = endedId === entry.senderId && endedId !== entry.checkerId && endedId !== entry.receiverId;
+      if (atSenderOnly) {
+        // The sender may have just sent a newer block the checking side has not
+        // read yet: wait for the checking side's next turn end to decide.
+        const checker = await snapshotOf(deps.paseo, entry.checkerId);
+        if ((checker?.lastUserMessageAt ?? null) !== entry.mark) continue;
+      }
+      let sender = await snapshotOf(deps.paseo, entry.senderId);
+      if (entry.senderId === endedId) {
+        for (let reread = 0; reread < OWN_TURN_REREADS && isBusy(sender); reread += 1) {
+          await sleep(OWN_TURN_REREAD_MS);
+          sender = await snapshotOf(deps.paseo, entry.senderId);
+        }
+      }
+      if (sender === null || sender.archivedAt != null || sender.status === "closed") {
+        deps.state.pending.delete(entry.key);
+        log(`[paseo-bm] ${entry.senderId} is archived, closed or gone; the BM-FORMAT notice was not sent.`);
+        continue;
+      }
+      if (isBusy(sender)) continue;
+      await deps.paseo.agents.ref(entry.senderId).send(formatNotice(entry.kind, entry.requestId, entry.issues));
+      deps.state.pending.delete(entry.key);
+      deps.state.sent.set(counted, (deps.state.sent.get(counted) ?? 0) + 1);
+      deps.state.notifiedBlocks.add(entry.hash);
+    } catch (error) {
+      log(`[paseo-bm] could not send BM-FORMAT to ${entry.senderId}: ${describeError(error)}; trying again at a later turn end.`);
+    } finally {
+      deps.state.sending.delete(entry.key);
+    }
+  }
+}
+
+function isBusy(snapshot: FormatAgentSnapshot | null): boolean {
+  return snapshot?.status === "running" || snapshot?.status === "initializing";
+}
+
+/** Handler body of `on("agent.turn_ended")`. Never throws. */
+export async function checkTurnFormat(event: FormatTurnEvent, deps: FormatDeps): Promise<FormatOutcome> {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  try {
+    const role = roleOfProvider(event?.agent?.provider);
+    if (role === null) return "ignored";
+    try {
+      await detect(event, role, deps, log);
+    } catch (error) {
+      log(`[paseo-bm] checking the BM blocks of ${event.agent.id} failed: ${describeError(error)}`);
+    }
+    await flush(event.agent.id, deps, log);
+    return "checked";
+  } catch (error) {
+    log(`[paseo-bm] the BM-FORMAT check failed: ${describeError(error)}`);
+    return "ignored";
+  }
+}
+
+export type FormatHost = Partial<Pick<PluginServerContext, "on">>;
+
+/** Registers the check on `agent.turn_ended`; a no-op on a host without `on`. */
+export function registerFormatCheck(host: FormatHost, state: FormatState = createFormatState()): () => void {
+  if (typeof host.on !== "function") return () => {};
+  const remove = host.on("agent.turn_ended", async (event, context) => {
+    await checkTurnFormat(event as unknown as FormatTurnEvent, { paseo: context.paseo as unknown as FormatPaseo, state });
+  });
+  return typeof remove === "function" ? remove : () => {};
+}

package/server/install-home.ts

@@ -0,0 +1,187 @@
+/**
+ * Where the trace store lives (WP-202, Dashboard Design §3.1).
+ *
+ * The server bundle cannot work this out by itself: Paseo 0.8 compiles
+ * `index.server.ts` into a CommonJS bundle and forks a worker with no cwd, and
+ * the module-URL global is empty there (errata bm-dnc), which is why the payload
+ * guard in test/plugin-bundle-cjs.test.ts forbids naming it at all. The authority is therefore
+ * the path Paseo itself recorded when the plugin was installed:
+ * `config.plugins["paseo-bm"] = { source: "directory", path }`, where `path` is
+ * `<install home>/plugin/<version>`. Two levels up is the install home, so a
+ * user who installed with `--home` or `PASEO_BM_HOME` is handled with no extra
+ * configuration.
+ *
+ * Read-only by construction: this module reads `install.json` to confirm it
+ * found the right directory and never writes anything. When it cannot be sure,
+ * it returns a reason instead of throwing — tracing then stays off and the rest
+ * of the Dashboard (bead statistics) keeps working.
+ *
+ * SDK facts this relies on (checked against @getpaseo/protocol 0.8.0
+ * `MutableDaemonConfigSchema`, not guessed):
+ * - `config.plugins` is `Record<string, { source: "directory"; path: string; enabled?: boolean }>`.
+ */
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+/** Plugin id the installer registers with Paseo (design §3.2 `paseo.pluginId`). */
+export const PLUGIN_ID = "paseo-bm";
+
+/** Directory of the trace store inside the install home (design §3.2). */
+export const TRACES_DIR_NAME = "traces";
+
+/**
+ * Directory inside the install home for UI state that is not trace data
+ * (`answer-marks.json`). The pin order an earlier version kept here is no
+ * longer read, and is left alone (delta 20260918f §4.5).
+ */
+export const UI_DIR_NAME = "ui";
+
+/** Highest `install.json` schema version this code understands (design §3.2). */
+export const SUPPORTED_RECORD_SCHEMA_VERSION = 1;
+
+/** Minimal SDK view this module needs. `PaseoApi` is structurally assignable to it. */
+export interface InstallHomePaseo {
+  config: {
+    get(): Promise<{
+      config: {
+        plugins?: Record<string, unknown>;
+      };
+    }>;
+  };
+}
+
+/** The bits of `node:fs` this module needs, injectable so tests need no real home. */
+export interface InstallHomeFs {
+  readFileSync(path: string, encoding: "utf8"): string;
+}
+
+export interface ResolveInstallHomeDeps {
+  paseo: InstallHomePaseo;
+  fs: InstallHomeFs;
+  /** `os.homedir()`; injected so the fallback is testable. */
+  homedir: () => string;
+}
+
+/**
+ * Either the install home, or the readable reason tracing is off.
+ *
+ * `source` records how it was found, which is what a support question ("why is
+ * my history empty?") actually needs.
+ */
+export type InstallHomeResolution =
+  | { home: string; tracesDir: string; source: "plugin-path" | "default-home" }
+  | { home: null; tracesDir: null; reason: string };
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** `<install home>/plugin/<version>` → `<install home>`, or null when the shape is wrong. */
+export function installHomeFromPluginPath(pluginPath: string): string | null {
+  if (typeof pluginPath !== "string" || pluginPath.trim() === "" || !isAbsolute(pluginPath)) return null;
+  const versionDir = resolve(pluginPath);
+  const pluginDir = dirname(versionDir);
+  const home = dirname(pluginDir);
+  // Guard against a path so short that dirname() starts returning the same root.
+  if (home === pluginDir || pluginDir === versionDir) return null;
+  return home;
+}
+
+/**
+ * True when `<home>/install.json` is readable, is JSON, and carries a
+ * `schemaVersion` this build understands.
+ *
+ * A newer profile means a newer paseo-bm wrote it; this build must not assume
+ * it understands that directory, so it reports "not confirmed" rather than
+ * using it (same posture as `E_RECORD_SCHEMA_TOO_NEW` in the CLI).
+ */
+export function confirmInstallHome(
+  home: string,
+  fs: InstallHomeFs,
+): { ok: true } | { ok: false; reason: string } {
+  const recordPath = join(home, "install.json");
+  let raw: string;
+  try {
+    raw = fs.readFileSync(recordPath, "utf8");
+  } catch {
+    return { ok: false, reason: `no readable install.json at ${recordPath}` };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: `install.json at ${recordPath} is not valid JSON` };
+  }
+  const version = asRecord(parsed)?.["schemaVersion"];
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    return { ok: false, reason: `install.json at ${recordPath} has no usable schemaVersion` };
+  }
+  if (version > SUPPORTED_RECORD_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      reason: `install.json at ${recordPath} has schemaVersion ${version}, newer than this plugin understands (${SUPPORTED_RECORD_SCHEMA_VERSION})`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Resolves the install home in the three steps of design §3.1, and never throws.
+ *
+ * 1. the directory Paseo registered for this plugin, two levels up;
+ * 2. confirmed by a readable `install.json`;
+ * 3. otherwise `~/.paseo-bm`, confirmed the same way.
+ *
+ * Anything else returns `{ home: null, reason }` so the caller can disable
+ * tracing with a message a person can act on.
+ */
+export async function resolveInstallHome(
+  deps: ResolveInstallHomeDeps,
+): Promise<InstallHomeResolution> {
+  const disabled = (reason: string): InstallHomeResolution => ({ home: null, tracesDir: null, reason });
+
+  let plugins: Record<string, unknown> | undefined;
+  try {
+    const { config } = await deps.paseo.config.get();
+    plugins = asRecord(config?.plugins);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return disabled(`could not read the Paseo configuration: ${message}`);
+  }
+
+  const entry = asRecord(plugins?.[PLUGIN_ID]);
+  const registeredPath = typeof entry?.["path"] === "string" ? (entry["path"] as string) : null;
+
+  if (registeredPath !== null) {
+    const home = installHomeFromPluginPath(registeredPath);
+    if (home === null) {
+      return disabled(`the registered plugin path is not a usable directory: ${registeredPath}`);
+    }
+    const confirmed = confirmInstallHome(home, deps.fs);
+    if (confirmed.ok) {
+      return { home, tracesDir: join(home, TRACES_DIR_NAME), source: "plugin-path" };
+    }
+    // Fall through to the default home: a directory plugin can be registered
+    // from somewhere that is not an install home at all (a developer checkout),
+    // and the default home may still hold a real installation.
+    const fallback = join(deps.homedir(), ".paseo-bm");
+    if (fallback !== home) {
+      const fallbackConfirmed = confirmInstallHome(fallback, deps.fs);
+      if (fallbackConfirmed.ok) {
+        return { home: fallback, tracesDir: join(fallback, TRACES_DIR_NAME), source: "default-home" };
+      }
+      return disabled(`${confirmed.reason}; ${fallbackConfirmed.reason}`);
+    }
+    return disabled(confirmed.reason);
+  }
+
+  const fallback = join(deps.homedir(), ".paseo-bm");
+  const fallbackConfirmed = confirmInstallHome(fallback, deps.fs);
+  if (fallbackConfirmed.ok) {
+    return { home: fallback, tracesDir: join(fallback, TRACES_DIR_NAME), source: "default-home" };
+  }
+  return disabled(
+    `Paseo has no directory plugin registered as "${PLUGIN_ID}"; ${fallbackConfirmed.reason}`,
+  );
+}

package/server/live-timeline.ts

@@ -0,0 +1,129 @@
+/**
+ * Skills and user messages read live from an agent's timeline, when a trace
+ * is opened.
+ *
+ * The collector records both from the turn it was installed on. Everything an
+ * agent did before that is still in Paseo's own timeline for as long as the
+ * agent exists, so opening a trace fills the gap from there instead of making
+ * the user wait for new turns.
+ *
+ * Only Workers and Reviewers are read: each belongs to one request, so its
+ * whole timeline is that request's. A Manager serves every request of the
+ * workspace, and nothing in its timeline says which request a message was
+ * about.
+ *
+ * Verified on Paseo 0.8: `timeline.refetch({ direction: "tail" })` returns the
+ * newest page and `startCursor`; `direction: "before"` with that cursor pages
+ * back. Real agents needed 2–5 pages of 200 and under 200 ms.
+ */
+import { redactText, skillsFromItem } from "./collector";
+import { isPluginNotice } from "./notices";
+import { MAX_MESSAGE_CHARS, TRUNCATION_MARKER } from "./trace-store";
+import type { TraceMessage } from "../shared/contracts";
+import { byAt, uniqueBy } from "../shared/order";
+
+/** A long-lived agent is read at most this far back. */
+export const LIVE_PAGE_LIMIT = 200;
+export const LIVE_MAX_PAGES = 25;
+
+export interface LiveTimelinePaseo {
+  agents: {
+    ref?(agentId: string): {
+      timeline: { refetch(options: Record<string, unknown>): Promise<unknown> };
+    };
+  };
+}
+
+export interface LiveExtras {
+  skills: Array<{ agentId: string; skill: string; at: string | null }>;
+  userMessages: TraceMessage[];
+}
+
+interface Page {
+  entries?: Array<{ item?: unknown; timestamp?: unknown }>;
+  hasOlder?: unknown;
+  startCursor?: unknown;
+}
+
+function capped(text: string): { text: string; truncated: boolean } {
+  if (text.length <= MAX_MESSAGE_CHARS) return { text, truncated: false };
+  return { text: `${text.slice(0, MAX_MESSAGE_CHARS - TRUNCATION_MARKER.length)}${TRUNCATION_MARKER}`, truncated: true };
+}
+
+/**
+ * Reads an agent's timeline newest page first, back at most `pages` pages,
+ * handing each page's entries (oldest first, as Paseo returns them) to
+ * `visit`. Returns how many entries were read. Never throws: an agent that
+ * cannot be read simply yields nothing.
+ */
+export async function readTimelinePages(
+  paseo: LiveTimelinePaseo,
+  agentId: string,
+  options: { pages: number; limit: number },
+  visit: (entries: NonNullable<Page["entries"]>) => void,
+): Promise<number> {
+  const ref = paseo.agents.ref?.(agentId);
+  if (ref === undefined) return 0;
+  let cursor: unknown;
+  let read = 0;
+  for (let page = 0; page < options.pages; page += 1) {
+    let payload: Page;
+    try {
+      payload = (await ref.timeline.refetch(
+        cursor === undefined
+          ? { direction: "tail", limit: options.limit }
+          : { direction: "before", cursor, limit: options.limit },
+      )) as Page;
+    } catch {
+      return read;
+    }
+    const entries = payload.entries ?? [];
+    read += entries.length;
+    visit(entries);
+    if (payload.hasOlder !== true || payload.startCursor === undefined || payload.startCursor === null) return read;
+    cursor = payload.startCursor;
+  }
+  return read;
+}
+
+/** Skills and typed user messages of one agent's timeline, back to the start (bounded). */
+async function readAgent(paseo: LiveTimelinePaseo, agentId: string, out: LiveExtras, env: NodeJS.ProcessEnv): Promise<void> {
+  await readTimelinePages(paseo, agentId, { pages: LIVE_MAX_PAGES, limit: LIVE_PAGE_LIMIT }, (entries) => {
+    for (const entry of entries) {
+      const item = entry.item as { type?: unknown; text?: unknown; clientMessageId?: unknown } | undefined;
+      if (item === undefined || item === null) continue;
+      const at = typeof entry.timestamp === "string" ? entry.timestamp : null;
+      for (const skill of skillsFromItem(item as never)) out.skills.push({ agentId, skill, at });
+      if (
+        item.type === "user_message" &&
+        typeof item.clientMessageId === "string" &&
+        typeof item.text === "string" &&
+        !isPluginNotice(item.text)
+      ) {
+        const { text, truncated } = capped(redactText(item.text, env));
+        out.userMessages.push({ agentId, at: at ?? "", text, truncated, origin: "user" });
+      }
+    }
+  });
+}
+
+export async function readLiveExtras(
+  paseo: LiveTimelinePaseo,
+  agentIds: readonly string[],
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<LiveExtras> {
+  const out: LiveExtras = { skills: [], userMessages: [] };
+  await Promise.all(agentIds.map((agentId) => readAgent(paseo, agentId, out, env)));
+  return out;
+}
+
+/** Recorded and live entries together, once each, oldest first. */
+export function mergeExtras(recorded: LiveExtras, live: LiveExtras): LiveExtras {
+  return {
+    skills: uniqueBy([...recorded.skills, ...live.skills].sort(byAt), (entry) => `${entry.agentId}|${entry.skill}`),
+    userMessages: uniqueBy(
+      [...recorded.userMessages, ...live.userMessages].sort(byAt),
+      (message) => `${message.agentId}|${message.text}`,
+    ),
+  };
+}