rovecode 0.3.3 → 0.4.0-beta.3

package/src/telemetry/otel-lanes.ts

@@ -1,89 +0,0 @@
-/** Lane spans for the #39 hook set (port #82): every external agentic-CLI lane (core/tasks.ts TaskInfo.kind
- *  "external" — claude / codex / opencode / agy, port #47) that reached `running` yields exactly ONE
- *  `rovecode.lane` span in its OWN trace, built from TaskInfo snapshots alone (TaskManager.subscribe,
- *  tasks.ts:304) and emitted ONCE when the task settles. It is a root span on purpose: TaskInfo carries no
- *  runId, and under `rovecode serve` or concurrent runs the run that started the lane would be a guess — a
- *  span parented to the wrong trace is worse than a separate one (the run's own `rovecode.tool` span for the
- *  `task` call already sits in the run's trace). Child tasks (kind absent) trace themselves through the
- *  runtime's hooks (cli/boot-tasks.ts:97) and are skipped here, never counted twice; a task cancelled while
- *  still queued never ran and yields nothing; a running lane's progress re-emits (tasks.ts:341) open nothing.
- *
- *  start / end are the snapshot's own startedAt / finishedAt (unixNano-equal — not the observer's clock).
- *  Attributes (ids, sizes and outcomes only — never the goal, label, summary, error, log tail or card text):
- *  rovecode.task_id · rovecode.lane (the adapter id) · rovecode.status ∈ done|failed|cancelled · rovecode.depth ·
- *  rovecode.exit_code (int; OMITTED when the runner reported null — abandoned pipe — or the lane was refused
- *  before any spawn) · rovecode.lane.model (only when ROVECODE_LANE_<ID>_MODEL set it) · rovecode.tokens.{input,
- *  output,cacheRead,cacheWrite} (only when the CLI reported usage: lanes/job.ts:87 defaults a silent CLI to
- *  {0,0}, so an all-zero usage is treated as "nothing came back") · rovecode.patch_lines (when the merge-back
- *  measured one) · rovecode.lane.resumable (bool: a CLI session id came back). Status code 1 for done AND
- *  cancelled (the #39 "stopped" rule), 2 / "lane failed" for failed.
- *
- *  Pattern source: pi packages/agent/src/harness/telemetry.ts (MIT @ 853a80d, header credit only — naming/shape
- *  reference, no code copied): `pi.harness.run` as one span per unit of work with outcome + usage attributes
- *  (:235-256) → rovecode.lane; the attribute policy of packages/telemetry/README.md:385-391. */
-
-import { isTerminal, type TaskStatus } from "../core/tasks.ts";
-import { hex } from "./otel-export.ts";
-import { bool, int, str, type OtelSpan } from "./otlp.ts";
-
-/** The lane seam (#47): the TaskInfo snapshot fields this module reads, and nothing else — a structural
- *  type so TaskManager (core/tasks.ts, whose TaskInfo gains `kind` / `laneExit` / `laneModel` / `laneSession`
- *  with the lanes port) satisfies `LaneSource` with no change here. `kind` other than "external" = a child
- *  agent task, traced through the runtime's hooks and skipped by this observer. */
-export interface LaneTaskInfo {
-  id: string;
-  /** the adapter id of an external lane ("claude" | "codex" | "opencode" | "agy"), or a child agent's name */
-  agent: string;
-  status: TaskStatus;
-  depth: number;
-  kind?: "agent" | "external";
-  startedAt?: number;
-  finishedAt?: number;
-  /** the lane CLI's exit code; null = never observed (abandoned pipe); absent = refused before any spawn */
-  laneExit?: number | null;
-  /** only when ROVECODE_LANE_<ID>_MODEL chose the model */
-  laneModel?: string;
-  /** only what the CLI reported — an all-zero usage is treated as "nothing came back", never as zero tokens */
-  usage?: { input: number; output: number; cacheRead?: number; cacheWrite?: number };
-  patchLines?: number;
-  /** a CLI session id came back (the lane is resumable) */
-  laneSession?: string;
-}
-export interface LaneSource { subscribe(fn: (t: LaneTaskInfo) => void): () => void }
-
-/** subscribe to `tasks`; `emit` receives each finished lane span exactly once; returns the unsubscribe */
-export function observeLanes(tasks: LaneSource, emit: (span: OtelSpan) => void, now: () => number = Date.now): () => void {
-  const open = new Map<string, OtelSpan>();
-  return tasks.subscribe((t) => {
-    if (t.kind !== "external") return;
-    if (t.status === "running") {
-      if (open.has(t.id)) return; // a progress re-emit
-      const s: OtelSpan = { traceId: hex(16), spanId: hex(8), name: "rovecode.lane", start: t.startedAt ?? now(), attrs: new Map(), events: [], status: { code: 0 } };
-      s.attrs.set("rovecode.task_id", str(t.id)); s.attrs.set("rovecode.lane", str(t.agent)); s.attrs.set("rovecode.depth", int(t.depth));
-      open.set(t.id, s);
-      return;
-    }
-    if (!isTerminal(t.status)) return;
-    const s = open.get(t.id);
-    if (!s) return; // queued → cancelled: it never ran
-    open.delete(t.id);
-    emit(finishLane(s, t));
-  });
-}
-
-/** the terminal snapshot's data onto the span (TaskInfo only — nothing derived from text) */
-export function finishLane(s: OtelSpan, t: LaneTaskInfo): OtelSpan {
-  s.attrs.set("rovecode.status", str(t.status));
-  if (typeof t.laneExit === "number") s.attrs.set("rovecode.exit_code", int(t.laneExit));
-  if (t.laneModel) s.attrs.set("rovecode.lane.model", str(t.laneModel));
-  const u = t.usage;
-  if (u && (u.input !== 0 || u.output !== 0 || (u.cacheRead ?? 0) !== 0 || (u.cacheWrite ?? 0) !== 0)) {
-    s.attrs.set("rovecode.tokens.input", int(u.input)); s.attrs.set("rovecode.tokens.output", int(u.output));
-    s.attrs.set("rovecode.tokens.cacheRead", int(u.cacheRead ?? 0)); s.attrs.set("rovecode.tokens.cacheWrite", int(u.cacheWrite ?? 0));
-  }
-  if (t.patchLines !== undefined) s.attrs.set("rovecode.patch_lines", int(t.patchLines));
-  s.attrs.set("rovecode.lane.resumable", bool(t.laneSession !== undefined && t.laneSession !== ""));
-  s.end = t.finishedAt ?? Date.now();
-  s.status = t.status === "failed" ? { code: 2, message: "lane failed" } : { code: 1 };
-  return s;
-}

package/src/telemetry/otel-logs.ts

@@ -1,131 +0,0 @@
-/** OTLP log records for the #39 hook set (port #82): the ExportLogsServiceRequest encoder plus the approval
- *  ledger that turns the EXISTING `approval` hook member (core/hooks.ts:98) into `rovecode.approval` records.
- *  The hook set's approval() records the request and returns void — the human is still asked and their
- *  verdict stands — so the record's decision has to be OBSERVED from the tool events that follow: the
- *  `pre_tool` hook runs BEFORE the prompt (core/tools.ts:112 → :128), which means a tool span is already open
- *  and "awaiting execution" when the card fires; the next `tool_execution_start` for a same-tool span still
- *  awaiting execution is the allow, a `tool_call_failed{permission_denied}` for such a span the deny, and a
- *  request still pending at post_run is `unanswered` (a run aborted while the card was up — tools.ts:141).
- *  otel.ts owns the spans and does that matching (the ids ride along only when exactly ONE candidate span
- *  matched — never a guessed id); this module owns the pending queue and the records.
- *
- *  One LogRecord per request: body `rovecode.approval`, attrs rovecode.tool · rovecode.session_id (the approval ctx
- *  is the runtime's {cwd, sessionId}, hooks.ts:298 — no runId exists there) · rovecode.decision ∈ allow|deny|
- *  unanswered · rovecode.lane (the adapter id, for a `task start` of an external lane — never the card text) ·
- *  rovecode.call_id + traceId/spanId when correlated; severityNumber 9/INFO for allow and unanswered, 13/WARN
- *  for deny. args / revisedArgs / reason / card text are never exported. Approvals a cached "always" verdict
- *  answers (tools.ts:122) never reach the hook and so are not recorded.
- *
- *  Pattern sources (shape only, no code copied): Claude Code's monitoring docs (proprietary — pattern mention
- *  only) publish a `tool_decision` event with tool_name + decision (accept|reject) + source; pi
- *  packages/telemetry (MIT @ 853a80d, README.md:385-391) for the attribute policy (ids/outcomes only).
- *  OTLP/JSON field names are the public opentelemetry-proto logs spec, hand-encoded. */
-
-import { kv, resourceAttrs, scopeOf, str, unixNano, type OtlpKeyValue, type OtlpValue } from "./otlp.ts";
-
-export type ApprovalDecision = "allow" | "deny" | "unanswered";
-export const SEVERITY_INFO = 9;
-export const SEVERITY_WARN = 13;
-
-export interface LogRecord {
-  time: number;
-  severityNumber: number;
-  severityText: string;
-  body: string;
-  attrs: Map<string, OtlpValue>;
-  traceId?: string;
-  spanId?: string;
-}
-
-// ---------- wire types (OTLP/HTTP JSON, ExportLogsServiceRequest subset) ----------
-
-export interface OtlpLogRecord {
-  timeUnixNano: string; observedTimeUnixNano: string;
-  severityNumber: number; severityText: string;
-  body: { stringValue: string };
-  attributes: OtlpKeyValue[];
-  traceId?: string; spanId?: string;
-}
-export interface OtlpLogsRequest {
-  resourceLogs: { resource: { attributes: OtlpKeyValue[] }; scopeLogs: { scope: { name: string; version?: string }; logRecords: OtlpLogRecord[] }[] }[];
-}
-
-export function encodeLogsRequest(serviceName: string, records: readonly LogRecord[]): OtlpLogsRequest {
-  return {
-    resourceLogs: [{
-      resource: { attributes: resourceAttrs(serviceName) },
-      scopeLogs: [{
-        scope: scopeOf(),
-        logRecords: records.map((r) => ({
-          timeUnixNano: unixNano(r.time), observedTimeUnixNano: unixNano(r.time),
-          severityNumber: r.severityNumber, severityText: r.severityText,
-          body: { stringValue: r.body }, attributes: kv(r.attrs),
-          ...(r.traceId ? { traceId: r.traceId } : {}), ...(r.spanId ? { spanId: r.spanId } : {}),
-        })),
-      }],
-    }],
-  };
-}
-
-// ---------- approval ledger ----------
-
-export interface PendingApproval {
-  tool: string;
-  sessionId: string;
-  /** adapter id of an external lane start (`task start {agent:"codex"}`) */
-  lane?: string;
-  /** stable fingerprint of the request args, matched against the awaiting span's — null = unknown (tool-only match) */
-  fp: string | null;
-  at: number;
-}
-/** what the correlator attaches when exactly one span matched */
-export interface ApprovalIds { traceId: string; spanId: string; callId: string }
-
-export interface ApprovalLedger {
-  /** a card fired for `tool` (the human is being asked now) */
-  request(req: PendingApproval): void;
-  /** the oldest pending request for `tool` whose fingerprint matches (or is unknown) — removed and answered */
-  resolve(tool: string, fp: string | null, decision: "allow" | "deny", now: number, ids?: ApprovalIds): boolean;
-  /** pending requests for `tool` (the correlator's candidate count) */
-  pendingFor(tool: string): number;
-  /** every request still pending becomes `unanswered` (post_run / session_close) */
-  drain(now: number): void;
-  /** records recorded since the last take() */
-  take(): LogRecord[];
-  readonly size: number;
-}
-
-export function createApprovalLedger(): ApprovalLedger {
-  const pending: PendingApproval[] = [];
-  let records: LogRecord[] = [];
-  const record = (p: PendingApproval, decision: ApprovalDecision, now: number, ids?: ApprovalIds): void => {
-    const attrs = new Map<string, OtlpValue>([["rovecode.tool", str(p.tool)], ["rovecode.session_id", str(p.sessionId)], ["rovecode.decision", str(decision)]]);
-    if (p.lane) attrs.set("rovecode.lane", str(p.lane));
-    if (ids) attrs.set("rovecode.call_id", str(ids.callId));
-    const warn = decision === "deny";
-    records.push({ time: now, severityNumber: warn ? SEVERITY_WARN : SEVERITY_INFO, severityText: warn ? "WARN" : "INFO", body: "rovecode.approval", attrs, ...(ids ? { traceId: ids.traceId, spanId: ids.spanId } : {}) });
-  };
-  return {
-    request(req) { pending.push(req); },
-    resolve(tool, fp, decision, now, ids) {
-      const i = pending.findIndex((p) => p.tool === tool && (p.fp === null || fp === null || p.fp === fp));
-      if (i < 0) return false;
-      const [p] = pending.splice(i, 1);
-      record(p!, decision, now, ids);
-      return true;
-    },
-    pendingFor: (tool) => pending.filter((p) => p.tool === tool).length,
-    drain(now) { for (const p of pending.splice(0)) record(p, "unanswered", now); },
-    take() { const out = records; records = []; return out; },
-    get size() { return records.length; },
-  };
-}
-
-/** a stable fingerprint of hook-visible args (object keys sorted); undefined when not serializable */
-export function argsFingerprint(args: unknown): string | null {
-  try {
-    return JSON.stringify(args, (_k, v: unknown) => (v && typeof v === "object" && !Array.isArray(v)
-      ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
-      : v)) ?? null;
-  } catch { return null; }
-}

package/src/telemetry/otel-metrics.ts

@@ -1,136 +0,0 @@
-/** Cumulative OTLP metrics for the #39 hook set (port #82): a tiny in-memory registry of monotonic Sums and
- *  explicit-bucket Histograms plus the ExportMetricsServiceRequest encoder. CUMULATIVE on purpose
- *  (aggregationTemporality 2, startTimeUnixNano = the exporter's construction, every point carries the
- *  total since then): the OTel SDK default, and Prometheus-backed collectors drop DELTA points. Counters are
- *  never reset after a POST — the second run's request carries first + second totals. `dirty` says whether
- *  anything changed since the last encode, so a run with no turns and no retries POSTs nothing.
- *
- *  Families (fed by otel.ts):
- *    rovecode.tokens            Sum {token}   rovecode.token.type ∈ input|output|cacheRead|cacheWrite + provider/model
- *    rovecode.request.duration  Histogram ms  pinned bounds DURATION_BOUNDS; one observation per rovecode.turn (provider/model/stop_reason)
- *    rovecode.request.retries   Sum {retry}   provider/model + rovecode.retry.status (int, when the reason parses) — never the reason text
- *    rovecode.cost_usd          Sum USD (double) provider/model — only when the turn priced
- *  Attribute policy as the traces (pi telemetry/README.md:387-389): ids, sizes and outcomes only.
- *
- *  Pattern sources (family names / shapes only, no code copied): gemini-cli docs/cli/telemetry.md (Apache-2.0,
- *  Copyright 2025 Google LLC; snapshot research/source_snapshots/google-gemini-gemini-cli @ 0bd1d43) —
- *  `gemini_cli.api_response` (:518) carries per-request token counts by type and the request duration, and the
- *  `gemini_cli.tool.call.count` counter family (:959) is keyed by name + outcome; Claude Code's monitoring
- *  docs (proprietary — pattern mention only, nothing copied) publish `claude_code.token.usage` split by a token
- *  `type` attribute and a `cost.usage` counter. rovecode names them `rovecode.*`, keeps the NormalizedUsage
- *  spelling of the token types, and hand-encodes the public OTLP/JSON metrics proto (int64 / fixed64 as
- *  decimal strings, doubles as numbers). */
-
-import { kv, resourceAttrs, scopeOf, unixNano, type OtlpKeyValue, type OtlpValue } from "./otlp.ts";
-
-export const AGGREGATION_CUMULATIVE = 2;
-/** rovecode.request.duration explicit bounds in ms — pinned (a dashboard's buckets must not drift) */
-export const DURATION_BOUNDS: readonly number[] = [100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000];
-
-export type MetricAttrs = readonly (readonly [string, OtlpValue])[];
-
-// ---------- wire types (OTLP/HTTP JSON, ExportMetricsServiceRequest subset) ----------
-
-export interface OtlpNumberPoint { attributes: OtlpKeyValue[]; startTimeUnixNano: string; timeUnixNano: string; asInt?: string; asDouble?: number }
-export interface OtlpHistogramPoint {
-  attributes: OtlpKeyValue[]; startTimeUnixNano: string; timeUnixNano: string;
-  count: string; sum: number; bucketCounts: string[]; explicitBounds: number[];
-}
-export type OtlpMetric =
-  | { name: string; unit: string; sum: { dataPoints: OtlpNumberPoint[]; aggregationTemporality: number; isMonotonic: boolean } }
-  | { name: string; unit: string; histogram: { dataPoints: OtlpHistogramPoint[]; aggregationTemporality: number } };
-export interface OtlpMetricsRequest {
-  resourceMetrics: { resource: { attributes: OtlpKeyValue[] }; scopeMetrics: { scope: { name: string; version?: string }; metrics: OtlpMetric[] }[] }[];
-}
-
-// ---------- registry ----------
-
-interface SumSeries { attrs: Map<string, OtlpValue>; value: number }
-interface HistSeries { attrs: Map<string, OtlpValue>; count: number; sum: number; buckets: number[] }
-interface SumMetric { kind: "sum"; name: string; unit: string; asDouble: boolean; series: Map<string, SumSeries> }
-interface HistMetric { kind: "histogram"; name: string; unit: string; bounds: readonly number[]; series: Map<string, HistSeries> }
-
-export interface MetricsRegistry {
-  /** the cumulative window start (ms) — every point's startTimeUnixNano */
-  readonly startMs: number;
-  /** something was recorded since the last encode() */
-  readonly dirty: boolean;
-  /** add `delta` (≥ 0) to a monotonic Sum series; `asDouble` picks the double point encoding (cost) */
-  addSum(name: string, unit: string, attrs: MetricAttrs, delta: number, asDouble?: boolean): void;
-  /** one observation into an explicit-bucket Histogram series */
-  recordHistogram(name: string, unit: string, bounds: readonly number[], attrs: MetricAttrs, value: number): void;
-  /** the whole cumulative state as ONE request (all points stamped `nowMs`); clears `dirty`, never the totals */
-  encode(serviceName: string, nowMs: number): OtlpMetricsRequest;
-}
-
-/** series key: the attribute tuples sorted by key (so insertion order never splits a series) */
-const seriesKey = (attrs: MetricAttrs): string => JSON.stringify([...attrs].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
-
-export function createMetrics(startMs: number): MetricsRegistry {
-  const metrics = new Map<string, SumMetric | HistMetric>();
-  let dirty = false;
-  const sumOf = (name: string, unit: string, asDouble: boolean): SumMetric => {
-    let m = metrics.get(name);
-    if (!m) { m = { kind: "sum", name, unit, asDouble, series: new Map() }; metrics.set(name, m); }
-    if (m.kind !== "sum") throw new Error(`metric ${name} is a ${m.kind}`);
-    return m;
-  };
-  const histOf = (name: string, unit: string, bounds: readonly number[]): HistMetric => {
-    let m = metrics.get(name);
-    if (!m) { m = { kind: "histogram", name, unit, bounds, series: new Map() }; metrics.set(name, m); }
-    if (m.kind !== "histogram") throw new Error(`metric ${name} is a ${m.kind}`);
-    return m;
-  };
-  return {
-    startMs,
-    get dirty() { return dirty; },
-    addSum(name, unit, attrs, delta, asDouble = false) {
-      if (!(delta >= 0) || !Number.isFinite(delta)) return; // monotonic: never a negative or NaN step
-      const m = sumOf(name, unit, asDouble);
-      const k = seriesKey(attrs);
-      const s = m.series.get(k) ?? { attrs: new Map(attrs), value: 0 };
-      s.value += delta;
-      m.series.set(k, s);
-      dirty = true;
-    },
-    recordHistogram(name, unit, bounds, attrs, value) {
-      if (!Number.isFinite(value)) return;
-      const m = histOf(name, unit, bounds);
-      const k = seriesKey(attrs);
-      const s = m.series.get(k) ?? { attrs: new Map(attrs), count: 0, sum: 0, buckets: new Array<number>(bounds.length + 1).fill(0) };
-      s.count++; s.sum += value;
-      let i = 0;
-      while (i < bounds.length && value > bounds[i]!) i++; // bucket i holds (bounds[i-1], bounds[i]]; the last is the overflow
-      s.buckets[i]!++;
-      m.series.set(k, s);
-      dirty = true;
-    },
-    encode(serviceName, nowMs) {
-      dirty = false;
-      return encodeMetricsRequest(serviceName, [...metrics.values()], startMs, nowMs);
-    },
-  };
-}
-
-// ---------- encoding ----------
-
-function encodeMetricsRequest(serviceName: string, metrics: readonly (SumMetric | HistMetric)[], startMs: number, nowMs: number): OtlpMetricsRequest {
-  const start = unixNano(startMs), now = unixNano(nowMs);
-  const stamp = (attrs: Map<string, OtlpValue>) => ({ attributes: kv(attrs), startTimeUnixNano: start, timeUnixNano: now });
-  const out: OtlpMetric[] = metrics.map((m) => m.kind === "sum"
-    ? {
-      name: m.name, unit: m.unit,
-      sum: {
-        dataPoints: [...m.series.values()].map((s) => ({ ...stamp(s.attrs), ...(m.asDouble ? { asDouble: s.value } : { asInt: String(Math.trunc(s.value)) }) })),
-        aggregationTemporality: AGGREGATION_CUMULATIVE, isMonotonic: true,
-      },
-    }
-    : {
-      name: m.name, unit: m.unit,
-      histogram: {
-        dataPoints: [...m.series.values()].map((s) => ({ ...stamp(s.attrs), count: String(s.count), sum: s.sum, bucketCounts: s.buckets.map(String), explicitBounds: [...m.bounds] })),
-        aggregationTemporality: AGGREGATION_CUMULATIVE,
-      },
-    });
-  return { resourceMetrics: [{ resource: { attributes: resourceAttrs(serviceName) }, scopeMetrics: [{ scope: scopeOf(), metrics: out }] }] };
-}