# @danypops/jittor Token and context observability, optimization policies, provider integrations, supervised Bun daemon, and CLI for Jittor. See the [repo root README](../../README.md) for the two-package overview and [`@danypops/pi-jittor`](../pi-jittor) for the Pi extension that talks to this daemon. ## Architecture `src/` is organized by Jittor's domain and concrete integrations: - `observability/` — token, cost, context, task-focus, model-run, and provider-budget observations; its store and source boundaries live beside that model - `optimization/routing/` — budget pressure, route decisions, overrides, and enforcement state - `optimization/model-selection/` — benchmark evidence, model ranking, and their source/store boundaries - `optimization/recovery/` — bounded recovery policies - `sessions/` — session identity and mutation authorization - `codex/`, `openrouter/`, `anthropic/`, `google-vertex/` — provider-specific translation and telemetry - `lmarena/`, `artificial-analysis/` — benchmark-source translation - `sqlite/` — observation and session persistence - `vehicle/` — authenticated operation transport - `daemon.ts` — composition root and maintenance loop - `index.ts` — stable public package surface Dependencies point toward `observability/` and `optimization/`; provider, SQLite, Vehicle, CLI, and Pi models are translated at their boundaries. SQLite runs in WAL mode with versioned migrations, bounded queries, pruning, and checkpoints. Operations currently include bounded metric recording/query/pruning, benchmark and provenance-bearing model-catalog refresh/status/query, context assessment and content-free snapshot deltas, routing control, telemetry polling, and service checkpointing. Every operation is exposed through the authenticated typed client; benchmark operations also have CLI parity. Token counts carry explicit scope and provenance (`provider-reported`, `provider-count-api`, `tokenizer-exact-text`, or `structural-estimate`). Provider aggregates remain authoritative, exact local tokenization is labeled exact for text only, and envelope/media/provider residuals remain explicit instead of being assigned to individual context items. See [`docs/TOKEN_MEASUREMENT.md`](docs/TOKEN_MEASUREMENT.md) for the contract, OpenAI-family adapter, privacy boundary, module benchmark, and E2E test layers. ## Provider telemetry - ChatGPT-authenticated Codex subscription usage - OpenRouter API key usage, response accounting, and model pricing - Anthropic official per-response rate-limit headers (requests, tokens, input/output tokens, and optional Priority Tier buckets) - Google Vertex AI classified failure pressure (quota/auth/invalid-request/overload/transport), since Vertex has no documented remaining-budget header or personal polling endpoint Provider adapters currently include official OpenRouter key/usage/model telemetry and an explicitly experimental Codex subscription adapter. The Codex adapter follows the pinned open-source CLI `/wham/usage` payload and `x-codex-*` response-header contracts, accepts additional metered limits, and fails closed on malformed windows or impossible percentages. File credentials must be explicitly configured and private (`0600`); Jittor reads only the access token and account ID, never refreshes credentials, and never logs or persists OAuth secrets. Anthropic has no personal-account polling endpoint (its Admin/Rate Limits API is documented as unavailable for individual accounts), so Jittor instead reads the official `anthropic-ratelimit-*` response headers Pi observes on every Messages API call and fails closed on schema drift the same way. Google Vertex AI has neither a personal polling endpoint nor a documented remaining-quota response header, so Jittor never fabricates a Vertex budget bar; it instead classifies Vertex's `google.rpc.Status` failure shape (quota, authentication, invalid-request, overload, transport, unknown) from Pi's bounded, content-free `errorMessage` and records only a bounded failure-count metric. If Codex usage becomes `telemetry unavailable`, check `jittor telemetry poll --json`: the active daemon must list `codex-subscription`. A manually started or older npm-installed daemon can own the shared runtime handle while a correctly configured systemd service is inactive; stop that process and restart the configured service. The human status view reports this mismatch without displaying credential paths or values. Jittor never carries an expired percentage across its reset or assumes the reset replenished the subscription—until a fresh provider observation arrives, it reports `reset pending` instead. The third-party `anthropic-vertex` provider (Anthropic Claude models served through Google Vertex, e.g. via `@twogiants/pi-anthropic-vertex`) is tracked separately from both of the above: it reuses Pi's own Anthropic Messages stream implementation with Anthropic's official `@anthropic-ai/vertex-sdk` client, so its wire shape is Anthropic's, but its quota accounting is Google's. Jittor applies Google Vertex's failure classification to it (real-world reports confirm its 429s still carry GCP's own quota-exceeded shape even through Anthropic's own SDK) and, best-effort, also checks for genuine Anthropic rate-limit response headers on it, since it is unverified whether this specific passthrough ever forwards them. Either way, every metric is tagged `anthropic-vertex`, never blended into direct Anthropic's `anthropic` source or Pi's unrelated native `google-vertex` provider, since each represents a different account/quota pool. Blocking always has a daemon-independent escape hatch: `/jittor off` (in the extension) immediately enters persisted monitor-only mode and never blocks provider requests, regardless of daemon state. ## Provenance-bearing model catalog Set `JITTOR_MODELS_DEV_CATALOG=1` to opt into bounded models.dev ingestion. `jittor catalog status|refresh|list [--json]` exposes last-good snapshot state and provider-serving limits, capabilities, modalities, lifecycle, and pricing with per-field authority. Live provider usage/cost remains authoritative; explicit local query overrides win over catalog metadata. See [`docs/MODEL_CATALOG.md`](docs/MODEL_CATALOG.md). ## Benchmark evidence Jittor can ingest bounded OpenRouter model metadata, p50 latency/throughput ordering, and Design Arena Elo rankings as provenance-bearing evidence without treating OpenRouter as model-scope authority. Enable online ingestion explicitly with `JITTOR_OPENROUTER_BENCHMARKS=1`; it is off by default. OpenRouter model metadata and operational ordering are public; Design Arena ingestion additionally uses `OPENROUTER_API_KEY` from the supervised service environment without retaining it. Snapshots preserve the upstream publisher, normalized model identities, immutable retrieval revisions, source URLs, confidence, license terms, and explicit freshness deadlines. A malformed or oversized refresh leaves the last complete snapshot visible and records only a payload-safe failure state. Design Arena rates models across dozens of arena/category pairs (music, video, text-to-speech, ASCII art, ...); Jittor ingests only the bounded allowlist of categories (`codecategories`, `website`, `uicomponent`, `dataviz`, `svg`) that measure frontend/UI-generation skill relevant to routing a coding agent, tagged into one `design` domain distinct from `coding`. A model with no OpenRouter-reachable identity (proprietary platforms, image/video generators) is skipped rather than fabricated into unroutable evidence. Jittor also ingests LMArena's own official Hugging Face dataset (`lmarena-ai/leaderboard-dataset`, via the public `datasets-server.huggingface.co` API -- no credential required) for its Code Arena (`webdev`) and Agent Arena human-preference battles, and, when `ARTIFICIAL_ANALYSIS_API_KEY` is configured, Artificial Analysis's own direct API (adds a `math` domain and measured per-model latency). LMArena's Bradley-Terry/IPS ratings aren't on the same scale as Artificial Analysis's 0-100 indices, so they're tagged under distinct `-arena`-suffixed dimensions instead of blended into the same average. Use the authenticated CLI channels independently: ```text jittor benchmarks status [--json] jittor benchmarks refresh [--force] [--json] jittor benchmarks list --source openrouter-models [--model provider/model] [--dimension name] [--limit 1..500] [--json] ``` Only complete snapshots are queryable. Query output reports both completeness and freshness. See [`docs/BENCHMARK_SOURCES.md`](docs/BENCHMARK_SOURCES.md) for source authority, provenance, conflict, and redistribution rules. The ranking operation (`optimization/model-selection/ranking.ts`) accepts an explicit bounded candidate set and never adds identities found only in evidence. It scores quality (a domain-specific dimension, e.g. `quality-coding`, and a type-specific dimension, e.g. `quality-type-planning`, each optional and additive over the universal `quality-general` fallback), cost, latency, context, and local reliability with bounded user weights, budget-pressure adjustment, component confidence, freshness, provenance, and deterministic tie-breaking. Missing evidence remains unknown and lowers confidence. Jittor separately records content-free local model observations from Pi's public lifecycle: TTFT, wall latency, output throughput, token/cache/cost efficiency, provider retries, tool-loop counts, failures, and two independent classifications derived only from bounded tool names: domain (subject matter, e.g. `coding`) and type (activity, e.g. `research`, `planning`). Prompts, responses, tool arguments/results, credentials, and project paths are never retained. Robust aggregates report sample size, median, p90, median absolute deviation, recency, and confidence without merging local observations into external benchmark facts. ## Content-free OTLP export Configure `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` (or the standard generic endpoint) to opt into bounded asynchronous OTLP/HTTP JSON export. `jittor export status|flush [--json]` reports credential-safe health. The mapper pins evolving GenAI conventions and has no content-capture mode. See [`docs/OTLP_EXPORT.md`](docs/OTLP_EXPORT.md). ## Historical Pi usage backfill `jittor backfill status|dry-run|run|cancel [--json]` imports only persisted content-free Pi usage facts into the same charts as live observations. Opaque identities and atomic SQLite claims make reimport, concurrency, moved sessions, and restart safe; scans and progress are bounded and cancelable. See [`docs/USAGE_BACKFILL.md`](docs/USAGE_BACKFILL.md). ## Context pressure Papyrus emits content-free prompt-injection observations through Pi's shared extension event bus. Jittor validates and records their exact Rule/Task character sizes, prompt share, fingerprint repetition, and explicitly estimated token size. Jittor also records completed, aborted, and unmatched Pi compactions with duration, reason, retry state, provenance-bearing pre/post context, summary size, reduction, regrowth milestones, mechanism identity, and bounded turns/injection/provider/cache/tool/outcome counters since the previous compaction. See [`docs/COMPACTION_EFFECTIVENESS.md`](docs/COMPACTION_EFFECTIVENESS.md). `jittor context [--since ] [--until ] [--json]` reports bounded average/p95/max injection, Rule/Task mix, unchanged rate, compaction frequency/duration/reasons, and between-compaction provider/cache facts. `jittor context delta --session-id [--json]` exposes the latest content-free structural delta; Pi's `/context` view resolves that opaque identity itself. Repeated prompt content is not labeled billed waste: provider-reported input/cache usage and an injection-disabled control are required before making cost or compaction-causality claims. See [`docs/CONTEXT_SNAPSHOTS.md`](docs/CONTEXT_SNAPSHOTS.md) for privacy, lifecycle, truncation, persistence, and stable-prefix semantics. ## CLI operations Every daemon operation is reachable from the CLI through the authenticated typed client only — no command reads the SQLite store or a provider adapter directly. Each command supports `--json` for stable machine output; without it, a purpose-built human presenter renders the same result, per [`docs/OUTPUT_CHANNELS.md`](docs/OUTPUT_CHANNELS.md). ```text jittor metrics record --source --scope --metric --value --unit [--observed-at ] [--attributes ] [--json] jittor metrics record-batch --observations [--json] jittor metrics query [--source ] [--scope ] [--metric ] [--since ] [--until ] [--limit ] [--order asc|desc] [--json] jittor metrics prune --before [--force] [--json] # force required if before is newer than 24h ago jittor metrics distinct-scopes --source --since --until [--limit 1..40] [--json] jittor metrics cost-by-task --since --until [--json] jittor service checkpoint [--json] jittor telemetry poll [--json] jittor compaction estimate [--json] jittor catalog status|refresh|list [--provider ] [--model ] [--limit ] [--json] jittor backfill status|dry-run|run|cancel [--json] jittor export status|flush [--json] jittor session register --session-id [--json] jittor session release --session-id [--session-secret ] [--json] jittor router status|decide|pause|resume|clear-override [--session-id ] [--session-secret ] [--json] jittor router override --route [--expires-at ] [--session-id ] [--session-secret ] [--json] jittor router current-route --route [--session-id ] [--session-secret ] [--json] jittor router available-routes [--route ...] [--session-id ] [--session-secret ] [--json] jittor op [--input ] ``` `jittor op` is a raw escape hatch restricted to the daemon's own `EXPECTED_OPERATION_NAMES`; it rejects an unrecognized operation name before ever reaching the daemon rather than forwarding it blindly. Human-readable metric listings and router status are bounded (at most 50 metric rows and 20 telemetry sources are printed; `--json` output is bounded independently by the daemon's own query and response-size limits). No command prints the daemon bearer token, a provider API key, or an OAuth credential; a daemon-unavailable error stays actionable ("install or start jittor.service") without ever including the token used to reach it. See [`docs/CALIBRATION.md`](docs/CALIBRATION.md) for routing thresholds and rollback, and [`docs/PROVIDER_RESEARCH.md`](docs/PROVIDER_RESEARCH.md) for verified provider API boundaries and caveats. ```bash bun test bun x tsc --noEmit bun run service:install ``` The systemd user unit binds only to `127.0.0.1`, discovers a 256-bit token without logging it, restarts on failure, and exposes authenticated health and operation endpoints.