@rynfar/meridian 1.29.0 → 1.29.2

package/README.md

@@ -7,14 +7,34 @@
   <a href="https://www.npmjs.com/package/@rynfar/meridian"><img src="https://img.shields.io/npm/v/@rynfar/meridian?style=flat-square&color=8b5cf6&label=npm" alt="npm"></a>
   <a href="#"><img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-a78bfa?style=flat-square" alt="Platform"></a>
   <a href="#"><img src="https://img.shields.io/badge/license-MIT-c4b5fd?style=flat-square" alt="License"></a>
+  <a href="https://discord.gg/7vNVFYBz"><img src="https://img.shields.io/badge/discord-join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
 </p>
 
 ---
 
-Meridian turns your Claude Max subscription into a local Anthropic API. Any tool that speaks the Anthropic or OpenAI protocol — OpenCode, OpenClaw, Crush, Cline, Aider, Pi, Droid, Open WebUI — connects to Meridian and gets Claude, powered by your existing subscription through the official Claude Code SDK.
-
-> [!IMPORTANT]
-> **Extra Usage billing fix (v0.x.x):** Previous versions defaulted Sonnet to `sonnet[1m]` (1M context), which is [always billed as Extra Usage](https://code.claude.com/docs/en/model-config#extended-context) on Max plans — even when regular usage isn't exhausted. Sonnet now defaults to 200k. If you're on an older version, update or set `MERIDIAN_SONNET_MODEL=sonnet` as a workaround. See [#255](https://github.com/rynfar/meridian/issues/255) for details.
+Meridian bridges the Claude Code SDK to the standard Anthropic API. No OAuth interception. No binary patches. No hacks. Just pure, documented SDK calls. Any tool that speaks the Anthropic or OpenAI protocol — OpenCode, Crush, Cline, Aider, Pi, Droid, Open WebUI — connects to Meridian and gets Claude, with session management, streaming, and prompt caching handled natively by the SDK.
+
+> [!NOTE]
+> ### How Meridian works with Anthropic
+>
+> Meridian is built entirely on the [Claude Code SDK](https://docs.anthropic.com/en/docs/claude-code/sdk). Every request flows through `query()` — the same documented function Anthropic provides for programmatic access. No OAuth tokens are extracted, no binaries are patched, nothing is reverse-engineered.
+>
+> Because we use the SDK, Anthropic remains in full control of prompt caching, context window management, compaction, rate limiting, and authentication. Meridian doesn't bypass these mechanisms — it depends on them. Max subscription tokens flow through the correct channel, governed by the same guardrails Anthropic built into Claude Code.
+>
+> What Meridian adds is a **presentation and interoperability layer**. We translate Claude Code's output into the standard Anthropic API format so developers can connect the editors, terminals, and workflows they prefer. The SDK does the work; Meridian formats the result.
+>
+> If you're looking for a tool that circumvents usage limits or bypasses Anthropic's controls, this project is not for you. We play nice with the SDK because we believe that's how developers can continue to choose their own frontends while respecting Anthropic's platform.
+
+> [!WARNING]
+> ### Why Meridian does not support OpenClaw
+>
+> There is technically a way to make Meridian work with OpenClaw, but we're not interested in pursuing it.
+>
+> The reason Claude Max offers generous usage limits is because Anthropic can justify it through Claude Code — their harness, their optimizations, their control. OpenClaw blows through that with autonomous workflows that Anthropic has little ability to manage or optimize. Using Opus to check an email when a local model would handle it fine isn't efficient use — it's waste that degrades the plan for everyone.
+>
+> I built Meridian because I believe developers should have the right to use the frontend of their choice. But that right comes with a responsibility: don't wreck the subscription for the rest of us. Sloppy autonomous agents that burn through Claude Max tokens are directly counter-productive to developers like me who depend on the plan being sustainable.
+>
+> Meridian's philosophy is simple — play nice with the SDK, let Anthropic optimize how they see fit, and use the frontend you want within the constraints of Claude Code. OpenClaw is not just a frontend; it's an autonomous system that abuses the Max plan. We won't be supporting it.
 
 ## Quick Start
 
@@ -38,13 +58,11 @@ Meridian runs on `http://127.0.0.1:3456`. Point any Anthropic-compatible tool at
 ANTHROPIC_API_KEY=x ANTHROPIC_BASE_URL=http://127.0.0.1:3456 opencode
 ```
 
-The API key value doesn't matter — Meridian authenticates through your Claude Max session, not API keys.
+The API key value is a placeholder — Meridian authenticates through the Claude Code SDK, not API keys. Most Anthropic-compatible tools require this field to be set, but any value works.
 
 ## Why Meridian?
 
-You're paying for Claude Max. It includes programmatic access through the Claude Code SDK. But your favorite coding tools expect an Anthropic API endpoint and an API key.
-
-Meridian bridges that gap. It runs locally, accepts standard Anthropic API requests, and routes them through the SDK using your Max subscription.
+The Claude Code SDK provides programmatic access to Claude. But your favorite coding tools expect an Anthropic API endpoint. Meridian bridges that gap — it runs locally, accepts standard API requests, and routes them through the SDK. Claude Code does the heavy lifting; Meridian translates the output.
 
 <p align="center">
   <img src="assets/how-it-works.svg" alt="How Meridian works" width="920"/>
@@ -275,29 +293,6 @@ MERIDIAN_DEFAULT_AGENT=pi meridian
 
 Pi mimics Claude Code's User-Agent, so automatic detection isn't possible. The `MERIDIAN_DEFAULT_AGENT` env var tells Meridian to use the pi adapter for all unrecognized requests. If you run other agents alongside pi, use the `x-meridian-agent: pi` header instead (requires pi-ai support for custom headers).
 
-### OpenClaw
-
-OpenClaw uses `@mariozechner/pi-ai` under the hood, so the pi adapter handles it with no additional code. Add a provider override in `~/.openclaw/openclaw.json`:
-
-```json
-{
-  "models": {
-    "providers": {
-      "anthropic": {
-        "baseUrl": "http://127.0.0.1:3456",
-        "apiKey": "dummy",
-        "models": [
-          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6 (Meridian)" },
-          { "id": "claude-opus-4-6", "name": "Claude Opus 4.6 (Meridian)" }
-        ]
-      }
-    }
-  }
-}
-```
-
-Then start Meridian with the pi adapter: `MERIDIAN_DEFAULT_AGENT=pi meridian`
-
 ### Any Anthropic-compatible tool
 
 ```bash
@@ -316,7 +311,6 @@ export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
 | [Aider](https://github.com/paul-gauthier/aider) | ✅ Verified | Env vars — file editing, streaming; `--no-stream` broken (litellm bug) |
 | [Open WebUI](https://github.com/open-webui/open-webui) | ✅ Verified | OpenAI-compatible endpoints — set base URL to `http://127.0.0.1:3456` |
 | [Pi](https://github.com/mariozechner/pi-coding-agent) | ✅ Verified | models.json config (see above) — requires `MERIDIAN_DEFAULT_AGENT=pi` |
-| [OpenClaw](https://github.com/openclaw/openclaw) | ✅ Verified | Provider config (see above) — uses pi adapter via `MERIDIAN_DEFAULT_AGENT=pi` |
 | [Continue](https://github.com/continuedev/continue) | 🔲 Untested | OpenAI-compatible endpoints should work — set `apiBase` to `http://127.0.0.1:3456` |
 
 Tested an agent or built a plugin? [Open an issue](https://github.com/rynfar/meridian/issues) and we'll add it.
@@ -488,10 +482,10 @@ npm run build  # build with bun + tsc
 ## FAQ
 
 **Is this allowed by Anthropic's terms?**
-Meridian uses the official Claude Code SDK — the same SDK Anthropic publishes for programmatic access. It authenticates through your existing Claude Max session using OAuth.
+Meridian uses the official Claude Code SDK — the same SDK Anthropic publishes and documents for programmatic access. It does not intercept credentials, modify binaries, or bypass any authentication. All requests flow through the SDK's own authentication and rate-limiting mechanisms.
 
 **How is this different from using an API key?**
-API keys are billed per token. Claude Max is a flat monthly fee. Meridian lets you use that subscription from any compatible tool.
+API keys provide direct API access billed per token. Claude Max includes programmatic access through the Claude Code SDK. Meridian translates SDK responses into the standard Anthropic API format, allowing compatible tools to connect through Claude Code.
 
 **What happens if my OAuth token expires?**
 Tokens expire roughly every 8 hours. Meridian detects the expiry, refreshes the token automatically, and retries the request — so requests continue transparently. If the refresh fails (e.g. the refresh token has expired after weeks of inactivity), Meridian returns a clear error telling you to run `claude login`.
@@ -514,7 +508,7 @@ You haven't run `meridian setup`. Without the plugin, OpenCode requests won't ha
 
 ## Contributing
 
-Issues and PRs welcome. See [`ARCHITECTURE.md`](ARCHITECTURE.md) for module structure and dependency rules, [`CLAUDE.md`](CLAUDE.md) for coding guidelines, and [`E2E.md`](E2E.md) for end-to-end test procedures.
+Issues and PRs welcome. Join the [Discord](https://discord.gg/7vNVFYBz) to discuss ideas before opening issues. See [`ARCHITECTURE.md`](ARCHITECTURE.md) for module structure and dependency rules, [`CLAUDE.md`](CLAUDE.md) for coding guidelines, and [`E2E.md`](E2E.md) for end-to-end test procedures.
 
 ## License
 

package/dist/{cli-msyx6dnk.js → cli-trtwsfge.js}

@@ -13833,6 +13833,50 @@ function buildQueryOptions(ctx) {
   };
 }
 
+// src/proxy/betas.ts
+var BILLABLE_BETA_PREFIXES_ON_MAX = [
+  "extended-cache-ttl-"
+];
+var DEFAULT_BETA_POLICY = "allow-safe";
+function getBetaPolicyFromEnv() {
+  const raw2 = process.env.MERIDIAN_BETA_POLICY;
+  if (raw2 === "allow-safe" || raw2 === "strip-all" || raw2 === "allow-all") {
+    return raw2;
+  }
+  return DEFAULT_BETA_POLICY;
+}
+function filterBetasForProfile(rawBetaHeader, profileType, policy = DEFAULT_BETA_POLICY) {
+  if (!rawBetaHeader) {
+    return { forwarded: undefined, stripped: [] };
+  }
+  const parsed = rawBetaHeader.split(",").map((b) => b.trim()).filter(Boolean);
+  if (parsed.length === 0) {
+    return { forwarded: undefined, stripped: [] };
+  }
+  if (profileType === "api") {
+    return { forwarded: parsed, stripped: [] };
+  }
+  if (policy === "allow-all") {
+    return { forwarded: parsed, stripped: [] };
+  }
+  if (policy === "strip-all") {
+    return { forwarded: undefined, stripped: parsed };
+  }
+  const forwarded = [];
+  const stripped = [];
+  for (const beta of parsed) {
+    if (BILLABLE_BETA_PREFIXES_ON_MAX.some((prefix) => beta.startsWith(prefix))) {
+      stripped.push(beta);
+    } else {
+      forwarded.push(beta);
+    }
+  }
+  return {
+    forwarded: forwarded.length > 0 ? forwarded : undefined,
+    stripped
+  };
+}
+
 // src/proxy/session/lineage.ts
 import { createHash as createHash2 } from "crypto";
 var MIN_SUFFIX_FOR_COMPACTION = 2;
@@ -14613,7 +14657,11 @@ function createProxyServer(config = {}) {
         const effortHeader = c.req.header("x-opencode-effort");
         const thinkingHeader = c.req.header("x-opencode-thinking");
         const taskBudgetHeader = c.req.header("x-opencode-task-budget");
-        const betaHeader = profile.type === "api" ? c.req.header("anthropic-beta") : undefined;
+        const rawBetaHeader = c.req.header("anthropic-beta");
+        const betaFilter = filterBetasForProfile(rawBetaHeader, profile.type, getBetaPolicyFromEnv());
+        if (betaFilter.stripped.length > 0) {
+          console.error(`[PROXY] ${requestMeta.requestId} stripped anthropic-beta(s) for Max profile: ${betaFilter.stripped.join(", ")}`);
+        }
         const effort = effortHeader || body.effort || undefined;
         let thinking = body.thinking || undefined;
         if (thinkingHeader !== undefined) {
@@ -14625,10 +14673,7 @@ function createProxyServer(config = {}) {
         }
         const parsedBudget = taskBudgetHeader ? Number.parseInt(taskBudgetHeader, 10) : NaN;
         const taskBudget = Number.isFinite(parsedBudget) ? { total: parsedBudget } : body.task_budget ? { total: body.task_budget.total ?? body.task_budget } : undefined;
-        const betas = betaHeader ? betaHeader.split(",").map((b) => b.trim()).filter(Boolean) : undefined;
-        if (!betaHeader && c.req.header("anthropic-beta")) {
-          console.error(`[PROXY] ${requestMeta.requestId} stripped anthropic-beta header (Max subscription — betas trigger extra usage billing)`);
-        }
+        const betas = betaFilter.forwarded;
         const agentSessionId = adapter.getSessionId(c);
         const profileSessionId = profile.id !== "default" && agentSessionId ? `${profile.id}:${agentSessionId}` : agentSessionId;
         const profileScopedCwd = profile.id !== "default" ? `${workingDirectory}::profile=${profile.id}` : workingDirectory;

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   startProxyServer
-} from "./cli-msyx6dnk.js";
+} from "./cli-trtwsfge.js";
 import"./cli-g9ypdz51.js";
 import"./cli-rtab0qa6.js";
 import"./cli-m9pfb7h9.js";

package/dist/proxy/betas.d.ts

@@ -0,0 +1,70 @@
+/**
+ * anthropic-beta header filtering for Max vs API profiles.
+ *
+ * Some betas (e.g. `extended-cache-ttl-*`) trigger Extra-Usage billing on
+ * Claude Max subscriptions. The default `allow-safe` policy strips only those
+ * for claude-max profiles while forwarding everything else so that prompt
+ * caching, 1M context, fine-grained tool streaming, and interleaved thinking
+ * continue to work as the SDK expects.
+ *
+ * Unconditional stripping (the previous behaviour) caused cache misses on
+ * every turn, which tripled TTFB and inflated token consumption roughly 3x on
+ * long conversations. See issue #278 for the original context.
+ *
+ * An operator can override the policy at runtime via the `MERIDIAN_BETA_POLICY`
+ * env var to force `strip-all` (safest — old behaviour) or `allow-all`
+ * (most permissive — matches api-profile behaviour) without a rebuild.
+ *
+ * This module is pure — no I/O, no imports from server.ts or session/.
+ */
+import type { ProfileType } from "./profiles";
+/**
+ * Beta prefixes that are known to trigger Extra-Usage billing on Max accounts.
+ *
+ * A beta is considered billable if its name starts with any of these strings.
+ * Keep this list conservative — prefer allowing unknown betas through over
+ * silently stripping something the SDK needs for normal operation.
+ */
+export declare const BILLABLE_BETA_PREFIXES_ON_MAX: readonly string[];
+/**
+ * Runtime policy for `anthropic-beta` header handling on claude-max profiles.
+ *
+ * - `allow-safe` (default): forward all betas except those matching
+ *   {@link BILLABLE_BETA_PREFIXES_ON_MAX}. Restores prompt caching + 1M
+ *   context while keeping the original billing-safety intent.
+ * - `strip-all`: the pre-fix (1.28.0 – 1.29.x) behaviour. Drops every beta
+ *   for claude-max profiles. Use this as a kill switch if the allow-safe
+ *   policy ever causes quota surprises.
+ * - `allow-all`: forward every beta unconditionally, same as api profiles.
+ *   Use only if you've verified your Max tier treats all betas as free.
+ */
+export type BetaPolicy = "allow-safe" | "strip-all" | "allow-all";
+export declare const DEFAULT_BETA_POLICY: BetaPolicy;
+export interface BetaFilterResult {
+    /** Betas to forward upstream. `undefined` means no header should be sent. */
+    forwarded: string[] | undefined;
+    /** Betas that were removed. Empty for api-type profiles. */
+    stripped: string[];
+}
+/**
+ * Read the beta policy from the `MERIDIAN_BETA_POLICY` env var.
+ *
+ * Falls back to {@link DEFAULT_BETA_POLICY} for missing or invalid values.
+ * Invalid values are silently ignored rather than crashing the proxy.
+ */
+export declare function getBetaPolicyFromEnv(): BetaPolicy;
+/**
+ * Filter an `anthropic-beta` header value for the given profile type.
+ *
+ * - For `api` profiles, all betas pass through unchanged regardless of policy.
+ * - For `claude-max` profiles, behaviour depends on `policy`:
+ *   - `allow-safe` (default): strip only billable betas
+ *     (see {@link BILLABLE_BETA_PREFIXES_ON_MAX}).
+ *   - `strip-all`: strip every beta.
+ *   - `allow-all`: forward every beta unchanged.
+ * - Whitespace and empty entries are trimmed.
+ * - Returns `forwarded: undefined` when the result would be an empty list so
+ *   callers can omit the header entirely.
+ */
+export declare function filterBetasForProfile(rawBetaHeader: string | undefined, profileType: ProfileType, policy?: BetaPolicy): BetaFilterResult;
+//# sourceMappingURL=betas.d.ts.map

package/dist/proxy/betas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"betas.d.ts","sourceRoot":"","sources":["../../src/proxy/betas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAE1D,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,CAAA;AAEjE,eAAO,MAAM,mBAAmB,EAAE,UAAyB,CAAA;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC/B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,CAMjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,WAAW,EAAE,WAAW,EACxB,MAAM,GAAE,UAAgC,GACvC,gBAAgB,CA0ClB"}

package/dist/proxy/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/proxy/server.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACtE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,CAAA;AAqBvD,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,KAAK,aAAa,EAEnB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAA+B,iBAAiB,EAAE,mBAAmB,EAAsC,MAAM,iBAAiB,CAAA;AAGzI,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAA;AAChE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,CAAA;AAoG7B,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CA0pDhF;AAED,wBAAsB,gBAAgB,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAiEhG"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/proxy/server.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACtE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,CAAA;AAsBvD,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,KAAK,aAAa,EAEnB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAA+B,iBAAiB,EAAE,mBAAmB,EAAsC,MAAM,iBAAiB,CAAA;AAGzI,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAA;AAChE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,CAAA;AAoG7B,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CA8pDhF;AAED,wBAAsB,gBAAgB,CAAC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAiEhG"}

package/dist/server.js

@@ -6,7 +6,7 @@ import {
   getMaxSessionsLimit,
   hashMessage,
   startProxyServer
-} from "./cli-msyx6dnk.js";
+} from "./cli-trtwsfge.js";
 import"./cli-g9ypdz51.js";
 import"./cli-rtab0qa6.js";
 import"./cli-m9pfb7h9.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynfar/meridian",
-  "version": "1.29.0",
+  "version": "1.29.2",
   "description": "Local Anthropic API powered by your Claude Max subscription. One subscription, every agent.",
   "type": "module",
   "main": "./dist/server.js",