typebulb 0.51.3 → 0.52.1

package/README.md

@@ -420,10 +420,10 @@ Run `typebulb models` to list the models available for the providers specified.
 Trusted bulbs can call AI providers **from their own code** at runtime, billed to your API keys.
 
 ```ts
-tb.ai({ messages, system?, effort?, provider?, model?, webSearch? })   // → Promise<{ text }>
+tb.ai({ messages, system?, effort?, provider?, model?, webSearch? })   // → Promise<{ text, usage? }>
 ```
 
-Name the provider and model explicitly — `tb.ai({ provider: "openai", model: "gpt-5.6-luna", … })` — or rely on the defaults you set in `.env`. `webSearch` defaults **off**; pass `webSearch: true` to give the model a web-search tool (searches bill to your key).
+Name the provider and model explicitly — `tb.ai({ provider: "openai", model: "gpt-5.6-luna", … })` — or rely on the defaults you set in `.env`. `webSearch` defaults **off**; pass `webSearch: true` to give the model a web-search tool (searches bill to your key). `usage` is the provider-reported token counts — `{ input, output, reasoning?, cacheRead? }`, reasoning included in `output` — absent when the provider reports none; use it to meter calls instead of estimating from text length.
 
 ### Reasoning effort
 
@@ -446,7 +446,7 @@ const { text } = await tb.ai({
 
 ### Streaming
 
-`tb.ai.stream({ … })` is the streaming counterpart of `tb.ai()` — an async iterable of `{ kind: "text" | "reasoning", text }` deltas. `tb.ai()` (await the full text) is unchanged; reach for `.stream` only when a response is long enough to be worth showing as it arrives.
+`tb.ai.stream({ … })` is the streaming counterpart of `tb.ai()` — an async iterable of `{ kind: "text" | "reasoning", text }` deltas, closed by one `{ kind: "usage", usage }` chunk with the call's token counts. `tb.ai()` (await the full text) is unchanged; reach for `.stream` only when a response is long enough to be worth showing as it arrives.
 
 ```ts
 let answer = "";
@@ -455,7 +455,7 @@ for await (const c of tb.ai.stream({ messages })) {
 }
 ```
 
-Breaking the loop stops the stream; same options as `tb.ai()`. **`kind: "reasoning"` chunks require `effort: 1-4` and a thinking-capable model**.
+Breaking the loop stops the stream; same options as `tb.ai()`. **`kind: "reasoning"` chunks require `effort: 1-4` and a thinking-capable model**. Match `kind` positively as above — a bare `else` that assumes "not reasoning means text" misreads the usage chunk.
 
 ### AI access
 

package/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: typebulb
 description: "Author and run Typebulb bulbs — single-file markdown apps (TypeScript/TSX) that run locally via `npx typebulb` (full power: filesystem, database, `server.ts`, `tb.ai`) or render live inline in your coding agent's session through Typebulb's agent mirror (sandboxed, client-only). A bulb can be a visual widget (chart, simulation, diagram, calculator, UI), a full-stack tool with a Node backend, or an AI app that calls models at runtime. Covers the bulb format, the `tb.*` API, trust, and the local run/inline workflow. Use when the user wants a bulb, a quick local tool (visual, backend-backed, or AI-powered), or something visual rendered inline in the conversation."
-version: 0.51.3
+version: 0.52.1
 ---
 
-> Generated from typebulb v0.51.3. `npx typebulb agent` prints the running version alongside the path to its packaged SKILL.md: if that version is newer than this one, replace this file with that one.
+> Generated from typebulb v0.52.1. `npx typebulb agent` prints the running version alongside the path to its packaged SKILL.md: if that version is newer than this one, replace this file with that one.
 
 # typebulb
 
@@ -428,10 +428,10 @@ Run `typebulb models` to list the models available for the providers specified.
 Trusted bulbs can call AI providers **from their own code** at runtime, billed to your API keys.
 
 ```ts
-tb.ai({ messages, system?, effort?, provider?, model?, webSearch? })   // → Promise<{ text }>
+tb.ai({ messages, system?, effort?, provider?, model?, webSearch? })   // → Promise<{ text, usage? }>
 ```
 
-Name the provider and model explicitly — `tb.ai({ provider: "openai", model: "gpt-5.6-luna", … })` — or rely on the defaults you set in `.env`. `webSearch` defaults **off**; pass `webSearch: true` to give the model a web-search tool (searches bill to your key).
+Name the provider and model explicitly — `tb.ai({ provider: "openai", model: "gpt-5.6-luna", … })` — or rely on the defaults you set in `.env`. `webSearch` defaults **off**; pass `webSearch: true` to give the model a web-search tool (searches bill to your key). `usage` is the provider-reported token counts — `{ input, output, reasoning?, cacheRead? }`, reasoning included in `output` — absent when the provider reports none; use it to meter calls instead of estimating from text length.
 
 ### Reasoning effort
 
@@ -454,7 +454,7 @@ const { text } = await tb.ai({
 
 ### Streaming
 
-`tb.ai.stream({ … })` is the streaming counterpart of `tb.ai()` — an async iterable of `{ kind: "text" | "reasoning", text }` deltas. `tb.ai()` (await the full text) is unchanged; reach for `.stream` only when a response is long enough to be worth showing as it arrives.
+`tb.ai.stream({ … })` is the streaming counterpart of `tb.ai()` — an async iterable of `{ kind: "text" | "reasoning", text }` deltas, closed by one `{ kind: "usage", usage }` chunk with the call's token counts. `tb.ai()` (await the full text) is unchanged; reach for `.stream` only when a response is long enough to be worth showing as it arrives.
 
 ```ts
 let answer = "";
@@ -463,7 +463,7 @@ for await (const c of tb.ai.stream({ messages })) {
 }
 ```
 
-Breaking the loop stops the stream; same options as `tb.ai()`. **`kind: "reasoning"` chunks require `effort: 1-4` and a thinking-capable model**.
+Breaking the loop stops the stream; same options as `tb.ai()`. **`kind: "reasoning"` chunks require `effort: 1-4` and a thinking-capable model**. Match `kind` positively as above — a bare `else` that assumes "not reasoning means text" misreads the usage chunk.
 
 ### AI access