@jaypie/mcp 0.8.183 → 0.8.185

package/dist/assets.js

@@ -55,11 +55,11 @@ function getMcpAssetPaths() {
  */
 function getMcpBuildInfo() {
     return {
-        commit: "77ae81b6"
+        commit: "a5a715a3"
             ,
-        version: "0.8.183"
+        version: "0.8.185"
             ,
-        versionString: "@jaypie/mcp@0.8.183#77ae81b6"
+        versionString: "@jaypie/mcp@0.8.185#a5a715a3"
             ,
     };
 }

package/package.json

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

package/release-notes/jaypie/1.2.119.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.119
+date: 2026-10-07
+summary: Pulls @jaypie/llm 1.3.60
+---
+
+## Changes
+
+- **`@jaypie/llm` 1.3.60**: `effort` accepts a per-model map, fallback entries take their own `effort`, and `resolveEffort` exports the native mapping.

package/release-notes/jaypie/1.2.120.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.120
+date: 2026-10-07
+summary: Pulls @jaypie/llm 1.3.61
+---
+
+## Changes
+
+- **`@jaypie/llm` 1.3.61**: `modelOptions` sets provider options per model for every attempt in a chain; `providerOptions` and `send` are deprecated.

package/release-notes/llm/1.3.60.md

@@ -0,0 +1,26 @@
+---
+version: 1.3.60
+date: 2026-10-07
+summary: effort accepts a per-model map, fallback entries take their own effort, and resolveEffort exports the native mapping
+---
+
+## Changes
+
+### Per-model effort (issue #612)
+
+A fallback chain mixes providers whose reasoning cost differs sharply at the same level, but `effort` was one value per call.
+
+- `effort` accepts `LlmEffortMap`. Each attempt (primary, fallback, linger pass) resolves its own level: exact model id, then `MODEL` catalog key whose value is exactly the model, then provider (or the `gemini` alias), then `default`. No match leaves the provider default.
+- Catalog keys match exact catalog values only, never name fragments, so `flash` cannot catch both Gemini Flash and GLM Flash.
+- `LlmFallbackConfig.effort` sets a single level for one entry and replaces the call's value there.
+- `LlmExchangeRequest.effort` records the level each attempt resolved.
+
+### `resolveEffort`
+
+- `resolveEffort({ model, effort, provider? })` returns `{ level, model, native, papered, provider }`, where `native` is the request fragment the adapter sends (e.g. `{ thinkingConfig: { thinkingLevel: "LOW" } }`). Undefined `native` means no level resolved or the model has no reasoning control.
+- Adapters expose `resolveEffort` and build requests from it, so the export and the wire request share one mapping.
+
+## Testing
+
+- `resolveEffort.spec.ts` covers map precedence, catalog keys, the provider alias, and native fragments per provider.
+- `OperateLoop` and `StreamLoop` specs cover map resolution and the exchange record; `Llm` specs cover per-entry effort on a fallback.

package/release-notes/llm/1.3.61.md

@@ -0,0 +1,28 @@
+---
+version: 1.3.61
+date: 2026-10-07
+summary: modelOptions sets provider options per model for every attempt in a chain; providerOptions and send are deprecated
+---
+
+## Changes
+
+### `modelOptions` (issue #614)
+
+`providerOptions` reached the primary only, so a fallback ran on defaults unless the caller rebuilt the chain with options on every entry.
+
+- `modelOptions` (`LlmModelOptions`) on `operate` and `stream` keys provider options by exact model id, `MODEL` catalog key, provider (or the `gemini` alias), or `default`. Each attempt (primary, fallback, linger pass) resolves it against its own model.
+- Every matching key merges, least to most specific: `default` → provider → catalog key → exact id. Objects merge deeply; arrays and scalars replace.
+- First-class `effort`, `temperature`, and `format` still win over resolved options.
+- When `modelOptions` is set, `providerOptions` (call and chain entry) is ignored.
+- `LlmExchangeRequest.providerOptions` records the options each attempt sent.
+- `resolveModelOptions({ model, modelOptions, provider? })` returns `{ keys, model, options, provider }`.
+
+### Deprecations
+
+- `providerOptions` on `LlmOperateOptions` and `LlmFallbackConfig` is deprecated and removed in 2.0. Use `modelOptions`.
+- `Llm.send` (instance and static) is deprecated and receives no new features. Use `operate`.
+
+## Testing
+
+- `modelOptions.spec.ts` covers merge order, deep merge, array replacement, the provider alias, ignoring `providerOptions`, and the issue's example through the OpenAI and Google adapters.
+- `OperateLoop` and `StreamLoop` specs cover resolution and the exchange record; `Llm` specs cover `modelOptions` reaching every fallback and the linger pass.

package/release-notes/mcp/0.8.184.md

@@ -0,0 +1,10 @@
+---
+version: 0.8.184
+date: 2026-10-07
+summary: Release notes for @jaypie/llm 1.3.60, testkit 1.2.82, and jaypie 1.2.119; llm skill documents per-model effort and resolveEffort
+---
+
+## Changes
+
+- **Release notes**: `@jaypie/llm` 1.3.60, `@jaypie/testkit` 1.2.82, and `jaypie` 1.2.119
+- **`llm` skill**: per-model effort maps, `LlmFallbackConfig.effort`, and `resolveEffort`

package/release-notes/mcp/0.8.185.md

@@ -0,0 +1,10 @@
+---
+version: 0.8.185
+date: 2026-10-07
+summary: Release notes for @jaypie/llm 1.3.61, testkit 1.2.83, and jaypie 1.2.120; llm skill documents modelOptions and the providerOptions and send deprecations
+---
+
+## Changes
+
+- **Release notes**: `@jaypie/llm` 1.3.61, `@jaypie/testkit` 1.2.83, and `jaypie` 1.2.120
+- **`llm` skill**: `modelOptions`, `resolveModelOptions`, and the deprecation of `providerOptions` and `send()`

package/release-notes/testkit/1.2.82.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.82
+date: 2026-10-07
+summary: Passes through resolveEffort from @jaypie/llm
+---
+
+## Changes
+
+- `resolveEffort` in the `@jaypie/llm` mock, passed through to the real implementation.

package/release-notes/testkit/1.2.83.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.83
+date: 2026-10-07
+summary: Passes through resolveModelOptions from @jaypie/llm
+---
+
+## Changes
+
+- `resolveModelOptions` in the `@jaypie/llm` mock, passed through to the real implementation.

package/skills/llm.md

@@ -138,9 +138,11 @@ 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
+### send() - Simple Completions (deprecated)
 
-For single-shot text completions:
+`send()` is deprecated and receives no new features (fallback, `effort`,
+`modelOptions`, tools). Prefer `operate()`, with `format` for structured
+output. For single-shot text completions:
 
 ```typescript
 const response = await Llm.send("Explain REST APIs", {
@@ -859,23 +861,41 @@ An incomplete `content` is the raw partial text, a string even when `format` was
 
 A `format` request answered with **no content** (zero output tokens, an empty candidate, a blocked prompt) settles incomplete with `error.detail` `Model returned no content: <stop reason>`, logged at `warn`, and `stopReason: "other"`. An adapter that supports the corrective turn tries it once first. A chain moves past an empty response like any cut-off, and an earlier partial is kept over a later empty one. When nothing but empty responses come back, `operate` throws `LlmIncompleteError` whatever `incomplete` says: there is no partial to return (issue #608).
 
-### Provider Options in a Chain
+### Model 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.
+`modelOptions` sets provider-specific request fields per model. Every attempt (primary, each fallback, and the linger pass) resolves the map against its own model, so options shaped for one provider (OpenAI `reasoning`, Gemini `thinkingConfig`) reach every model they fit and no other. Keys match the way [effort maps](#per-model-effort) do: exact model id, `MODEL` catalog key, provider (or alias such as `gemini`), `default`.
+
+Every matching key merges, least to most specific: `default` → provider → catalog key → exact id. Objects merge deeply; arrays and scalars replace. First-class fields (`effort`, `temperature`, `format`) still win.
 
 ```typescript
-const response = await llm.operate(input, {
+await llm.operate(input, {
+  model: LLM.MODEL.SOL,
   fallback: [
-    {
-      provider: "google",
-      model: LLM.MODEL.GEMINI_FLASH,
-      providerOptions: { thinkingConfig: { thinkingBudget: 1024 } },
-    },
+    { provider: "google", model: LLM.MODEL.GEMINI_FLASH },
+    { provider: "openai", model: "gpt-6-mini" },
   ],
-  providerOptions: { reasoning: { summary: "detailed" } }, // primary only
+  effort: { gemini_flash: "low", default: "medium" },
+  modelOptions: {
+    openai: { reasoning: { summary: "detailed" } },
+    gemini_flash: { thinkingConfig: { includeThoughts: true } },
+  },
 });
+// gpt-6-sol, gpt-6-mini: reasoning { summary: "detailed", effort: "medium" }
+// gemini-3.8-flash: thinkingConfig { includeThoughts: true, thinkingLevel: "LOW" }
 ```
 
+The exchange records the merged options each attempt sent (`LlmExchangeRequest.providerOptions`). `resolveModelOptions` returns them for one model, with the keys that matched in merge order:
+
+```typescript
+import { resolveModelOptions } from "@jaypie/llm";
+
+resolveModelOptions({ model: LLM.MODEL.SOL, modelOptions });
+// → { keys: ["openai"], model: "gpt-6-sol", provider: "openai",
+//     options: { reasoning: { summary: "detailed" } } }
+```
+
+`providerOptions` is deprecated and removed in 2.0. Until then, per-call `providerOptions` reach the primary only (including its linger pass) and a fallback receives only the `providerOptions` on its own entry. When `modelOptions` is set, `providerOptions` (call and chain entry) is ignored.
+
 ### Attempt Timeout
 
 `timeout` sets a per-attempt deadline in milliseconds. Without it, a provider that accepts the connection but never answers holds the chain until the runtime gives up (undici waits 300 s for response headers). A stalled attempt is aborted and throws `LlmTimeoutError` (a `LlmTransientError`, status 504, with `timeoutMs`):
@@ -1066,10 +1086,10 @@ budget runs out. Those errors carry `error.reason` (`LlmResponseErrorReason`)
 because status alone cannot identify them: an exhausted turn budget is a 429,
 exactly like a provider rate limit.
 
-| `reason`      | Status | Meaning                                                                                                                                                                      |
-| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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.                                                                                                               |
+| `reason`      | Status | Meaning                                                                                                                                                                                                                                                                                                                       |
+| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 and `stopReason` normalizes it. A fallback chain moves past it. With `format`, empty content settles here too and throws once the chain is spent. |
 
 ```typescript
@@ -1125,14 +1145,15 @@ describe("LLM Integration", () => {
 interface LlmOperateOptions {
   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)
+  effort?: LlmEffort | LlmEffortMap; // Reasoning effort (lowest|low|medium|high|highest), or a per-model map
   fallback?: LlmFallbackConfig[] | false; // Fallback provider chain
   format?: NaturalSchema | JsonObject | ZodType; // Structured output schema (natural syntax preferred)
   history?: LlmHistory; // Previous conversation
   hooks?: LlmHooks; // Lifecycle callbacks
   instructions?: string; // Additional instructions
   model?: string; // Model override
-  providerOptions?: JsonObject; // Provider-specific request fields (passthrough)
+  modelOptions?: LlmModelOptions; // Provider-specific request fields per model, every attempt
+  providerOptions?: JsonObject; // Deprecated: primary only; ignored when modelOptions is set
   system?: string; // System prompt
   temperature?: number; // Sampling temperature (0-2)
   tools?: LlmTool[] | Toolkit; // Available tools
@@ -1144,6 +1165,9 @@ interface LlmFallbackConfig {
   provider: string; // Provider name (e.g., "openai", "anthropic", "google")
   model?: string; // Model to use (optional, uses provider default)
   apiKey?: string; // API key (optional, uses environment variable)
+  effort?: LlmEffort; // Effort for this entry only, replacing the call's effort
+  providerOptions?: JsonObject; // Deprecated: this entry only; ignored when modelOptions is set
+  timeout?: number | false; // Per-attempt deadline for this entry only
 }
 ```
 
@@ -1220,9 +1244,62 @@ erroring):
   tools natively — no emulation.
 - **Bedrock** — not yet wired; `effort` is ignored.
 
-First-class `effort` takes precedence over a raw `providerOptions.reasoning`
-(same convention as `temperature`). For control the neutral scale doesn't
-express (an exact token budget, OpenAI `none`), use `providerOptions` directly.
+### Per-model effort
+
+Reasoning cost differs sharply between providers at the same level, so a
+fallback chain can set `effort` per model with a map. Each attempt (primary,
+every fallback, and the linger pass) resolves its own level, first match wins:
+
+1. **Exact model id** (`"gpt-6.1-sol"`)
+2. **`MODEL` catalog key** whose value is exactly the serving model (`"sol"`
+   for `MODEL.SOL`, `"gemini_flash"`, `"fireworks.glm"`); case-insensitive,
+   any separator. Keys never match by name fragment: `"flash"` matches nothing.
+3. **Provider** (`"openai"`, `"anthropic"`, `"google"`, `"xai"`,
+   `"openrouter"`, ...) or an alias (`"gemini"` → `google`)
+4. **`default`**
+5. No match leaves the provider default untouched
+
+```typescript
+await llm.operate(input, {
+  model: "gemini-3-flash",
+  fallback: [
+    { provider: "openai", model: "gpt-6.1-sol" },
+    { provider: "anthropic", model: "claude-opus-5-5", effort: "highest" },
+  ],
+  effort: { gemini: "low", "gpt-6.1-sol": "medium", default: "high" },
+});
+```
+
+A single `LlmEffort` keeps its meaning everywhere. A fallback entry's own
+`effort` replaces the call's value (single or map) for that entry. The exchange
+records the level each attempt resolved (`LlmExchangeRequest.effort`).
+
+### `resolveEffort`
+
+`resolveEffort` returns the level a model resolves to and the request fragment
+its adapter would send (`native`), or no `native` when the model has no
+reasoning control:
+
+```typescript
+import { resolveEffort } from "@jaypie/llm";
+
+resolveEffort({ model: "gemini-3-flash", effort: "low" });
+// → { level: "low", model: "gemini-3-flash", provider: "google", papered: false,
+//     native: { thinkingConfig: { thinkingLevel: "LOW" } } }
+
+resolveEffort({ model: "claude-opus-5-5", effort: { anthropic: "high" } });
+// → { level: "high", ..., native: { output_config: { effort: "high" } } }
+```
+
+Accepts an optional `provider` when the model id alone does not route (e.g. an
+OpenRouter path). Comparing `native` across levels shows which are distinct on
+a model: `lowest` and `low` on Claude both send `{ effort: "low" }`, so one of
+the two is redundant in an effort sweep.
+
+First-class `effort` takes precedence over a raw `reasoning` in
+`modelOptions` (same convention as `temperature`). For control the neutral
+scale does not express (an exact token budget, OpenAI `none`), use
+`modelOptions` directly.
 
 ## Prompt Caching
 
@@ -1252,9 +1329,9 @@ 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
+## Model Options and Output Limits
 
-`providerOptions` passes provider-specific request fields straight through to
+`modelOptions` passes provider-specific request fields straight through to
 the underlying API: Anthropic merges them into the Messages request body;
 Google merges them into the generation config.
 
@@ -1269,19 +1346,16 @@ truncate:
 - **Streaming** (`stream()`): the model maximum — e.g., 128,000 for current
   Claude models (64,000 for Haiku), 65,536 for Gemini 2.5/3.x
 
-Override per call with `providerOptions`:
+Override per model with `modelOptions`:
 
 ```typescript
-// Anthropic: max_tokens
 await Llm.operate(input, {
   model: LLM.MODEL.SONNET,
-  providerOptions: { max_tokens: 32000 },
-});
-
-// Google: maxOutputTokens
-await Llm.operate(input, {
-  model: LLM.MODEL.GEMINI_PRO,
-  providerOptions: { maxOutputTokens: 32000 },
+  fallback: [{ provider: "google", model: LLM.MODEL.GEMINI_PRO }],
+  modelOptions: {
+    anthropic: { max_tokens: 32000 }, // Anthropic: max_tokens
+    google: { maxOutputTokens: 32000 }, // Google: maxOutputTokens
+  },
 });
 ```
 
@@ -1290,13 +1364,13 @@ 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.
+the ceiling. Set `maxOutputTokens` (Google) or `max_tokens` (Anthropic,
+Mistral) in `modelOptions` to pin it per model.
 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`
+multi-minute request. Override with `modelOptions: { mistral: { max_tokens } }`.
+OpenRouter varies by routed model; pass `max_tokens` via `modelOptions`
 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()`.