@rynfar/meridian 1.29.1 → 1.29.2

package/README.md

@@ -7,31 +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 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, OpenClaw, 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.
+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.
 
-> [!IMPORTANT]
-> ### Meridian is unaffected by the April 5, 2025 third-party blocks
+> [!NOTE]
+> ### How Meridian works with Anthropic
 >
-> On April 5, 2025, Anthropic began blocking third-party tools that bypass Claude Code by intercepting OAuth tokens and replaying them against internal API endpoints. Tools that extract `~/.claude/` credentials, proxy raw OAuth bearer tokens, or patch Claude Code binaries to redirect traffic may no longer function.
+> 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.
 >
-> **Meridian does not do any of this.** Its architecture is fundamentally different:
+> 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.
 >
-> - **SDK-native.** Every request calls [`query()`](https://docs.anthropic.com/en/docs/claude-code/sdk) from `@anthropic-ai/claude-agent-sdk` — the same function Anthropic documents for programmatic Claude Code access. No OAuth tokens are extracted, intercepted, or replayed.
-> - **Real Claude Code sessions.** The SDK spawns the actual Claude Code process, manages its own authentication, and handles all communication with Anthropic's servers. Meridian's traffic doesn't *look like* Claude Code — it *is* Claude Code.
-> - **Documented API surface only.** Session resume, MCP tool servers, agent definitions, thinking configuration, permission modes, tool blocking — every feature Meridian uses is a published, documented SDK option. Nothing is reverse-engineered or patched.
-> - **Native benefits and controls preserved.** Prompt caching, conversation persistence, context window management, and compaction all function exactly as they do in Claude Code — because the SDK manages them directly. This means Anthropic's engineering investments in efficiency and their rate-limiting controls work as designed. Max subscription tokens flow through the correct channel, governed by the same guardrails Anthropic built into Claude Code. Meridian doesn't bypass these mechanisms; it depends on them.
+> 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.
 >
-> A small number of adjustments were made in response to the April 5th changes — notably stripping `anthropic-beta` headers that could trigger unintended Extra Usage billing on Max subscriptions ([#281](https://github.com/rynfar/meridian/issues/281)). We are also evaluating system prompt handling to ensure nothing conflicts with Claude Code's expectations. These are compatibility adjustments, not workarounds. Our philosophy is to let Claude Code be the foundation and never fight the SDK — we work with it and add our own layer on top.
+> 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.
 >
-> **Our position is straightforward.** Anthropic asks developers to use Claude Code as the harness for Max subscription access — we do. We call their SDK, respect its authentication flow, use its documented features, and operate within its designed boundaries. We are not circumventing Claude Code; we are building on top of 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.
 >
-> 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. Developers should have the right to choose their own interface and integrate with their own tooling — that's not circumvention, it's the reason SDKs exist.
+> 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.
 >
-> For Meridian to stop working, Anthropic would need to restrict the Claude Code SDK itself or remove documented features that legitimate SDK consumers depend on. We don't believe that's the intent. We're building within Anthropic's ecosystem and constraints because we genuinely value their tools and models. We simply want the freedom to choose how we experience them — and we hope Anthropic sees that as the kind of ecosystem engagement their SDK was designed to enable.
+> 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
 
@@ -290,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
@@ -331,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.
@@ -529,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.1",
+  "version": "1.29.2",
   "description": "Local Anthropic API powered by your Claude Max subscription. One subscription, every agent.",
   "type": "module",
   "main": "./dist/server.js",