@traice/codex-collector 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# Internal Spend Codex Collector
+
+This installs a local bridge from Codex developer-agent usage into trAIce
+Internal Spend.
+
+Internal Spend is intentionally separate from product-runtime LLM attribution:
+collector data goes to `/api/v1/internal-usage`, not `/api/v1/events`.
+
+## What It Collects
+
+- Codex token-count rows from `~/.codex/sessions/**/*.jsonl`
+- Codex OTel `response.completed` token events from `127.0.0.1:4318/v1/logs`
+- local install identity: employee email/name, team name, device principal
+- Codex context metadata: repo/cwd, model, thread id, sandbox/approval mode
+- optional monthly seat/subscription commitment, e.g. `--seat-monthly-usd 200`
+
+Prompts are not sent. Codex OTel is configured with `log_user_prompt = false`.
+
+## Install On This Device
+
+Published install shape:
+
+```sh
+read -rsp "trAIce API key: " TRAICE_API_KEY; echo
+export TRAICE_API_KEY
+npx @traice/codex-collector@latest install \
+  --server-url https://app.runtraice.com \
+  --employee-email you@company.com \
+  --employee-name "Your Name" \
+  --team-name Engineering \
+  --seat-monthly-usd 200
+unset TRAICE_API_KEY
+```
+
+Local repo development can still run:
+
+```sh
+node tools/internal-spend-codex/install.mjs \
+  --employee-email you@company.com \
+  --employee-name "Your Name" \
+  --team-name Engineering \
+  --seat-monthly-usd 200
+```
+
+The installer:
+
+- creates or reuses the `internal-spend-poc` workspace in local dev
+- enables the workspace `internalSpendEnabled` flag
+- creates a real API key for `/api/v1/internal-usage`
+- writes private collector config to `~/.traice/internal-spend-codex/install.json`
+- appends an idempotent trAIce `[otel]` block to user-level
+  `~/.codex/config.toml`
+
+Codex ignores telemetry settings in project `.codex/config.toml`, so the user
+config patch is intentional.
+
+## Start The Collector
+
+Foreground:
+
+```sh
+npx @traice/codex-collector@latest collect
+```
+
+Local repo development can use `node tools/internal-spend-codex/collector.mjs`.
+
+macOS LaunchAgent:
+
+```sh
+read -rsp "trAIce API key: " TRAICE_API_KEY; echo
+export TRAICE_API_KEY
+npx @traice/codex-collector@latest install \
+  --server-url https://app.runtraice.com \
+  --employee-email you@company.com \
+  --team-name Engineering \
+  --seat-monthly-usd 200 \
+  --launch-agent
+unset TRAICE_API_KEY
+```
+
+The collector listens on:
+
+```text
+http://127.0.0.1:4318/v1/logs
+```
+
+and forwards normalized internal usage rows to:
+
+```text
+http://127.0.0.1:3003/api/v1/internal-usage
+```
+
+View the module at:
+
+```text
+http://127.0.0.1:3003/dashboard?tab=internal
+```
+
+## Employee And Team Mapping
+
+For this local collector, identity comes from install flags:
+
+- `--employee-email`
+- `--employee-name`
+- `--team-name`
+- `--source-principal`
+- `--seat-monthly-usd`
+
+If omitted, the installer falls back to global git identity and local OS user.
+Future org-wide installs should feed the same fields from MDM/SSO/directory
+data. CSV and vendor connectors should use the same `/api/v1/internal-usage`
+contract and fill employee/team fields directly or via identity mapping.
+
+The API key can be provided with `TRAICE_API_KEY`, `--api-key-stdin`, or
+`--api-key`. Prefer `TRAICE_API_KEY` or `--api-key-stdin` for user installs so
+keys do not end up in shell history.
+
+Private config and collector state default to `~/.traice/internal-spend-codex`.
+Use `--out /path/to/private-dir` only when an org installer manages that
+directory and permissions explicitly.
+
+`--seat-monthly-usd` records a monthly subscription commitment for the
+employee/source pair. It is shown separately from per-request usage cost because
+Codex token logs do not include provider invoice amounts.
+
+## Current Open Codex Agents
+
+Existing Codex processes usually will not reload new user-level OTel config in
+place. To cover already-open agents, the collector tails
+`~/.codex/sessions/**/*.jsonl` and ingests `token_count` events appended by
+running Codex sessions.
+
+New or restarted Codex agents use native OTel export through the installed
+`[otel]` config. Already-open agents are covered by session JSONL token-count
+tailing where those files are available.
+
+## One-Shot Backfill
+
+Run a single session-file scan without opening the OTel listener:
+
+```sh
+npx @traice/codex-collector@latest collect --once
+```
+
+The collector keeps local dedupe state in:
+
+```text
+~/.traice/internal-spend-codex/collector-state.json
+```
+
+so restarting it should not intentionally duplicate historical rows.

package/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dir = dirname(fileURLToPath(import.meta.url));
+const [command = 'collect', ...args] = process.argv.slice(2);
+const script = command === 'install'
+  ? 'install.mjs'
+  : command === 'collect' || command === 'collector'
+    ? 'collector.mjs'
+    : null;
+
+if (!script) {
+  console.error('Usage: traice-codex-collector <install|collect> [options]');
+  process.exit(2);
+}
+
+const result = spawnSync(process.execPath, [resolve(dir, script), ...args], {
+  stdio: 'inherit',
+});
+
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+process.exit(result.status ?? 1);