klaus-agent 0.2.0 → 0.2.2

package/README.md

@@ -2,7 +2,7 @@
 
 Universal agent framework SDK. Inject tools, skills, and systemPrompt to build your agent — no wrapper needed.
 
-通用 Agent 框架 SDK。注入 tools、skills、systemPrompt 即可构建 agent，无需再包一层。
+[中文文档](./README.zh-CN.md)
 
 ## Install
 
@@ -47,12 +47,11 @@ const messages = await agent.prompt("Say hello");
 
 Single package, 14 modules, zero wrappers. All capabilities are built-in and opt-in via config.
 
-单包架构，14 个模块，零包装层。所有能力内置，通过 config 按需启用。
-
 ```
 src/
 ├── core/           Agent + AgentLoop (nested dual-loop runtime)
-├── llm/            Provider abstraction + Anthropic implementation
+├── llm/            Provider registry + abstraction
+├── providers/      5 built-in protocol providers (Anthropic, OpenAI, OpenAI Responses, OpenAI Codex, Gemini)
 ├── tools/          Tool executor (sequential/parallel) + MCP adapter
 ├── approval/       Queue-based approval system
 ├── session/        JSONL tree persistence with branching
@@ -106,19 +105,26 @@ await agent.dispose();
 
 ### LLM Provider
 
-Provider-agnostic abstraction. Built-in Anthropic provider with streaming, retry (3 attempts, exponential backoff), and extended thinking support.
-
-```typescript
-import { registerProvider, resolveProvider } from "@klaus-ai/agent";
+Provider-agnostic abstraction with 5 built-in protocol providers. All providers support streaming, retry (3 attempts, exponential backoff), and extended thinking. Connect any compatible service by providing a custom `baseUrl`.
 
-// Register a custom provider
-registerProvider("openai", (config) => new MyOpenAIProvider(config.apiKey));
+Built-in providers: `anthropic`, `openai`, `openai-responses`, `openai-codex`, `google`
 
-// Use it
+```typescript
+// Use any built-in provider
 const agent = createAgent({
   model: { provider: "openai", model: "gpt-4", maxContextTokens: 128000 },
   ...
 });
+
+// Connect a compatible service via custom baseUrl
+const agent2 = createAgent({
+  model: { provider: "openai", model: "my-model", maxContextTokens: 128000, baseUrl: "https://my-service/v1" },
+  ...
+});
+
+// Register a fully custom provider
+import { registerProvider } from "@klaus-ai/agent";
+registerProvider("my-provider", (config) => new MyProvider(config.apiKey, config.baseUrl));
 ```
 
 Provider interface:
@@ -131,6 +137,26 @@ interface LLMProvider {
 // Stream events: text | tool_call_start | tool_call_delta | thinking | done | error
 ```
 
+Cost tracking — provide per-million-token pricing via `ModelConfig.cost`, and the agent automatically calculates actual dollar costs on each `message_end` event:
+
+```typescript
+const agent = createAgent({
+  model: {
+    provider: "anthropic",
+    model: "claude-sonnet-4-20250514",
+    maxContextTokens: 200000,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  },
+  ...
+});
+
+agent.subscribe((event) => {
+  if (event.type === "message_end" && event.usage?.cost) {
+    console.log(`Request cost: $${event.usage.cost.total.toFixed(6)}`);
+  }
+});
+```
+
 ### Canonical Message Format
 
 Provider-agnostic message types used throughout the framework: