@meterbility/codex-cli-adapter 0.3.1

package/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 Meterbility authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------------------------------------
+
+Note: This MIT license covers everything in this repository EXCEPT the
+contents of the /ee directory (when present), which are licensed under the
+Elastic License 2.0 (ELv2) — see /ee/LICENSE.
+
+The /ee directory is reserved for Enterprise Edition modules: multi-tenant
+fleet orchestration, SSO/RBAC, audit logs, and long-retention features.
+
+Nothing under /ee today; the directory is created as a forward-compatible
+marker so the licensing boundary is visible before any /ee code lands.

package/README.md

@@ -0,0 +1,11 @@
+# @meterbility/codex-cli-adapter
+
+Part of [Meterbility](https://github.com/HoneycombHairDevelopers/Meterbility) — the debugger for AI agents. Capture every run, inspect every decision, pause and inject live, fork from any step.
+
+Ingests Codex CLI rollout sessions from `~/.codex/sessions`.
+
+```bash
+npm install @meterbility/codex-cli-adapter
+```
+
+See the [Meterbility documentation](https://github.com/HoneycombHairDevelopers/Meterbility#readme) for the full guide. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import { Store } from '@meterbility/collector';
+
+/**
+ * Codex Desktop / CLI session JSONL schema. Three top-level types live
+ * inside the file; the discriminator is `type` and the per-record body
+ * lives under `payload`.
+ */
+interface CodexSessionMetaPayload {
+    id: string;
+    timestamp: string;
+    cwd?: string;
+    originator?: string;
+    cli_version?: string;
+    source?: string;
+    model_provider?: string;
+    base_instructions?: {
+        text?: string;
+    };
+    git?: {
+        branch?: string;
+        commit?: string;
+    };
+}
+interface CodexResponseItemMessage {
+    type: "message";
+    role: "user" | "assistant";
+    content: Array<{
+        type: "input_text";
+        text: string;
+    } | {
+        type: "output_text";
+        text: string;
+    } | {
+        type: string;
+        [k: string]: unknown;
+    }>;
+}
+interface CodexResponseItemFunctionCall {
+    type: "function_call";
+    call_id?: string;
+    id?: string;
+    name?: string;
+    arguments?: string;
+}
+interface CodexResponseItemFunctionCallOutput {
+    type: "function_call_output";
+    call_id?: string;
+    output?: string;
+}
+type CodexResponseItem = CodexResponseItemMessage | CodexResponseItemFunctionCall | CodexResponseItemFunctionCallOutput | {
+    type: string;
+    [k: string]: unknown;
+};
+interface CodexEventMsgPayload {
+    type: string;
+    [k: string]: unknown;
+}
+type CodexRecord = {
+    type: "session_meta";
+    timestamp?: string;
+    payload: CodexSessionMetaPayload;
+} | {
+    type: "response_item";
+    timestamp?: string;
+    payload: CodexResponseItem;
+} | {
+    type: "event_msg";
+    timestamp?: string;
+    payload: CodexEventMsgPayload;
+};
+declare function isResponseItem(r: CodexRecord): r is {
+    type: "response_item";
+    timestamp?: string;
+    payload: CodexResponseItem;
+};
+declare function isMessage(p: CodexResponseItem): p is CodexResponseItemMessage;
+declare function isFunctionCall(p: CodexResponseItem): p is CodexResponseItemFunctionCall;
+declare function isFunctionCallOutput(p: CodexResponseItem): p is CodexResponseItemFunctionCallOutput;
+declare function textOfMessage(m: CodexResponseItemMessage): string;
+
+interface ParsedCodexRecord {
+    record: CodexRecord;
+    offset: number;
+    length: number;
+}
+declare function readCodexSession(path: string, startOffset?: number): Promise<ParsedCodexRecord[]>;
+declare function parseBuffer(buf: Buffer, startOffset?: number): ParsedCodexRecord[];
+declare function endOffset(records: ParsedCodexRecord[], fallback?: number): number;
+
+interface CodexIngestResult {
+    run_id: string;
+    steps_added: number;
+    bytes_read: number;
+    status: "ok" | "empty";
+}
+/**
+ * Ingest a Codex Desktop / Codex CLI rollout file. Maps each assistant
+ * `response_item.message` (or `function_call`) to one Meterbility Step. The
+ * preceding user message becomes the conversation history. If a
+ * subsequent function_call_output matches a function_call's call_id, we
+ * attach it as the Outcome.
+ *
+ * Codex doesn't expose token usage in the rollout JSONL, so token
+ * counts are zero and steps are tagged `cost:approx`. The fork engine
+ * still works — the conversation history is captured verbatim.
+ */
+declare function ingestCodexSession(store: Store, path: string): Promise<CodexIngestResult>;
+
+interface DiscoveredCodexSession {
+    path: string;
+    session_id: string;
+    date_dir: string;
+    size_bytes: number;
+    mtime: Date;
+}
+declare function codexHome(): string;
+declare function codexSessionsRoot(): string;
+/**
+ * Walk `~/.codex/sessions/<year>/<month>/<day>/rollout-*.jsonl` and
+ * return every session log Meterbility can ingest, newest first.
+ */
+declare function discoverCodexSessions(): Promise<DiscoveredCodexSession[]>;
+
+export { type CodexEventMsgPayload, type CodexIngestResult, type CodexRecord, type CodexResponseItem, type CodexResponseItemFunctionCall, type CodexResponseItemFunctionCallOutput, type CodexResponseItemMessage, type CodexSessionMetaPayload, type DiscoveredCodexSession, type ParsedCodexRecord, codexHome, codexSessionsRoot, discoverCodexSessions, endOffset, ingestCodexSession, isFunctionCall, isFunctionCallOutput, isMessage, isResponseItem, parseBuffer, readCodexSession, textOfMessage };

package/dist/index.js

@@ -0,0 +1,394 @@
+// src/types.ts
+function isResponseItem(r) {
+  return r.type === "response_item";
+}
+function isMessage(p) {
+  return p.type === "message";
+}
+function isFunctionCall(p) {
+  return p.type === "function_call";
+}
+function isFunctionCallOutput(p) {
+  return p.type === "function_call_output";
+}
+function textOfMessage(m) {
+  return m.content.map((c) => {
+    if (typeof c === "object" && c && "text" in c && typeof c.text === "string") {
+      return c.text;
+    }
+    return "";
+  }).filter((s) => s.length > 0).join("\n");
+}
+
+// src/parser.ts
+import { readFile } from "fs/promises";
+async function readCodexSession(path, startOffset = 0) {
+  const buf = await readFile(path);
+  return parseBuffer(buf, startOffset);
+}
+function parseBuffer(buf, startOffset = 0) {
+  const records = [];
+  let offset = startOffset;
+  if (startOffset > 0) {
+    while (offset < buf.length && buf[offset - 1] !== 10) offset += 1;
+  }
+  let lineStart = offset;
+  for (let i = offset; i <= buf.length; i++) {
+    if (i === buf.length || buf[i] === 10) {
+      const line = buf.subarray(lineStart, i).toString("utf-8").trim();
+      if (line.length > 0) {
+        try {
+          records.push({
+            record: JSON.parse(line),
+            offset: lineStart,
+            length: i - lineStart + (i < buf.length ? 1 : 0)
+          });
+        } catch (err) {
+          console.warn(
+            `[meter/codex] skipping malformed JSONL at ${lineStart}: ${err.message}`
+          );
+        }
+      }
+      lineStart = i + 1;
+    }
+  }
+  return records;
+}
+function endOffset(records, fallback = 0) {
+  if (records.length === 0) return fallback;
+  const last = records[records.length - 1];
+  return last.offset + last.length;
+}
+
+// src/ingest.ts
+import { randomUUID } from "crypto";
+import { stat } from "fs/promises";
+import { hashJson } from "@meterbility/shared";
+import {
+  getIngestOffset,
+  getRunBySessionId,
+  insertRun,
+  insertStep,
+  recordContextSnapshot,
+  setIngestOffset,
+  setRunStatus,
+  updateRunTotals,
+  upsertAgent,
+  upsertProjectByCwd
+} from "@meterbility/collector";
+var SOURCE_RUNTIME = "codex-cli";
+async function ingestCodexSession(store, path) {
+  const offset = getIngestOffset(store, SOURCE_RUNTIME, path);
+  const tail = await readCodexSession(path, offset);
+  if (tail.length === 0) {
+    return { run_id: "", steps_added: 0, bytes_read: 0, status: "empty" };
+  }
+  const fileStat = await stat(path);
+  const fullSize = fileStat.size;
+  const all = offset === 0 ? tail : await readCodexSession(path, 0);
+  const meta = inferMeta(all);
+  const sessionId = meta.id;
+  const project = upsertProjectByCwd(store, meta.cwd ?? "(unknown)");
+  const agent = upsertAgent(store, project.project_id, "codex-cli");
+  const existing = sessionId ? getRunBySessionId(store, sessionId) : void 0;
+  let runId;
+  if (existing) {
+    runId = existing.run_id;
+  } else {
+    runId = `run_${randomUUID()}`;
+    const run = {
+      run_id: runId,
+      agent_id: agent.agent_id,
+      project_id: project.project_id,
+      source_session_id: sessionId,
+      source_runtime: SOURCE_RUNTIME,
+      title: inferTitle(all),
+      status: "in_progress",
+      started_at: meta.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+      git_branch: meta.git?.branch,
+      cwd: meta.cwd,
+      tokens_total_input: 0,
+      tokens_total_output: 0,
+      tokens_total_cached: 0,
+      cost_cents: 0,
+      step_count: 0,
+      tags: ["cost:approx"]
+    };
+    insertRun(store, run);
+  }
+  let stepsAdded = 0;
+  for await (const step of buildSteps(all, runId, store, meta)) {
+    insertStep(store, step);
+    stepsAdded += 1;
+  }
+  const last = lastTimestamp(all);
+  setRunStatus(store, runId, finalStatus(all), last);
+  updateRunTotals(store, runId);
+  setIngestOffset(store, SOURCE_RUNTIME, path, endOffset(tail, fullSize));
+  return {
+    run_id: runId,
+    steps_added: stepsAdded,
+    bytes_read: fullSize - offset,
+    status: "ok"
+  };
+}
+function inferMeta(records) {
+  for (const r of records) {
+    if (r.record.type === "session_meta") return r.record.payload;
+  }
+  return { id: "", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function inferTitle(records) {
+  for (const r of records) {
+    if (!isResponseItem(r.record)) continue;
+    if (!isMessage(r.record.payload)) continue;
+    if (r.record.payload.role !== "user") continue;
+    const text = textOfMessage(r.record.payload);
+    if (text.trim().length === 0) continue;
+    return text.split("\n")[0].slice(0, 80);
+  }
+  return void 0;
+}
+function lastTimestamp(records) {
+  for (let i = records.length - 1; i >= 0; i--) {
+    const ts = records[i].record.timestamp;
+    if (ts) return ts;
+  }
+  return void 0;
+}
+function finalStatus(records) {
+  for (let i = records.length - 1; i >= 0; i--) {
+    const r = records[i].record;
+    if (r.type === "event_msg" && r.payload.type === "task_complete") {
+      return "ok";
+    }
+  }
+  return "in_progress";
+}
+async function* buildSteps(records, runId, store, meta) {
+  const systemPromptText = meta.base_instructions?.text;
+  let systemPromptRef;
+  if (systemPromptText) {
+    systemPromptRef = await store.blobs.putString(systemPromptText);
+  }
+  const history = [];
+  let sequence = 0;
+  let prevStepId;
+  const outputByCallId = /* @__PURE__ */ new Map();
+  for (const r of records) {
+    if (!isResponseItem(r.record)) continue;
+    if (isFunctionCallOutput(r.record.payload) && r.record.payload.call_id) {
+      outputByCallId.set(r.record.payload.call_id, r.record.payload);
+    }
+  }
+  for (let i = 0; i < records.length; i++) {
+    const r = records[i];
+    if (!isResponseItem(r.record)) continue;
+    const payload = r.record.payload;
+    if (isMessage(payload) && payload.role === "user") {
+      const text = textOfMessage(payload);
+      const ref = await store.blobs.putString(text);
+      history.push({ role: "user", content_ref: ref });
+      continue;
+    }
+    if (isMessage(payload) && payload.role === "assistant") {
+      const text = textOfMessage(payload);
+      const action = parseActionFromAgentText(text);
+      const decisionRef = await store.blobs.putJson(payload.content);
+      const components = await snapshotComponents(
+        store,
+        systemPromptRef,
+        history
+      );
+      const snapshot = {
+        id: hashJson(components),
+        components
+      };
+      const snapshotBlobRef = await store.blobs.putJson(snapshot);
+      recordContextSnapshot(
+        store,
+        snapshot.id,
+        snapshotBlobRef,
+        snapshot.components.length
+      );
+      const stepId = `stp_${randomUUID()}`;
+      const outcome = { status: "ok" };
+      const step = {
+        step_id: stepId,
+        run_id: runId,
+        parent_step_id: prevStepId,
+        sequence,
+        timestamp: r.record.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+        model: meta.model_provider ?? "codex-unknown",
+        context_snapshot_id: snapshot.id,
+        decision_ref: decisionRef,
+        action,
+        outcome,
+        tokens: {
+          input: 0,
+          output: 0,
+          cached_read: 0,
+          cache_creation: 0
+        },
+        latency_ms: 0,
+        cost_cents: 0,
+        tags: ["cost:approx", "codex"],
+        status: "ok"
+      };
+      yield step;
+      const historyRef = await store.blobs.putString(text);
+      history.push({ role: "assistant", content_ref: historyRef });
+      sequence += 1;
+      prevStepId = stepId;
+      continue;
+    }
+    if (isFunctionCall(payload)) {
+      const action = {
+        kind: "tool_call",
+        tool_name: payload.name ?? "function",
+        tool_use_id: payload.call_id ?? payload.id,
+        tool_input: safeParseJson(payload.arguments)
+      };
+      const decisionRef = await store.blobs.putJson(payload);
+      const matchedOutput = payload.call_id ? outputByCallId.get(payload.call_id) : void 0;
+      const outcome = matchedOutput ? {
+        status: "ok",
+        tool_result_ref: await store.blobs.putString(
+          matchedOutput.output ?? ""
+        ),
+        summary: matchedOutput.output?.split("\n")[0]?.slice(0, 200)
+      } : { status: "pending" };
+      const components = await snapshotComponents(
+        store,
+        systemPromptRef,
+        history
+      );
+      const snapshot = {
+        id: hashJson(components),
+        components
+      };
+      const snapshotBlobRef = await store.blobs.putJson(snapshot);
+      recordContextSnapshot(
+        store,
+        snapshot.id,
+        snapshotBlobRef,
+        snapshot.components.length
+      );
+      const stepId = `stp_${randomUUID()}`;
+      yield {
+        step_id: stepId,
+        run_id: runId,
+        parent_step_id: prevStepId,
+        sequence,
+        timestamp: r.record.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+        model: meta.model_provider ?? "codex-unknown",
+        context_snapshot_id: snapshot.id,
+        decision_ref: decisionRef,
+        action,
+        outcome,
+        tokens: { input: 0, output: 0, cached_read: 0, cache_creation: 0 },
+        latency_ms: 0,
+        cost_cents: 0,
+        tags: ["cost:approx", "codex"],
+        status: outcome.status === "pending" ? "in_progress" : "ok"
+      };
+      sequence += 1;
+      prevStepId = stepId;
+      continue;
+    }
+  }
+}
+async function snapshotComponents(store, systemPromptRef, history) {
+  const components = [];
+  if (systemPromptRef) {
+    components.push({ type: "system_prompt", content_ref: systemPromptRef });
+  }
+  if (history.length > 0) {
+    components.push({ type: "conversation_history", messages: [...history] });
+  }
+  return components;
+}
+var TOOL_CALL_RE = /\[external_agent_tool_call:\s*(\w+)\]/;
+function parseActionFromAgentText(text) {
+  const m = text.match(TOOL_CALL_RE);
+  if (m) {
+    return {
+      kind: "tool_call",
+      tool_name: m[1],
+      text
+    };
+  }
+  return text.trim().length > 0 ? { kind: "message", text } : { kind: "thinking_only" };
+}
+function safeParseJson(s) {
+  if (!s) return null;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}
+
+// src/discover.ts
+import { readdir, stat as stat2 } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+function codexHome() {
+  return process.env.CODEX_HOME ?? join(homedir(), ".codex");
+}
+function codexSessionsRoot() {
+  return join(codexHome(), "sessions");
+}
+async function discoverCodexSessions() {
+  const root = codexSessionsRoot();
+  const out = [];
+  await walk(root, "", out);
+  out.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+  return out;
+}
+async function walk(dir, rel, out) {
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = join(dir, e);
+    let s;
+    try {
+      s = await stat2(full);
+    } catch {
+      continue;
+    }
+    if (s.isDirectory()) {
+      await walk(full, rel ? `${rel}/${e}` : e, out);
+    } else if (e.startsWith("rollout-") && e.endsWith(".jsonl")) {
+      out.push({
+        path: full,
+        session_id: extractSessionId(e),
+        date_dir: rel,
+        size_bytes: s.size,
+        mtime: s.mtime
+      });
+    }
+  }
+}
+function extractSessionId(filename) {
+  const m = filename.match(/rollout-[\d-]+T[\d-]+-([0-9a-f-]+)\.jsonl$/);
+  return m?.[1] ?? filename.replace(/\.jsonl$/, "");
+}
+export {
+  codexHome,
+  codexSessionsRoot,
+  discoverCodexSessions,
+  endOffset,
+  ingestCodexSession,
+  isFunctionCall,
+  isFunctionCallOutput,
+  isMessage,
+  isResponseItem,
+  parseBuffer,
+  readCodexSession,
+  textOfMessage
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@meterbility/codex-cli-adapter",
+  "version": "0.3.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@meterbility/shared": "^0.3.0",
+    "@meterbility/spec": "^0.3.0",
+    "@meterbility/collector": "^0.3.0"
+  },
+  "description": "Codex CLI session capture adapter for Meterbility",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HoneycombHairDevelopers/Meterbility.git",
+    "directory": "adapters/codex-cli"
+  },
+  "homepage": "https://github.com/HoneycombHairDevelopers/Meterbility#readme",
+  "bugs": {
+    "url": "https://github.com/HoneycombHairDevelopers/Meterbility/issues"
+  },
+  "engines": {
+    "node": ">=20.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "tsup": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "dts": true,
+    "clean": true
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}