@agi-cli/sdk 0.1.133 → 0.1.135

package/README.md

@@ -4,14 +4,14 @@
 
 ## Overview
 
-`@agi-cli/sdk` is the unified SDK for building AI agents with AGI CLI. It re-exports all functionality from the underlying packages (`@agi-cli/core`, `@agi-cli/providers`, `@agi-cli/auth`, etc.) in a tree-shakable way.
+`@agi-cli/sdk` is the unified SDK for building AI agents with AGI CLI. All authentication, configuration, providers, prompts, tools, and core AI functionality are included in this single package.
 
 **Why use the SDK?**
 - ✅ **Single import**: All functionality from one package
 - ✅ **Tree-shakable**: Bundlers only include what you use
 - ✅ **Type-safe**: Full TypeScript support with comprehensive types
 - ✅ **Zero circular dependencies**: Clean architecture
-- ✅ **Consistent API**: No need to remember which package exports what
+- ✅ **Consistent API**: No need to remember which module exports what
 
 ## Installation
 
@@ -25,7 +25,7 @@ bun add @agi-cli/sdk
 import { generateText, resolveModel } from '@agi-cli/sdk';
 import type { ProviderId } from '@agi-cli/sdk';
 
-const model = resolveModel('anthropic', 'claude-3-5-sonnet-20241022');
+const model = resolveModel('anthropic', 'claude-sonnet-4-20250514');
 
 const { text } = await generateText({
   model,
@@ -37,7 +37,7 @@ console.log(text);
 
 ## What's Included?
 
-### Types (from `@agi-cli/types`)
+### Types
 
 All shared types are available:
 
@@ -52,7 +52,7 @@ import type {
 } from '@agi-cli/sdk';
 ```
 
-### Providers (from `@agi-cli/providers`)
+### Providers
 
 Provider catalog and utilities:
 
@@ -72,16 +72,16 @@ import {
 } from '@agi-cli/sdk';
 
 // Check available providers
-console.log(providerIds); // ['openai', 'anthropic', 'google', 'openrouter', 'opencode']
+console.log(providerIds); // ['openai', 'anthropic', 'google', 'openrouter', 'opencode', 'solforge']
 
 // Get model information
 const models = catalog.anthropic.models;
 
 // Validate provider/model combination
-const result = validateProviderModel('anthropic', 'claude-3-5-sonnet-20241022');
+const result = validateProviderModel('anthropic', 'claude-sonnet-4-20250514');
 ```
 
-### Authentication (from `@agi-cli/auth`)
+### Authentication
 
 Manage API keys and OAuth:
 
@@ -106,35 +106,30 @@ const url = await authorize('anthropic');
 console.log(`Visit: ${url}`);
 ```
 
-### Configuration (from `@agi-cli/config`)
+### Configuration
 
 Load and manage configuration:
 
 ```typescript
-import { loadConfig, readConfig } from '@agi-cli/sdk';
+import { loadConfig } from '@agi-cli/sdk';
 import type { AGIConfig } from '@agi-cli/sdk';
 
 const config = await loadConfig();
 console.log(config.provider); // 'anthropic'
-console.log(config.model);    // 'claude-3-5-sonnet-20241022'
+console.log(config.model);    // 'claude-sonnet-4-20250514'
 ```
 
-### Prompts (from `@agi-cli/prompts`)
+### Prompts
 
 Pre-built system prompts:
 
 ```typescript
-import { systemPrompt, codeContext } from '@agi-cli/sdk';
+import { providerBasePrompt } from '@agi-cli/sdk';
 
-const prompt = systemPrompt('dev', {
-  workdir: '/home/user/project',
-  platform: 'linux',
-});
-
-const context = codeContext({ includeGitInfo: true });
+const prompt = providerBasePrompt('anthropic');
 ```
 
-### Core AI Functions (from `@agi-cli/core`)
+### Core AI Functions
 
 AI SDK re-exports and utilities:
 
@@ -181,28 +176,7 @@ const { object } = await generateObject({
 const tools = await discoverProjectTools('/path/to/project');
 ```
 
-### Database (from `@agi-cli/database`)
-
-Database access:
-
-```typescript
-import { getDb, dbSchema } from '@agi-cli/sdk';
-
-const db = getDb();
-const messages = await db.select().from(dbSchema.messages);
-```
-
-### Server (from `@agi-cli/server`)
-
-Create an HTTP server:
-
-```typescript
-import { createServer } from '@agi-cli/sdk';
-
-const app = createServer();
-```
-
-### Error Handling (from `@agi-cli/core`)
+### Error Handling
 
 Typed error classes:
 
@@ -237,39 +211,30 @@ The SDK is fully tree-shakable. Modern bundlers (Vite, Rollup, esbuild, webpack)
 import { generateText, resolveModel } from '@agi-cli/sdk';
 ```
 
-## Direct Package Access (Not Recommended)
-
-While you _can_ import directly from individual packages, we recommend using the SDK for consistency:
-
-```typescript
-// ❌ Discouraged - fragmented imports
-import { catalog } from '@agi-cli/providers';
-import { generateText } from '@agi-cli/core';
-import type { ProviderId } from '@agi-cli/types';
-
-// ✅ Recommended - single source of truth
-import { catalog, generateText } from '@agi-cli/sdk';
-import type { ProviderId } from '@agi-cli/sdk';
-```
-
 ## Architecture
 
-The SDK follows a clean dependency graph with zero circular dependencies:
+The SDK contains all functionality internally:
 
 ```
-@agi-cli/types (foundation)
-    ↓
-@agi-cli/providers, @agi-cli/auth, @agi-cli/config
-    ↓
-@agi-cli/database, @agi-cli/prompts
-    ↓
-@agi-cli/core
-    ↓
-@agi-cli/server
-    ↓
-@agi-cli/sdk ← YOU ARE HERE (single source of truth)
+@agi-cli/sdk/src/
+├── auth/           ← Authentication (OAuth, API keys)
+├── config/         ← Configuration (global + project)
+├── core/           ← Core AI functionality
+│   ├── providers/     (model resolution)
+│   ├── tools/         (builtin tools)
+│   ├── streaming/     (artifacts)
+│   └── errors.ts      (error classes)
+├── prompts/        ← System prompts
+├── providers/      ← Provider catalog & utilities
+└── index.ts        ← Main exports
 ```
 
+Related packages:
+- `@agi-cli/database` - SQLite persistence (depends on sdk)
+- `@agi-cli/server` - HTTP API (depends on sdk, database)
+- `@agi-cli/api` - Type-safe API client (standalone)
+- `@agi-cli/web-sdk` - React hooks & components (depends on api)
+
 ## Examples
 
 ### Basic Agent
@@ -356,8 +321,7 @@ import type {
   CoreMessage,
   Tool,
   DiscoveredTool,
-  Artifact,
-  ExecutionContext
+  Artifact
 } from '@agi-cli/sdk';
 
 // All types are fully documented and type-safe

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agi-cli/sdk",
-	"version": "0.1.133",
+	"version": "0.1.135",
 	"description": "AI agent SDK for building intelligent assistants - tree-shakable and comprehensive",
 	"author": "ntishxyz",
 	"license": "MIT",

package/src/core/src/terminals/manager.ts

@@ -112,7 +112,7 @@ export class TerminalManager {
 	async killAll(): Promise<void> {
 		const killPromises = Array.from(this.terminals.keys()).map((id) =>
 			this.kill(id).catch((err) =>
-				console.error(`Failed to kill terminal ${id}:`, err),
+				logger.error(`Failed to kill terminal ${id}`, err),
 			),
 		);
 

package/src/index.ts

@@ -42,6 +42,8 @@ export {
 	hasModel,
 	getFastModel,
 	getFastModelForAuth,
+	getModelNpmBinding,
+	isAnthropicBasedModel,
 } from './providers/src/index.ts';
 export {
 	isProviderAuthorized,
@@ -77,6 +79,27 @@ export {
 	filterModelsForAuthType,
 	getOAuthModelPrefixes,
 } from './providers/src/index.ts';
+export {
+	addAnthropicCacheControl,
+	createAnthropicCachingFetch,
+	createConditionalCachingFetch,
+} from './providers/src/index.ts';
+export {
+	createAnthropicOAuthFetch,
+	createAnthropicOAuthModel,
+} from './providers/src/index.ts';
+export type { AnthropicOAuthConfig } from './providers/src/index.ts';
+export { createGoogleModel } from './providers/src/index.ts';
+export type { GoogleProviderConfig } from './providers/src/index.ts';
+export { createZaiModel, createZaiCodingModel } from './providers/src/index.ts';
+export type { ZaiProviderConfig } from './providers/src/index.ts';
+export {
+	getOpenRouterInstance,
+	createOpenRouterModel,
+} from './providers/src/index.ts';
+export type { OpenRouterProviderConfig } from './providers/src/index.ts';
+export { createOpencodeModel } from './providers/src/index.ts';
+export type { OpencodeProviderConfig } from './providers/src/index.ts';
 
 // =======================
 // Authentication (from internal auth module)

package/src/providers/src/anthropic-caching.ts

@@ -0,0 +1,202 @@
+type MessageBlock = {
+	type: string;
+	cache_control?: { type: string };
+	[key: string]: unknown;
+};
+
+type Message = {
+	role: string;
+	content: unknown;
+	[key: string]: unknown;
+};
+
+type ParsedBody = {
+	system?: MessageBlock[];
+	messages?: Message[];
+	[key: string]: unknown;
+};
+
+export function addAnthropicCacheControl(parsed: ParsedBody): ParsedBody {
+	const MAX_SYSTEM_CACHE = 1;
+	const MAX_MESSAGE_CACHE = 1;
+	let systemCacheUsed = 0;
+	let messageCacheUsed = 0;
+
+	if (parsed.system && Array.isArray(parsed.system)) {
+		parsed.system = parsed.system.map((block, index) => {
+			if (block.cache_control) return block;
+			if (
+				systemCacheUsed < MAX_SYSTEM_CACHE &&
+				index === 0 &&
+				block.type === 'text'
+			) {
+				systemCacheUsed++;
+				return { ...block, cache_control: { type: 'ephemeral' } };
+			}
+			return block;
+		});
+	}
+
+	if (parsed.messages && Array.isArray(parsed.messages)) {
+		const messageCount = parsed.messages.length;
+		parsed.messages = parsed.messages.map((msg, msgIndex) => {
+			const isLast = msgIndex === messageCount - 1;
+
+			if (Array.isArray(msg.content)) {
+				const blocks = msg.content as MessageBlock[];
+				const content = blocks.map((block, blockIndex) => {
+					if (block.cache_control) return block;
+					if (
+						isLast &&
+						messageCacheUsed < MAX_MESSAGE_CACHE &&
+						blockIndex === blocks.length - 1
+					) {
+						messageCacheUsed++;
+						return { ...block, cache_control: { type: 'ephemeral' } };
+					}
+					return block;
+				});
+				return { ...msg, content };
+			}
+
+			if (
+				isLast &&
+				messageCacheUsed < MAX_MESSAGE_CACHE &&
+				typeof msg.content === 'string'
+			) {
+				messageCacheUsed++;
+				return {
+					...msg,
+					content: [
+						{
+							type: 'text',
+							text: msg.content,
+							cache_control: { type: 'ephemeral' },
+						},
+					],
+				};
+			}
+
+			return msg;
+		});
+	}
+
+	return parsed;
+}
+
+export function createAnthropicCachingFetch(): typeof fetch {
+	return async (input: RequestInfo | URL, init?: RequestInit) => {
+		let body = init?.body;
+		if (body && typeof body === 'string') {
+			try {
+				const parsed = JSON.parse(body);
+				const modified = addAnthropicCacheControl(parsed);
+				body = JSON.stringify(modified);
+			} catch {
+				// If parsing fails, send as-is
+			}
+		}
+		return fetch(input, { ...init, body });
+	};
+}
+
+export function createConditionalCachingFetch(
+	shouldCache: (model: string) => boolean,
+	model: string,
+): typeof fetch {
+	return async (input: RequestInfo | URL, init?: RequestInit) => {
+		if (!shouldCache(model)) {
+			return fetch(input, init);
+		}
+
+		let body = init?.body;
+		if (body && typeof body === 'string') {
+			try {
+				const parsed = JSON.parse(body);
+
+				const MAX_SYSTEM_CACHE = 1;
+				const MAX_MESSAGE_CACHE = 1;
+				let systemCacheUsed = 0;
+				let messageCacheUsed = 0;
+
+				if (parsed.messages && Array.isArray(parsed.messages)) {
+					const messageCount = parsed.messages.length;
+					parsed.messages = parsed.messages.map(
+						(msg: Message, msgIndex: number) => {
+							if (msg.role === 'system' && systemCacheUsed < MAX_SYSTEM_CACHE) {
+								systemCacheUsed++;
+								if (typeof msg.content === 'string') {
+									return {
+										...msg,
+										content: [
+											{
+												type: 'text',
+												text: msg.content,
+												cache_control: { type: 'ephemeral' },
+											},
+										],
+									};
+								}
+								if (Array.isArray(msg.content)) {
+									const blocks = msg.content as MessageBlock[];
+									const content = blocks.map((block, i) => {
+										if (i === blocks.length - 1 && !block.cache_control) {
+											return { ...block, cache_control: { type: 'ephemeral' } };
+										}
+										return block;
+									});
+									return { ...msg, content };
+								}
+							}
+
+							const isLast = msgIndex === messageCount - 1;
+
+							if (Array.isArray(msg.content)) {
+								const blocks = msg.content as MessageBlock[];
+								const content = blocks.map((block, blockIndex) => {
+									if (block.cache_control) return block;
+									if (
+										isLast &&
+										messageCacheUsed < MAX_MESSAGE_CACHE &&
+										blockIndex === blocks.length - 1
+									) {
+										messageCacheUsed++;
+										return { ...block, cache_control: { type: 'ephemeral' } };
+									}
+									return block;
+								});
+								return { ...msg, content };
+							}
+
+							if (
+								isLast &&
+								messageCacheUsed < MAX_MESSAGE_CACHE &&
+								typeof msg.content === 'string'
+							) {
+								messageCacheUsed++;
+								return {
+									...msg,
+									content: [
+										{
+											type: 'text',
+											text: msg.content,
+											cache_control: { type: 'ephemeral' },
+										},
+									],
+								};
+							}
+
+							return msg;
+						},
+					);
+				}
+
+				body = JSON.stringify(parsed);
+			} catch {
+				// If parsing fails, send as-is
+			}
+		}
+
+		return fetch(input, { ...init, body });
+	};
+}

package/src/providers/src/anthropic-oauth-client.ts

@@ -0,0 +1,157 @@
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { addAnthropicCacheControl } from './anthropic-caching.ts';
+
+const CLAUDE_CLI_VERSION = '1.0.61';
+
+export type AnthropicOAuthConfig = {
+	oauth: {
+		access: string;
+		refresh: string;
+		expires: number;
+	};
+	toolNameTransformer?: (name: string) => string;
+};
+
+function buildOAuthHeaders(accessToken: string): Record<string, string> {
+	const headers: Record<string, string> = {
+		authorization: `Bearer ${accessToken}`,
+		'anthropic-beta':
+			'claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14',
+		'anthropic-dangerous-direct-browser-access': 'true',
+		'anthropic-version': '2023-06-01',
+		'user-agent': `claude-cli/${CLAUDE_CLI_VERSION} (external, cli)`,
+		'x-app': 'cli',
+		'content-type': 'application/json',
+		accept: 'application/json',
+		'x-stainless-arch': process.arch === 'arm64' ? 'arm64' : 'x64',
+		'x-stainless-helper-method': 'stream',
+		'x-stainless-lang': 'js',
+		'x-stainless-os':
+			process.platform === 'darwin'
+				? 'MacOS'
+				: process.platform === 'win32'
+					? 'Windows'
+					: 'Linux',
+		'x-stainless-package-version': '0.70.0',
+		'x-stainless-retry-count': '0',
+		'x-stainless-runtime': 'node',
+		'x-stainless-runtime-version': process.version,
+		'x-stainless-timeout': '600',
+	};
+	return headers;
+}
+
+function filterExistingHeaders(
+	initHeaders: HeadersInit | undefined,
+): Record<string, string> {
+	const headers: Record<string, string> = {};
+	if (!initHeaders) return headers;
+
+	if (initHeaders instanceof Headers) {
+		initHeaders.forEach((value, key) => {
+			if (key.toLowerCase() !== 'x-api-key') {
+				headers[key] = value;
+			}
+		});
+	} else if (Array.isArray(initHeaders)) {
+		for (const [key, value] of initHeaders) {
+			if (
+				key &&
+				key.toLowerCase() !== 'x-api-key' &&
+				typeof value === 'string'
+			) {
+				headers[key] = value;
+			}
+		}
+	} else {
+		for (const [key, value] of Object.entries(initHeaders)) {
+			if (key.toLowerCase() !== 'x-api-key' && typeof value === 'string') {
+				headers[key] = value;
+			}
+		}
+	}
+	return headers;
+}
+
+export function createAnthropicOAuthFetch(
+	config: AnthropicOAuthConfig,
+): typeof fetch {
+	const { oauth, toolNameTransformer } = config;
+
+	return async (input: string | URL | Request, init?: RequestInit) => {
+		const existingHeaders = filterExistingHeaders(init?.headers);
+		const oauthHeaders = buildOAuthHeaders(oauth.access);
+		const headers = { ...existingHeaders, ...oauthHeaders };
+
+		let url = typeof input === 'string' ? input : input.toString();
+		if (url.includes('/v1/messages') && !url.includes('beta=true')) {
+			url += url.includes('?') ? '&beta=true' : '?beta=true';
+		}
+
+		let body = init?.body;
+		if (body && typeof body === 'string') {
+			try {
+				const parsed = JSON.parse(body);
+
+				if (toolNameTransformer) {
+					if (parsed.tools && Array.isArray(parsed.tools)) {
+						parsed.tools = parsed.tools.map(
+							(tool: { name: string; [key: string]: unknown }) => ({
+								...tool,
+								name: toolNameTransformer(tool.name),
+							}),
+						);
+					}
+
+					if (parsed.messages && Array.isArray(parsed.messages)) {
+						parsed.messages = parsed.messages.map(
+							(msg: { content: unknown; [key: string]: unknown }) => {
+								if (Array.isArray(msg.content)) {
+									const content = msg.content.map(
+										(block: {
+											type: string;
+											name?: string;
+											[key: string]: unknown;
+										}) => {
+											if (
+												(block.type === 'tool_use' ||
+													block.type === 'tool_result') &&
+												block.name
+											) {
+												return {
+													...block,
+													name: toolNameTransformer(block.name),
+												};
+											}
+											return block;
+										},
+									);
+									return { ...msg, content };
+								}
+								return msg;
+							},
+						);
+					}
+				}
+
+				const withCache = addAnthropicCacheControl(parsed);
+				body = JSON.stringify(withCache);
+			} catch {
+				// If parsing fails, send as-is
+			}
+		}
+
+		return fetch(url, { ...init, body, headers });
+	};
+}
+
+export function createAnthropicOAuthModel(
+	model: string,
+	config: AnthropicOAuthConfig,
+) {
+	const customFetch = createAnthropicOAuthFetch(config);
+	return createAnthropic({
+		apiKey: '',
+		fetch: customFetch as typeof fetch,
+	})(model);
+}

package/src/providers/src/google-client.ts

@@ -0,0 +1,16 @@
+import { google, createGoogleGenerativeAI } from '@ai-sdk/google';
+
+export type GoogleProviderConfig = {
+	apiKey?: string;
+};
+
+export function createGoogleModel(
+	model: string,
+	config?: GoogleProviderConfig,
+) {
+	if (config?.apiKey) {
+		const instance = createGoogleGenerativeAI({ apiKey: config.apiKey });
+		return instance(model);
+	}
+	return google(model);
+}

package/src/providers/src/index.ts

@@ -13,6 +13,8 @@ export {
 	hasModel,
 	getFastModel,
 	getFastModelForAuth,
+	getModelNpmBinding,
+	isAnthropicBasedModel,
 } from './utils.ts';
 export { validateProviderModel } from './validate.ts';
 export { estimateModelCostUsd } from './pricing.ts';
@@ -41,3 +43,24 @@ export {
 	filterModelsForAuthType,
 	getOAuthModelPrefixes,
 } from './oauth-models.ts';
+export {
+	addAnthropicCacheControl,
+	createAnthropicCachingFetch,
+	createConditionalCachingFetch,
+} from './anthropic-caching.ts';
+export {
+	createAnthropicOAuthFetch,
+	createAnthropicOAuthModel,
+} from './anthropic-oauth-client.ts';
+export type { AnthropicOAuthConfig } from './anthropic-oauth-client.ts';
+export { createGoogleModel } from './google-client.ts';
+export type { GoogleProviderConfig } from './google-client.ts';
+export { createZaiModel, createZaiCodingModel } from './zai-client.ts';
+export type { ZaiProviderConfig } from './zai-client.ts';
+export {
+	getOpenRouterInstance,
+	createOpenRouterModel,
+} from './openrouter-client.ts';
+export type { OpenRouterProviderConfig } from './openrouter-client.ts';
+export { createOpencodeModel } from './opencode-client.ts';
+export type { OpencodeProviderConfig } from './opencode-client.ts';

package/src/providers/src/openai-oauth-client.ts

@@ -14,8 +14,6 @@ export type OpenAIOAuthConfig = {
 	instructions?: string;
 	reasoningEffort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh';
 	reasoningSummary?: 'auto' | 'detailed';
-	promptCacheKey?: string;
-	promptCacheRetention?: 'in_memory' | '24h';
 };
 
 async function ensureValidToken(
@@ -185,19 +183,6 @@ export function createOpenAIOAuthFetch(config: OpenAIOAuthConfig) {
 					}
 				}
 
-				const cacheKey =
-					parsed.providerOptions?.openai?.promptCacheKey ||
-					config.promptCacheKey;
-				const cacheRetention =
-					parsed.providerOptions?.openai?.promptCacheRetention ||
-					config.promptCacheRetention;
-				if (cacheKey) {
-					parsed.prompt_cache_key = cacheKey;
-				}
-				if (cacheRetention) {
-					parsed.prompt_cache_retention = cacheRetention;
-				}
-
 				delete parsed.max_output_tokens;
 				delete parsed.max_completion_tokens;
 

package/src/providers/src/opencode-client.ts

@@ -0,0 +1,80 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { catalog } from './catalog-merged.ts';
+import { createAnthropicCachingFetch } from './anthropic-caching.ts';
+import type { ProviderId } from '../../types/src/index.ts';
+
+export type OpencodeProviderConfig = {
+	apiKey?: string;
+};
+
+function normalizeModelIdentifier(provider: ProviderId, model: string): string {
+	const prefix = `${provider}/`;
+	return model.startsWith(prefix) ? model.slice(prefix.length) : model;
+}
+
+export function createOpencodeModel(
+	model: string,
+	config?: OpencodeProviderConfig,
+) {
+	const entry = catalog.opencode;
+	const normalizedModel = normalizeModelIdentifier('opencode', model);
+	const modelInfo =
+		entry?.models.find((m) => m.id === normalizedModel) ??
+		entry?.models.find((m) => m.id === model);
+	const resolvedModelId = modelInfo?.id ?? normalizedModel ?? model;
+	const binding = modelInfo?.provider?.npm ?? entry?.npm;
+	const apiKey = config?.apiKey ?? process.env.OPENCODE_API_KEY ?? '';
+	const baseURL =
+		modelInfo?.provider?.baseURL ||
+		modelInfo?.provider?.api ||
+		entry?.api ||
+		'https://opencode.ai/zen/v1';
+	const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined;
+
+	if (binding === '@ai-sdk/openai') {
+		const instance = createOpenAI({ apiKey, baseURL });
+		return instance(resolvedModelId);
+	}
+	if (binding === '@ai-sdk/anthropic') {
+		const cachingFetch = createAnthropicCachingFetch();
+		const instance = createAnthropic({
+			apiKey,
+			baseURL,
+			fetch: cachingFetch as typeof fetch,
+		});
+		return instance(resolvedModelId);
+	}
+	if (binding === '@ai-sdk/openai-compatible') {
+		const instance = createOpenAICompatible({
+			name: entry?.label ?? 'opencode',
+			baseURL,
+			headers,
+		});
+		return instance(resolvedModelId);
+	}
+
+	const ocOpenAI = createOpenAI({ apiKey, baseURL });
+	const cachingFetch = createAnthropicCachingFetch();
+	const ocAnthropic = createAnthropic({
+		apiKey,
+		baseURL,
+		fetch: cachingFetch as typeof fetch,
+	});
+	const ocCompat = createOpenAICompatible({
+		name: entry?.label ?? 'opencode',
+		baseURL,
+		headers,
+	});
+
+	const id = resolvedModelId.toLowerCase();
+	if (id.includes('claude')) return ocAnthropic(resolvedModelId);
+	if (
+		id.includes('qwen3-coder') ||
+		id.includes('grok-code') ||
+		id.includes('kimi-k2')
+	)
+		return ocCompat(resolvedModelId);
+	return ocOpenAI(resolvedModelId);
+}

package/src/providers/src/openrouter-client.ts

@@ -0,0 +1,30 @@
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { createConditionalCachingFetch } from './anthropic-caching.ts';
+
+export type OpenRouterProviderConfig = {
+	apiKey?: string;
+};
+
+function isAnthropicModel(model: string): boolean {
+	const lower = model.toLowerCase();
+	return lower.includes('anthropic') || lower.includes('claude');
+}
+
+export function getOpenRouterInstance(
+	model?: string,
+	config?: OpenRouterProviderConfig,
+) {
+	const apiKey = config?.apiKey ?? process.env.OPENROUTER_API_KEY ?? '';
+	const customFetch = model
+		? createConditionalCachingFetch(isAnthropicModel, model)
+		: undefined;
+	return createOpenRouter({ apiKey, fetch: customFetch });
+}
+
+export function createOpenRouterModel(
+	model: string,
+	config?: OpenRouterProviderConfig,
+) {
+	const openrouter = getOpenRouterInstance(model, config);
+	return openrouter.chat(model);
+}

package/src/providers/src/solforge-client.ts

@@ -7,6 +7,7 @@ import { svm } from 'x402/shared';
 import nacl from 'tweetnacl';
 import { createOpenAI } from '@ai-sdk/openai';
 import { createAnthropic } from '@ai-sdk/anthropic';
+import { addAnthropicCacheControl } from './anthropic-caching.ts';
 
 const DEFAULT_BASE_URL = 'https://router.solforge.sh';
 const DEFAULT_RPC_URL = 'https://api.mainnet-beta.solana.com';
@@ -148,87 +149,7 @@ export function createSolforgeFetch(
 					if (promptCacheRetention)
 						parsed.prompt_cache_retention = promptCacheRetention;
 
-					const MAX_SYSTEM_CACHE = 1;
-					const MAX_MESSAGE_CACHE = 1;
-					let systemCacheUsed = 0;
-					let messageCacheUsed = 0;
-
-					if (parsed.system && Array.isArray(parsed.system)) {
-						parsed.system = parsed.system.map(
-							(
-								block: { type: string; cache_control?: unknown },
-								index: number,
-							) => {
-								if (block.cache_control) return block;
-								if (
-									systemCacheUsed < MAX_SYSTEM_CACHE &&
-									index === 0 &&
-									block.type === 'text'
-								) {
-									systemCacheUsed++;
-									return { ...block, cache_control: { type: 'ephemeral' } };
-								}
-								return block;
-							},
-						);
-					}
-
-					if (parsed.messages && Array.isArray(parsed.messages)) {
-						const messageCount = parsed.messages.length;
-						parsed.messages = parsed.messages.map(
-							(
-								msg: {
-									role: string;
-									content: unknown;
-									[key: string]: unknown;
-								},
-								msgIndex: number,
-							) => {
-								const isLast = msgIndex === messageCount - 1;
-
-								if (Array.isArray(msg.content)) {
-									const blocks = msg.content as {
-										type: string;
-										cache_control?: unknown;
-									}[];
-									const content = blocks.map((block, blockIndex) => {
-										if (block.cache_control) return block;
-										if (
-											isLast &&
-											messageCacheUsed < MAX_MESSAGE_CACHE &&
-											blockIndex === blocks.length - 1
-										) {
-											messageCacheUsed++;
-											return { ...block, cache_control: { type: 'ephemeral' } };
-										}
-										return block;
-									});
-									return { ...msg, content };
-								}
-
-								if (
-									isLast &&
-									messageCacheUsed < MAX_MESSAGE_CACHE &&
-									typeof msg.content === 'string'
-								) {
-									messageCacheUsed++;
-									return {
-										...msg,
-										content: [
-											{
-												type: 'text',
-												text: msg.content,
-												cache_control: { type: 'ephemeral' },
-											},
-										],
-									};
-								}
-
-								return msg;
-							},
-						);
-					}
-
+					addAnthropicCacheControl(parsed);
 					body = JSON.stringify(parsed);
 				} catch {}
 			}
@@ -404,7 +325,21 @@ async function processSinglePayment(args: {
 }): Promise<{ attempts: number; balance?: number | string }> {
 	args.callbacks.onPaymentSigning?.();
 
-	const paymentPayload = await createPaymentPayload(args);
+	let paymentPayload: PaymentPayload;
+	try {
+		paymentPayload = await createPaymentPayload(args);
+	} catch (err) {
+		const errMsg = err instanceof Error ? err.message : String(err);
+		const isInsufficientFunds =
+			errMsg.toLowerCase().includes('insufficient') ||
+			errMsg.toLowerCase().includes('not enough') ||
+			errMsg.toLowerCase().includes('balance');
+		const userMsg = isInsufficientFunds
+			? 'Insufficient USDC balance in wallet for payment'
+			: `Payment failed: ${errMsg}`;
+		args.callbacks.onPaymentError?.(userMsg);
+		throw new Error(`Solforge: ${userMsg}`);
+	}
 	const walletHeaders = args.buildWalletHeaders();
 	const headers = {
 		'Content-Type': 'application/json',

package/src/providers/src/utils.ts

@@ -98,3 +98,24 @@ export function getFastModelForAuth(
 
 	return sorted[0]?.id ?? filteredModels[0]?.id;
 }
+
+export function getModelNpmBinding(
+	provider: ProviderId,
+	model: string,
+): string | undefined {
+	const entry = catalog[provider];
+	if (!entry) return undefined;
+	const modelInfo = entry.models?.find((m) => m.id === model);
+	return modelInfo?.provider?.npm ?? entry.npm;
+}
+
+export function isAnthropicBasedModel(
+	provider: ProviderId,
+	model: string,
+): boolean {
+	if (provider === 'anthropic') return true;
+	const npm = getModelNpmBinding(provider, model);
+	if (npm === '@ai-sdk/anthropic') return true;
+	const lower = model.toLowerCase();
+	return lower.includes('claude') || lower.includes('anthropic');
+}

package/src/providers/src/zai-client.ts

@@ -0,0 +1,47 @@
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { catalog } from './catalog-merged.ts';
+
+export type ZaiProviderConfig = {
+	apiKey?: string;
+};
+
+export function createZaiModel(model: string, config?: ZaiProviderConfig) {
+	const entry = catalog.zai;
+	const baseURL = entry?.api || 'https://api.z.ai/api/paas/v4';
+	const apiKey =
+		config?.apiKey ||
+		process.env.ZAI_API_KEY ||
+		process.env.ZHIPU_API_KEY ||
+		'';
+	const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined;
+
+	const instance = createOpenAICompatible({
+		name: entry?.label ?? 'Z.AI',
+		baseURL,
+		headers,
+	});
+
+	return instance(model);
+}
+
+export function createZaiCodingModel(
+	model: string,
+	config?: ZaiProviderConfig,
+) {
+	const entry = catalog['zai-coding'];
+	const baseURL = entry?.api || 'https://api.z.ai/api/coding/paas/v4';
+	const apiKey =
+		config?.apiKey ||
+		process.env.ZAI_API_KEY ||
+		process.env.ZHIPU_API_KEY ||
+		'';
+	const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined;
+
+	const instance = createOpenAICompatible({
+		name: entry?.label ?? 'Z.AI Coding',
+		baseURL,
+		headers,
+	});
+
+	return instance(model);
+}