sentinelayer-cli 0.6.2 → 0.8.1

package/src/agents/documentation/tools/base.js

@@ -0,0 +1,151 @@
+// Shared helpers for Samir's (documentation) domain tools (#A23).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import ignore from "ignore";
+
+const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".venv",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".sentinelayer",
+  ".sentinel",
+  ".turbo",
+  ".idea",
+  ".vscode",
+  "__pycache__",
+  ".cache",
+]);
+const MAX_FILE_SIZE_BYTES = 1024 * 1024;
+const SEVERITIES = Object.freeze(["P0", "P1", "P2", "P3"]);
+
+export function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+export function createFinding({
+  severity,
+  kind,
+  file,
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = null,
+  tool = "",
+  persona = "documentation",
+} = {}) {
+  const normalizedSeverity = SEVERITIES.includes(String(severity || "").toUpperCase())
+    ? String(severity).toUpperCase()
+    : "P3";
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "documentation",
+    severity: normalizedSeverity,
+    file: toPosix(file || ""),
+    line: Number.isFinite(Number(line)) ? Math.max(0, Math.floor(Number(line))) : 0,
+    evidence: String(evidence || "").trim().slice(0, 400),
+    rootCause: String(rootCause || "").trim(),
+    recommendedFix: String(recommendedFix || "").trim(),
+    confidence:
+      confidence === null || confidence === undefined
+        ? null
+        : Math.max(0, Math.min(1, Number(confidence) || 0)),
+  };
+}
+
+async function readIgnorePatterns(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    return String(raw || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+async function createIgnoreMatcher(rootPath) {
+  const matcher = ignore();
+  const gitignore = await readIgnorePatterns(path.join(rootPath, ".gitignore"));
+  const sentinel = await readIgnorePatterns(
+    path.join(rootPath, ".sentinelayerignore")
+  );
+  matcher.add([...gitignore, ...sentinel]);
+  return (relativePath, isDirectory) => {
+    const normalized = toPosix(relativePath);
+    if (!normalized) {
+      return false;
+    }
+    const candidate = isDirectory ? `${normalized}/` : normalized;
+    return matcher.ignores(candidate);
+  };
+}
+
+export async function* walkRepoFiles({
+  rootPath = process.cwd(),
+  extensions = new Set(),
+  maxFileSize = MAX_FILE_SIZE_BYTES,
+} = {}) {
+  const resolvedRoot = path.resolve(rootPath);
+  const ignoreMatcher = await createIgnoreMatcher(resolvedRoot);
+  const wantedExtensions =
+    extensions instanceof Set
+      ? extensions
+      : new Set(Array.isArray(extensions) ? extensions : []);
+  const stack = [resolvedRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relativePath = toPosix(path.relative(resolvedRoot, fullPath));
+      if (entry.isDirectory()) {
+        if (!relativePath || DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          continue;
+        }
+        if (ignoreMatcher(relativePath, true)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (ignoreMatcher(relativePath, false)) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (wantedExtensions.size > 0 && !wantedExtensions.has(ext) && !wantedExtensions.has("")) {
+        continue;
+      }
+      let stat = null;
+      try {
+        stat = await fsp.stat(fullPath);
+      } catch {
+        stat = null;
+      }
+      if (!stat || stat.size > maxFileSize) {
+        continue;
+      }
+      yield { fullPath, relativePath, stat };
+    }
+  }
+}

package/src/agents/documentation/tools/dead-link-check.js

@@ -0,0 +1,58 @@
+// dead-link-check — find markdown relative links that point at non-existent files (#A23).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const LINK_REGEX = /\[[^\]]*\]\(([^)\s]+)\)/g;
+
+export async function runDeadLinkCheck({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const findings = [];
+  for await (const { fullPath, relativePath } of walkRepoFiles({
+    rootPath: resolvedRoot,
+    extensions: new Set([".md"]),
+  })) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const rel = toPosix(relativePath);
+    const dir = path.posix.dirname(rel);
+    let m;
+    while ((m = LINK_REGEX.exec(content)) !== null) {
+      const target = m[1].split("#")[0];
+      if (!target || /^https?:/i.test(target) || target.startsWith("mailto:")) continue;
+      const normalizedTarget = target.replace(/\?.*$/, "");
+      const resolvedTarget = path.posix.normalize(`${dir}/${normalizedTarget}`);
+      const absolute = path.join(resolvedRoot, resolvedTarget);
+      let exists = false;
+      try {
+        await fsp.stat(absolute);
+        exists = true;
+      } catch {
+        exists = false;
+      }
+      if (!exists) {
+        const lineIndex = content.slice(0, m.index).split(/\r?\n/).length;
+        findings.push(
+          createFinding({
+            tool: "dead-link-check",
+            kind: "documentation.dead-link",
+            severity: "P3",
+            file: rel,
+            line: lineIndex,
+            evidence: `${m[0]} → ${resolvedTarget} does not exist`,
+            rootCause: "Broken markdown link — readers follow it to a 404 and lose trust in the docs.",
+            recommendedFix: "Update the link to the new path, or delete the reference if the target was intentionally removed.",
+            confidence: 0.85,
+          })
+        );
+      }
+    }
+  }
+  return findings;
+}

package/src/agents/documentation/tools/docstring-coverage.js

@@ -0,0 +1,78 @@
+// docstring-coverage — find exported functions without a preceding comment (#A23).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "@babel/parser";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const JS_EXTS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
+
+function hasLeadingComment(node) {
+  return Array.isArray(node.leadingComments) && node.leadingComments.length > 0;
+}
+
+export async function runDocstringCoverage({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: JS_EXTS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    const rel = toPosix(relativePath);
+    if (/(^|\/)(tests?|__tests__|specs?)\//.test(rel)) continue;
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let ast;
+    try {
+      ast = parse(content, {
+        sourceType: "unambiguous",
+        errorRecovery: true,
+        plugins:
+          rel.endsWith(".ts") || rel.endsWith(".tsx") ? ["typescript", "jsx"] : ["jsx"],
+      });
+    } catch {
+      continue;
+    }
+    for (const stmt of ast.program.body) {
+      if (
+        stmt.type === "ExportNamedDeclaration" &&
+        stmt.declaration?.type === "FunctionDeclaration"
+      ) {
+        const fn = stmt.declaration;
+        if (hasLeadingComment(stmt) || hasLeadingComment(fn)) continue;
+        findings.push(
+          createFinding({
+            tool: "docstring-coverage",
+            kind: "documentation.undocumented-export",
+            severity: "P3",
+            file: rel,
+            line: fn.loc?.start?.line || 0,
+            evidence: `export function ${fn.id?.name || "<anonymous>"} has no leading comment`,
+            rootCause: "Public exports ship without explanation. Consumers reverse-engineer expected behavior from implementation.",
+            recommendedFix: "Add a JSDoc block describing parameters, return value, and any non-obvious preconditions.",
+            confidence: 0.4,
+          })
+        );
+      }
+    }
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) continue;
+    const fullPath = path.isAbsolute(trimmed) ? trimmed : path.join(resolvedRoot, trimmed);
+    const relativePath = path.relative(resolvedRoot, fullPath).replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}

package/src/agents/documentation/tools/index.js

@@ -0,0 +1,52 @@
+// Samir (documentation persona) domain-tool registry (#A23).
+
+import { runApiDiff } from "./api-diff.js";
+import { runDeadLinkCheck } from "./dead-link-check.js";
+import { runDocstringCoverage } from "./docstring-coverage.js";
+import { runReadmeFreshness } from "./readme-freshness.js";
+
+export const DOCUMENTATION_TOOLS = Object.freeze({
+  "docstring-coverage": {
+    id: "docstring-coverage",
+    description: "Flag exported functions (JS/TS) without a leading comment / JSDoc block.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runDocstringCoverage,
+  },
+  "readme-freshness": {
+    id: "readme-freshness",
+    description: "Flag missing top-level README.md or README > 180 days older than the newest source file.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, staleDays: { type: "number" } } },
+    handler: runReadmeFreshness,
+  },
+  "api-diff": {
+    id: "api-diff",
+    description: "Detect HTTP endpoints in source and flag any that lack a matching entry in docs/, openapi*, swagger*, or API.md.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runApiDiff,
+  },
+  "dead-link-check": {
+    id: "dead-link-check",
+    description: "Scan markdown files for relative links whose target file doesn't exist.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runDeadLinkCheck,
+  },
+});
+
+export const DOCUMENTATION_TOOL_IDS = Object.freeze(Object.keys(DOCUMENTATION_TOOLS));
+
+export async function dispatchDocumentationTool(toolId, args = {}) {
+  const tool = DOCUMENTATION_TOOLS[toolId];
+  if (!tool) throw new Error(`Unknown documentation tool: ${toolId}`);
+  return tool.handler(args);
+}
+
+export async function runAllDocumentationTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of DOCUMENTATION_TOOL_IDS) {
+    const out = await dispatchDocumentationTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export { runApiDiff, runDeadLinkCheck, runDocstringCoverage, runReadmeFreshness };

package/src/agents/documentation/tools/readme-freshness.js

@@ -0,0 +1,61 @@
+// readme-freshness — flag stale READMEs (#A23).
+
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const STALE_DAYS = 180;
+
+export async function runReadmeFreshness({ rootPath, staleDays = STALE_DAYS } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const now = Date.now();
+  const threshold = now - staleDays * 24 * 60 * 60 * 1000;
+  const findings = [];
+  let codeMaxMtime = 0;
+  let readme = null;
+  for await (const { relativePath, stat } of walkRepoFiles({ rootPath: resolvedRoot })) {
+    const rel = toPosix(relativePath);
+    if (/(^|\/)README\.md$/i.test(rel) && !readme) {
+      readme = { rel, mtime: Number(stat?.mtimeMs || 0) };
+    }
+    if (/\.(js|jsx|ts|tsx|py|go|rb|mjs|cjs)$/i.test(rel)) {
+      codeMaxMtime = Math.max(codeMaxMtime, Number(stat?.mtimeMs || 0));
+    }
+  }
+  if (!readme) {
+    findings.push(
+      createFinding({
+        tool: "readme-freshness",
+        kind: "documentation.no-readme",
+        severity: "P2",
+        file: "",
+        line: 0,
+        evidence: "No top-level README.md",
+        rootCause: "A repo without a README has no entry point for new contributors.",
+        recommendedFix: "Add a README.md with: project purpose, quickstart, and how to contribute.",
+        confidence: 0.9,
+      })
+    );
+    return findings;
+  }
+  if (readme.mtime && readme.mtime < threshold && codeMaxMtime > readme.mtime) {
+    const ageDays = Math.floor((now - readme.mtime) / (24 * 60 * 60 * 1000));
+    const driftDays = Math.floor((codeMaxMtime - readme.mtime) / (24 * 60 * 60 * 1000));
+    findings.push(
+      createFinding({
+        tool: "readme-freshness",
+        kind: "documentation.stale-readme",
+        severity: "P3",
+        file: readme.rel,
+        line: 0,
+        evidence: `README last modified ${ageDays}d ago; newest code ${driftDays}d newer`,
+        rootCause: "README is falling behind the code. New contributors will be guided by outdated instructions.",
+        recommendedFix: "Review the quickstart + architecture sections and update anything that's moved.",
+        confidence: 0.45,
+      })
+    );
+  }
+  return findings;
+}
+
+export { STALE_DAYS };

package/src/agents/envelope/fix-cycle.js

@@ -0,0 +1,45 @@
+/**
+ * Iterative fix-cycle helper (#A8 envelope).
+ *
+ * Pattern: when the envelope loop reports stuckReason or remaining
+ * findings, a fix-cycle re-runs the loop with an amended prompt and a
+ * reduced toolset, bounded by maxCycles. Used by personas that want
+ * Jules-tier "try until green" behavior.
+ */
+
+import { runEnvelopeLoop } from "./loop.js";
+
+export const DEFAULT_MAX_CYCLES = 3;
+
+/**
+ * @param {object} params
+ * @param {Function} params.runCycle         — async ({ cycle }) => { findings, messages, stuckReason, ... }
+ * @param {Function} [params.isResolved]     — sync (result) => boolean; default: findings empty AND no stuckReason
+ * @param {number}   [params.maxCycles]
+ */
+export async function runFixCycle({
+  runCycle,
+  isResolved,
+  maxCycles = DEFAULT_MAX_CYCLES,
+} = {}) {
+  if (typeof runCycle !== "function") {
+    throw new TypeError("runFixCycle requires a runCycle function");
+  }
+  const checkResolved = typeof isResolved === "function"
+    ? isResolved
+    : (result) => Array.isArray(result?.findings) && result.findings.length === 0 && !result?.stuckReason;
+
+  const history = [];
+  for (let cycle = 1; cycle <= maxCycles; cycle += 1) {
+    const result = await runCycle({ cycle });
+    history.push(result);
+    if (checkResolved(result)) {
+      return { resolved: true, cyclesUsed: cycle, history };
+    }
+  }
+  return { resolved: false, cyclesUsed: maxCycles, history };
+}
+
+// Re-export runEnvelopeLoop so consumers can import the whole kit
+// from one module path in downstream PRs.
+export { runEnvelopeLoop };

package/src/agents/envelope/index.js

@@ -0,0 +1,31 @@
+/**
+ * Agent envelope foundation (#A8).
+ *
+ * Generic multi-turn agent envelope that all 12 non-Jules personas adopt to
+ * become "Jules-tier" — i.e., stateful agents with a turn loop, stuck
+ * detection, and optional fix-cycles. Jules keeps its bespoke
+ * src/agents/jules/ package because it has additional swarm-coordination
+ * logic; everyone else shares this envelope.
+ *
+ * Public surface (stable):
+ *   createAgentEnvelope(config) -> EnvelopeInstance
+ *
+ * An EnvelopeInstance has .run(inputs) that executes a bounded multi-turn
+ * loop over the configured tools and returns:
+ *   {
+ *     messages:  [...full message trace...],
+ *     findings:  [...structured findings...],
+ *     stuckReason: null | "no-tool-calls" | "max-turns" | "budget-exceeded",
+ *     turnsUsed: number,
+ *     toolInvocations: [{turn, tool, input, output, error?}]
+ *   }
+ *
+ * The envelope delegates actual LLM invocation to a pluggable client
+ * supplied by the caller (so different personas can route to different
+ * providers). The envelope itself is provider-agnostic.
+ */
+
+export { runEnvelopeLoop, DEFAULT_MAX_TURNS, DEFAULT_STUCK_THRESHOLD } from "./loop.js";
+export { detectStuck } from "./pulse.js";
+export { runFixCycle } from "./fix-cycle.js";
+export { createEventStream } from "./stream.js";

package/src/agents/envelope/loop.js

@@ -0,0 +1,150 @@
+/**
+ * Multi-turn agent loop (#A8 — the core of the envelope).
+ *
+ * Runs a plan → tool-calls → observe → continue/stop cycle with a hard
+ * maxTurns guard, stuck detection via pulse.detectStuck, and per-turn
+ * budget checks supplied by the caller.
+ *
+ * The loop is LLM-client-agnostic: callers pass a `client` that implements
+ * `async client.generatePlan(messages, options) -> plan`.
+ *
+ * A plan has shape:
+ *   {
+ *     stopReason:   "end-turn" | "tool-use" | null,
+ *     content:      string,   // may include reasoning / narration
+ *     toolCalls:    [{ name, input }],
+ *     findings:     [...],    // optional per-turn findings
+ *   }
+ */
+
+import { detectStuck } from "./pulse.js";
+
+export const DEFAULT_MAX_TURNS = 10;
+export const DEFAULT_STUCK_THRESHOLD = 2;
+
+/**
+ * @param {object} params
+ * @param {object} params.client
+ * @param {Array}  params.initialMessages
+ * @param {Array}  params.tools            - list of { name, invoke(input) => Promise }
+ * @param {object} [params.options]
+ * @param {number} [params.options.maxTurns]
+ * @param {number} [params.options.stuckThreshold]
+ * @param {Function} [params.options.shouldAllowCall] - gate invoked before each LLM call
+ * @param {Function} [params.options.onTurn]          - callback per turn
+ */
+export async function runEnvelopeLoop({
+  client,
+  initialMessages = [],
+  tools = [],
+  options = {},
+} = {}) {
+  if (!client || typeof client.generatePlan !== "function") {
+    throw new TypeError("runEnvelopeLoop requires a client with generatePlan()");
+  }
+
+  const maxTurns = Number.isInteger(options.maxTurns) ? options.maxTurns : DEFAULT_MAX_TURNS;
+  const stuckThreshold = Number.isInteger(options.stuckThreshold)
+    ? options.stuckThreshold
+    : DEFAULT_STUCK_THRESHOLD;
+  const shouldAllowCall = typeof options.shouldAllowCall === "function"
+    ? options.shouldAllowCall
+    : () => ({ allow: true });
+  const onTurn = typeof options.onTurn === "function" ? options.onTurn : null;
+
+  const messages = [...initialMessages];
+  const findings = [];
+  const toolInvocations = [];
+  const toolByName = new Map(tools.map((t) => [t.name, t]));
+  const turnStates = [];
+
+  let turnsUsed = 0;
+  let stuckReason = null;
+
+  for (let turn = 1; turn <= maxTurns; turn += 1) {
+    const budgetDecision = shouldAllowCall({ turn, messages });
+    if (budgetDecision && budgetDecision.allow === false) {
+      stuckReason = "budget-exceeded";
+      break;
+    }
+
+    let plan;
+    try {
+      plan = await client.generatePlan(messages, { turn, tools: tools.map((t) => t.name) });
+    } catch (err) {
+      messages.push({ role: "error", content: String(err) });
+      stuckReason = "client-error";
+      turnsUsed = turn;
+      break;
+    }
+
+    const toolCalls = Array.isArray(plan?.toolCalls) ? plan.toolCalls : [];
+    messages.push({ role: "assistant", content: plan?.content ?? "", toolCalls });
+    if (Array.isArray(plan?.findings)) {
+      findings.push(...plan.findings);
+    }
+
+    if (onTurn) {
+      try {
+        onTurn({ turn, plan });
+      } catch {
+        // onTurn is advisory; never let observer errors break the loop
+      }
+    }
+
+    turnsUsed = turn;
+    turnStates.push({ turn, hadToolCalls: toolCalls.length > 0 });
+
+    if (detectStuck(turnStates, stuckThreshold)) {
+      stuckReason = "no-tool-calls";
+      break;
+    }
+
+    if (plan?.stopReason === "end-turn") {
+      break;
+    }
+
+    // Execute tools.
+    for (const call of toolCalls) {
+      const tool = toolByName.get(call.name);
+      if (!tool) {
+        messages.push({
+          role: "tool-result",
+          toolName: call.name,
+          error: `Unknown tool: ${call.name}`,
+        });
+        toolInvocations.push({ turn, tool: call.name, input: call.input, error: "unknown-tool" });
+        continue;
+      }
+      try {
+        const output = await tool.invoke(call.input);
+        messages.push({
+          role: "tool-result",
+          toolName: call.name,
+          output,
+        });
+        toolInvocations.push({ turn, tool: call.name, input: call.input, output });
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        messages.push({
+          role: "tool-result",
+          toolName: call.name,
+          error: errorMessage,
+        });
+        toolInvocations.push({ turn, tool: call.name, input: call.input, error: errorMessage });
+      }
+    }
+  }
+
+  if (!stuckReason && turnsUsed >= maxTurns) {
+    stuckReason = "max-turns";
+  }
+
+  return {
+    messages,
+    findings,
+    stuckReason,
+    turnsUsed,
+    toolInvocations,
+  };
+}

package/src/agents/envelope/pulse.js

@@ -0,0 +1,18 @@
+/**
+ * Stuck-detection pulse (#A8 envelope).
+ *
+ * Called by the loop after each turn. If the agent has emitted zero
+ * tool calls for `threshold` consecutive turns, the loop short-circuits
+ * with stuckReason="no-tool-calls" — prevents infinite reasoning
+ * without action.
+ */
+
+/**
+ * @param {Array<{turn: number, hadToolCalls: boolean}>} turnStates
+ * @param {number} threshold
+ */
+export function detectStuck(turnStates, threshold = 2) {
+  if (!Array.isArray(turnStates) || turnStates.length < threshold) return false;
+  const recent = turnStates.slice(-threshold);
+  return recent.every((state) => state.hadToolCalls === false);
+}

package/src/agents/envelope/stream.js

@@ -0,0 +1,40 @@
+/**
+ * Streaming event adapter (#A8 envelope).
+ *
+ * Wraps the envelope loop's onTurn callback so personas can publish
+ * turn-level events to any sink (Telegram forum topic, SSE channel,
+ * console spinner). The adapter normalizes event shape so sink
+ * implementations don't need to know envelope internals.
+ */
+
+/**
+ * @param {object} [options]
+ * @param {Function} [options.sink] - (event) => void
+ */
+export function createEventStream({ sink } = {}) {
+  const emit = typeof sink === "function" ? sink : () => {};
+  const events = [];
+
+  return {
+    /** Call this as the envelope loop's onTurn callback. */
+    onTurn: ({ turn, plan }) => {
+      const event = {
+        type: "turn",
+        turn,
+        planSummary: {
+          stopReason: plan?.stopReason ?? null,
+          toolCallCount: Array.isArray(plan?.toolCalls) ? plan.toolCalls.length : 0,
+          findingCount: Array.isArray(plan?.findings) ? plan.findings.length : 0,
+        },
+      };
+      events.push(event);
+      try {
+        emit(event);
+      } catch {
+        // sinks are advisory; never let them break the loop
+      }
+    },
+    /** Get the buffered event history. */
+    history: () => events.slice(),
+  };
+}