@jaypie/mcp 0.8.178 → 0.8.180

package/dist/assets.js

@@ -55,11 +55,11 @@ function getMcpAssetPaths() {
  */
 function getMcpBuildInfo() {
     return {
-        commit: "77e42bd7"
+        commit: "bd1e9e07"
             ,
-        version: "0.8.178"
+        version: "0.8.180"
             ,
-        versionString: "@jaypie/mcp@0.8.178#77e42bd7"
+        versionString: "@jaypie/mcp@0.8.180#bd1e9e07"
             ,
     };
 }

package/package.json

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

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/jaypie/1.2.116.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.116
+date: 2026-09-29
+summary: Pulls @jaypie/llm 1.3.57
+---
+
+## Changes
+
+- **`@jaypie/llm` 1.3.57**: a fallback chain advances past an incomplete (truncated) response; new `incomplete: "return" | "throw"` option with `LlmIncompleteError`; `response.stopReason` normalized as `LlmStopReason`; Anthropic spending-cap and bundled 4xx errors no longer classify as retryable.

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/llm/1.3.57.md

@@ -0,0 +1,47 @@
+---
+version: 1.3.57
+date: 2026-09-29
+summary: A fallback chain advances past an incomplete (truncated) response; new incomplete option, LlmIncompleteError, and a standard stopReason; Anthropic spending-cap and bundled 4xx errors classify correctly
+---
+
+## Changes
+
+### Fallback on incomplete (issue #602)
+
+A response the provider cut short (`status: "incomplete"`, `error.reason: "incomplete"`: an output token ceiling or a content filter) was returned as success, so a configured chain never advanced.
+
+- `operate` now moves to the next chain entry on an incomplete response, as it does on a thrown error.
+- When no entry finishes, the latest incomplete response is returned rather than an error. `fallbackAttempts` counts every attempt made.
+- A primary that cut off skips the linger pass: the same model would cut off the same way.
+- Loop stops (`max_turns`, `tool_errors`) never fall over.
+- The hand-off logs `Provider X returned incomplete; failing over` at `debug` and tallies under the `incomplete` kind.
+
+### `incomplete` option
+
+`incomplete: "return" | "throw"` decides what reaches the caller once the chain is spent. `"return"` (default) keeps the partial with `status: "incomplete"`; `"throw"` raises `LlmIncompleteError` (status 502, category `incomplete`) carrying the settled response on `.response`. Jaypie 2 will default to `"throw"`.
+
+### Standard stop reason
+
+`LlmOperateResponse.stopReason` (`LlmStopReason`) normalizes the final model call's stop across providers: `end_turn`, `max_tokens`, `content_filter`, `refusal`, `tool_use`, or `other`. Gemini `MAX_TOKENS`, Chat Completions `length`, Anthropic `max_tokens`, and OpenAI `max_output_tokens` all read `max_tokens`.
+
+### Error classification under bundling (issue #604)
+
+An Anthropic spending-cap 400 surfaced as a retryable `LlmTransientError` (504) and tallied under `retryable`.
+
+- `You have reached your specified API usage limits` classifies as `Quota` with `reason: "billing"`: no retries, immediate failover, tallied under `quota`.
+- The Anthropic adapter classifies by HTTP `status` first: 429 rate limit, 408 and 5xx retryable, every other 4xx unrecoverable. An esbuild-renamed class (`BadRequestError3`) previously fell through to `Unknown`, so every bundled Anthropic 4xx was retried.
+- A class-name fallback strips a bundler's numeric suffix.
+- Bedrock matches on the AWS SDK's literal `error.name` instead of the class name.
+- Anthropic and OpenAI client error classes carry a literal `name`.
+
+### Documentation
+
+- An incomplete `content` is the raw partial string even when `format` was requested.
+- Mixed chains mix output budgets: Anthropic, Google, and Mistral cap non-streaming at 16,384 while OpenAI, xAI, and Meta send no ceiling.
+
+## Testing
+
+- `runWithFallback` specs cover soft failover, lone-model return, linger skip, partial over a later error, `settle`, and a `settle` throw that does not fail over.
+- `Llm` class specs cover failover on incomplete, whole-chain cut-off, fallback error after a primary cut-off, loop stops not failing over, and `incomplete: "throw"`.
+- Adapter specs cover the spending-cap message, renamed Anthropic classes by status (400, 401, 403, 404, 429, 500, 529) and without one, and renamed Bedrock exceptions.
+- `standardStopReason` and `OperateLoop` specs cover the normalized stop reason, including a `structured_output` tool answer as `end_turn`.

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/mcp/0.8.180.md

@@ -0,0 +1,10 @@
+---
+version: 0.8.180
+date: 2026-09-29
+summary: Release notes for @jaypie/llm 1.3.57, @jaypie/testkit 1.2.80, and jaypie 1.2.116; llm skill documents incomplete failover and stopReason
+---
+
+## Changes
+
+- **Release notes**: `@jaypie/llm` 1.3.57, `@jaypie/testkit` 1.2.80, and `jaypie` 1.2.116
+- **`llm` skill**: documents failover on incomplete responses, the `incomplete` option and `LlmIncompleteError`, `response.stopReason`, raw partial `content` under `format`, and the output budget asymmetry across providers

package/release-notes/testkit/1.2.80.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.80
+date: 2026-09-29
+summary: Re-exports LlmIncompleteError and LlmStopReason from the llm mock
+---
+
+## Changes
+
+- `LlmIncompleteError` and `LlmStopReason` re-exported from the `@jaypie/llm` mock alongside the other errors and enums.

package/skills/llm.md

@@ -130,8 +130,14 @@ response.history; // LlmHistory - for follow-up calls
 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"
+response.stopReason; // LlmStopReason: "end_turn" | "max_tokens" | "content_filter" | "refusal" | "tool_use" | "other"
 ```
 
+`stopReason` is normalized across providers (Gemini `MAX_TOKENS`, Chat
+Completions `length`, Anthropic `max_tokens`, and OpenAI `max_output_tokens`
+all read `max_tokens`). The provider's own value rides
+`exchange.response.stopReason`.
+
 ### send() - Simple Completions
 
 For single-shot text completions:
@@ -800,7 +806,9 @@ for await (const chunk of Llm.stream(input, {
 
 ## Fallback Providers
 
-Configure a chain of fallback providers. Any error (rate limit, 5xx, network flake, bad request) moves to the next entry at once, with no retry or wait. When every entry has failed, the primary runs once more with its full retry policy; if that fails, the call throws. A caller abort (`LlmAbortError`) never falls over:
+Configure a chain of fallback providers. Any error (rate limit, 5xx, network flake, bad request) moves to the next entry at once, with no retry or wait. When every entry has failed, the primary runs once more with its full retry policy; if that fails, the call throws. A caller abort (`LlmAbortError`) never falls over.
+
+A response the provider cut short (`status: "incomplete"` with `error.reason: "incomplete"`: an output token ceiling or a content filter) also moves to the next entry. When no entry finishes, the latest incomplete response is returned rather than an error, and a primary that cut off does not linger (the same model would cut off the same way). Loop stops (`max_turns`, `tool_errors`) never fall over:
 
 ```typescript
 // Instance-level configuration
@@ -827,6 +835,28 @@ const response = await Llm.operate(input, {
 });
 ```
 
+### Incomplete Responses
+
+`incomplete` decides what reaches the caller once the chain is spent. `"return"` (the default) returns the partial with `status: "incomplete"`; `"throw"` raises `LlmIncompleteError` (status 502) carrying the settled response on `.response`. Either way a chain moves past an incomplete first. Jaypie 2 will default to `"throw"`.
+
+```typescript
+import { LlmIncompleteError, LlmStopReason } from "@jaypie/llm";
+
+try {
+  const response = await Llm.operate(input, {
+    format: Extraction,
+    incomplete: "throw",
+    model: [LLM.MODEL.GEMINI_FLASH, LLM.MODEL.SOL],
+  });
+} catch (error) {
+  if (error instanceof LlmIncompleteError) {
+    error.response.stopReason; // LlmStopReason.MaxTokens
+  }
+}
+```
+
+An incomplete `content` is the raw partial text, a string even when `format` was requested: a truncated answer is not the object the format promises. Check `status` (or use `incomplete: "throw"`) before reading `content` as the formatted object.
+
 ### Provider Options in a Chain
 
 `providerOptions` belongs to the model it was written for. Per-call `providerOptions` reach the primary only (including its linger pass); a fallback receives only the `providerOptions` on its own entry, or none. Options shaped for one provider (OpenAI `reasoning`, Gemini `thinkingConfig`) would otherwise break every other provider in the chain. Prefer first-class `effort` and `temperature`, which translate per provider.
@@ -864,6 +894,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
 
@@ -922,6 +953,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 },
@@ -941,6 +974,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)
@@ -1033,7 +1068,7 @@ exactly like a provider rate limit.
 | ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `max_turns`   | 429    | The model asked for another tool call after `turns` ran out. Nothing failed; the run did not converge.                                                                       |
 | `tool_errors` | 502    | Tool execution failed six times in a row and the loop stopped.                                                                                                               |
-| `incomplete`  | 502    | The provider cut the model off before it finished (an output token ceiling, a content filter). `content` holds the partial text; `error.detail` names the provider's reason. |
+| `incomplete`  | 502    | The provider cut the model off before it finished (an output token ceiling, a content filter). `content` holds the partial text; `error.detail` names the provider's reason and `stopReason` normalizes it. A fallback chain moves past it. |
 
 ```typescript
 import { LlmResponseErrorReason } from "@jaypie/llm";
@@ -1249,12 +1284,19 @@ await Llm.operate(input, {
 ```
 
 OpenAI, xAI, and Meta leave the limit unset (their defaults do not truncate early).
+A chain that mixes them with Anthropic, Google, or Mistral therefore mixes
+output budgets: a Gemini primary resolves to 16,384 non-streaming while an
+OpenAI fallback sends no ceiling, so swapping the primary moves the effective
+budget with nothing at the call site changing. Reasoning tokens count against
+the ceiling. Set `providerOptions.maxOutputTokens` (Google) or `max_tokens`
+(Anthropic, Mistral) on the call or chain entry to pin it.
 Mistral is capped (32,768 streaming / 16,384 non-streaming) despite publishing
 no low ceiling: a Mistral model can degenerate into restating its answer when
 `format` and tools are combined, and an uncapped completion turns that into a
 multi-minute request. Override with `providerOptions: { max_tokens }`.
 OpenRouter varies by routed model; pass `max_tokens` via `providerOptions`
-when needed. A truncated response surfaces `stop_reason: "max_tokens"` —
+when needed. A truncated response settles `status: "incomplete"` with
+`stopReason: "max_tokens"` and moves a fallback chain to its next entry;
 raise the limit or switch to `stream()`.
 
 ## See Also