@yansigit/opencodex 2.33.0 → 2.35.0

package/src/server/sse-frame-buffer.ts

@@ -1,3 +1,5 @@
+import { isCyberPolicyCode, isCyberPolicyMessage } from "../lib/errors";
+
 export const MAX_CLIENT_SSE_FRAME_BYTES = 4 * 1024 * 1024;
 
 const LF_LF = Uint8Array.of(10, 10);
@@ -106,10 +108,35 @@ function isResponsesTerminalFrame(block: Uint8Array): boolean {
   const payload = data.join("\n");
   if (payload === "[DONE]") return false;
   try {
-    const parsed = JSON.parse(payload) as { type?: unknown };
-    return parsed.type === "response.completed"
+    const parsed = JSON.parse(payload) as {
+      type?: unknown;
+      code?: unknown;
+      message?: unknown;
+      error?: unknown;
+      last_error?: unknown;
+      response?: { error?: unknown; incomplete_details?: unknown };
+    };
+    if (parsed.type === "response.completed"
       || parsed.type === "response.failed"
-      || parsed.type === "response.incomplete";
+      || parsed.type === "response.incomplete") return true;
+    if (parsed.type !== "error") return false;
+    // A top-level error is terminal for this boundary only when it carries the
+    // same high-confidence cyber-policy evidence used by relay.ts. Ordinary
+    // upstream errors remain transport failures and still become a bounded 502.
+    const candidates = [
+      parsed,
+      parsed.error,
+      parsed.last_error,
+      parsed.response?.error,
+      parsed.response?.incomplete_details,
+    ];
+    for (const candidate of candidates) {
+      if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
+      const record = candidate as { code?: unknown; message?: unknown };
+      if (isCyberPolicyCode(typeof record.code === "string" ? record.code : undefined)) return true;
+      if (typeof record.message === "string" && isCyberPolicyMessage(record.message)) return true;
+    }
+    return false;
   } catch {
     return false;
   }
@@ -289,4 +316,4 @@ export function joinSseFrameBytes(parts: readonly Uint8Array[]): Uint8Array {
     offset += part.byteLength;
   }
   return joined;
-}
+}

package/src/server/ws-bridge.ts

@@ -34,6 +34,8 @@ export interface WsData {
   authContext?: CodexAuthContext; // last resolved account decision for observability/registry cleanup
   cancel?: () => void; // cancels the in-flight stream reader/fetch
   turnId?: number; // monotonically increasing per socket; prevents stale frames after replacement turns
+  /** Fixed-size logical session lane derived at the HTTP upgrade boundary. */
+  sessionLaneId?: string;
   /** Discriminator: Responses reframing vs transparent live/realtime sideband relay. */
   kind?: "responses" | "live-sideband";
   liveUpstream?: WebSocket;
@@ -60,10 +62,20 @@ export interface WsData {
  * A test that only asserts "the socket opened" would still pass if the admission
  * were dropped from the payload, so the payload itself is what gets asserted.
  */
-export function buildResponsesWsData(headers: Headers, admission: DataPlaneAdmission, admissionLease?: AdmissionReservation<ServerWebSocket<WsData>>): WsData {
+export function buildResponsesWsData(
+  headers: Headers,
+  admission: DataPlaneAdmission,
+  admissionLease?: AdmissionReservation<ServerWebSocket<WsData>>,
+  sessionLaneId?: string,
+): WsData {
   // Auth is handshake-time only on this path: the per-frame contexts have no
   // request headers left to re-resolve from, so the decision rides along here.
-  return { headers, admission, ...(admissionLease ? { admissionLease } : {}) };
+  return {
+    headers,
+    admission,
+    ...(admissionLease ? { admissionLease } : {}),
+    ...(sessionLaneId ? { sessionLaneId } : {}),
+  };
 }
 
 export class WsSendDroppedError extends Error {

package/src/smoke/fingerprint-cache.ts

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+export interface SmokeCacheEntry {
+  fingerprint: string;
+  timestamp: number;
+  status: "passed" | "skipped" | "failed";
+  reason?: string;
+  modelsTested?: string[];
+}
+
+export interface SmokeCacheData {
+  version: number;
+  providers: Record<string, SmokeCacheEntry>;
+}
+
+const CACHE_VERSION = 1;
+
+export function defaultSmokeCachePath(): string {
+  return join(homedir(), ".opencodex", "live-inference-cache.json");
+}
+
+function defaultCachePath(customPath?: string): string {
+  return customPath ?? defaultSmokeCachePath();
+}
+
+function emptyCache(): SmokeCacheData {
+  return { version: CACHE_VERSION, providers: {} };
+}
+
+function walkTs(root: string, relDir: string): string[] {
+  const paths: string[] = [];
+  const fullDir = join(root, relDir);
+  if (!existsSync(fullDir)) return paths;
+  for (const entry of readdirSync(fullDir, { withFileTypes: true })) {
+    const relPath = join(relDir, entry.name);
+    if (entry.isDirectory()) {
+      paths.push(...walkTs(root, relPath));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".ts")) {
+      paths.push(relPath);
+    }
+  }
+  return paths;
+}
+
+function collectProviderSourcePaths(provider: string, root: string): string[] {
+  const smokePaths = ["src/smoke/runner.ts", "src/smoke/live-scenarios.ts"];
+  let paths: string[];
+  switch (provider) {
+    case "google":
+    case "google-antigravity":
+    case "google-aistudio":
+      paths = [...smokePaths, "src/adapters/google.ts", "src/adapters/google-wire-compiler.ts", "src/adapters/google-tool-schema.ts", "src/adapters/google-antigravity-wire.ts", "src/types/tools.ts", "src/server/responses-undeclared-tool-guard.ts"];
+      break;
+    case "cursor":
+      paths = [...smokePaths, "src/adapters/cursor.ts", ...walkTs(root, "src/adapters/cursor")];
+      break;
+    case "command-code":
+      paths = [...smokePaths, "src/adapters/command-code.ts", "src/adapters/command-code-project-context.ts", "src/providers/command-code-efforts.ts"];
+      break;
+    case "openai":
+    case "openai-responses":
+      paths = [...smokePaths, "src/adapters/openai-responses.ts", "src/adapters/responses-tool-schema.ts"];
+      break;
+    default:
+      paths = [...smokePaths, `src/adapters/${provider}.ts`];
+      break;
+  }
+  return [...new Set(paths)].filter(path => existsSync(join(root, path))).sort();
+}
+
+export async function computeProviderSourceFingerprint(
+  provider: string,
+  projectRoot?: string,
+): Promise<string> {
+  const root = resolve(projectRoot ?? process.cwd());
+  const hash = createHash("sha256");
+  const paths = collectProviderSourcePaths(provider, root);
+  if (paths.length === 0) return hash.update(`empty:${provider}`, "utf8").digest("hex");
+  for (const relPath of paths) {
+    hash.update(`${relPath}\0`, "utf8");
+    hash.update(readFileSync(join(root, relPath)));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+export async function loadSmokeCache(customPath?: string): Promise<SmokeCacheData> {
+  const cachePath = defaultCachePath(customPath);
+  if (!existsSync(cachePath)) return emptyCache();
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath, "utf8")) as SmokeCacheData;
+    if (typeof parsed !== "object" || parsed === null) return emptyCache();
+    return {
+      version: typeof parsed.version === "number" ? parsed.version : CACHE_VERSION,
+      providers: typeof parsed.providers === "object" && parsed.providers !== null ? parsed.providers : {},
+    };
+  } catch {
+    return emptyCache();
+  }
+}
+
+export async function saveSmokeCache(data: SmokeCacheData, customPath?: string): Promise<void> {
+  const cachePath = defaultCachePath(customPath);
+  mkdirSync(dirname(cachePath), { recursive: true });
+  writeFileSync(cachePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+export function shouldRunSmokeForProvider(
+  provider: string,
+  currentFingerprint: string,
+  options?: { force?: boolean; cache?: SmokeCacheData },
+): boolean {
+  if (options?.force) return true;
+  const entry = options?.cache?.providers[provider];
+  if (!entry) return true;
+  if (entry.fingerprint !== currentFingerprint) return true;
+  return entry.status !== "passed";
+}
+
+export async function recordSmokeResult(
+  provider: string,
+  entry: SmokeCacheEntry,
+  customPath?: string,
+): Promise<void> {
+  const cache = await loadSmokeCache(customPath);
+  cache.providers[provider] = entry;
+  await saveSmokeCache(cache, customPath);
+}

package/src/smoke/live-scenarios.ts

@@ -0,0 +1,33 @@
+export type SmokeLevel = 1 | 2 | 3;
+
+export interface SmokeScenario {
+  level: SmokeLevel;
+  name: string;
+  buildRequest: (modelId: string, options?: { previousResponseId?: string; toolResult?: string }) => Record<string, unknown>;
+}
+
+export function buildSmokeScenarioRequest(
+  level: SmokeLevel,
+  modelId: string,
+  options: { previousResponseId?: string; toolCallId?: string; toolResult?: string } = {},
+): Record<string, unknown> {
+  const common = { model: modelId, stream: true };
+  if (level === 1) return {
+    ...common,
+    input: [{ role: "user", content: [{ type: "input_text", text: "Reply with exactly five words and include a brief reasoning process." }] }],
+  };
+  if (level === 2) return {
+    ...common,
+    input: [{ role: "user", content: [{ type: "input_text", text: "Use the provided exec_command tool to run echo \"smoke_test_123\"." }] }],
+    tools: [{ type: "function", name: "exec_command", description: "Execute a shell command.", parameters: { type: "object", properties: { cmd: { type: "string" } }, required: ["cmd"] } }],
+  };
+  return {
+    ...common,
+    ...(options.previousResponseId ? { previous_response_id: options.previousResponseId } : {}),
+    input: [{ type: "function_call_output", call_id: options.toolCallId ?? "smoke_call", output: options.toolResult ?? "smoke_test_123" }],
+  };
+}
+
+export const BasicStreamingTurn: SmokeScenario = { level: 1, name: "BasicStreamingTurn", buildRequest: (model, options) => buildSmokeScenarioRequest(1, model, options) };
+export const ToolCallingTurn: SmokeScenario = { level: 2, name: "ToolCallingTurn", buildRequest: (model, options) => buildSmokeScenarioRequest(2, model, options) };
+export const MultiTurnContinuity: SmokeScenario = { level: 3, name: "MultiTurnContinuity", buildRequest: (model, options) => buildSmokeScenarioRequest(3, model, options) };

package/src/smoke/runner.ts

@@ -0,0 +1,119 @@
+import { loadConfig, resolveEnvValue } from "../config";
+import { getCredential } from "../oauth/store";
+import type { OAuthCredentials } from "../oauth/types";
+import type { OcxProviderConfig } from "../types";
+import { computeProviderSourceFingerprint, loadSmokeCache, recordSmokeResult, shouldRunSmokeForProvider } from "./fingerprint-cache";
+import { buildSmokeScenarioRequest } from "./live-scenarios";
+
+export interface ProviderSmokeResult {
+  provider: string;
+  modelId: string;
+  status: "passed" | "skipped" | "failed";
+  reason?: string;
+  level1Passed: boolean;
+  level2Passed: boolean;
+  level3Passed: boolean;
+  durationMs: number;
+  error?: string;
+}
+
+function result(provider: string, modelId: string, started: number, extra: Partial<ProviderSmokeResult>): ProviderSmokeResult {
+  return { provider, modelId, status: "failed", level1Passed: false, level2Passed: false, level3Passed: false, durationMs: Date.now() - started, ...extra };
+}
+
+export function providerHasSmokeCredential(
+  provider: Partial<Pick<OcxProviderConfig, "apiKey" | "authMode" | "headers">>,
+  credential?: OAuthCredentials | null,
+): boolean {
+  if (resolveEnvValue(provider.apiKey)?.trim()) return true;
+  if (Object.entries(provider.headers ?? {}).some(([name, value]) => /authorization|cookie|api[-_]?key/i.test(name) && typeof value === "string" && value.trim().length > 0)) return true;
+  if (provider.authMode === "forward") return true;
+  return provider.authMode === "oauth" && Boolean(credential?.access?.trim() || credential?.refresh?.trim());
+}
+
+function classifyHttp(status: number, body: string): "not_authenticated" | "quota_exhausted" | undefined {
+  if (status === 401 || status === 403) return "not_authenticated";
+  if (status === 429 || /credit|quota|insufficient.?balance|billing/i.test(body)) return "quota_exhausted";
+  return undefined;
+}
+
+export async function runProviderSmoke(options: { provider: string; modelId?: string; proxyUrl?: string; force?: boolean; cachePath?: string }): Promise<ProviderSmokeResult> {
+  const started = Date.now();
+  const config = loadConfig();
+  const providerConfig = config.providers[options.provider];
+  const modelId = options.modelId ?? config.subagentModels?.[0] ?? "gpt-5";
+  if (!providerConfig || providerConfig.disabled === true) return result(options.provider, modelId, started, { status: "skipped", reason: "not_authenticated" });
+  const credential = providerConfig.authMode === "oauth" ? getCredential(options.provider) : null;
+  if (!providerHasSmokeCredential(providerConfig, credential)) return result(options.provider, modelId, started, { status: "skipped", reason: "not_authenticated" });
+  const fingerprint = await computeProviderSourceFingerprint(options.provider);
+  const cache = await loadSmokeCache(options.cachePath);
+  if (!shouldRunSmokeForProvider(options.provider, fingerprint, { force: options.force, cache })) return result(options.provider, modelId, started, { status: "skipped", reason: "cached_pass" });
+
+  const baseUrl = options.proxyUrl ?? "http://127.0.0.1:10100/v1/responses";
+  let level1Passed = false, level2Passed = false, level3Passed = false;
+  let previousResponseId: string | undefined;
+  let emittedToolCallId: string | undefined;
+  try {
+    for (const level of [1, 2, 3] as const) {
+      const reqBody = buildSmokeScenarioRequest(level, modelId, {
+        previousResponseId,
+        toolCallId: emittedToolCallId,
+        toolResult: "smoke_test_123",
+      });
+      const response = await fetch(baseUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(reqBody),
+        signal: AbortSignal.timeout(30000),
+      });
+      const body = await response.text();
+      if (!response.ok) {
+        const reason = classifyHttp(response.status, body);
+        if (reason) {
+          const skipped = result(options.provider, modelId, started, { status: "skipped", reason, level1Passed, level2Passed, level3Passed });
+          await recordSmokeResult(options.provider, { fingerprint, timestamp: Date.now(), status: "skipped", reason, modelsTested: [modelId] }, options.cachePath);
+          return skipped;
+        }
+        throw new Error(`HTTP ${response.status}: ${body.slice(0, 200)}`);
+      }
+      const events = body.split(/\r?\n/).filter(line => line.startsWith("data: ")).flatMap(line => { try { return [JSON.parse(line.slice(6)) as Record<string, unknown>]; } catch { return []; } });
+      let jsonPayload: Record<string, unknown> | undefined;
+      try {
+        jsonPayload = JSON.parse(body) as Record<string, unknown>;
+      } catch {
+        jsonPayload = undefined;
+      }
+      const completed = events.find(event => event.type === "response.completed");
+      const responseData = (completed?.response as Record<string, unknown> | undefined) ?? (jsonPayload?.status === "completed" ? jsonPayload : undefined);
+      if (level === 1) level1Passed = events.some(event => event.type === "response.output_text.delta" || event.type === "response.output_item.added") || responseData?.status === "completed";
+      if (level === 2) {
+        const itemsFromEvents = events.flatMap(event => {
+          const item = event.item as Record<string, unknown> | undefined;
+          const output = (event.response as Record<string, unknown> | undefined)?.output;
+          return [item, ...(Array.isArray(output) ? output : [])].filter(value => value?.type === "function_call") as Record<string, unknown>[];
+        });
+        const itemsFromJson = Array.isArray(jsonPayload?.output) ? (jsonPayload!.output as Record<string, unknown>[]).filter(v => v?.type === "function_call") : [];
+        const calls = [...itemsFromEvents, ...itemsFromJson];
+        level2Passed = calls.some(call => {
+          try {
+            const rawArgs = typeof call.arguments === "string" ? JSON.parse(call.arguments) : call.arguments;
+            const args = rawArgs && typeof rawArgs === "object" ? rawArgs as Record<string, unknown> : {};
+            if (call.call_id || call.id) {
+              emittedToolCallId = String(call.call_id ?? call.id);
+            }
+            return typeof args.cmd === "string" && args.cmd.includes("echo") && args.cmd.includes("smoke_test_123");
+          } catch { return false; }
+        });
+      }
+      if (level === 3) level3Passed = (Boolean(completed) || responseData?.status === "completed") && !/400|thought.?signature|continuity/i.test(body);
+      if (responseData?.id) previousResponseId = String(responseData.id);
+      if (![level1Passed, level2Passed, level3Passed][level - 1]) throw new Error(`level ${level} assertion failed`);
+    }
+    await recordSmokeResult(options.provider, { fingerprint, timestamp: Date.now(), status: "passed", modelsTested: [modelId] }, options.cachePath);
+    return result(options.provider, modelId, started, { status: "passed", level1Passed, level2Passed, level3Passed });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await recordSmokeResult(options.provider, { fingerprint, timestamp: Date.now(), status: "failed", reason: message, modelsTested: [modelId] }, options.cachePath);
+    return result(options.provider, modelId, started, { status: "failed", level1Passed, level2Passed, level3Passed, error: message });
+  }
+}

package/src/telemetry/dispatcher.ts

@@ -0,0 +1,44 @@
+import type { LedgerRecord } from "./types";
+
+export type GhCommandRunner = (args: string[]) => Promise<string>;
+
+export interface AutonomousRemediationConfig {
+  autonomousRemediation?: { enabled?: boolean; instanceId?: string };
+}
+
+export type DispatchResult =
+  | { status: "skipped"; reason: "unauthorized" | "invalid-record" }
+  | { status: "dispatched"; issueNumber?: number; issueUrl?: string; existing: boolean };
+
+const defaultRunner: GhCommandRunner = async args => {
+  const proc = Bun.spawn(["gh", ...args], { stdout: "pipe", stderr: "pipe" });
+  return await new Response(proc.stdout).text();
+};
+
+export async function dispatchAutonomousFix(
+  record: LedgerRecord,
+  config: AutonomousRemediationConfig,
+  run: GhCommandRunner = defaultRunner,
+): Promise<DispatchResult> {
+  const authorization = config.autonomousRemediation;
+  const eventInstance = typeof record.details?.instanceId === "string" ? record.details.instanceId : undefined;
+  if (authorization?.enabled !== true || !authorization.instanceId || (eventInstance !== undefined && eventInstance !== authorization.instanceId)) {
+    return { status: "skipped", reason: "unauthorized" };
+  }
+  if (!record.fingerprint) return { status: "skipped", reason: "invalid-record" };
+
+  const search = await run(["issue", "list", "--repo", "yansigit/opencodex", "--state", "open", "--search", `fingerprint:${record.fingerprint}`]);
+  const existing = search.match(/(?:^|\D)(\d+)(?:\D|$)/);
+  if (existing) {
+    const issueNumber = Number(existing[1]);
+    return { status: "dispatched", issueNumber, existing: true };
+  }
+
+  const metadata = { fingerprint: record.fingerprint, instanceId: authorization.instanceId, firstSeen: record.firstSeen, lastSeen: record.lastSeen, count: record.count, ...(record.details ?? {}) };
+  const body = `<!-- opencodex-failure-telemetry ${JSON.stringify(metadata)} -->\n\nFailure fingerprint: ${record.fingerprint}\n\nThis issue was dispatched by the verified local telemetry instance.`;
+  const title = `Autonomous fix: ${String(record.details?.failureKind ?? "failure")} (${record.fingerprint})`;
+  const created = await run(["issue", "create", "--repo", "yansigit/opencodex", "--title", title, "--body", body, "--label", "agent:jules,autonomous-fix,instance:verified"]);
+  const url = created.match(/https?:\/\/\S+/)?.[0];
+  const issueNumber = url?.match(/\/issues\/(\d+)/)?.[1];
+  return { status: "dispatched", existing: false, ...(url ? { issueUrl: url } : {}), ...(issueNumber ? { issueNumber: Number(issueNumber) } : {}) };
+}

package/src/telemetry/fingerprint.ts

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+import type { FailureEvent, FailureFingerprint } from "./types";
+
+const EPHEMERAL_KEYS = /^(timestamp|.*(?:request|session)[_-]?id|line|column|col)$/i;
+const EPHEMERAL_TEXT = [
+  /\b(?:request|session)[_-]?id\s*[:=]\s*[^\s,;]+/gi,
+  /\b(?:timestamp|time)\s*[:=]\s*[^\s,;]+/gi,
+  /:\d+\s*:\s*\d+(?=\b|\D)/g,
+  /\b(?:line|col(?:umn)?)\s*[:=]?\s*\d+/gi,
+  /\b\d{10,13}\b/g,
+];
+
+function canonical(value: unknown): unknown {
+  if (typeof value === "string") return EPHEMERAL_TEXT.reduce((text, pattern) => text.replace(pattern, ""), value).replace(/\s+/g, " ").trim();
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !EPHEMERAL_KEYS.test(key)).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)]));
+  }
+  return value;
+}
+
+export function computeFailureFingerprint(event: FailureEvent): FailureFingerprint {
+  return createHash("sha256").update(JSON.stringify(canonical(event))).digest("hex");
+}

package/src/telemetry/hook.ts

@@ -0,0 +1,43 @@
+import { resolveAutonomousRemediationConfig, type AutonomousRemediationConfig } from "../config/autonomous-remediation";
+import { TelemetryLedger } from "./ledger";
+import type { LedgerRecord } from "./types";
+
+export type RuntimeFailureCategory = "websocket_1006" | "tool_repetition_loop" | "upstream_wire_error";
+
+export interface RuntimeFailureContext {
+  category?: RuntimeFailureCategory;
+  provider?: string;
+  model?: string;
+  requestId?: string;
+  sessionId?: string;
+  timestamp?: number;
+  config?: AutonomousRemediationConfig | unknown;
+  ledger?: TelemetryLedger;
+}
+
+let defaultLedger: TelemetryLedger | undefined;
+
+function categoryFor(error: unknown, requested?: RuntimeFailureCategory): RuntimeFailureCategory {
+  if (requested) return requested;
+  const message = error instanceof Error ? error.message : String(error);
+  if (/1006|abnormal closure|websocket/i.test(message)) return "websocket_1006";
+  if (/tool.{0,32}(repeat|loop)|(?:repeat|loop).{0,32}tool/i.test(message)) return "tool_repetition_loop";
+  return "upstream_wire_error";
+}
+
+export function interceptRuntimeFailure(error: unknown, context: RuntimeFailureContext = {}): LedgerRecord | null {
+  const config = resolveAutonomousRemediationConfig(context.config);
+  if (!config.enabled) return null;
+  const ledger = context.ledger ?? (defaultLedger ??= new TelemetryLedger());
+  const category = categoryFor(error, context.category);
+  const signature = error instanceof Error ? error.message : String(error);
+  return ledger.recordFailure({
+    failureKind: category,
+    signature,
+    ...(context.provider ? { provider: context.provider } : {}),
+    ...(context.model ? { model: context.model } : {}),
+    ...(context.requestId ? { requestId: context.requestId } : {}),
+    ...(context.sessionId ? { sessionId: context.sessionId } : {}),
+    ...(context.timestamp !== undefined ? { timestamp: context.timestamp } : {}),
+  }, config.rollingWindowMs);
+}

package/src/telemetry/ledger.ts

@@ -0,0 +1,54 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { computeFailureFingerprint } from "./fingerprint";
+import type { FailureEvent, FailureFingerprint, LedgerRecord, RemediationStatus } from "./types";
+
+type Stored = LedgerRecord & { occurrences: number[] };
+
+export class TelemetryLedger {
+  private readonly db: Database;
+
+  constructor(path = join(homedir(), ".opencodex", "telemetry-issues.sqlite")) {
+    if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+    this.db = new Database(path, { create: true });
+    this.db.run("CREATE TABLE IF NOT EXISTS failure_events (fingerprint TEXT PRIMARY KEY, first_seen INTEGER NOT NULL, last_seen INTEGER NOT NULL, count INTEGER NOT NULL, status TEXT NOT NULL, details TEXT, occurrences TEXT NOT NULL)");
+  }
+
+  recordFailure(event: FailureEvent, windowMs: number): LedgerRecord {
+    const fingerprint = computeFailureFingerprint(event);
+    const timestamp = event.timestamp ?? Date.now();
+    const old = this.db.query("SELECT * FROM failure_events WHERE fingerprint = ?").get(fingerprint) as Stored | null;
+    const occurrences = [...(old ? JSON.parse((old as unknown as { occurrences: string }).occurrences) : []), timestamp].filter((seen) => seen >= timestamp - windowMs).sort((a, b) => a - b);
+    const record: LedgerRecord = { fingerprint, firstSeen: old?.firstSeen ?? timestamp, lastSeen: timestamp, count: occurrences.length, status: old?.status ?? "monitoring", ...(old?.details ? { details: JSON.parse(old.details as unknown as string) } : {}) };
+    this.db.query("INSERT INTO failure_events (fingerprint, first_seen, last_seen, count, status, details, occurrences) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(fingerprint) DO UPDATE SET first_seen=excluded.first_seen, last_seen=excluded.last_seen, count=excluded.count, status=excluded.status, details=excluded.details, occurrences=excluded.occurrences").run(fingerprint, record.firstSeen, timestamp, record.count, record.status, record.details ? JSON.stringify(record.details) : null, JSON.stringify(occurrences));
+    return record;
+  }
+
+  getRecord(fingerprint: FailureFingerprint): LedgerRecord | null {
+    const row = this.db.query("SELECT fingerprint, first_seen, last_seen, count, status, details FROM failure_events WHERE fingerprint = ?").get(fingerprint) as Record<string, unknown> | null;
+    if (!row) return null;
+    return { fingerprint: row.fingerprint as string, firstSeen: row.first_seen as number, lastSeen: row.last_seen as number, count: row.count as number, status: row.status as RemediationStatus, ...(row.details ? { details: JSON.parse(row.details as string) } : {}) };
+  }
+
+  listRecords(): LedgerRecord[] {
+    return this.db.query("SELECT fingerprint, first_seen, last_seen, count, status, details FROM failure_events ORDER BY last_seen DESC").all().map(row => {
+      const value = row as Record<string, unknown>;
+      return { fingerprint: value.fingerprint as string, firstSeen: value.first_seen as number, lastSeen: value.last_seen as number, count: value.count as number, status: value.status as RemediationStatus, ...(value.details ? { details: JSON.parse(value.details as string) } : {}) };
+    });
+  }
+
+  updateStatus(fingerprint: FailureFingerprint, status: RemediationStatus, details?: Record<string, unknown>): void {
+    this.db.query("UPDATE failure_events SET status = ?, details = ? WHERE fingerprint = ?").run(status, details ? JSON.stringify(details) : null, fingerprint);
+  }
+
+  shouldDispatch(fingerprint: FailureFingerprint, threshold: number, windowMs: number): boolean {
+    const row = this.db.query("SELECT status, last_seen, occurrences FROM failure_events WHERE fingerprint = ?").get(fingerprint) as { status: RemediationStatus; last_seen: number; occurrences: string } | null;
+    if (!row || row.status !== "monitoring") return false;
+    const count = (JSON.parse(row.occurrences) as number[]).filter((seen) => seen >= row.last_seen - windowMs).length;
+    return count >= threshold;
+  }
+
+  close(): void { this.db.close(); }
+}

package/src/telemetry/types.ts

@@ -0,0 +1,23 @@
+export type RemediationStatus = "monitoring" | "dispatched" | "fixed" | "ignored";
+
+export interface FailureEvent {
+  failureKind: string;
+  provider?: string;
+  model?: string;
+  signature: string;
+  timestamp?: number;
+  requestId?: string;
+  sessionId?: string;
+  [key: string]: unknown;
+}
+
+export type FailureFingerprint = string;
+
+export interface LedgerRecord {
+  fingerprint: FailureFingerprint;
+  firstSeen: number;
+  lastSeen: number;
+  count: number;
+  status: RemediationStatus;
+  details?: Record<string, unknown>;
+}