rovecode 0.3.2 → 0.4.0-beta.2

package/src/skills/spec.ts

@@ -1,162 +0,0 @@
-/** agentskills.io-compatible SKILL.md frontmatter (port #72): the spec field set, a lenient | strict validator and
- *  the skill-specific frontmatter walker. Pattern sources (no code copied): pi packages/coding-agent/src/core/skills.ts
- *  (MIT — validateName :92-115, validateDescription :117-127, warn-and-load :276-345, name → parent-dir fallback :319),
- *  opencode-2026 skill/index.ts:53-59 (MIT — type-only checks; unknown fields ignored, skills.mdx:45), hermes
- *  agent/skill_utils.py:1182-1198 (MIT — the 60-char cut was a PROMPT truncation, never a load rule). The field set
- *  and limits follow the agentskills.io specification (verified 2026-09-04): name ≤ 64, lower-case [a-z0-9] joined by
- *  single hyphens, equal to the parent directory; description 1–1024; compatibility ≤ 500; metadata string → string;
- *  allowed-tools one space-separated string (experimental — parsed as DATA, never enforced). The spec defines NO
- *  archive format and says nothing about unknown keys: rovecode warns once and loads (`version` is its own known key).
- *
- *  Why a second walker beside index.ts parseFrontmatter: that helper drops every colon-less line — core/agents.ts
- *  checkFrontmatterLines and tui/commands.ts depend on exactly that, so it stays byte-identical — and therefore
- *  cannot carry an indented `metadata:` map or a `>` / `|` block-scalar description. parseSkillFrontmatter reads the
- *  flat `key: value` files the old loader read the same way (same quote strip, same body slice) and additionally:
- *  nested pairs under `metadata:` become the metadata map; indented lines under any other key are continuation text
- *  joined by ONE space (`>`, `>-`, `|` scalars read as one line); a colon inside an unquoted value is kept; BOM and
- *  CRLF tolerated; a key whose children are `- item` lines is recorded as a list (allowed-tools must be a string). */
-
-export const NAME_MAX = 64;
-export const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-export const DESCRIPTION_MAX = 1024;
-export const COMPATIBILITY_MAX = 500;
-/** the spec's six fields + rovecode's own `version` (never warned about) */
-export const KNOWN_KEYS: ReadonlySet<string> = new Set(["name", "description", "license", "compatibility", "metadata", "allowed-tools", "version"]);
-
-export type FieldShape = "scalar" | "list" | "map";
-export type ValidateMode = "lenient" | "strict";
-
-export interface SkillFrontmatter {
-  /** top-level values: inline text, or continuation lines joined by one space; quotes stripped */
-  fields: Record<string, string>;
-  /** how every top-level key was written (metadata is a map when it has indented children) */
-  shapes: Record<string, FieldShape>;
-  /** the `metadata:` map, string values only */
-  metadata: Record<string, string>;
-  /** metadata keys whose value was a nested map, a list or empty — not a string */
-  metadataNonString: string[];
-  body: string;
-}
-
-/** the validated field set of one SKILL.md */
-export interface SkillMeta {
-  name: string;
-  description: string;
-  /** top-level `version`, else `metadata.version`, else "" */
-  version: string;
-  license?: string;
-  compatibility?: string;
-  metadata: Record<string, string>;
-  /** `allowed-tools` whitespace-split — data only */
-  allowedTools: string[];
-}
-
-export interface Validation {
-  meta: SkillMeta;
-  /** the file must not load (lenient) / the check fails (strict) */
-  errors: string[];
-  /** lenient mode: loaded anyway, reported */
-  warnings: string[];
-  /** strict mode: unknown keys — printed, never a failure */
-  notes: string[];
-}
-
-const BLOCK_SCALAR = /^[>|][+-]?$/;
-/** `key: value` where the key is identifier-shaped — a nested-map line, not a sentence holding a colon */
-const MAP_LINE = /^[A-Za-z0-9_-]+:(\s|$)/;
-const unquote = (v: string): string => v.trim().replace(/^["']|["']$/g, "");
-
-/** null when the text has no `---` block or the block is unterminated (the two INVALID shapes). */
-export function parseSkillFrontmatter(raw: string): SkillFrontmatter | null {
-  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
-  const firstEnd = text.indexOf("\n");
-  if (firstEnd === -1 || text.slice(0, firstEnd).replace(/\r$/, "") !== "---") return null;
-  const close = /\r?\n---[ \t]*(?=\r?\n|$)/g;
-  close.lastIndex = firstEnd;
-  const m = close.exec(text);
-  if (m === null) return null;
-  const block = text.slice(firstEnd + 1, m.index);
-  // past the closing `---` line, then one blank separator line — the parseFrontmatter body slice
-  const body = text.slice(m.index + m[0].length).replace(/^\r?\n/, "").replace(/^\r?\n/, "");
-
-  const fields: Record<string, string> = {};
-  const shapes: Record<string, FieldShape> = {};
-  const metadata: Record<string, string> = {};
-  const metadataNonString: string[] = [];
-  const markNonString = (k: string): void => { delete metadata[k]; if (!metadataNonString.includes(k)) metadataNonString.push(k); };
-  let key: string | undefined; // the open top-level key
-  let blockScalar = false;
-  let metaKey: string | undefined; // the open metadata sub-key
-  let metaIndent = -1;
-  for (const line of block.split(/\r?\n/)) {
-    const t = line.trim();
-    if (t === "" || t.startsWith("#")) continue;
-    const indent = line.length - line.trimStart().length;
-    if (indent === 0) {
-      const i = line.indexOf(":");
-      if (i <= 0) { key = undefined; continue; } // not a `key: value` line — skipped, as parseFrontmatter skips it
-      key = line.slice(0, i).trim();
-      const rest = line.slice(i + 1).trim();
-      metaKey = undefined; metaIndent = -1;
-      blockScalar = BLOCK_SCALAR.test(rest);
-      if (key === "metadata") { shapes[key] = rest === "" ? "map" : "scalar"; if (rest !== "") fields[key] = unquote(rest); continue; }
-      shapes[key] = "scalar";
-      fields[key] = blockScalar ? "" : unquote(rest);
-      continue;
-    }
-    if (key === undefined) continue;
-    if (key === "metadata" && shapes[key] === "map") {
-      if (metaKey !== undefined && indent > metaIndent) { markNonString(metaKey); continue; } // nested map / list under a sub-key
-      const i = t.indexOf(":");
-      if (t.startsWith("- ") || i <= 0) { shapes[key] = "list"; continue; } // `metadata:` holding a list
-      metaKey = t.slice(0, i).trim(); metaIndent = indent;
-      const v = t.slice(i + 1).trim();
-      if (v === "") markNonString(metaKey); else metadata[metaKey] = unquote(v);
-      continue;
-    }
-    const cont = fields[key] ?? "";
-    if (!blockScalar && shapes[key] === "scalar" && cont === "") {
-      if (t.startsWith("- ")) shapes[key] = "list"; else if (MAP_LINE.test(t)) shapes[key] = "map";
-    }
-    fields[key] = cont === "" ? t : `${cont} ${t}`;
-  }
-  return { fields, shapes, metadata, metadataNonString, body };
-}
-
-/** The spec checks. Lenient (the loader): an empty or missing description is the ONE error, everything else a
- *  warning and the file loads (a missing name falls back to the directory name — pi:319). Strict (`validate`,
- *  `pack`): every spec violation is an error; unknown keys are notes in both modes' spirit — never a failure. */
-export function validateSkillMeta(fm: SkillFrontmatter, dirBasename: string, mode: ValidateMode): Validation {
-  const errors: string[] = [], warnings: string[] = [], notes: string[] = [];
-  const flag = (msg: string): void => { (mode === "strict" ? errors : warnings).push(msg); };
-  const f = fm.fields;
-  const description = f["description"] ?? "";
-  if (description === "") errors.push(`description is required (1–${DESCRIPTION_MAX} characters)`);
-  else if (description.length > DESCRIPTION_MAX) flag(`description is ${description.length} characters (max ${DESCRIPTION_MAX})`);
-  let name = f["name"] ?? "";
-  if (name === "") {
-    if (mode === "strict") errors.push("name is required");
-    else warnings.push(`name missing — using the directory name "${dirBasename}"`);
-    name = dirBasename;
-  } else {
-    if (name.length > NAME_MAX) flag(`name is ${name.length} characters (max ${NAME_MAX})`);
-    if (!NAME_RE.test(name)) flag(`name "${name}" must be lower-case letters, digits and single hyphens (no leading, trailing or double hyphen)`);
-    if (name !== dirBasename) flag(`name "${name}" does not match its directory "${dirBasename}"`);
-  }
-  const compatibility = f["compatibility"] || undefined;
-  if (compatibility !== undefined && compatibility.length > COMPATIBILITY_MAX) flag(`compatibility is ${compatibility.length} characters (max ${COMPATIBILITY_MAX})`);
-  const metaShape = fm.shapes["metadata"];
-  if (metaShape !== undefined && metaShape !== "map") flag("metadata must be a map of string keys to string values");
-  if (fm.metadataNonString.length > 0) flag(`metadata values must be strings: ${fm.metadataNonString.join(", ")}`);
-  const toolsShape = fm.shapes["allowed-tools"];
-  if (toolsShape !== undefined && toolsShape !== "scalar") flag("allowed-tools must be one space-separated string");
-  const unknown = Object.keys(fm.shapes).filter((k) => !KNOWN_KEYS.has(k));
-  if (unknown.length > 0) (mode === "strict" ? notes : warnings).push(`unknown frontmatter keys: ${unknown.join(", ")}`);
-  const version = f["version"] || fm.metadata["version"] || "";
-  const license = f["license"] || undefined;
-  const allowedTools = (f["allowed-tools"] ?? "").split(/\s+/).filter((t) => t !== "");
-  const meta: SkillMeta = { name, description, version, metadata: fm.metadata, allowedTools };
-  if (license !== undefined) meta.license = license;
-  if (compatibility !== undefined) meta.compatibility = compatibility;
-  return { meta, errors, warnings, notes };
-}

package/src/skills/tools.ts

@@ -1,69 +0,0 @@
-/** Skill tools (hermes pattern): `skill_view` returns a body and bumps the
- *  usage sidecar; `skills_list` returns the index. Above 50 skills the index
- *  is too big for the system prompt, so `skills_list` is the only access path
- *  and `buildSkillsIndex` returns "" (prompt_builder.py:2083 reject rule). */
-
-import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
-import { SkillStore, skillLifecycle, type Skill, type SkillUsage } from "./index.ts";
-
-export const INDEX_PROMPT_LIMIT = 50; // hermes: >50 skills → skills_list tool only
-
-function renderIndexLine(s: Skill, usage: SkillUsage | undefined, now: number): string {
-  const state = skillLifecycle(s, usage, now);
-  return `- ${s.name}${s.version ? ` (v${s.version})` : ""}: ${s.description}${state === "stale" ? " [stale]" : ""}`;
-}
-
-/** System-prompt index. Empty string when the catalogue outgrows the prompt. */
-export function buildSkillsIndex(store: SkillStore, now: number = Date.now()): string {
-  const skills = store.list();
-  if (skills.length === 0 || skills.length > INDEX_PROMPT_LIMIT) return "";
-  return skills.map((s) => renderIndexLine(s, store.usage(s.name), now)).join("\n");
-}
-
-export function createSkillTools(store: SkillStore): Tool[] {
-  const skillView: Tool = {
-    schema: {
-      name: "skill_view",
-      description:
-        "Read one skill's full instructions. Use when a skill in the index matches the task.",
-      args: {
-        type: "object",
-        properties: { name: { type: "string", description: "skill name from the index" } },
-        required: ["name"],
-      },
-    },
-    kind: "read",
-    sequential: true, // sidecar write
-    execute(args): Promise<ToolOutput> {
-      const raw = args as { name?: unknown };
-      const name = typeof raw.name === "string" ? raw.name : "";
-      const skill = store.get(name);
-      if (!skill) return Promise.resolve({ ok: false, output: `no skill named '${name}'` });
-      const usage = store.bumpUsage(skill);
-      // the FULL description, not the index's clipped line: the model opened this skill to read it, so
-      // the sentence saying when to use it belongs here in one piece
-      const header = `# ${skill.name} (v${skill.version})\n\n${skill.fullDescription}\n\n`;
-      return Promise.resolve({ ok: true, output: header + skill.body, data: usage });
-    },
-  };
-
-  const skillsList: Tool = {
-    schema: {
-      name: "skills_list",
-      description:
-        "List available skills (name, version, description, staleness). Use to discover skills when the system prompt has no skill index.",
-      args: { type: "object", properties: {} },
-    },
-    kind: "read",
-    execute(_args: unknown, _ctx: ToolContext): Promise<ToolOutput> {
-      store.scan(); // fresh catalogue even when the caller forgot to rescan
-      const skills = store.list();
-      if (skills.length === 0) return Promise.resolve({ ok: true, output: "no skills installed" });
-      const now = Date.now();
-      const lines = skills.map((s) => renderIndexLine(s, store.usage(s.name), now));
-      return Promise.resolve({ ok: true, output: lines.join("\n"), data: { count: skills.length } });
-    },
-  };
-
-  return [skillView, skillsList];
-}

package/src/skills/versioned.ts

@@ -1,227 +0,0 @@
-/** Versioned edit ledger for skill/memory files (PORT #16, prime-agent MIT).
- *
- *  Port of the refinement/versioned-state machinery in prime-agent
- *  packages/coding-agent/src/core/refinement/refinement.ts:
- *    - per-edit before/after snapshots + version bump  (AppliedRefinementEdit:85,
- *      `version = before ? before.version + 1 : 1`:770, record push:788)
- *    - optimistic-concurrency baseline check → typed reject, no write  (735-749)
- *    - rollback built from recorded before/after, itself a new history entry
- *      (rollbackProposal:813-845, rollbackOf:100)
- *    - append-only JSONL history beside the store; malformed lines skipped so a
- *      bad append can never break rollback  (refinements.jsonl:25, 374-400)
- *
- *  Deliberately NOT ported (BLUEPRINT §5 + prime's reward-hacking findings):
- *  no auto-refinement loop (prime's reviewAutoRefine LLM gate stays out), no
- *  LLM proposal pass, and no grader/eval surface anywhere in this API
- *  (ouroboros rule: graders stay hidden from agent-facing code). Edits happen
- *  only when a human or an explicit tool call invokes commit()/rollback().
- *
- *  Storage: sidecar JSONL beside the target file — `<target>.versions.jsonl`
- *  (mirrors the house `SKILL.md.usage.json` sidecar). One line per edit:
- *  {version, baseVersion, before, after, reason, timestamp, rollbackTo?}.
- *  Every record carries FULL before/after content, so record v restores both
- *  content@v (`after`) and content@v-1 (`before`). With the newest K records
- *  retained, rollback covers versions [oldest.baseVersion .. newest.version].
- *  History is bounded: past `maxEdits` records the oldest are evicted, and
- *  versions older than the window become unreachable (typed reject).
- *  Versions are monotonic and never reused after eviction. */
-
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-
-export const LEDGER_SUFFIX = ".versions.jsonl";
-export const DEFAULT_MAX_EDITS = 20;
-
-export interface VersionedEdit {
-  /** version this edit produced (monotonic; = baseVersion + 1) */
-  version: number;
-  /** version the editor read before making the change */
-  baseVersion: number;
-  /** full target content before the edit (content at baseVersion) */
-  before: string;
-  /** full target content after the edit (content at version) */
-  after: string;
-  reason: string;
-  /** ms epoch */
-  timestamp: number;
-  /** set when this edit was produced by rollback(): the restored version */
-  rollbackTo?: number;
-}
-
-/** Inclusive range of versions rollback can currently restore. */
-export interface VersionRange { from: number; to: number }
-
-export type CommitResult =
-  | { ok: true; edit: VersionedEdit }
-  | { ok: false; code: "version-conflict"; baseVersion: number; currentVersion: number; message: string };
-
-export type RollbackResult =
-  | { ok: true; edit: VersionedEdit }
-  | { ok: false; code: "unknown-version"; requested: number; available: VersionRange | null; message: string };
-
-// ---------- internals ----------
-
-/** Atomic write (house pattern, skills/index.ts writeUsageAtomic): tmp + rename. */
-function atomicWrite(path: string, text: string): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, text);
-  renameSync(tmp, path);
-}
-
-/** Parse one JSONL line into an edit, or null when malformed (prime: skip, never throw). */
-function parseEdit(line: string): VersionedEdit | null {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(line);
-  } catch {
-    return null;
-  }
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
-  const r = raw as Record<string, unknown>;
-  if (
-    typeof r["version"] !== "number" || typeof r["baseVersion"] !== "number" ||
-    typeof r["before"] !== "string" || typeof r["after"] !== "string" ||
-    typeof r["reason"] !== "string" || typeof r["timestamp"] !== "number"
-  ) return null;
-  const edit: VersionedEdit = {
-    version: r["version"], baseVersion: r["baseVersion"],
-    before: r["before"], after: r["after"],
-    reason: r["reason"], timestamp: r["timestamp"],
-  };
-  if (typeof r["rollbackTo"] === "number") edit.rollbackTo = r["rollbackTo"];
-  return edit;
-}
-
-// ---------- ledger ----------
-
-export interface VersionLedgerOptions {
-  /** sidecar path (default: `<target>${LEDGER_SUFFIX}`) */
-  ledgerPath?: string;
-  /** bounded snapshot count; oldest records evicted past this (default 20, min 1) */
-  maxEdits?: number;
-}
-
-export class VersionLedger {
-  readonly ledgerPath: string;
-  private readonly maxEdits: number;
-
-  constructor(readonly targetPath: string, opts: VersionLedgerOptions = {}) {
-    this.ledgerPath = opts.ledgerPath ?? targetPath + LEDGER_SUFFIX;
-    this.maxEdits = Math.max(1, opts.maxEdits ?? DEFAULT_MAX_EDITS);
-  }
-
-  /** Retained edits, oldest → newest. Malformed lines are skipped; duplicate
-   *  versions keep the last occurrence (append order wins). */
-  history(): VersionedEdit[] {
-    if (!existsSync(this.ledgerPath)) return [];
-    const byVersion = new Map<number, VersionedEdit>();
-    for (const line of readFileSync(this.ledgerPath, "utf8").split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      const edit = parseEdit(trimmed);
-      if (edit) byVersion.set(edit.version, edit);
-    }
-    return [...byVersion.values()].sort((a, b) => a.version - b.version);
-  }
-
-  /** Current version: 0 until the first recorded edit; unaffected by eviction. */
-  version(): number {
-    return this.history().at(-1)?.version ?? 0;
-  }
-
-  /** Current on-disk content of the target ("" when the file does not exist). */
-  read(): string {
-    return existsSync(this.targetPath) ? readFileSync(this.targetPath, "utf8") : "";
-  }
-
-  /** Versions rollback can restore right now, or null before the first edit.
-   *  Derived from the CONTIGUOUS suffix of retained records: a corruption hole
-   *  (missing/garbled record) breaks before/after coverage, so a naive
-   *  first..last span would advertise versions rollback cannot restore. */
-  range(): VersionRange | null {
-    const edits = this.history();
-    const last = edits.at(-1);
-    if (!last) return null;
-    let start = edits.length - 1;
-    while (start > 0 && edits[start - 1]!.version === edits[start]!.baseVersion) start--;
-    return { from: edits[start]!.baseVersion, to: last.version };
-  }
-
-  /** Content at a recorded version, or undefined when evicted/unknown. Besides a
-   *  record's own `after`, any record with baseVersion === version restores it via
-   *  `before` — recoverable even when the record that PRODUCED it was corrupted. */
-  contentAt(version: number): string | undefined {
-    const edits = this.history();
-    const direct = edits.find((e) => e.version === version);
-    if (direct) return direct.after;
-    return edits.find((e) => e.baseVersion === version)?.before;
-  }
-
-  /** True when the target was modified outside the ledger since the last edit. */
-  drifted(): boolean {
-    const last = this.history().at(-1);
-    return last !== undefined && this.read() !== last.after;
-  }
-
-  /** Record an edit and write the target. Optimistic concurrency: `baseVersion`
-   *  must equal the current version or the commit is rejected BEFORE any disk
-   *  mutation — no partial write. `before` is read from disk here, so the
-   *  record stays truthful even if the target drifted externally. */
-  commit(after: string, reason: string, baseVersion: number, now: number = Date.now()): CommitResult {
-    const currentVersion = this.version();
-    if (baseVersion !== currentVersion) {
-      return {
-        ok: false, code: "version-conflict", baseVersion, currentVersion,
-        message: `baseVersion ${baseVersion} does not match current version ${currentVersion}; re-read and retry`,
-      };
-    }
-    return { ok: true, edit: this.write(after, reason, currentVersion, now) };
-  }
-
-  /** One-call rollback to any retained version. Recorded as a NEW edit with
-   *  `rollbackTo` (prime `rollbackOf` pattern) — history is append-only, and
-   *  the restored content is byte-exact from the stored snapshot. */
-  rollback(toVersion: number, reason?: string, now: number = Date.now()): RollbackResult {
-    const content = this.contentAt(toVersion);
-    if (content === undefined) {
-      const available = this.range();
-      return {
-        ok: false, code: "unknown-version", requested: toVersion, available,
-        message: available
-          ? `version ${toVersion} is not restorable; available: ${available.from}..${available.to}`
-          : `version ${toVersion} is not restorable; no recorded edits`,
-      };
-    }
-    const edit = this.write(content, reason ?? `rollback to v${toVersion}`, this.version(), now, toVersion);
-    return { ok: true, edit };
-  }
-
-  /** Append the record, evict past the bound, then atomically write the target.
-   *  Ledger-first ordering: a crash between the two leaves an honest record
-   *  (visible via drifted()) rather than an unrecorded content change. */
-  private write(after: string, reason: string, currentVersion: number, now: number, rollbackTo?: number): VersionedEdit {
-    const edit: VersionedEdit = {
-      version: currentVersion + 1, baseVersion: currentVersion,
-      before: this.read(), after, reason, timestamp: now,
-      ...(rollbackTo !== undefined ? { rollbackTo } : {}),
-    };
-    mkdirSync(dirname(this.ledgerPath), { recursive: true });
-    // Heal a torn trailing append: a crash mid-append can leave the last line
-    // without "\n" — appending straight on would concatenate this record into the
-    // torn line, making the NEW commit invisible to history()/version().
-    let record = JSON.stringify(edit) + "\n";
-    if (existsSync(this.ledgerPath)) {
-      const raw = readFileSync(this.ledgerPath);
-      if (raw.length > 0 && raw[raw.length - 1] !== 0x0a) record = "\n" + record;
-    }
-    appendFileSync(this.ledgerPath, record, "utf8");
-    const edits = this.history();
-    if (edits.length > this.maxEdits) {
-      const kept = edits.slice(edits.length - this.maxEdits);
-      atomicWrite(this.ledgerPath, kept.map((e) => JSON.stringify(e)).join("\n") + "\n");
-    }
-    atomicWrite(this.targetPath, after);
-    return edit;
-  }
-}

package/src/telemetry/otel-export.ts

@@ -1,122 +0,0 @@
-/** OTLP/HTTP exporter pipe (port #82) — ONE exporter for the three signals the #39 hook set emits:
- *  traces (`<base>/v1/traces`), metrics (`<base>/v1/metrics`) and logs (`<base>/v1/logs`). The base is the
- *  configured ROVECODE_OTEL_ENDPOINT with a trailing `/v1/traces` stripped (so a full traces URL still yields
- *  its siblings), each POST rides the #39 REF'D timeout (Bun unrefs AbortSignal.timeout — hooks.ts idiom)
- *  and is tracked so flush() awaits every outstanding one; the export path never throws.
- *
- *  Failure policy: 5xx / timeout / network stay per-export warnings with the #39 texts byte-identical
- *  (`OTLP export to <url> failed: HTTP 500` / `… timed out after 5000ms` / `… ECONNREFUSED`) and never
- *  disable anything. HTTP 404 / 405 / 501 on a signal mean the collector does not serve that path at all
- *  (an old collector without the logs receiver, a traces-only proxy): THAT signal is disabled for the life
- *  of this exporter (one per runtime: the process's one hook set on the CLI/TUI, one per session under
- *  `rovecode serve`) after ONE note — `OTLP collector <base> does not accept <signal> (HTTP <n>) — <signal>
- *  export disabled` — while the other signals continue. A malformed endpoint (`http://`, `host:4318`) makes
- *  the exporter unusable: no POST is ever attempted (the #39 one-note rule; otel.ts raises it).
- *
- *  Moved verbatim out of otel.ts (post / track / flush / withTimeout / TIMED_OUT / errText / hex /
- *  normalizeEndpoint / validEndpoint) so that file stays under the 400-line cap; otel.ts re-exports the
- *  public names, so `import … from "telemetry/otel.ts"` is unchanged. OTLP/HTTP paths and JSON field names
- *  follow the public opentelemetry-proto spec (hand-encoded; no @opentelemetry dependency). */
-
-import { randomBytes } from "node:crypto";
-
-export const DEFAULT_EXPORT_TIMEOUT_MS = 5000;
-export const OTLP_TRACES_PATH = "/v1/traces";
-export type OtlpSignal = "traces" | "metrics" | "logs";
-export const OTLP_SIGNALS: readonly OtlpSignal[] = ["traces", "metrics", "logs"];
-/** HTTP statuses that say "this path is not served here" — the signal is switched off, not retried */
-const NOT_SERVED: ReadonlySet<number> = new Set([404, 405, 501]);
-
-/** base URL or full traces URL (either, with or without trailing slashes) → <base>/v1/traces */
-export function normalizeEndpoint(endpoint: string): string {
-  const base = endpoint.trim().replace(/\/+$/, "");
-  return base.endsWith(OTLP_TRACES_PATH) ? base : base + OTLP_TRACES_PATH;
-}
-/** the collector base: the normalized traces URL minus its `/v1/traces` — the siblings hang off it */
-export const baseOf = (endpoint: string): string => normalizeEndpoint(endpoint).slice(0, -OTLP_TRACES_PATH.length);
-export const signalUrl = (endpoint: string, signal: OtlpSignal): string => `${baseOf(endpoint)}/v1/${signal}`;
-
-/** an absolute http(s) URL with a host — `http://` does not parse and `host:4318` parses host-less,
- *  and both would normalize to `http:/v1/traces` (host "v1") and stall every export to the timeout */
-export function validEndpoint(endpoint: string): boolean {
-  try { const u = new URL(endpoint.trim()); return (u.protocol === "http:" || u.protocol === "https:") && u.hostname !== ""; } catch { return false; }
-}
-
-export interface OtlpExporterOptions {
-  endpoint: string;
-  headers?: Record<string, string>;
-  fetch?: typeof fetch;
-  timeoutMs?: number;
-  /** every export note (per-export failures, the one-shot per-signal disable) */
-  warn: (note: string) => void;
-}
-export interface OtlpExporter {
-  readonly base: string;
-  /** false = malformed endpoint: nothing is ever POSTed (the caller says so once) */
-  readonly usable: boolean;
-  url(signal: OtlpSignal): string;
-  /** POST one encoded request; fire-and-forget, tracked for flush(); never throws */
-  post(signal: OtlpSignal, body: string): void;
-  /** await every outstanding POST (posts issued while waiting are awaited too) */
-  flush(): Promise<void>;
-  /** the signal was switched off by a 404/405/501 (diagnostic seam) */
-  disabled(signal: OtlpSignal): boolean;
-}
-
-export function createOtlpExporter(opts: OtlpExporterOptions): OtlpExporter {
-  const base = baseOf(opts.endpoint);
-  const usable = validEndpoint(opts.endpoint);
-  const headers = { ...(opts.headers ?? {}), "content-type": "application/json" };
-  const fetchFn = opts.fetch ?? fetch;
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_EXPORT_TIMEOUT_MS;
-  const pending = new Set<Promise<void>>();
-  const off = new Set<OtlpSignal>();
-  const url = (signal: OtlpSignal): string => `${base}/v1/${signal}`;
-  const send = async (signal: OtlpSignal, body: string): Promise<void> => {
-    if (!usable || off.has(signal)) return;
-    const target = url(signal);
-    const fail = (reason: string): void => opts.warn(`OTLP export to ${target} failed: ${reason}`);
-    const ac = new AbortController();
-    try {
-      const res = await withTimeout(fetchFn(target, { method: "POST", headers, body, signal: ac.signal }), timeoutMs, ac);
-      if (res === TIMED_OUT) { fail(`timed out after ${timeoutMs}ms`); return; }
-      await res.arrayBuffer().catch(() => undefined); // release the connection; a success body is `{}`
-      if (res.ok) return;
-      if (NOT_SERVED.has(res.status)) { // one note, then silence for this signal (a second in-flight POST that raced the first says nothing more)
-        if (!off.has(signal)) { off.add(signal); opts.warn(`OTLP collector ${base} does not accept ${signal} (HTTP ${res.status}) — ${signal} export disabled`); }
-        return;
-      }
-      fail(`HTTP ${res.status}`);
-    } catch (e) { fail(errText(e)); }
-  };
-  return {
-    base, usable, url,
-    post(signal, body) { const p = send(signal, body); pending.add(p); void p.then(() => { pending.delete(p); }); },
-    async flush() { while (pending.size > 0) await Promise.all([...pending]); },
-    disabled: (signal) => off.has(signal),
-  };
-}
-
-// ---------- helpers (moved from otel.ts) ----------
-
-/** random hex id of `bytes` bytes; the all-zero id is invalid in OTel */
-export function hex(bytes: number): string {
-  let h: string;
-  do h = randomBytes(bytes).toString("hex"); while (/^0+$/.test(h));
-  return h;
-}
-export const TIMED_OUT: unique symbol = Symbol("rovecode.otel.timeout");
-/** resolves TIMED_OUT after ms on a REF'D timer and aborts the request's controller (hooks.ts idiom);
- *  the race is independent of the fetch honoring the signal, so a stuck transport still settles */
-export function withTimeout<T>(p: Promise<T>, ms: number, ac: AbortController): Promise<T | typeof TIMED_OUT> {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => { ac.abort(); resolve(TIMED_OUT); }, ms);
-    (timer as unknown as { ref?: () => void }).ref?.();
-    p.then((v) => { clearTimeout(timer); resolve(v); }, (e: unknown) => { clearTimeout(timer); reject(e); });
-  });
-}
-export function errText(e: unknown): string {
-  if (e instanceof Error) return e.message;
-  if (typeof e === "object" && e !== null && typeof (e as { message?: unknown }).message === "string") return (e as { message: string }).message;
-  return String(e);
-}