@puku-ai/sdk 4.0.5 → 4.0.6

package/README.md

@@ -77,7 +77,6 @@ returns a model-not-found error.
 |---------------|----------|-------|
 | `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
@@ -168,25 +167,155 @@ Every feature below was exercised against the live Puku gateway at
 | `stream.finalMessage()`                            | ✅ works | `MessageStream` |
 | `stream.on("text", cb)` listener                    | ✅ works | `MessageStream` |
 | `client.beta.messages.toolRunner(...).runUntilDone()` | ✅ works | `client.beta.messages` |
+| `client.messages.countTokens`                       | ✅ works | `count-tokens.ts` |
+| `client.messages.batches.create / retrieve / results` | ✅ works | `batch-results.ts` (D1-backed storage) |
+| Server-side `web_search` (both streaming + non-streaming variants) | ✅ works | `web-search.ts`, `web-search-stream.ts` (gateway forwards `tool_use` to puku-research-gateway and maps back to `web_search_tool_result`) |
+| Structured outputs (`output_config.format`) — zod / json-schema / raw / standard-schema | ✅ works (non-streaming; raw occasionally flaky) | `structured-outputs-*.ts` |
 | `ToolError` class (exceptions from the runner)     | ✅ works | `helpers/beta` |
 | MCP helpers (`mcpTool`, `mcpTools`, `mcpMessage`, `mcpMessages`, `mcpResourceToContent`, `mcpResourceToFile`) | ✅ exported | `helpers/beta/mcp` |
 | Agent toolset (`betaAgentToolset20260401`, `betaBashTool`, `betaReadTool`, `betaWriteTool`, `betaEditTool`, `betaGlobTool`, `betaGrepTool`) | ✅ exported | `tools/agent-toolset` |
 | Full error hierarchy (`APIError`, `RateLimitError`, `AuthenticationError`, …) | ✅ works | static on `PukuAI` |
 
-### Known gateway gaps (SDK calls the correct path, gateway returns 404)
+### Known gateway gaps
 
 | Feature                              | Status | Note |
 |--------------------------------------|--------|------|
-| `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. |
+| Structured-outputs JSON parser (`output_config.format`) — streaming variant | ⚠ flaky | Passes most runs but `puku-ai-2.8` / `puku-ai-2.7` occasionally emit a duplicate JSON key in the payload which the SDK's Zod parser rejects. Re-running usually passes — not a regression, just model-output variance. |
+| Structured-outputs JSON parser (`output_config.format`) — `raw` variant | ⚠ flaky | Same root cause: `puku-ai-2.8` occasionally emits non-JSON prose (e.g. `I computed …`) or a malformed JSON payload (e.g. an unterminated string) inside the synthetic tool call, which the SDK's `JSON.parse` rejects. Re-running usually passes — not a regression, just model-output variance. |
+
+### Beta managed-agents surface (preview)
+
+The Puku gateway serves Anthropic-shaped responses for the beta managed-agents
+namespace so SDK code that calls them does not 404. These exist so SDK
+examples round-trip against the live gateway while the full managed-agents
+runtime track is reopened — they are **not a production control plane**.
+
+| Surface                              | Status | What you can do with it |
+|--------------------------------------|--------|-------------------------|
+| `client.beta.sessions.*`             | ✅ works | Run a managed-agent loop — create session, post `events.send`, stream `events.stream`. The gateway drives the LLM turn and emits the same Anthropic-shaped SSE events the SDK's `SessionToolRunner` consumes. |
+| `client.beta.agents.*`               | ⚠ limited | CRUD round-trip. `agents.create` returns a populated `BetaAgent` shape but no remote agent execution. |
+| `client.beta.environments.*`         | ⚠ limited | `POST /environments` returns `{id, status:'ready'}` synchronously — no `creating → ready` polling. |
+| `client.beta.environments.*.work.{poll,ack,heartbeat,stop,retrieve,update}` | ⚠ limited | The work queue round-trips so `WorkPoller`/`EnvironmentWorker` terminate. One synthetic work item per session. |
+| `client.beta.vaults.*`               | ⚠ limited | CRUD + `credentials.create`. Secret tokens are dropped — `vault_ids` passed to `sessions.create` are ignored (sessions don't need credentials in puku). |
+| `client.beta.skills.{create,list,retrieve,delete}` | ⚠ limited | Multipart upload + metadata only. Accepts `files` and `files[]` field names. |
+| `client.beta.skills.versions.{create,list,retrieve,delete}` | ⚠ limited | Multipart upload + metadata only. Idempotent on `(skill_id, version)` — 409 on duplicate. |
+| `client.beta.skills.versions.download` | ⚠ limited | Returns a 22-byte empty-zip body so `response.blob()` decodes a real `Blob`. Real archive bytes are not stored. |
+| `client.files.{upload,list,retrieve,download,delete}` (non-beta `/v1/files`) | ⚠ limited | Bytes held in-memory only — not persisted anywhere durable. |
+
+#### Working example: managed-agent session with `toolRunner`
+
+This is the loop `client.beta.sessions.*` actually drives for you. You create
+a session, post a user message, open the event stream, and the SDK's
+`toolRunner` dispatches any `agent.tool_use` events back through
+`events.send` automatically.
+
+```ts
+import PukuAI from "@puku-ai/sdk";
+
+const client = new PukuAI();
+
+// 1. Create an environment + an agent + a session.
+const env = await client.beta.environments.create({ name: "demo" });
+const agent = await client.beta.agents.create({
+  name: "weather-bot",
+  model: "puku-ai-2.8",
+  environment: { type: "cloud", id: env.id },
+  tools: [
+    // Tools the gateway's tool registry will resolve at agent-turn time.
+    { type: "agent_toolset_20260401" },
+  ],
+});
+const session = await client.beta.sessions.create({
+  agent_id: agent.id,
+  environment_id: env.id,
+});
+
+// 2. Define a runnable tool the gateway will round-trip.
+const getWeather = {
+  name: "get_weather",
+  description: "Return the current temperature for a city.",
+  input_schema: {
+    type: "object",
+    properties: { city: { type: "string" } },
+    required: ["city"],
+  },
+  run: async (input: { city: string }) =>
+    JSON.stringify({ temp_c: 22.4, city: input.city }),
+};
+
+// 3. Post a user message and stream the agent turn.
+await client.beta.sessions.events.send(session.id, {
+  type: "user.message",
+  content: [{ type: "text", text: "What's the weather in Tokyo?" }],
+});
+
+for await (const event of client.beta.sessions.events.stream(session.id)) {
+  // `agent.message` is the final assistant turn; everything before it
+  // is either tool_use / tool_result round-trips or status transitions.
+  if (event.type === "agent.message") {
+    console.log("agent:", event.content);
+  }
+}
+
+// 4. Clean up.
+await client.beta.sessions.delete(session.id);
+await client.beta.agents.delete(agent.id);
+await client.beta.environments.delete(env.id);
+```
+
+#### Working example: skill upload + version
+
+The skills router accepts multipart upload and round-trips a single version
+per skill. Real archive bytes are not stored — `versions.download` returns a
+22-byte empty zip so `response.blob()` succeeds.
+
+```ts
+import PukuAI from "@puku-ai/sdk";
+
+const client = new PukuAI();
+
+// Upload a skill.
+const skill = await client.skills.create({
+  display_name: "my-skill",
+  files: [new File(["# SKILL"], "SKILL.md", { type: "text/markdown" })],
+});
+
+// Add a version (auto-generated timestamp, or pass one explicitly).
+const v1 = await client.beta.skills.versions.create(skill.id, {
+  files: [new File(["# v1"], "SKILL.md", { type: "text/markdown" })],
+});
+
+// List versions, retrieve one, download (returns an empty zip blob).
+const page = await client.beta.skills.versions.list(skill.id);
+const fetched = await client.beta.skills.versions.retrieve(skill.id, v1.version);
+const blob = await client.beta.skills.versions.download(skill.id, v1.version);
+console.log(page.data.length, fetched.version, blob.size); // 1, "20260101T000000Z", 22
+
+// Cleanup — delete cascades to all versions.
+await client.beta.skills.delete(skill.id);
+```
+
+#### Working example: file upload + download (non-beta `/v1/files`)
+
+`client.files.*` is the non-beta Anthropic Files API stub. Bytes are held in
+memory and not persisted anywhere durable.
+
+```ts
+import PukuAI from "@puku-ai/sdk";
+
+const client = new PukuAI();
+
+const file = await client.files.upload({
+  file: new File(["hello"], "hello.txt", { type: "text/plain" }),
+});
+console.log(file.id, file.filename, file.size_bytes); // file_xxx, "hello.txt", 5
+
+const list = await client.files.list();
+const blob = await client.files.download(file.id);
+console.log(await blob.text()); // "hello"
+
+await client.files.delete(file.id);
+```
 
 
 
@@ -263,7 +392,7 @@ import PukuAI, { mcpTools, mcpMessage, mcpMessages, mcpResourceToFile } from "@p
 const client = new PukuAI();
 
 // `mcpTools` converts an MCP client from @modelcontextprotocol/sdk into
-// a list of Anthropic tool definitions. The SDK ships every helper
+
 
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
@@ -318,12 +447,15 @@ import { betaReadTool, betaBashTool } from "@puku-ai/sdk";
 const tools = [betaReadTool({ workdir: "/tmp/sandbox" })];
 ```
 
-> `setupSkills`, `resolveSkillVersion`, and `extractSkillArchive` require
-> `/v1/skills/{id}/versions/{version}` (download/retrieve/list) and
-> `/v1/sessions/{id}`, which the Puku gateway doesn't proxy. 
-> archive-validation helpers (`assertSafeMemberNames`,
-> `assertNoSpecialMembers`, `runArchiveTool`, `archiveTopDir`, `readHead`)
-> stay available — they are pure functions and don't touch the gateway.
+> `setupSkills`, `resolveSkillVersion`, and `extractSkillArchive` round-trip
+> against `/v1/skills/{id}/versions/{version}` + `/v1/sessions/{id}`. The
+> gateway now serves those endpoints (multipart upload + metadata in-memory,
+> download returns a 22-byte empty zip), so the helpers no longer 404 —
+> but `extractSkillArchive` will receive an empty zip body and cannot
+> extract real archive contents. The pure archive-validation helpers
+> (`assertSafeMemberNames`, `assertNoSpecialMembers`, `runArchiveTool`,
+> `archiveTopDir`, `readHead`) stay available — they don't touch the
+> gateway.
 
 ## Namespace
 

package/package.json

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