opencode-turnstile 0.0.0-stage → 0.1.0

package/src/journal.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Telemetry boundary: JSONL journal and human-readable trace
+ * persistence. A `Journaler` instance is created per plugin setup from the
+ * resolved config and injected into the state, gate, and wiring layers,
+ * so no module-level paths exist and tests can redirect all writes. Journaling is
+ * fail-open by contract: no write ever breaks execution.
+ */
+
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+
+/**
+ * Resolves the default metrics directory from an environment. Relative
+ * `XDG_DATA_HOME` or `HOME` values are ignored: the XDG spec demands the
+ * former be absolute, and this plugin's contract is that the resulting
+ * path is never relative.
+ * @param env Environment to consult; defaults to `process.env`.
+ * @returns The absolute default metrics directory.
+ */
+export function defaultMetricsDir(env: Record<string, string | undefined> = process.env): string {
+  const abs = (v: string | undefined): string | undefined =>
+    v !== undefined && path.isAbsolute(v) ? v : undefined
+  const home = abs(env.HOME) ?? os.homedir()
+  const base = abs(env.XDG_DATA_HOME) ?? path.join(home, ".local/share")
+  return path.join(base, "opencode", "metrics")
+}
+
+/** Default metrics directory, used only before config resolves (e.g. to
+ * journal a malformed config file). */
+export const DEFAULT_METRICS_DIR: string = defaultMetricsDir()
+
+/** Default JSONL journal path inside {@link DEFAULT_METRICS_DIR}. */
+export const DEFAULT_JOURNAL_PATH: string = path.join(DEFAULT_METRICS_DIR, "turnstile.jsonl")
+
+/** Rotation bound comment: a journal file rotates when it exceeds the
+ * configured byte size; generations `.1`…`.N` shift up, the oldest is
+ * pruned. Disk usage is bounded at (N + 1) × maxBytes per journal. The
+ * stat cost per append is negligible; the shift is a handful of renames
+ * that happens once per maxBytes of journal growth. */
+
+/**
+ * Returns the current time as an ISO-8601 timestamp.
+ * @returns The current UTC timestamp, e.g. `2026-10-08T12:00:00.000Z`.
+ */
+export function now(): string {
+  return new Date().toISOString()
+}
+
+/**
+ * Rotates a journal file when it grows past the size limit, keeping at
+ * most `maxGenerations` numbered generations. Silent on any failure.
+ * @param file Path of the journal file to check and rotate.
+ * @param maxBytes Rotation threshold in bytes.
+ * @param maxGenerations Number of numbered generations to keep.
+ */
+export function rotateIfLarge(file: string, maxBytes: number, maxGenerations: number): void {
+  try {
+    const stat = fs.statSync(file)
+    if (stat.size <= maxBytes) return
+    // prune the oldest generation first so the shift below has a free slot
+    const oldest = `${file}.${maxGenerations}`
+    try {
+      fs.unlinkSync(oldest)
+    } catch {
+      // no generation at the limit yet; nothing to prune
+    }
+    for (let gen = maxGenerations - 1; gen >= 1; gen--) {
+      try {
+        fs.renameSync(`${file}.${gen}`, `${file}.${gen + 1}`)
+      } catch {
+        // missing generation: skip; lower generations still shift correctly
+      }
+    }
+    fs.renameSync(file, `${file}.1`)
+  } catch {
+    // missing file or stat failure: nothing to rotate
+  }
+}
+
+/**
+ * Appends one line to a file, creating the parent directory first. The
+ * caller is responsible for rotating when a size bound applies (the
+ * JSONL journal and trace both call `rotateIfLarge` before appending).
+ * Silent on any failure: journaling must never break execution.
+ * @param file Path of the file to append to.
+ * @param text The line to append (a trailing newline is added).
+ */
+export function appendLine(file: string, text: string): void {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.appendFileSync(file, text + "\n")
+  } catch {
+    // journaling must never break execution
+  }
+}
+
+/** Telemetry writer injected into the state, gate, and wiring layers. */
+export interface Journaler {
+  /** Absolute path of the JSONL journal file. */
+  journalPath: string
+  /** Absolute path of the human-readable trace file. */
+  tracePath: string
+  /**
+   * Appends one structured entry to the JSONL journal, timestamped.
+   * @param entry The journal entry; a `ts` field is prepended.
+   */
+  journal(entry: Record<string, unknown>): void
+  /**
+   * Appends one line to the trace file in the AGENTS.md trace contract
+   * format (`YYYY-MM-DD HH:MM | agent | event | detail`). No-op when the
+   * config disables the trace.
+   * @param agent The acting agent label (e.g. `orchestrator`, `reviewer`).
+   * @param event The event kind (e.g. `dispatch`, `gate`, `verdict`).
+   * @param detail Free-form event detail, truncated to 200 characters.
+   */
+  traceEvent(agent: string, event: string, detail: string): void
+}
+
+/**
+ * Creates a telemetry writer bound to the given metrics directory.
+ * @param options.metricsDir Directory that receives both telemetry files.
+ * @param options.trace Whether trace lines are written (journal always is).
+ * @param options.maxBytes Rotation threshold per journal file.
+ * @param options.maxGenerations Rotated generations kept per journal file.
+ * @returns A Journaler writing `turnstile.jsonl` and `gate-events.jsonl`
+ *     under `options.metricsDir`.
+ */
+export function createJournaler(options: {
+  metricsDir: string
+  trace: boolean
+  maxBytes: number
+  maxGenerations: number
+}): Journaler {
+  const journalPath = path.join(options.metricsDir, "turnstile.jsonl")
+  const tracePath = path.join(options.metricsDir, "gate-events.jsonl")
+  return {
+    journalPath,
+    tracePath,
+    journal(entry: Record<string, unknown>): void {
+      rotateIfLarge(journalPath, options.maxBytes, options.maxGenerations)
+      appendLine(journalPath, JSON.stringify({ ts: now(), ...entry }))
+    },
+    traceEvent(agent: string, event: string, detail: string): void {
+      if (!options.trace) return
+      // The trace file shares the journal's rotation bound (AGENTS.md
+      // retention contract: bounded at (N + 1) × maxBytes per file).
+      rotateIfLarge(tracePath, options.maxBytes, options.maxGenerations)
+      const d = new Date()
+      const pad = (n: number): string => String(n).padStart(2, "0")
+      appendLine(
+        tracePath,
+        `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())} | ${agent} | ${event} | ${String(detail).slice(0, 200)}`,
+      )
+    },
+  }
+}

package/src/markers.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Marker boundary: `GATE:`/`VERDICT:` marker parsing with
+ * per-task dedup, plus agent attribution helpers. Pure with respect to
+ * journal and filesystem, so callers journal the returned marker events.
+ */
+
+import type { GateState, MarkerEvent, TaskInput } from "./types.ts"
+
+// `export const` keeps the regex literals load-bearing for
+// scripts/check-markers.mjs, which extracts them by name and asserts the
+// README's marker examples still parse. Keep each regex on one line and
+// edit the README examples and these literals together.
+// prettier-ignore
+export const GATE_RE = /^\s*[`>#*\s]*GATE: (PASS|FAIL) tests=\d+ passed=\d+ failed=\d+/gm
+// prettier-ignore
+export const VERDICT_RE = /^\s*[`>#*\s]*VERDICT: (APPROVE|BLOCK) crit=\d+ high=\d+ med=\d+ low=\d+/gm
+
+/** Agents contracted to emit GATE/VERDICT markers; marker-less output from
+ * anything else is normal, not a violation. */
+export const BARE_OUTPUT_AGENTS: readonly string[] = ["test-runner", "reviewer", "plan-reviewer"]
+
+/**
+ * Compiles a marker regex from a config-provided source string with `gm`
+ * flags. Production matchers use `String.match`, so `lastIndex` state is
+ * not an issue; tests must strip `g` before `.test`.
+ * @param source Regex source string (no delimiters, no flags).
+ * @param fallback Regex to return when the source fails to compile.
+ * @returns The compiled regex, or the fallback when the source is invalid.
+ */
+export function compileMarkerRegex(source: string, fallback: RegExp): RegExp {
+  try {
+    return new RegExp(source, "gm")
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * Extracts the subagent name from a task dispatch input, trying the known
+ * host field spellings in order.
+ * @param input The dispatch input, or null/undefined.
+ * @returns The agent name as a string, or an empty string when unknown.
+ */
+export function agentFromTaskInput(input: TaskInput | undefined | null): string {
+  return String(input?.subagent_type ?? input?.agent ?? input?.subagent ?? "")
+}
+
+/**
+ * Parses GATE and VERDICT markers out of assistant text, mutating the given
+ * gate state (dedup set, gate-pass flag, verdict list) and returning only
+ * first-sight observations for the caller to journal. The reviewer round
+ * cap is counted per dispatch in `gates.ts`, not here.
+ *
+ * Only the last GATE/VERDICT match per text is observed (latest-wins);
+ * earlier matches in the same text are reported via `suppressed` so the
+ * caller can journal their loss. Latest-wins also applies across texts:
+ * an observed `GATE: FAIL` clears a previously recorded `GATE: PASS`.
+ *
+ * Streaming sources (`message.part.updated`, text deltas) re-deliver the
+ * same accumulated text; dedup on marker identity ensures the journal only
+ * ever sees first sight. `dedupScope` partitions the dedup set: task-result
+ * deliveries pass a unique scope per delivery so a re-run emitting a
+ * byte-identical marker is still journaled, while streaming sources share
+ * the empty scope.
+ *
+ * @param state Mutable gate state for the parent session.
+ * @param text The assistant text to scan.
+ * @param gateRe The gate marker regex (defaults to the canonical GATE_RE).
+ * @param verdictRe The verdict marker regex (defaults to VERDICT_RE).
+ * @param dedupScope Key prefix partitioning the dedup set (default "").
+ * @returns Marker events observed for the first time in this text.
+ */
+export function parseGateMarkers(
+  state: GateState,
+  text: string,
+  gateRe: RegExp = GATE_RE,
+  verdictRe: RegExp = VERDICT_RE,
+  dedupScope = "",
+): MarkerEvent[] {
+  const events: MarkerEvent[] = []
+  if (!text) return events
+  const gates = text.match(gateRe) ?? []
+  const verdicts = text.match(verdictRe) ?? []
+  const gate = gates[gates.length - 1] ?? null
+  const verdict = verdicts[verdicts.length - 1] ?? null
+  if (gate) {
+    const key = `${dedupScope}gate\u0000${gate}`
+    if (!state.seen.has(key)) {
+      state.seen.add(key)
+      const result: "PASS" | "FAIL" = gate.includes("PASS") ? "PASS" : "FAIL"
+      // A re-run's FAIL un-greens a gate set by an earlier PASS, even across
+      // different texts: the latest observed result wins.
+      state.hasGatePass = result === "PASS"
+      events.push({ kind: "gate", marker: gate, result, suppressed: gates.length - 1 })
+    }
+  }
+  if (verdict) {
+    const key = `${dedupScope}verdict\u0000${verdict}`
+    if (!state.seen.has(key)) {
+      state.seen.add(key)
+      state.verdicts.push(verdict)
+      // `rounds` reflects the dispatch-based reviewer round count; verdicts
+      // no longer increment it (cap is enforced per dispatch in gates.ts).
+      events.push({
+        kind: "verdict",
+        marker: verdict,
+        rounds: state.reviewRounds,
+        suppressed: verdicts.length - 1,
+      })
+    }
+  }
+  return events
+}