tokenjam 0.2.0__tar.gz

tokenjam-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Global owner — all files require review from @anilmurty
+* @anilmurty

tokenjam-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Report a bug in TokenJam
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear description of what went wrong.
+
+**To reproduce**
+```bash
+# The command you ran
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Error output**
+```
+# Full error output
+```
+
+**Environment**
+- OS:
+- Python version (`python3 --version`):
+- tj version (`pip show tokenjam`):
+- Output of `tj doctor` (if relevant):

tokenjam-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Suggest a feature or improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**What problem does this solve?**
+A clear description of the problem or use case.
+
+**Proposed solution**
+How you think it should work.
+
+**Alternatives considered**
+Any other approaches you considered.

tokenjam-0.2.0/.github/ISSUE_TEMPLATE/integration_request.md

@@ -0,0 +1,21 @@
+---
+name: Integration request
+about: Request a new framework or provider integration
+title: 'Integration: '
+labels: integration
+assignees: ''
+---
+
+**Framework / Provider**
+Name and link to the project.
+
+**How it handles telemetry today**
+Does it have built-in OTel support? What spans/events does it emit?
+
+**Proposed approach**
+- [ ] Provider patch (monkey-patch API calls)
+- [ ] Framework patch (wrap LLM/tool abstractions)
+- [ ] OTLP bridge (thin wrapper around built-in OTel support)
+
+**Are you willing to implement this?**
+Yes / No — if yes, please read `tokenjam/sdk/integrations/anthropic.py` as the reference implementation before starting.

tokenjam-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Summary
+
+<!-- What does this PR do? 1-3 sentences. -->
+
+## Checklist
+
+- [ ] Tests pass (`pytest tests/unit/ tests/synthetic/ tests/agents/ tests/integration/`)
+- [ ] Lint clean (`ruff check tokenjam/`)
+- [ ] Type check clean (`mypy tokenjam/`)
+- [ ] CLAUDE.md updated (if architecture changed)
+- [ ] Test spans use `tests/factories.py` (not raw `NormalizedSpan`)

tokenjam-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,mcp]"
+
+      - name: Lint
+        run: ruff check tokenjam/
+
+      - name: Type check
+        run: mypy tokenjam/
+
+      - name: Run tests
+        run: pytest tests/unit/ tests/synthetic/ tests/agents/ tests/integration/
+
+  test-ts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install and test TypeScript SDK
+        working-directory: sdk-ts
+        run: npm install && npm test

tokenjam-0.2.0/.github/workflows/publish-npm.yml

@@ -0,0 +1,35 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-npm:
+    if: startsWith(github.ref_name, 'v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        working-directory: sdk-ts
+        run: npm install
+
+      - name: Run tests
+        working-directory: sdk-ts
+        run: npm test
+
+      - name: Build
+        working-directory: sdk-ts
+        run: npm run build
+
+      - name: Publish
+        working-directory: sdk-ts
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

tokenjam-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-pypi:
+    if: startsWith(github.ref_name, 'v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install build ".[dev,mcp]"
+
+      - name: Run tests
+        run: pytest tests/unit/ tests/synthetic/ tests/agents/ tests/integration/ -x
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tokenjam-0.2.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+**/__pycache__/
+**/*.pyc
+**/*.pyo
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# DuckDB
+*.duckdb
+*.duckdb.wal
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / lint caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+
+# Node (sdk-ts)
+sdk-ts/node_modules/
+sdk-ts/dist/
+
+# Secrets and env files
+.env
+.env.*
+ocw.toml
+.ocw/
+
+# Claude Code
+.claude/
+.omc/
+.mcp.json
+
+# Superpowers skill output (internal planning artifacts, not for OSS)
+docs/superpowers/
+.gstack/

tokenjam-0.2.0/.tj/config.toml

@@ -0,0 +1,27 @@
+# TokenJam configuration
+# Docs: https://github.com/Metabuilder-Labs/openclawwatch#configuration
+
+[defaults.budget]
+daily_usd = 5.0
+
+[security]
+ingest_secret = "77755a66f3beea005867bafe9183663e7420435d3bff69c4453f4cadab103fc6"
+
+[capture]
+prompts = false
+completions = false
+tool_outputs = false
+
+[storage]
+path = "~/.tj/telemetry.duckdb"
+retention_days = 90
+
+# Per-agent overrides (optional):
+# [agents.my-agent]
+# description = "My email agent"
+#   [agents.my-agent.budget]
+#   daily_usd = 5.00
+#   session_usd = 1.00
+#   [[agents.my-agent.sensitive_actions]]
+#   name = "send_email"
+#   severity = "critical"

tokenjam-0.2.0/AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md — TokenJam
+
+> **AI coding agents working in this repo should read [`CLAUDE.md`](./CLAUDE.md) instead.**
+> CLAUDE.md is the maintained source of truth and is kept up to date by the agents
+> working in this codebase. This file exists only for tools that look specifically
+> for AGENTS.md (Codex, Gemini Code, etc.).
+
+## Quick rules for agents that don't read CLAUDE.md
+
+1. Storage is **DuckDB** — never `import sqlite3`, never write SQLite queries
+2. Config is **TOML** — `tomllib.load()` requires `open(path, "rb")` binary mode
+3. `tokenjam/core/` has **no CLI or HTTP imports** — pure domain logic only
+4. `@watch()` alone does **not** create LLM spans — requires `patch_anthropic()` etc.
+5. Never use unicode bullet characters in output — Rich handles formatting
+6. Tests use `InMemoryBackend` and `tests/factories.py` — never construct `NormalizedSpan` directly
+
+**Read [CLAUDE.md](./CLAUDE.md) for the full architecture, development guide, and current rules.**

tokenjam-0.2.0/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.7] - 2026-04-13
+
+### Added
+- **MCP server (`tj mcp`)** — stdio-based Model Context Protocol server giving Claude Code direct access to OCW observability data. 13 tool handlers: status, traces, alerts, budget headroom, cost summary, drift report, tool stats, trace detail, acknowledge alerts, setup project, list sessions, open dashboard. Dual-mode operation: routes queries through REST API when `tj serve` is running, falls back to read-only DuckDB otherwise. Auto-starts `tj serve` on demand.
+- **Claude Code integration (`tj onboard --claude-code`)** — one-command setup for Claude Code telemetry. Configures OTLP log exporter in `~/.claude/settings.json`, sets project-level `OTEL_RESOURCE_ATTRIBUTES`, adds Docker-compatible endpoint to shell env, and optionally installs background daemon. Re-runs resync the auth header to fix 401s without manual setup.
+- **Logs ingestion (`POST /v1/logs`)** — new OTLP log endpoint that converts Claude Code log events (`api_request`, `tool_result`, `api_error`, `user_prompt`, `tool_decision`) into NormalizedSpans with deterministic trace/span IDs. Spans flow through the standard ingest pipeline for cost, alerts, and drift.
+- **`tj drift` CLI** — behavioral drift report with Rich table output showing baseline vs latest session Z-scores per dimension (input tokens, output tokens, duration, tool call count, tool sequence similarity). Color-coded thresholds, `--json` support, exit code 1 if drift detected.
+- **`tj budget` CLI + API** — view and set per-agent daily/session cost limits. `GET/POST /api/v1/budget` endpoints. `resolve_effective_budget()` with per-field fallback so each budget dimension independently falls back to defaults.
+- **Architecture documentation** (`docs/architecture.md`) — comprehensive architecture doc covering design principles, data flow, SDK internals, alert system, drift detection, MCP server, Claude Code pipeline, and testing architecture.
+- `ClaudeCodeEvents` semantic conventions in `tokenjam/otel/semconv.py` for Claude Code log event attributes
+
+### Fixed
+- Budget resolution inconsistency between AlertEngine enforcement and CLI display — both now use `resolve_effective_budget()` with field-level merge
+- Drift display threshold bug in Z-score comparison
+- `tj stop` now passes `-w` to `launchctl unload` to prevent auto-restart on macOS; added Linux systemd support
+- Waterfall tooltip clipping for right-edge spans in web UI
+- CLAUDE.md install command corrected from `pip install tokenjam` to `pip install tokenjam`
+
+### Improved
+- README updated with Claude Code integration section, budget/drift CLI references, MCP server docs
+- Web UI: budget headroom display, cost-today column in active sessions table, tooltip polish
+- Onboard wizard: expanded for Claude Code workflow, status command enhancements
+- MCP tool descriptions optimized for better agent tool selection
+
+### Changed
+- Removed historical task specs from `.claude/specs/` (design intent preserved in `docs/architecture.md`)
+- CLAUDE.md "Task Specs" section replaced with "Further Reading" linking to architecture doc
+- 338 tests passing (up from 223)
+
+## [0.1.6] - 2026-04-08
+
+### Improved
+- **`tj onboard` UX overhaul**
+  - Removed agent ID prompt — agents are auto-discovered when spans arrive
+  - Budget is now a global default (`[defaults.budget]`) that applies to all agents
+  - Per-agent `[agents.X.budget]` overrides the default when configured
+  - Cleaner budget prompt: "Daily budget in USD per agent (0 = no limit, default 5)"
+  - Daemon installs automatically (skip with `--no-daemon`)
+  - Rich next-steps output with instrumentation code example
+  - Minimal config file with commented per-agent example
+
+## [0.1.5] - 2026-04-08
+
+### Fixed
+- **Pricing file missing from pip wheel** — `pricing/models.toml` was at the repo root, outside the `tokenjam/` package. Moved to `tokenjam/pricing/models.toml` so it's included in the wheel. All costs showed `$0.000000` in v0.1.4.
+
+### Improved
+- **Web UI polish** — custom hover tooltips on waterfall bars (cost, duration, model), back arrow on trace detail, agent name heading, tighter layout, hint text on Status and Traces views
+- **Waterfall bar labels** — now show cost alongside duration and model name
+
+### Added
+- Manual release testing checklist (`tests/manual-new-release-tests.md`)
+- Pre-release testing checklist (`tests/manual-pre-release-testing.md`)
+
+### Changed
+- Task specs moved from `.claude/` to `.claude/specs/`
+
+## [0.1.4] - 2026-04-08
+
+### Fixed
+- SDK DuckDB lock error when `tj serve` is running — bootstrap now detects the server and sends spans via HTTP (`TjHttpExporter`) instead of opening DuckDB directly
+- LiteLLM model names no longer include provider prefix (`gpt-4o-mini` not `openai/gpt-4o-mini`), fixing pricing lookup failures
+- LiteLLM streaming wrappers now correctly attribute provider and stripped model name
+
+### Added
+- OpenClaw integration — zero-code OTLP ingestion for OpenClaw agents (PR #15)
+- Web UI restyled to opencla.watch palette (deep navy + electric blue, IBM Plex Mono, Bricolage Grotesque)
+- Inline SVG logo in web UI sidebar
+
+### Changed
+- Node.js upgraded from 20 to 22 in CI and publish workflows
+- npm SDK bumped to 0.1.4 (matching Python release)
+- README: added Web UI section, updated roadmap (4 items complete, 5 new)
+
+## [0.1.3] - 2026-04-07
+
+### Added
+- **Web UI** — local dashboard served by `tj serve` at `http://127.0.0.1:7391/`
+  - Status view with agent cards, cost, tokens, alerts (auto-refresh 5s)
+  - Traces view with span waterfall visualization and click-to-inspect detail
+  - Cost view with breakdown by day/agent/model/tool and summary totals
+  - Alerts view with severity filtering and expandable JSON detail
+  - Drift view with baseline vs latest session Z-score pass/fail
+- `GET /api/v1/status` endpoint — agent status data (mirrors `tj status --json`)
+- Drift endpoint now lists all agents when `agent_id` is omitted
+- LiteLLM provider integration (`patch_litellm()`)
+- Single-file Preact SPA — no build step, dark theme, JetBrains Mono
+
+### Changed
+- CORS updated to regex matching for `localhost:*` ports
+- API key injected into UI via `<meta>` tag (no user prompt needed)
+
+## [0.1.2] - 2026-04-07
+
+### Fixed
+- `tj serve` printing wrong metrics port (9464 instead of 7391)
+- `tj onboard` launchd daemon install now degrades gracefully on failure instead of crashing
+- CLI commands now fall back to REST API when DuckDB is locked by `tj serve`
+
+### Added
+- `tj stop` command — graceful shutdown of daemon or background process
+- `tj uninstall` command — clean removal of all OCW data, config, and daemon
+- 16 runnable example agents across 4 tiers: single provider, single framework, multi-agent, and alerts/drift demos
+- API fallback backend (`ApiBackend`) so CLI works while `tj serve` holds the DB lock
+
+### Changed
+- README: added toy agent quick-start, example agents section, corrected metrics URL, updated CLI reference
+- CLAUDE.md: updated CLI command table, repo layout, added PyPI package name rule
+
+## [0.1.1] - 2026-04-06
+
+### Fixed
+- `tj export` returning empty output due to corrupted DuckDB span indexes
+- `tj status` showing `?` instead of `●` for completed sessions
+- `tj status` showing `$0.000000` cost due to `date.today()` vs UTC date mismatch
+- `tj cost` showing spurious `$0.000000` row from session-level spans with no model
+
+### Added
+- `tj trace` prefix matching — short trace IDs now resolve like git short hashes
+- PyPI and npm publish workflows (`publish-pypi.yml`, `publish-npm.yml`)
+- PyPI metadata: README as long description, classifiers, project URLs
+- `CODEOWNERS` requiring review from @anilmurty
+
+### Changed
+- Renamed npm package from `@tokenjam/sdk` to `@tokenjam/sdk`
+- Consolidated `AGENTS.md` to point at `CLAUDE.md` as source of truth
+
+## [0.1.0] - 2026-04-05
+
+### Added
+- Core observability pipeline: span ingestion, session tracking, cost calculation
+- DuckDB storage backend with migration runner
+- 13 alert types with 6 dispatch channels (stdout, file, ntfy, webhook, Discord, Telegram)
+- Z-score behavioral drift detection with automatic baseline building
+- JSON Schema validation for tool outputs (declared or genson-inferred)
+- CLI commands: `onboard`, `status`, `traces`, `cost`, `alerts`, `drift`, `tools`, `export`, `serve`, `doctor`
+- REST API with OTLP JSON ingest endpoint and Prometheus metrics
+- Python SDK: `@watch()` decorator, `patch_anthropic()`, `patch_openai()`, and 9 more provider/framework integrations
+- TypeScript SDK (`@tokenjam/sdk`): `TjClient` and `SpanBuilder` for Node.js agents
+- Auto-bootstrap: TracerProvider initializes lazily on first `@watch()` or `patch_*()` call
+- Community-maintained model pricing table (`pricing/models.toml`)
+- Session continuity via `conversation_id` across process restarts
+- GitHub Actions CI (Python 3.10/3.11/3.12 + TypeScript)