@jaypie/mcp 0.8.179 → 0.8.181

package/dist/assets.js

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

package/package.json

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

package/release-notes/dynamodb/0.6.14.md

@@ -0,0 +1,21 @@
+---
+version: 0.6.14
+date: 2026-10-02
+summary: Adds patchEntity, a targeted UpdateItem that sets or removes listed fields without moving GSI entries or overwriting other fields
+---
+
+## Changes
+
+- **`patchEntity({ id, set?, remove?, condition?, names?, values? })`** (#606).
+  Sends a targeted `UpdateItem` that sets and removes only the listed
+  attributes. `updatedAt` and every GSI key stay unchanged, so the entity
+  keeps its place in `queryByScope` and other index queries, and concurrent
+  writes to other fields are never overwritten with a stale copy. Returns the
+  entity as stored after the write.
+- Protected attributes (`id`, `model`, `updatedAt`, `archivedAt`, `deletedAt`,
+  `index*`, and every pk/sk field of a registered index) throw
+  `BadRequestError`; change those with `updateEntity`. A missing entity throws
+  `NotFoundError`; a failed `condition` throws `ConflictError`.
+- **Docs:** `updateEntity` and `queryByScope` documentation explains that each
+  `updateEntity` moves the entity's `indexModel` entry, and recommends
+  `patchEntity` for counters, heartbeats, and "last X" fields.

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

@@ -0,0 +1,10 @@
+---
+version: 0.8.181
+date: 2026-10-02
+summary: Release notes for @jaypie/dynamodb 0.6.14 and @jaypie/testkit 1.2.81; dynamodb skill documents patchEntity
+---
+
+## Changes
+
+- **Release notes**: `@jaypie/dynamodb` 0.6.14 and `@jaypie/testkit` 1.2.81
+- **`dynamodb` skill**: documents `patchEntity`, the protected attributes, and why each `updateEntity` moves an entity's `indexModel` entry

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/release-notes/testkit/1.2.81.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.81
+date: 2026-10-02
+summary: Adds the patchEntity mock for @jaypie/dynamodb
+---
+
+## Changes
+
+- `patchEntity` mock in the `@jaypie/dynamodb` mock; resolves to `{ id, ...set }` by default.

package/skills/dynamodb.md

@@ -127,7 +127,7 @@ interface StorableEntity {
 ### Entity Operations
 
 ```typescript
-import { APEX, createEntity, getEntity, updateEntity, deleteEntity, archiveEntity, destroyEntity } from "@jaypie/dynamodb";
+import { APEX, createEntity, getEntity, patchEntity, updateEntity, deleteEntity, archiveEntity, destroyEntity } from "@jaypie/dynamodb";
 
 // Create entity — indexEntity auto-populates GSI keys, createdAt, updatedAt
 const record = await createEntity({
@@ -148,9 +148,12 @@ const record = await createEntity({
 // Get by primary key (id only)
 const item = await getEntity({ id: "abc-123" });
 
-// Update — sets updatedAt, re-indexes
+// Update — writes the whole item, sets updatedAt, re-indexes (moves GSI entries)
 await updateEntity({ entity: { ...item, name: "Updated Name" } });
 
+// Patch — sets only the listed fields; updatedAt and GSI keys unchanged
+await patchEntity({ id: "abc-123", set: { lastUsedAt: new Date() } });
+
 // Conditional update — write-time guard; throws ConflictError if it fails
 await updateEntity({
   entity: { ...item, status: "complete" },
@@ -176,13 +179,55 @@ await destroyEntity({ id: "abc-123" });
 |----------|-------------|
 | `createEntity({ entity, preserveTimestamps? })` | Create entity; returns `null` if `id` exists (conditional `attribute_not_exists(id)`) |
 | `getEntity({ id })` | Get by primary key (id only) |
-| `updateEntity({ entity, condition?, names?, preserveTimestamps?, values? })` | Update (sets `updatedAt`, re-indexes). Pass `condition` (a ConditionExpression, with `names`/`values` bindings) to guard the write; throws `ConflictError` (409) and leaves the item unchanged when the condition fails |
+| `updateEntity({ entity, condition?, names?, preserveTimestamps?, values? })` | Update (writes the whole item, sets `updatedAt`, re-indexes; each call moves the entity's GSI entries). Pass `condition` (a ConditionExpression, with `names`/`values` bindings) to guard the write; throws `ConflictError` (409) and leaves the item unchanged when the condition fails |
+| `patchEntity({ id, set?, remove?, condition?, names?, values? })` | Targeted `UpdateItem`: sets/removes only the listed attributes; leaves `updatedAt` and every GSI key unchanged. Throws `BadRequestError` (400) for index keys and timestamps, `NotFoundError` (404) when absent, `ConflictError` (409) when `condition` fails. See [Patching Fields Without Re-indexing](#patching-fields-without-re-indexing) |
 | `transitionEntity({ id, from?, set })` | Conditionally update by status: reads the entity, merges `set`, writes guarded by `#status = from`; throws `ConflictError` (409) on a race, `NotFoundError` (404) when absent. Validates `from`/`set.status` against the model's `status` vocabulary |
 | `deleteEntity({ id })` | Soft delete (`deletedAt`, `#deleted` suffix on GSI pk) |
 | `archiveEntity({ id })` | Archive (`archivedAt`, `#archived` suffix on GSI pk) |
 | `destroyEntity({ id })` | Hard delete (permanent) |
 | `transactWriteEntities({ entities, conditionalCreate?, condition?, preserveTimestamps? })` | Write many entities atomically; `conditionalCreate: true` guards every `Put` with `attribute_not_exists(id)` (`condition` for a custom expression), throwing `ConflictError` (409) when a conditional check fails |
 
+### Patching Fields Without Re-indexing
+
+`updateEntity` writes the whole item with `PutItem` and sets `updatedAt` to the write time. For entities that are written often (counters, heartbeats, "last X" fields), that has two consequences:
+
+1. **The index entry moves.** `updatedAt` is part of every GSI sort key (`scope#updatedAt`), so each `updateEntity` moves the entity's `indexModel` entry (and every other index entry). DynamoDB moves a GSI entry by deleting it and inserting it again, asynchronously, and GSI reads are always eventually consistent. A `queryByScope` (or any other index query) that runs between the delete and the insert does not return the entity.
+2. **Stale fields overwrite newer ones.** The `Put` writes every attribute as the caller read it. When two read-modify-write calls overlap, the later one undoes the earlier one (for example, a status change or a credential rotation).
+
+`patchEntity` sends a targeted `UpdateItem` that sets and removes only the listed attributes. It does not change `updatedAt` or any index key, so the entity stays in place in every index, and it never writes attributes the caller did not list.
+
+```typescript
+import { patchEntity } from "@jaypie/dynamodb";
+
+// Record a heartbeat without moving the entity in queryByScope
+await patchEntity({
+  id: endpoint.id,
+  set: { lastDeliveryAt: new Date() },
+});
+
+// Set and remove in one write, guarded by a condition
+const patched = await patchEntity({
+  id: endpoint.id,
+  set: { lastDeliveryAt: new Date(), lastStatus: 200 },
+  remove: ["lastError"],
+  condition: "#status = :active",
+  names: { "#status": "status" },
+  values: { ":active": "active" },
+});
+// patched: the full entity as stored after the write
+```
+
+| Use | When |
+|-----|------|
+| `patchEntity` | Counters, heartbeats, "last X" timestamps, and any field that is not an index key and should not reorder listings |
+| `updateEntity` | Changes to index keys (`scope`, `alias`, `category`, `type`, `xid`, custom index fields) or changes that should advance `updatedAt` |
+
+- **Protected attributes.** `set` and `remove` cannot name `id`, `model`, `updatedAt`, `archivedAt`, `deletedAt`, any `index*` attribute, or any `pk`/`sk` field of a registered index (`scope`, `alias`, `category`, `type`, `xid`, and custom index fields). These throw `BadRequestError` (400) before any write, because changing them requires re-indexing through `updateEntity`. An empty patch also throws `BadRequestError`.
+- **Existence.** Every patch is guarded by `attribute_exists(id)`, so it never creates an item. A missing entity throws `NotFoundError` (404).
+- **Conditions.** `condition` is combined with the existence guard as `attribute_exists(id) AND (condition)`. When it fails, the item is left unchanged and `ConflictError` (409) is thrown. Placeholders `#s<n>`, `:s<n>`, and `#r<n>` are reserved for the generated expression; passing them in `names`/`values` throws `BadRequestError`.
+- **Ordering.** `updatedAt` does not change, so listings sorted by `updatedAt` do not reflect a patch. Use `updateEntity` when a change should move the entity to the top of a listing.
+- **Values.** `Date` values are stored as ISO 8601 strings. TTL is not changed.
+
 ### Preserving Timestamps (Imports)
 
 Every write stamps `updatedAt` with the write time, and every `scope#updatedAt` sort key follows it. Migrations, restores, and replays pass `preserveTimestamps: true` to `createEntity`, `updateEntity`, `transactWriteEntities`, or `seedEntities` (as an option) to keep the entity's own `createdAt`/`updatedAt`. Missing values fall back to now. TTL handling, date serialization, and conditional-write error mapping still apply, so raw `PutCommand` workarounds are unnecessary.
@@ -329,6 +374,8 @@ All queries return `{ items, lastEvaluatedKey }` and support pagination. `scope`
 import { APEX, queryByScope, queryByAlias, queryByCategory, queryByType, queryByXid } from "@jaypie/dynamodb";
 
 // List by model (scope optional)
+// Each updateEntity moves the entity's indexModel entry; patch frequently
+// written fields with patchEntity so listings stay stable
 const { items } = await queryByScope({ model: "record", scope: APEX });
 
 // List across all scopes

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.
@@ -1038,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";
@@ -1254,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