one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/anthropic-auth.ts

@@ -0,0 +1,98 @@
+/**
+ * The login a request goes out under, and the rest of a request's identity
+ * (lib/ledger): every input that makes pi-ai build a differently shaped
+ * request. An Anthropic OAuth login (a Claude subscription) carries pi's
+ * identity betas and Claude Code's tool names; Sign in with ChatGPT drops
+ * OpenAI's per-message `configuration_update` items and the cache fields
+ * (pi-ai openai-responses.js isChatGPTSignIn); thinking turned off drops
+ * pi-ai's per-message effort markers on a model that takes them. A change
+ * of any of them opens an epoch, so recorded history is never replayed in a
+ * shape pi would not build.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { RequestIdentity } from "./ledger/records.ts";
+
+/** mtime cache: this runs on every provider request, the hottest path there is. */
+let authCache: { mtimeMs: number; oauth: ReadonlySet<string> } | undefined;
+
+/** The providers pi's auth.json holds an OAuth login for. */
+function oauthProviders(): ReadonlySet<string> {
+	// getAgentDir() honours PI_CODING_AGENT_DIR, so an isolated one-code app
+	// reads its own auth.json rather than ~/.pi's.
+	const path = join(getAgentDir(), "auth.json");
+	try {
+		const mtimeMs = statSync(path).mtimeMs;
+		const cached = authCache;
+		if (cached && cached.mtimeMs === mtimeMs) return cached.oauth;
+		const auth = JSON.parse(readFileSync(path, "utf8")) as Record<string, { type?: unknown; refresh?: unknown } | undefined>;
+		const oauth = new Set(Object.entries(auth ?? {}).flatMap(([provider, entry]) => (entry?.type === "oauth" || typeof entry?.refresh === "string" ? [provider] : [])));
+		authCache = { mtimeMs, oauth };
+		return oauth;
+	} catch {
+		authCache = undefined;
+		return new Set();
+	}
+}
+
+/** True when pi's auth.json holds an OAuth login for Anthropic. */
+export function isAnthropicOAuth(): boolean {
+	return oauthProviders().has("anthropic");
+}
+
+/** OpenAI's own endpoint, where pi-ai treats a login that is not an `sk-` key as Sign in with ChatGPT. */
+const OPENAI_API = "https://api.openai.com/v1";
+
+/**
+ * The auth kind a request to `provider` goes out with: "oauth" for an
+ * Anthropic subscription login, "chatgpt" for Sign in with ChatGPT on
+ * OpenAI's own endpoint, else "key".
+ */
+export function authKind(provider: string | undefined, baseUrl?: string): "oauth" | "chatgpt" | "key" {
+	if (provider === "anthropic") return isAnthropicOAuth() ? "oauth" : "key";
+	if (provider === "openai" && baseUrl === OPENAI_API && oauthProviders().has("openai")) return "chatgpt";
+	return "key";
+}
+
+interface IdentityModel {
+	api?: string;
+	provider?: string;
+	id?: string;
+	baseUrl?: string;
+	reasoning?: boolean;
+	thinkingLevelMap?: Record<string, unknown>;
+	compat?: unknown;
+}
+
+/**
+ * Whether pi-ai puts its per-message effort markers in the request (an
+ * effort directive before each earlier reply, a Responses
+ * `configuration_update`): only on a model that takes them, and not while
+ * thinking is off there (pi-ai anthropic-messages.js effortMessages).
+ * Undefined on a model without them, or when the level is unknown.
+ */
+function effortMarkers(model: IdentityModel, thinkingLevel: string | undefined): boolean | undefined {
+	if ((model.compat as { supportsMidConvoEffort?: boolean } | undefined)?.supportsMidConvoEffort !== true || thinkingLevel === undefined) return undefined;
+	return !(thinkingLevel === "off" && model.reasoning === true && model.thinkingLevelMap?.off !== null);
+}
+
+/**
+ * Who a request to `model` goes to and how pi-ai shapes it, as the ledger
+ * records it; a change opens an epoch. `thinkingLevel` is the session's
+ * (`pi.getThinkingLevel()`). Undefined without a full model.
+ */
+export function requestIdentity(model: IdentityModel | undefined, thinkingLevel?: string): RequestIdentity | undefined {
+	if (!model?.api || !model.provider || !model.id) return undefined;
+	const markers = effortMarkers(model, thinkingLevel);
+	return { api: model.api, provider: model.provider, model: model.id, auth: authKind(model.provider, model.baseUrl), ...(markers !== undefined ? { effortMarkers: markers } : {}) };
+}
+
+/**
+ * The identity of a request this session sends to `model` now, under the
+ * session's thinking level (undefined where the API lacks it: a test double).
+ */
+export function sessionIdentity(pi: { getThinkingLevel?: () => string }, model: IdentityModel | undefined): RequestIdentity | undefined {
+	return requestIdentity(model, typeof pi.getThinkingLevel === "function" ? pi.getThinkingLevel() : undefined);
+}

package/extensions/lib/anthropic-payload.ts

@@ -1,7 +1,8 @@
 /**
  * Recognising an Anthropic Messages request body inside a `before_provider_request`
  * payload (pure). Shared by context-management (clear_thinking), compaction
- * (its replayed request) and tool-search (deferred tool definitions).
+ * (its replayed request), tool-search (deferred tool definitions) and
+ * idle-compact (the cache lifetime).
  */
 
 /** Anthropic Messages API shape: `messages` + `max_tokens`, and not an OpenAI `input`. */
@@ -13,3 +14,83 @@ export function looksLikeAnthropicRequest(payload: unknown): boolean {
 	const model = typeof record.model === "string" ? record.model : "";
 	return model.includes("claude") || typeof record.max_tokens === "number";
 }
+
+/**
+ * The payload with `betas` added, each once, after the ones pi set. pi-ai 1.0
+ * sends `payload.betas` as the final `anthropic-beta` header (it wins over a
+ * configured header), so a beta goes here, never into the headers (findings
+ * §54). The payload is returned unchanged when nothing is missing.
+ */
+export function withBetas<T extends Record<string, unknown>>(payload: T, betas: readonly string[]): T {
+	const existing: unknown[] = Array.isArray(payload.betas) ? payload.betas : [];
+	const missing = [...new Set(betas)].filter((beta) => !existing.includes(beta));
+	if (missing.length === 0) return payload;
+	return { ...payload, betas: [...existing, ...missing] };
+}
+
+/** Anthropic's beta for a `role: "system"` message after the first one. */
+export const MID_CONVERSATION_SYSTEM_BETA = "mid-conversation-system-2026-04-07";
+/** Anthropic's beta for a system message's `clear_at`. */
+export const CLEAR_AT_BETA = "mid-conversation-system-clear-at-2026-08-21";
+/** Anthropic's beta for reference-form `tool_addition` blocks. */
+export const MID_CONVERSATION_TOOL_CHANGES_BETA = "mid-conversation-tool-changes-2026-07-01";
+
+type Message = { role?: unknown; content?: unknown };
+type Block = Record<string, unknown> & { cache_control?: unknown };
+
+/** pi's directive-only effort message, which cannot carry a cache mark. */
+export function isEmptySystemMessage(message: Message | undefined): boolean {
+	return message?.role === "system" && Array.isArray(message.content) && message.content.length === 0;
+}
+
+/** A system message with a `clear_at` nudge: a string body, and Anthropic refuses a cache mark on it. */
+function isClearAtMessage(message: Message): boolean {
+	return message?.role === "system" && "clear_at" in (message as object);
+}
+
+/**
+ * The messages with pi's conversation cache mark on the last block that can
+ * carry it. pi marks the last block of the last message it built; system
+ * messages added after it in `before_provider_request` (the context message,
+ * the per-turn budget, a tool addition) would otherwise sit outside the mark,
+ * so it moves onto the last one, as Claude Code marks its own. pi's empty
+ * effort messages and a `clear_at` nudge are skipped over. Unchanged when the
+ * mark already sits there or no added system message ends the request.
+ */
+export function reseatMessageMark<T extends Message>(messages: T[]): T[] {
+	let target = messages.length - 1;
+	while (target >= 0 && (isEmptySystemMessage(messages[target]) || isClearAtMessage(messages[target]))) target--;
+	const tail = messages[target];
+	if (tail?.role !== "system" || !Array.isArray(tail.content) || tail.content.length === 0) return messages;
+	const tailBlocks = tail.content as Block[];
+	if (tailBlocks[tailBlocks.length - 1].cache_control !== undefined) return messages;
+	let from = target - 1;
+	while (from >= 0 && messages[from]?.role === "system") from--;
+	const source = messages[from];
+	if (!source || !Array.isArray(source.content) || source.content.length === 0) return messages;
+	const sourceBlocks = source.content as Block[];
+	const { cache_control, ...unmarked } = sourceBlocks[sourceBlocks.length - 1];
+	if (cache_control === undefined) return messages;
+	const copy = [...messages];
+	copy[from] = { ...source, content: [...sourceBlocks.slice(0, -1), unmarked] };
+	copy[target] = { ...tail, content: [...tailBlocks.slice(0, -1), { ...tailBlocks[tailBlocks.length - 1], cache_control }] };
+	return copy;
+}
+
+/**
+ * Whether a request body caches with a one-hour TTL: a breakpoint on the
+ * system, the tools or a message carries `cache_control.ttl: "1h"` (pi's long
+ * retention on Anthropic, through pi's own compat gating, so the body is the
+ * ground truth). OpenAI bodies have no breakpoints and answer false.
+ */
+export function hasOneHourCache(payload: unknown): boolean {
+	if (!payload || typeof payload !== "object") return false;
+	const body = payload as { system?: unknown; tools?: unknown; messages?: unknown };
+	const list = (value: unknown): unknown[] => (Array.isArray(value) ? value : []);
+	const oneHour = (block: unknown) => (block as { cache_control?: { ttl?: unknown } } | null)?.cache_control?.ttl === "1h";
+	return (
+		list(body.system).some(oneHour) ||
+		list(body.tools).some(oneHour) ||
+		list(body.messages).some((message) => oneHour(message) || list((message as { content?: unknown } | null)?.content).some(oneHour))
+	);
+}

package/extensions/lib/anthropic-server-call.ts

@@ -0,0 +1,230 @@
+/**
+ * The I/O half of the native web tools: one streamed Messages call carrying
+ * an Anthropic server tool, folded by `anthropic-server-tools.ts`.
+ *
+ * A raw `fetch` rather than pi's `completeSimple`: pi's stream parser drops
+ * `server_tool_use` and `web_*_tool_result` blocks, and those carry what
+ * decides between the answer and the fallback. Streamed because a
+ * non-streaming call with server tools can sit past undici's five-minute
+ * headers timeout (findings §43).
+ */
+
+import { type Api, calculateCost, type Model, type Usage } from "@earendil-works/pi-ai";
+import {
+	createServerCallAccumulator,
+	nativeEligibility,
+	type Outcome,
+	parseSseBuffer,
+	pickNativeWebModel,
+	type ServerCallResult,
+	type ThinkingFields,
+	thinkingOff,
+	thinkingRetry,
+	tokenCounts,
+	WEB_SEARCH_COST_PER_REQUEST,
+} from "./anthropic-server-tools.ts";
+
+import { modelSpec } from "./model-policy.ts";
+import { runWithDeadline } from "./operation-deadline.ts";
+
+/** Observed calls take 8 to 16 s; a stuck one gives way to the fallback. */
+const NATIVE_CALL_TIMEOUT_MS = 120_000;
+
+/** pi's header maps: a `null` value removes that header. */
+type HeaderMap = Record<string, string | null>;
+
+export interface ServerCallAuth {
+	apiKey: string;
+	headers?: HeaderMap;
+	baseUrl?: string;
+}
+
+interface ServerCallReply {
+	result: ServerCallResult;
+	/** pi's usage shape with the cost filled in, searches included. */
+	usage: Usage;
+}
+
+/** pi's `Usage` for one call: token cost from the catalog price, plus Anthropic's per-search fee. */
+export function serverCallUsage(model: Model<Api>, result: ServerCallResult): Usage {
+	const usage: Usage = { ...tokenCounts(result.usage), cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+	usage.cost = calculateCost(model, usage);
+	const searches = result.usage.server_tool_use?.web_search_requests ?? 0;
+	usage.cost = { ...usage.cost, total: usage.cost.total + searches * WEB_SEARCH_COST_PER_REQUEST };
+	return usage;
+}
+
+/**
+ * Run one call. The thinking-off fields for `model` are merged into `body`; a
+ * 400 that rejects them is retried once with the fields the error names, and
+ * `learned` (per extension, keyed by `provider/id`) remembers those so later
+ * calls send them first. Throws on any other HTTP error, a timeout or a
+ * cancel; the caller falls back.
+ */
+export async function runServerCall(
+	model: Model<Api>,
+	auth: ServerCallAuth,
+	body: Record<string, unknown>,
+	signal: AbortSignal | undefined,
+	learned?: Map<string, ThinkingFields>,
+): Promise<ServerCallReply> {
+	const url = `${(auth.baseUrl ?? model.baseUrl ?? "https://api.anthropic.com").replace(/\/+$/, "")}/v1/messages`;
+	const headers: Record<string, string> = {};
+	for (const [name, value] of Object.entries({ ...(model.headers as HeaderMap | undefined), ...auth.headers })) {
+		if (value !== null) headers[name] = value;
+	}
+	Object.assign(headers, {
+		"content-type": "application/json",
+		accept: "text/event-stream",
+		"anthropic-version": "2023-06-01",
+		"x-api-key": auth.apiKey,
+	});
+	const timeout = AbortSignal.timeout(NATIVE_CALL_TIMEOUT_MS);
+	const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+
+	const key = modelSpec(model);
+	let thinking = learned?.get(key) ?? thinkingOff(model);
+	for (let attempt = 0; ; attempt++) {
+		const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({ ...body, ...thinking }), signal: combined });
+		if (!response.ok) {
+			const text = await response.text();
+			const message = errorMessage(text);
+			const retry = response.status === 400 && attempt === 0 ? thinkingRetry(message) : undefined;
+			if (retry) {
+				thinking = retry;
+				continue;
+			}
+			throw new Error(`Anthropic API error (${response.status}): ${message}`);
+		}
+		// Remembered only once the model accepted them, so an unrelated 400 that
+		// happens to name a switch cannot pin wrong fields for the session.
+		if (attempt > 0) learned?.set(key, thinking);
+		const accumulator = createServerCallAccumulator();
+		try {
+			await readStream(response, accumulator);
+		} catch (error) {
+			// The tokens and searches streamed before the break were still billed.
+			throw new ServerCallError((error as Error).message, serverCallUsage(model, accumulator.result()), error);
+		}
+		const result = accumulator.result();
+		return { result, usage: serverCallUsage(model, result) };
+	}
+}
+
+/** The slice of pi's model registry the resolver reads. */
+interface RegistryLike {
+	getAvailable(): Model<Api>[];
+	getApiKeyAndHeaders(
+		model: Model<Api>,
+	): Promise<{ ok: true; apiKey?: string; headers?: HeaderMap; baseUrl?: string } | { ok: false; error: string }>;
+}
+
+type NativeWebTarget = { ok: true; model: Model<Api>; auth: ServerCallAuth } | { ok: false; reason: string };
+
+/**
+ * Whether this session runs the native web tools, and on which model with
+ * which credentials. Not-eligible is the normal case on every other provider,
+ * so callers use the reason only for diagnostics, never in a result.
+ */
+async function resolveNativeWeb(ctx: { model?: Model<Api>; modelRegistry: RegistryLike }, signal: AbortSignal): Promise<NativeWebTarget> {
+	const session = ctx.model;
+	if (!session || session.provider !== "anthropic") return { ok: false, reason: "not an Anthropic session" };
+	const sessionAuth = await ctx.modelRegistry.getApiKeyAndHeaders(session);
+	signal.throwIfAborted();
+	if (!sessionAuth.ok) return { ok: false, reason: sessionAuth.error };
+	const eligible = nativeEligibility({ sessionModel: session, baseUrl: sessionAuth.baseUrl, apiKey: sessionAuth.apiKey });
+	if (!eligible.ok) return eligible;
+	const model = pickNativeWebModel(ctx.modelRegistry.getAvailable(), session);
+	if (!model) return { ok: false, reason: "no model on this provider supports dynamic filtering (Claude 4.6 or later)" };
+	// The pick is same-provider, but its credentials are resolved on their own
+	// and checked again: a per-model base URL or key must not slip past the gate.
+	const auth = model === session ? sessionAuth : await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	signal.throwIfAborted();
+	if (!auth.ok || !auth.apiKey || !nativeEligibility({ sessionModel: model, baseUrl: auth.baseUrl, apiKey: auth.apiKey }).ok) {
+		return { ok: false, reason: `no usable credentials for ${model.provider}/${model.id}` };
+	}
+	return { ok: true, model, auth: { apiKey: auth.apiKey, headers: auth.headers, baseUrl: auth.baseUrl } };
+}
+
+export type NativeAttempt =
+	/** The session cannot use the native tools; today's path runs with no note. */
+	| { kind: "skipped" }
+	| { kind: "answered"; text: string; cutOff: boolean; spec: string; result: ServerCallResult }
+	/** The call ran and did not answer; `reason` goes into the fallback's note. */
+	| { kind: "fell-back"; reason: string }
+	| { kind: "cancelled" };
+
+/**
+ * The native step both web tools share: resolve, call, report usage, and
+ * decide with `outcome` whether the call answered. Never throws: a failure
+ * is a `fell-back` with the reason, a cancel is `cancelled`.
+ */
+export async function tryNativeWeb(
+	ctx: { model?: Model<Api>; modelRegistry: RegistryLike },
+	request: {
+		body: (modelId: string) => Record<string, unknown>;
+		outcome: (result: ServerCallResult) => Outcome;
+		onUsage: (usage: Usage) => void;
+		/** Called once the native path is chosen, before the call (a progress update). */
+		onStart?: (spec: string) => void;
+		/** The caller's per-session memo of each model's thinking-off fields. */
+		learned?: Map<string, ThinkingFields>;
+		signal: AbortSignal | undefined;
+	},
+): Promise<NativeAttempt> {
+	try {
+		const native = await runWithDeadline((signal) => resolveNativeWeb(ctx, signal), {
+			signal: request.signal,
+			timeoutMs: NATIVE_CALL_TIMEOUT_MS,
+			message: "Native web authentication did not answer within 120 seconds.",
+		});
+		if (!native.ok) return { kind: "skipped" };
+		const spec = modelSpec(native.model);
+		request.onStart?.(spec);
+		const reply = await runServerCall(native.model, native.auth, request.body(native.model.id), request.signal, request.learned);
+		request.onUsage(reply.usage);
+		const outcome = request.outcome(reply.result);
+		return outcome.ok
+			? { kind: "answered", text: outcome.text, cutOff: outcome.cutOff, spec, result: reply.result }
+			: { kind: "fell-back", reason: outcome.reason };
+	} catch (error) {
+		if (error instanceof ServerCallError && error.usage.totalTokens > 0) request.onUsage(error.usage);
+		if (request.signal?.aborted) return { kind: "cancelled" };
+		return { kind: "fell-back", reason: `the call failed: ${(error as Error).message}` };
+	}
+}
+
+function errorMessage(body: string): string {
+	try {
+		const parsed = JSON.parse(body) as { error?: { message?: string } };
+		return parsed.error?.message ?? body;
+	} catch {
+		return body;
+	}
+}
+
+/** A stream that broke after it started, with the usage it had reported by then. */
+class ServerCallError extends Error {
+	constructor(
+		message: string,
+		readonly usage: Usage,
+		cause: unknown,
+	) {
+		super(message, { cause });
+	}
+}
+
+async function readStream(response: Response, accumulator: ReturnType<typeof createServerCallAccumulator>): Promise<void> {
+	const reader = response.body?.getReader();
+	if (!reader) throw new Error("Anthropic API returned no response body");
+	const decoder = new TextDecoder();
+	let buffer = "";
+	while (true) {
+		const { done, value } = await reader.read();
+		buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+		const { events, rest } = parseSseBuffer(done ? `${buffer}\n\n` : buffer);
+		buffer = rest;
+		for (const event of events) accumulator.push(event);
+		if (done) break;
+	}
+}