@puku-ai/sdk 4.0.0 → 4.0.1

package/README.md

@@ -25,6 +25,7 @@ console.log(msg.content[0].text);
 
 - [Install](#install)
 - [Configuration](#configuration)
+- [Supported models](#supported-models)
 - [Usage](#usage)
 - [Working features](#working-features)
 - [Namespace](#namespace)
@@ -65,6 +66,20 @@ const client = new PukuAI({
 });
 ```
 
+Defaults: `maxRetries = 2`, `timeout = 600_000` ms (10 min). 
+
+## Supported models
+
+Exactly three model names are accepted by the Puku gateway. Any other string
+returns a model-not-found error.
+
+| Model         | Family   | Notes |
+|---------------|----------|-------|
+| `puku-ai-2.7` | Puku AI  | Cheaper, lower-latency. |
+| `puku-ai-2.8` | Puku AI  | Default for most workloads. |
+| `opus-4.8`    | Opus     | Strongest reasoning; pick this for fallbacks (`fallbacks: [{ model: "opus-4.8" }]`). |
+
+
 ## Usage
 
 ### Blocking
@@ -140,12 +155,8 @@ All error classes are static members of the `PukuAI` class,
 ## Working features
 
 Every feature below was exercised against the live Puku gateway at
-
-
-```bash
-PUKU_BASE_URL="" \
-PUKU_API_KEY=pk_live_... \
-```
+`PUKU_BASE_URL=` with a `pk_live_*` API key (see
+`.env` and `.env.staging.example`). 
 
 ### Verified against the live gateway
 
@@ -168,6 +179,14 @@ PUKU_API_KEY=pk_live_... \
 |--------------------------------------|--------|------|
 | `client.messages.countTokens`        | ⚠ 404  | SDK POSTs to `/v1/messages/count_tokens` exactly like upstream. Puku's gateway does not proxy this endpoint. |
 | `client.messages.batches.create`     | ⚠ 404  | SDK POSTs to `/v1/messages/batches` exactly like upstream. Puku's gateway does not proxy this endpoint. |
+| `client.beta.agents.*`               | ⚠ 404  | SDK POSTs to `/v1/agents/*` exactly like upstream. Puku's gateway does not proxy these endpoints yet. |
+| `client.beta.environments.*`         | ⚠ 404  | SDK POSTs to `/v1/environments/*` exactly like upstream. Puku's gateway does not proxy these endpoints yet. |
+| `client.beta.sessions.*`             | ⚠ 404  | SDK POSTs to `/v1/sessions/*` exactly like upstream. Puku's gateway does not proxy these endpoints yet. |
+| `client.beta.vaults.*`               | ⚠ 404  | SDK POSTs to `/v1/vaults/*` exactly like upstream. Puku's gateway does not proxy these endpoints yet. |
+| `client.beta.skills.{listVersions, retrieve, delete}` | ⚠ 404 | SDK POSTs/GETs to `/v1/skills/{id}/versions/...` exactly like upstream. Puku's gateway does not proxy these endpoints yet. The pure archive-validation helpers (`assertSafeMemberNames`, `assertNoSpecialMembers`, `runArchiveTool`, `archiveTopDir`, `readHead`) remain usable. |
+| `client.messages.batches.results`    | ⚠ n/a  | Not exercised against the live gateway because `batches.create` already 404s. |
+| Structured-outputs JSON parser (`output_format` / `output_config.format`) | ⚠ not wired | The SDK accepts the option but no structured-outputs parser is hooked into the stream finalizer. The `JSONOutputFormat` shape exists in types only. |
+| Server-side `web_search` tool result | ⚠ not proxied | The SDK forwards a `web_search_20250305` tool definition; the gateway does not execute the search and returns the placeholder shape. Use the agent toolset + your own search client instead. |
 
 
 
@@ -198,7 +217,7 @@ const getWeather = {
 
 const finalMessage = await client.beta.messages
   .toolRunner({
-    model: "puku-ai--2.8",
+    model: "puku-ai-2.8",
     max_tokens: 512,
     messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
     tools: [getWeather],
@@ -220,7 +239,7 @@ import PukuAI from "@puku-ai/sdk";
 const client = new PukuAI();
 
 const stream = client.messages.stream({
-  model: "puku-ai--2.8",
+  model: "puku-ai-2.8",
   max_tokens: 128,
   messages: [{ role: "user", content: "Say hello in three languages." }],
 });
@@ -255,7 +274,7 @@ await mcp.connect(clientT);
 const tools = await mcpTools({ mcpClient: mcp });
 
 const reply = await client.beta.messages.create({
-  model: "puku-ai--2.8",
+  model: "puku-ai-2.8",
   max_tokens: 512,
   mcp_servers: [{ type: "url", url: "https://mcp.example.com/sse", name: "example" }],
   messages: [{ role: "user", content: "Find any open PRs." }],
@@ -334,7 +353,7 @@ PukuAI.VERSION;          // SDK version
 ### CJS / ESM shim
 
 When you `require('@puku-ai/sdk')`, the default export is a callable function
-that instantiates `PukuAI` — matching the `@anthropic-ai/sdk` convention:
+that instantiates `PukuAI`:
 
 ```ts
 // CJS or ESM-from-CJS:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puku-ai/sdk",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "PukuAI client SDK",
   "type": "module",
   "main": "./sdk.cjs",

package/sdk.cjs

@@ -7853,9 +7853,9 @@ var init_batches = __esm(() => {
 var MODEL_NONSTREAMING_TOKENS;
 var init_constants = __esm(() => {
   MODEL_NONSTREAMING_TOKENS = {
-    "puku-opus-4@20250514": 8192,
-    "puku.puku-opus-4-1-20250805-v1:0": 8192,
-    "puku-opus-4-1@20250805": 8192
+    "puku-ai-2.7": 8192,
+    "puku-ai-2.8": 8192,
+    "opus-4.8": 8192
   };
 });
 
@@ -8937,7 +8937,7 @@ var init_BetaToolRunner = __esm(() => {
       };
       this.#completion = promiseWithResolvers();
       if (params.compactionControl?.enabled) {
-        console.warn("Puku: The `compactionControl` parameter is deprecated and will be removed in a future version. " + 'Use server-side compaction instead by passing `edits: [{ type: "compact_20260112" }]` in the params passed to `toolRunner()`. ' + "See https://puku.ai/docs/en/build-with-puku/compaction");
+        console.warn("Puku: The `compactionControl` parameter is deprecated and will be removed in a future version. " + 'Use server-side compaction instead by passing `edits: [{ type: "compact_20260112" }]` in the params passed to `toolRunner()`. ' + "See https://puku.sh/docs/");
       }
     }
     async#checkAndCompact() {
@@ -14282,7 +14282,7 @@ function mcpResourceToFile(result) {
 init_ToolError();
 init_node2();
 
-//# debugId=85C7CF95569F331C64756E2164756E21
+//# debugId=012C3C55BCFA558A64756E2164756E21
 
 
 // Capture in a closure so the callable shim doesn't lose the export