vrr/codeburn
2
0
Fork 0
mirror of https://github.com/AgentSeal/codeburn.git synced 2026-08-21 14:34:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3
codeburn/docs/providers/NEW_PROVIDER.md
ozymandiashh 41deb44b06 chore: pin node via .nvmrc, add the new-provider checklist 
.nvmrc matches the engines floor and the appx pin (22.13.0), taming the
package-lock churn from contributors on drifting node/npm versions. The
checklist distills the house rules new-provider PRs keep relearning:
product split, cache-key coupling, reported-cost presence semantics,
defensive parsing, probeRoots for doctor, and the real-local-testing bar.
2026-08-04 03:17:41 +03:00

2.5 KiB
Raw Permalink Blame History

New provider checklist

Guide for adding a new session-discovery provider to codeburn. Follow every item; most exist because a past provider broke without them.

One provider, one product

  • A provider is one product. Same-vendor IDE and CLI products get separate providers.
  • Precedents: kimi / kimicode, cursor / cursor-agent, cline / cline-cli.
  • Do not merge products under one provider name. PROVIDER_PARSE_VERSIONS and PROVIDER_ENV_VARS are keyed by provider name, so merging couples cache invalidation across products.
  • Separate providers also keep codeburn doctor output legible.

Required pieces

  • src/providers/<name>.ts implementing the Provider contract.
  • Registration in src/providers/index.ts coreProviders (or the lazy list).
  • PROVIDER_ENV_VARS entry in src/session-cache.ts when discovery reads env overrides.
  • PROVIDER_PARSE_VERSIONS entry when cached entries must re-parse after parser changes.
  • probeRoots() is required for new providers, not optional. codeburn doctor uses it to tell "not installed" from "override points somewhere empty" - the silent-$0.00 class (#874, #899).

Cost rules

  • If the tool meters its own per-message cost, add the provider to the reported-cost allowlist in src/parser.ts (providerCallToCachedCall).
  • Cost presence is a PRESENCE check, not truthiness: a metered $0 stays reported (free/cached calls).
  • Computed costs go through calculateCost and set costIsEstimated: true.

Parsing rules

  • Defensive reads on every field - records may be any JSON.
  • Dedup keys namespaced as <provider>:<sessionId>:<messageId>.
  • Timestamps guard against seconds-vs-milliseconds: promote and reject implausible values (see kiro.ts / cline-cli.ts).
  • Never let one corrupt file throw - skip it.

Tests

  • Fixture-based tests under tests/providers/<name>.test.ts covering discovery, parsing, cost semantics, and probeRoots resolution.
  • The suite scrubs env in tests/setup/env-isolation.ts, so tests set their own overrides.

PR expectations

  • Proof of real local testing in the PR body: generated sessions from the actual tool, not only fixtures.
  • No Claude/Anthropic co-author trailers - CI rejects them.
  • Docs page under docs/providers/<name>.md describing the storage layout and any quirks.

Fastest path

Read src/providers/cline-cli.ts end to end first. It is the most recent provider and demonstrates every rule above.