ocp AGENTS.md

Inherits: @~/.cc-rules/AGENTS.md

OCP — Open Claude Proxy — Agent Guidelines

Scope: the dtzp555-max/ocp repository. Audience: any AI coding agent (Claude Code / Cursor / OpenCode / Copilot / Codex / Gemini) touching OCP source.

---

What this project is

OCP (Open Claude Proxy) is an open-source HTTP gateway that sits between the Claude Code CLI (cli.js) and Anthropic's public API. It forwards, observes, and multiplexes traffic that cli.js already emits — it is explicitly not an extension layer. A secondary role: registering OCP as a local provider inside OpenClaw (a sibling IDE-agnostic tool), so that users running OpenClaw against OCP see the same model list as native Claude Code.

Runtime: Node.js (ESM, .mjs throughout). No build step. No bundler. server.mjs is the single executable entrypoint; ocp and ocp-connect are CLI wrappers.

---

Stack

• Node.js 22.13+ (or 23.4+ on the 23 line), native ESM modules — keys.mjs imports node:sqlite at module load and nothing on any launch path passes --experimental-sqlite; see scripts/lib/node-floor.mjs
• http/https built-ins for the proxy core (no Express, no Fastify)
• models.json as the single source of truth for model metadata
• GitHub Actions for CI (alignment.yml, release.yml)
• gh CLI assumed for PR creation and release automation
• No TypeScript. No test framework beyond test-features.mjs (run via npm test; CI workflow .github/workflows/test.yml). Keep dependencies minimal.

---

Key files to know

• server.mjs — the proxy itself; every request path lives here. Governed by ALIGNMENT.md.
• models.json — single source of truth for model IDs, aliases, and context windows. See ADR 0003.
• models.schema.json — the schema models.json declares in its $schema. CI validates the SPOT against it (test-features.mjs) using the repo's own validateJsonSchema, so a malformed entry fails the build instead of surfacing downstream in OpenClaw.
• setup.mjs — first-time installer; reads models.json to derive bootstrap config.
• scripts/sync-openclaw.mjs — idempotent OpenClaw registry sync invoked by ocp update. See ADR 0004.
• ocp — user-facing CLI (install, update, start, stop, status, logs, etc.).
• scripts/b2-key-snapshot.mjs + docs/governance/b2-response-keys.json — the per-release record of every grandfathered Class B.2 endpoint's response key set, read from the wire. npm test boots a real server.mjs, probes every B.2 endpoint+method pair in ALIGNMENT.md's inventory, and fails on any key-path difference from the snapshot. If you add a field to a B.2 response, the suite goes red until you regenerate the snapshot (node scripts/b2-key-snapshot.mjs --write) — and regenerating is not authorization: ADR 0012 condition 5 still requires the field names in the PR body and the CHANGELOG. A removed or renamed key is not covered by ADR 0012 at all and needs its own ADR. Introduced by #346 to replace a CHANGELOG grep that could only ever see additions whose author wrote the marker. Since #357 there are TWO configuration profiles (scripts/b2-key-snapshot.mjs § B2_PROFILES), each with its own snapshot block, its own two-boot stability check and its own ALIGNMENT.md coverage check: probes (the default fleet configuration) and probesTuiPool (CLAUDE_TUI_MODE=true, OCP_TUI_POOL_SIZE=1, CLAUDE_SKIP_PERMISSIONS=true), which is what guards /health's tui.pool counter bag. Neither profile ever runs a real claude pane: OCP_TUI_TMUX_BIN points at a stub tmux that logs its argv and exits 1, and the suite asserts from that log that the only invocation is list-sessions — established by feeding a fake tmux to the real reapStaleTuiSessions: with the real tmux a TUI-mode boot can kill-session a live legacy-named ocp-tui-<8hex> session, and reaches kill-server only when no ordinary session is present (lib/tui/session.mjs's !othersRemain gate). The stub is justified by the reachable kill-session, not by the stronger claim. The snapshot's own notCovered block states what it cannot see; read it before treating a green run as coverage.
• scripts/lib/install-dir.mjs — the single answer to "where is this OCP installed?", resolved from the code's own location (fileURLToPath(import.meta.url)) rather than $HOME. doctor.mjs and upgrade.mjs each used to answer it with join(homedir(), "ocp"), which is wrong on any install not at $HOME/ocp — and the one host that isn't is the hardened one, relocated to /opt under an unprivileged user to close #328's escalation chain, so hardening moved it off the only path the updater could see. Named resolveInstallDir, not resolveOcpDir: keys.mjs already owns that name for the ~/.ocp data directory. Introduced by #350 (#348).
• lib/claude-capability.mjs — the boot-time capability gate for the claude CLI (#455/#462). OCP spawns claude on every request and had no version or capability gate; #453 made that sharper by depending on --system-prompt-file, which claude --help does not list. classifyCapabilityProbe() is pure and returns three verdicts, and the asymmetry is the design: only an observed error: unknown option '--x' is absent and refuses the boot; a missing binary, a blown budget or an unrecognised message is inconclusive, which warns and boots, so the gate cannot brick a fleet on an ambiguous reading. server.mjs does the spawn and the process.exit, following localToolsSafetyError / lib/host-gate.mjs. The probe's argv comes from buildCliArgs, never a hand-written list — that is the #339 shape, and mutation M5 (hardcode it) reddens on --tools. claude parses options before validating their values, so pointing --system-prompt-file at a missing path gives the two outcomes cleanly — and both exit 1, so the message discriminates and the exit code does not. Costs no quota (no model turn). Opt out with OCP_SKIP_CAPABILITY_PROBE=1; budget via CLAUDE_CAPABILITY_PROBE_TIMEOUT_MS. ltBoot sets the skip in its base env before the ...env spread, deliberately unlike OCP_TUI_TMUX_BIN — the tests that pin the gate have to be able to turn it back on.
• lib/spawn-token.mjs — the spawn-token decision extracted from server.mjs's resolveSpawnToken (#429/#343): makeResolveSpawnToken({ isExpiring, now }) applies the 5-minute expiry gate to CACHED creds on every spawn (the #146 forever-stale-token shape). The gate is mutation-proven by a fixed-now contrast test; production binds no injection, so behaviour is identical to the inline original.
• scripts/release-notes.mjs + scripts/lib/release-notes.mjs — what goes in a GitHub Release body, decided in a place npm test can reach. .github/workflows/release.yml used to pipe the CHANGELOG section verbatim into gh release create --notes-file; GitHub caps a body at 125 000 characters, v3.29.3's section is 169 670 bytes by wc -c on the awk's output (169 669 through Buffer.byteLength on what the extractor now returns — the awk appended one trailing newline, and knowing which instrument produced a figure is the difference between the two numbers you will see in this commit), so the API answered 422 … body is too long and v3.29.3 shipped with no Release (#441). The body is now the section when it fits — byte-identical, so nothing changes for a normal release — and otherwise a prefix cut at a block boundary (^#{1,6} or a top-level list marker) plus a pointer to CHANGELOG.md at the tag; assertWithinLimit then refuses loudly rather than letting the API be the only size check. The budget is counted in UTF-8 bytes although the cap is in characters, because a byte count is never smaller than a character count, so passing in bytes passes under either meaning — it costs headroom, never correctness. The workflow's run: body deliberately contains no ${{ }}: test-features.mjs slices it out between the #441 anchors and executes it verbatim, which is the only thing that can catch release.yml no longer calling any of this — a release step is otherwise untestable except by cutting a tag, and a tag is not re-cuttable.
• ALIGNMENT.md — the constitution. Binding for any server.mjs change. See ADR 0002.
• .github/workflows/alignment.yml — CI blacklist grep; fails the build on known-hallucinated tokens.
• CLAUDE.md — Claude-Code-specific session instructions + release_kit overlay (Iron Rule 5.5).
• docs/adr/ — Architecture Decision Records. Read these before proposing governance or SPOT changes. See docs/adr/README.md for the index.
• docs/superpowers/plans/ — active spec-kit plans. docs/superpowers/plans/shipped/ archives plans that have been delivered (don't propose changes against shipped plans — they're history). docs/superpowers/specs/ holds long-lived design documents that other code references (e.g., the SSE heartbeat design referenced from server.mjs).
• memory/constitution.md — spec-kit's project constitution (its standard memory/ location). Distinct from ~/.cc-rules/memory/ (cross-machine personal memory) and from this repo's ALIGNMENT.md (the OCP code-level constitution).