@jaypie/mcp 0.8.177 → 0.8.179

package/dist/assets.js

@@ -55,11 +55,11 @@ function getMcpAssetPaths() {
  */
 function getMcpBuildInfo() {
     return {
-        commit: "962b054a"
+        commit: "4e0d56bd"
             ,
-        version: "0.8.177"
+        version: "0.8.179"
             ,
-        versionString: "@jaypie/mcp@0.8.177#962b054a"
+        versionString: "@jaypie/mcp@0.8.179#4e0d56bd"
             ,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.8.177",
+  "version": "0.8.179",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/jaypie/1.2.114.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.114
+date: 2026-09-28
+summary: Pulls @jaypie/llm 1.3.55
+---
+
+## Changes
+
+- **`@jaypie/llm` 1.3.55**: usage reports one contract across every provider, with Gemini `output` including thinking tokens (#599); `tokenCost` is exported and bills each token once at its cache TTL; prompt caching defaults to a one-hour TTL; Google, OpenRouter, Fireworks, and Mistral stop sending the system prompt twice; `MODEL.SONNET` moves to Claude Sonnet 5.5.

package/release-notes/jaypie/1.2.115.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.115
+date: 2026-09-28
+summary: Pulls @jaypie/llm 1.3.56
+---
+
+## Changes
+
+- **`@jaypie/llm` 1.3.56**: failing over down a fallback chain logs at `debug` instead of `error` and `warn`; the report tally counts `failures` and `fallbacks`.

package/release-notes/llm/1.3.55.md

@@ -0,0 +1,53 @@
+---
+version: 1.3.55
+date: 2026-09-28
+summary: Usage reports one contract across every provider (reasoning within output, cache within input), tokenCost is exported and bills each token once at its cache TTL, prompt caching defaults to a one-hour TTL, and MODEL.SONNET moves to Claude Sonnet 5.5
+---
+
+## Changes
+
+### Usage contract
+
+`LlmUsageItem` now means the same thing for every provider, on both `operate()` and `stream()`: `input` counts all prompt tokens with `cacheRead`/`cacheWrite` as subsets of it, `output` counts all billed output with `reasoning` as a subset of it, and `total` is `input + output`.
+
+- **Gemini** `output` includes `thoughtsTokenCount` (#599). A thinking-heavy `gemini-3.8-flash` call reported 27% of its billed output. `input` also includes `toolUsePromptTokenCount`, and `cachedContentTokenCount` surfaces as `cacheRead`. The streamed `total` now comes from `totalTokenCount`.
+- **Anthropic** and **Bedrock** `input` include their cache reads and writes, which their APIs report outside `input_tokens`/`inputTokens`
+- **Streaming** carries `cacheRead`/`cacheWrite` on every provider. OpenRouter and Fireworks streams report `reasoning` (it was always `0`). Anthropic streams read cumulative `message_delta` usage.
+- **OpenAI, xAI, and Meta streams** emit usage. The done chunk waited for a `response.done` event the Responses API never sends, so a live stream reported no usage. It now follows the stream's end.
+- **Bedrock streams** emit usage. ConverseStream sends `metadata` after `messageStop`, and the done chunk fired at `messageStop` with zeros. It now follows the stream's end.
+- **Bedrock** `operate()` usage names the requested model. Converse responses do not echo the model id, so every item was labeled with the default (`amazon.nova-pro-v1:0`), and a Claude route was priced at Nova rates.
+- OpenRouter, Fireworks, and Mistral share one chat-completions usage mapper (camelCase and snake_case)
+
+### Token cost
+
+`tokenCost(usage, { model?, ttl? })` is exported (and re-exported by the testkit mock), along with the `LlmUsage`, `LlmUsageItem`, and `LlmCacheWriteTtl` types. It returns USD for `response.usage`, or `undefined` when any item is unpriced.
+
+- Bills each token once: `input` less cache tokens at the input rate, cache tokens at their cache rates, `output` less `reasoning` at the output rate, and `reasoning` at its own rate. It previously billed reasoning twice for Anthropic, OpenAI, and Fireworks, and cached input twice for OpenAI-compatible providers. Emulated OCR on Gemini now prices thinking once.
+- Bills cache writes at the TTL they were written with. It previously billed every write at the five-minute rate, which underpriced Anthropic's default one-hour writes by 37.5%.
+
+### Prompt-cache TTL
+
+- `cache: true` (or omitted) now writes with a one-hour TTL everywhere a provider accepts one: Anthropic (unchanged), OpenRouter (was five minutes), and Bedrock Claude 4.5+ routes (`cachePoint.ttl`, was Bedrock's five-minute default). `cache: "5m"` still selects five minutes. Nova, older Bedrock Claude, and providers without a TTL cache on their own schedule.
+- `LlmUsageItem.cacheWriteTtl` splits `cacheWrite` by TTL from Anthropic `usage.cache_creation` and Bedrock `usage.cacheDetails`. Pricing bills each TTL at its rate; writes the provider does not split bill at the `ttl` option (default `"1h"`).
+
+### System prompt sent once
+
+Google, OpenRouter, Fireworks, and Mistral sent the system prompt twice: once as the top-level system field and again from history, where the operate loop also places it. Every call with a system prompt paid for it twice (a 7,216-token system prompt billed as 14,432 on OpenRouter). Each now skips the history copy; a different system message elsewhere in history is kept.
+
+### Cache option on later turns
+
+Tool-loop turns after the first rebuilt the request without `cache`, so `cache: false` and `cache: "5m"` applied only to the first turn. `operate()` and `stream()` now carry it on every turn.
+
+### Anthropic structured-output fallback
+
+The tool-emulation fallback (used only when a model rejects native `output_config.format`) sent `tool_choice: { type: "any" }`, which Fable 5.1, Mythos 5.1, Opus 5.5, Sonnet 5.5, and later reject with a 400. Those models now get `{ type: "auto" }`; earlier models keep `any`.
+
+### Claude Sonnet 5.5
+
+- `MODEL.SONNET` is `claude-sonnet-5-5`, and so is `PROVIDER.ANTHROPIC.DEFAULT` through it. `MODEL.OPENROUTER.SONNET` is `anthropic/claude-sonnet-5.5`.
+- `COST["claude-sonnet-5-5"]`: $2 input, $10 output, $0.20 cache read, $2.50/$4.00 cache write (5m/1h). `claude-sonnet-5` keeps its entry.
+- Temperature is stripped for `claude-sonnet-5` and later up front, as it is for Opus 4.7+, instead of after a 400
+
+## Testing
+
+- `npm run test -w packages/llm`: new specs cover Gemini operate and stream usage (the #599 fixture), Anthropic and Bedrock cache folding in operate and stream, the Bedrock `metadata`-after-`messageStop` order, an OpenAI stream ending without `response.done`, the chat-completions mapper, single-billing of reasoning and cached input in `tokenCost`, emulated Gemini OCR cost, Sonnet 5 temperature stripping, per-TTL cache-write pricing and the `ttl` option, the Anthropic `cache_creation` and Bedrock `cacheDetails` splits, the one-hour default on OpenRouter and Bedrock Claude routes, the fallback `tool_choice` per model, Bedrock usage attributed to the requested model, the system prompt sent once on Google, OpenRouter, Fireworks, and Mistral, and `cache` on later loop turns

package/release-notes/llm/1.3.56.md

@@ -0,0 +1,26 @@
+---
+version: 1.3.56
+date: 2026-09-28
+summary: Failing over down a fallback chain logs at debug instead of error and warn, and the report tally counts failures and fallbacks
+---
+
+## Changes
+
+### Failover logging
+
+A timeout (or any failure) on a fail-fast attempt down a fallback chain logged `API call failed after 0 retries` at `error` and `Provider X failed` at `warn`, although the next model took over as designed.
+
+- `RetryExecutor` logs a zero-budget failure at `debug`: `API call timed out after 60000ms; not retrying` for a timeout, `API call failed; not retrying` or `API call rate limited; not retrying` otherwise. Exhausting a nonzero budget still logs `error`.
+- `runWithFallback` logs `Provider X failed; failing over` at `debug` when another model remains. Only the failure that reaches the caller (a lone model, or the linger pass) logs at `warn`. Both carry `kind` (`timeout` or the `LlmError` category).
+- A timeout that retries on the transient budget names its deadline in the retry `debug` line.
+
+### Report tally
+
+Inside a Jaypie handler, `operate()`, `ocr()`, and `question()` tally each failed provider attempt onto the `llm` report key:
+
+- `failures`: counts by `provider:model` and kind, e.g. `{ "openai:gpt-5.5": { "timeout": 1 } }`
+- `fallbacks`: counts each hand-off to another model, including the linger pass back to the primary
+
+## Testing
+
+- `npm run test -w packages/llm`: new `tallyFailure` and `runWithFallback` specs cover failure kinds, key resolution, the fallback count, and the debug/warn split; `RetryExecutor` specs cover the zero-budget debug lines for transient, rate-limit, and timeout failures

package/release-notes/mcp/0.8.178.md

@@ -0,0 +1,10 @@
+---
+version: 0.8.178
+date: 2026-09-28
+summary: Release notes for @jaypie/llm 1.3.55, @jaypie/testkit 1.2.79, and jaypie 1.2.114; llm skill documents the usage contract, tokenCost, and cache TTLs
+---
+
+## Changes
+
+- **Release notes**: `@jaypie/llm` 1.3.55, `@jaypie/testkit` 1.2.79, and `jaypie` 1.2.114
+- **`llm` skill**: documents the normalized usage contract (`reasoning` within `output`, `cacheRead`/`cacheWrite` within `input`), prices usage with the exported `tokenCost`, and describes the one-hour default cache TTL and `cacheWriteTtl`

package/release-notes/mcp/0.8.179.md

@@ -0,0 +1,10 @@
+---
+version: 0.8.179
+date: 2026-09-28
+summary: Release notes for @jaypie/llm 1.3.56 and jaypie 1.2.115; llm skill documents failover logging and the failures/fallbacks tally
+---
+
+## Changes
+
+- **Release notes**: `@jaypie/llm` 1.3.56 and `jaypie` 1.2.115
+- **`llm` skill**: documents the `failures` and `fallbacks` report totals and the debug-level failover logging under Attempt Timeout

package/release-notes/testkit/1.2.79.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.79
+date: 2026-09-28
+summary: Re-exports tokenCost from the llm mock
+---
+
+## Changes
+
+- `tokenCost` re-exported from `@jaypie/llm` alongside the other pure utilities, so specs that mock `@jaypie/llm` still price usage with the real function.

package/skills/llm.md

@@ -69,17 +69,32 @@ LlamaCloud serves LlamaParse, which extracts documents and generates no text. Th
 `LLM.COST` maps a literal model id to its standard list price per **million** tokens (`LlmModelCost`). Keys are string literals, not `MODEL.*` references, so a model retired from the catalog keeps its price and historic usage stays replayable. **Provider aliases are never priced.** A `-latest` id has no stable rate — the provider can repoint it at any time, and an entry under the alias would keep returning the old price with nothing to signal the move. `MODEL.MISTRAL.*` names aliases, so `COST[MODEL.MISTRAL.LARGE]` returns `undefined` by design: resolve the alias to the id the API echoes on the response (`response.model`) and price that.
 
 ```typescript
-import { LLM, type LlmModelCost } from "@jaypie/llm";
+import { Llm, LLM, tokenCost } from "@jaypie/llm";
 
-const rate: LlmModelCost | undefined = LLM.COST[response.model];
-const dollars = rate
-  ? (usage.input * rate.input + usage.output * rate.output) / 1e6
-  : 0;
+const response = await Llm.operate(input, { model: LLM.MODEL.SONNET });
+const dollars: number | undefined = tokenCost(response.usage, {
+  model: LLM.MODEL.SONNET, // fallback price when an item's echoed id is unpriced
+});
 ```
 
+`tokenCost(usage, { model?, ttl? })` returns USD for a usage list, or `undefined` when the list is empty or any item is unpriced, so "free" and "unknown" stay distinct. It bills each token once. Usage is normalized across every provider and both `operate()` and `stream()`: `input` counts all prompt tokens with `cacheRead`/`cacheWrite` as subsets of it, `output` counts all billed output with `reasoning` (thinking) as a subset of it, and `total` is `input + output`. Per item:
+
+| Tokens                                  | Rate                                                     |
+| --------------------------------------- | -------------------------------------------------------- |
+| `input − cacheRead − cacheWrite`        | `input`                                                  |
+| `cacheRead`                             | `cachedInputRead` (else `input`)                         |
+| `cacheWriteTtl["1h"]`, `["5m"]`         | `cachedInputWrite` at that TTL (scalar rates ignore TTL) |
+| `cacheWrite` the provider did not split | `cachedInputWrite` at the `ttl` option (default `"1h"`)  |
+| `output − reasoning`                    | `output`                                                 |
+| `reasoning`                             | `reasoning` (else `output`)                              |
+
+Anthropic and Bedrock report writes per TTL (`cacheWriteTtl`); pass `ttl: "5m"` when the call used `cache: "5m"` on a provider that does not. `Llm.ocr` prices emulated calls with `tokenCost`.
+
+`LlmModelCost` fields (USD per million tokens):
+
 | Field              | Meaning                                                                                                                                                                                                                                              |
 | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `input`            | Uncached input tokens                                                                                                                                                                                                                                |
+| `input`            | Uncached input tokens (`usage.input` less `cacheRead` and `cacheWrite`)                                                                                                                                                                              |
 | `output`           | Output tokens                                                                                                                                                                                                                                        |
 | `cachedInputRead`  | Cache-read (hit) tokens. Omitted when the provider does not price reads separately                                                                                                                                                                   |
 | `cachedInputWrite` | Cache-write tokens. Scalar when TTL-invariant (`0` where the provider publishes a free write, as Bedrock does for Nova), or keyed `{ "5m", "1h" }` matching `LlmCache`. Omitted means writes bill at `input` (a TTL-keyed premium is Anthropic-only) |
@@ -112,7 +127,7 @@ const response = await Llm.operate(input, {
 // Response structure
 response.content; // string | object (structured output)
 response.history; // LlmHistory - for follow-up calls
-response.usage; // Token usage per turn
+response.usage; // Token usage per turn: { input, output, reasoning, total, cacheRead?, cacheWrite?, cacheWriteTtl? }; reasoning ⊂ output, cache ⊂ input; price with tokenCost()
 response.reasoning; // Extended thinking (if available)
 response.status; // "completed" | "incomplete" | "in_progress"
 ```
@@ -849,6 +864,7 @@ const response = await llm.operate(input, {
 - `stream()` treats `timeout` as an idle timeout: it restarts with every chunk and pauses while the consumer holds one. A stall after partial output yields an error chunk.
 - No default applies; unset means no deadline. Size it above the slowest legitimate non-streaming response (long reasoning runs take minutes).
 - `Llm.ocr` keeps `timeout` as the LlamaParse job deadline.
+- A timeout that hands off to the next model logs at `debug` (`API call timed out after 60000ms; not retrying`, then `Provider openai failed; failing over`). Only the failure that reaches the caller logs at `warn`. The report tally counts it under `failures` and `fallbacks`.
 
 ### Fallback Response Metadata
 
@@ -907,6 +923,8 @@ Inside a Jaypie handler (`expressHandler`, `lambdaHandler`, and stream variants)
 ```json
 {
   "llm": {
+    "failures": { "openai:gpt-5.5": { "timeout": 1 } },
+    "fallbacks": 1,
     "operates": 2,
     "toolCalls": 3,
     "tools": { "get_weather": 2, "roll": 1 },
@@ -926,6 +944,8 @@ Inside a Jaypie handler (`expressHandler`, `lambdaHandler`, and stream variants)
 - `operates` counts loop executions; repeated calls sum every number
 - `usage` is keyed `provider:model` — fallback providers appear as separate keys
 - `tools` appears only when tools were called
+- `failures` counts failed provider attempts by `provider:model` and kind (`timeout`, `rate_limit`, `retryable`, `quota`, `unrecoverable`, `unknown`), from `operate()`, `ocr()`, and `question()`
+- `fallbacks` counts hand-offs to another model, including the final retry of the primary once a chain is spent
 - Outside a handler session the tally is skipped entirely (guarded on `log.sessionActive`), so a CLI or script calling `operate()` directly emits nothing
 
 ## LLM Observability (Datadog)
@@ -1071,7 +1091,7 @@ describe("LLM Integration", () => {
 
 ```typescript
 interface LlmOperateOptions {
-  cache?: boolean | 0 | "5m" | "1h"; // Prompt caching (default on: 1h Anthropic, 5m elsewhere; false/0 disables)
+  cache?: boolean | 0 | "5m" | "1h"; // Prompt caching (default on at 1h; false/0 disables)
   data?: Record<string, any>; // Placeholder substitution data
   effort?: LlmEffort; // Provider-neutral reasoning effort (lowest|low|medium|high|highest)
   fallback?: LlmFallbackConfig[] | false; // Fallback provider chain
@@ -1180,21 +1200,24 @@ tool-calling loop is billed at the provider's cache-read rate (~0.1x input)
 after the first write. Control with the scalar `cache` option:
 
 ```typescript
-await Llm.operate(input, { system: SYSTEM }); // cached (1h Anthropic, else 5m)
+await Llm.operate(input, { system: SYSTEM }); // cached @ 1h
 await Llm.operate(input, { system: SYSTEM, cache: "5m" }); // cached @ 5m
 await Llm.operate(input, { system: SYSTEM, cache: false }); // opt out
 ```
 
-`true`/omitted = enabled at the adapter default (`"1h"` on Anthropic, `"5m"`
-elsewhere); `false`/`0` = disabled; `"5m"`/`"1h"` = that TTL.
+`true`/omitted = enabled at `"1h"`; `false`/`0` = disabled; `"5m"`/`"1h"` =
+that TTL. A one-hour write costs more than a five-minute one (2x input vs
+1.25x on Anthropic) but reads cost the same, so it pays for itself after about
+three reads and survives the gaps between turns.
 
 Per provider: Anthropic `cache_control` on system + last tool; Bedrock
 `cachePoint` blocks (model-gated, auto-denylisted and retried without on a 400;
-5m only); OpenAI/xAI/Meta automatic caching + a stable `prompt_cache_key`; OpenRouter
+`ttl` sent on Claude 4.5+ routes, Nova and older Claude cache for 5m); OpenAI/xAI/Meta automatic caching + a stable `prompt_cache_key`; OpenRouter
 `cache_control` on the system message (forwarded to Anthropic/Gemini backends);
-Google implicit caching only (Gemini 2.5+). TTL applies to Anthropic/OpenRouter;
+Google implicit caching only (Gemini 2.5+; `cachedContentTokenCount` surfaces as `cacheRead`). TTL applies to Anthropic, OpenRouter, and Bedrock Claude 4.5+;
 others use provider defaults. Sub-threshold prefixes silently no-op. Cache
-tokens surface as `cacheRead`/`cacheWrite` on usage, in the exchange envelope
+tokens surface as `cacheRead`/`cacheWrite` on usage (with `cacheWriteTtl`
+splitting writes by TTL on Anthropic and Bedrock), in the exchange envelope
 `usageTotals`, and in the report tally.
 
 ## Provider Options and Output Limits