@adeildo/pi-providers 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adeildo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @adeildo/pi-providers
+
+[![npm](https://img.shields.io/npm/v/@adeildo/pi-providers)](https://www.npmjs.com/package/@adeildo/pi-providers)
+
+Provider features for [Pi](https://pi.dev). It has one, `subscription`.
+
+```bash
+pi install npm:@adeildo/pi-providers
+```
+
+It also comes in [`@adeildo/pi-harness`](../harness), with the rest of the pieces.
+
+## subscription
+
+With a Claude Pro or Max subscription connected through `/login anthropic`, Pi's requests count as paid extra usage. With `subscription`, they come out of the plan, the way Claude Code's do.
+
+> [!WARNING]
+> This makes Pi introduce itself to Anthropic as Claude Code. Using your subscription from anything other than Claude Code may break Anthropic's terms. It is on once the package is installed, so decide whether you're fine with that risk. To turn it off, switch off the extension in `pi config`, or set `"features": { "subscription": { "enabled": false } }` in the settings file below.
+
+Pi already sends Claude Code's identity with an OAuth token. Anthropic checks two more things before it bills a request to the plan.
+
+1. The user agent. It has to read `claude-cli/<version> (external, cli)`.
+2. The `system` blocks. The first one has to be a billing attribution line, and there can't be anything Claude Code wouldn't send. So pi's own prompt moves to the start of the first user message, wrapped in `<system-instructions>`. The model still reads it there and follows it.
+
+It acts on any provider that uses the Anthropic Messages API with an OAuth token, not only the one called `anthropic`, so a second account registered under another name is billed to its own plan. Requests with an API key go out untouched.
+
+Pi warns about extra usage on every Anthropic OAuth session. With the requests billed to the plan, turn the warning off in `~/.pi/agent/settings.json`:
+
+```json
+{ "warnings": { "anthropicExtraUsage": false } }
+```
+
+### Settings
+
+In `~/.pi/agent/extensions/pi-harness/settings.json`:
+
+| Key                              | Default     | Does                                                                                                    |
+| -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
+| `subscription.claudeCodeVersion` | `"2.1.280"` | The Claude Code version Pi reports. Anthropic won't serve newer models to versions it considers too old |
+
+When a request comes back with `400 claude_code_version_too_old`, raise the version:
+
+```json
+{ "subscription": { "claudeCodeVersion": "2.1.280" } }
+```
+
+## Credit
+
+The idea and the fingerprint come from [pi-claude-max](https://github.com/bradennss/pi-claude-max) by Braden Lamb, MIT. This is a rewrite. It reads the version from settings, carries pi's cache breakpoints over instead of dropping the one-hour TTL, moves every system block after the identity instead of only the second, and checks for an OAuth token instead of the provider name.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@adeildo/pi-providers",
+	"version": "4.0.0",
+	"description": "Provider features for Pi. Bills Anthropic OAuth requests to the Claude Pro or Max plan instead of extra usage.",
+	"keywords": [
+		"anthropic",
+		"claude",
+		"pi",
+		"pi-coding-agent",
+		"pi-extension",
+		"pi-package",
+		"subscription"
+	],
+	"homepage": "https://github.com/felipeadeildo/pi-harness/tree/main/packages/providers#readme",
+	"bugs": "https://github.com/felipeadeildo/pi-harness/issues",
+	"license": "MIT",
+	"author": {
+		"name": "adeildo",
+		"email": "contato@felipeadeildo.com",
+		"url": "https://github.com/felipeadeildo"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/felipeadeildo/pi-harness.git",
+		"directory": "packages/providers"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@adeildo/pi-kit": "4.0.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	}
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+import { createApp } from "@adeildo/pi-kit";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { subscription } from "./subscription/feature.ts";
+
+export { claudeCodeVersion, subscription } from "./subscription/feature.ts";
+
+export default function piProviders(pi: ExtensionAPI): void {
+	createApp(pi, { name: "pi-providers" }).use(subscription).build();
+}

package/src/subscription/billing.ts

@@ -0,0 +1,27 @@
+// How Claude Code tells Anthropic who it is. A request is billed to the Claude plan when it
+// carries Claude Code's user agent and a first system block with a billing attribution, which ends
+// in three characters of the first user message hashed with the version and a salt.
+import { createHash } from "node:crypto";
+
+export const CLAUDE_CODE_IDENTITY = "You are Claude Code, Anthropic's official CLI for Claude.";
+
+const FINGERPRINT_SALT = "59cf53e54c78";
+const SAMPLED_POSITIONS = [4, 7, 20];
+
+export function userAgent(version: string): string {
+	return `claude-cli/${version} (external, cli)`;
+}
+
+/** Positions past the end of the message count as "0", the way Claude Code pads them. */
+export function fingerprint(firstUserText: string, version: string): string {
+	const sampled = SAMPLED_POSITIONS.map((position) => firstUserText[position] ?? "0").join("");
+	return createHash("sha256")
+		.update(`${FINGERPRINT_SALT}${sampled}${version}`)
+		.digest("hex")
+		.slice(0, 3);
+}
+
+export function billingAttribution(firstUserText: string, version: string): string {
+	const stamp = `${version}.${fingerprint(firstUserText, version)}`;
+	return `x-anthropic-billing-header: cc_version=${stamp}; cc_entrypoint=cli;`;
+}

package/src/subscription/feature.ts

@@ -0,0 +1,43 @@
+// Bills Anthropic OAuth requests to the Claude Pro/Max plan instead of extra usage. It acts on any
+// provider that speaks the Anthropic Messages API with an OAuth token, not only the one named
+// `anthropic`, so a second account under another name gets the same treatment.
+import { defineFeature, isObject, matching, setting } from "@adeildo/pi-kit";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { userAgent } from "./billing.ts";
+import { billToPlan } from "./payload.ts";
+
+export const claudeCodeVersion = setting({
+	id: "subscription.claudeCodeVersion",
+	default: "2.1.280",
+	decoder: matching(/^\d+\.\d+\.\d+$/, "a Claude Code version like 2.1.280"),
+	ui: {
+		group: "Providers",
+		label: "Claude Code version",
+		description:
+			"The Claude Code version pi reports to Anthropic. Anthropic refuses newer models to versions it considers too old.",
+	},
+});
+
+export const subscription = defineFeature({
+	id: "subscription",
+	description: "Bill Anthropic OAuth requests to the Claude plan instead of extra usage",
+	settings: [claudeCodeVersion],
+	setup(scope) {
+		scope.on("before_provider_headers", (event, ctx) => {
+			if (usesSubscription(ctx))
+				event.headers["user-agent"] = userAgent(claudeCodeVersion.get(scope));
+		});
+
+		scope.on("before_provider_request", (event, ctx) => {
+			if (!usesSubscription(ctx) || !isObject(event.payload)) return undefined;
+			return billToPlan(event.payload, claudeCodeVersion.get(scope));
+		});
+	},
+});
+
+function usesSubscription(ctx: ExtensionContext): boolean {
+	const model = ctx.model;
+	if (model === undefined || model.api !== "anthropic-messages") return false;
+	return ctx.modelRegistry.isUsingOAuth(model);
+}

package/src/subscription/payload.ts

@@ -0,0 +1,87 @@
+// Rewrites the request pi builds for an Anthropic OAuth token. Anthropic's billing classifier reads
+// `system`, and any text there that Claude Code would not send costs extra usage. So `system` keeps
+// the attribution and the identity, and pi's prompt moves into the first user message, where the
+// model still follows it.
+import { isObject } from "@adeildo/pi-kit";
+
+import { billingAttribution, CLAUDE_CODE_IDENTITY } from "./billing.ts";
+
+export interface TextBlock {
+	type: "text";
+	text: string;
+	cache_control?: unknown;
+}
+
+type Payload = Record<string, unknown>;
+
+export function billToPlan(payload: Payload, version: string): Payload | undefined {
+	const system = claudeCodeSystem(payload.system);
+	if (system === undefined) return undefined;
+
+	const [identity, ...moved] = system;
+	const messages = Array.isArray(payload.messages) ? payload.messages : [];
+	const attribution: TextBlock = {
+		type: "text",
+		text: billingAttribution(firstUserText(messages), version),
+	};
+
+	return {
+		...payload,
+		system: [attribution, identity],
+		messages: prependInstructions(messages, moved),
+	};
+}
+
+function claudeCodeSystem(system: unknown): [TextBlock, ...TextBlock[]] | undefined {
+	if (!Array.isArray(system) || !system.every(isTextBlock)) return undefined;
+	const [first, ...rest] = system;
+	if (first === undefined || !first.text.startsWith(CLAUDE_CODE_IDENTITY)) return undefined;
+	return [first, ...rest];
+}
+
+function isTextBlock(block: unknown): block is TextBlock {
+	return isObject(block) && block.type === "text" && typeof block.text === "string";
+}
+
+function firstUserText(messages: readonly unknown[]): string {
+	const message = messages.find(isUserMessage);
+	if (message === undefined) return "";
+	if (typeof message.content === "string") return message.content;
+	if (!Array.isArray(message.content)) return "";
+	return message.content.find(isTextBlock)?.text ?? "";
+}
+
+function isUserMessage(message: unknown): message is Payload {
+	return isObject(message) && message.role === "user";
+}
+
+function prependInstructions(messages: readonly unknown[], moved: readonly TextBlock[]): unknown[] {
+	const text = moved
+		.map((block) => block.text)
+		.filter((part) => part.trim() !== "")
+		.join("\n\n");
+	if (text === "") return [...messages];
+
+	// The moved prompt takes over the cache breakpoint pi put on it, so the request keeps the same
+	// number of breakpoints and the prompt stays cached on its own.
+	const cacheControl = moved.findLast((block) => block.cache_control !== undefined)?.cache_control;
+	const instructions: TextBlock = {
+		type: "text",
+		text: `<system-instructions>\n${text}\n</system-instructions>`,
+		...(cacheControl === undefined ? {} : { cache_control: cacheControl }),
+	};
+
+	const index = messages.findIndex(isUserMessage);
+	const target = messages[index];
+	if (!isUserMessage(target)) return [{ role: "user", content: [instructions] }, ...messages];
+
+	const updated = [...messages];
+	updated[index] = { ...target, content: [instructions, ...contentBlocks(target.content)] };
+	return updated;
+}
+
+function contentBlocks(content: unknown): unknown[] {
+	if (Array.isArray(content)) return content;
+	if (typeof content === "string" && content !== "") return [{ type: "text", text: content }];
+	return [];
+}