@molecule/api-ai-agents-llm 1.0.3 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T23:28:05.760Z
+Generated: 2026-10-27T17:09:52.462Z
 -->
 
 # @molecule/api-ai-agents-llm
@@ -173,6 +173,30 @@ prefix on each of up to `maxSteps` turns. Note `onEvent` is only an
 INCREMENTAL live hook while streaming — with `stream: false` it fires once
 per turn with the whole response.
 
+`input.thinking` forwards the core chat contract's native thinking settings
+on every turn. Streamed reasoning is retained in `ChatMessage.reasoning`
+across tool calls, separately from assistant text and tool arguments.
+Omitting the option does not enable thinking or manufacture reasoning.
+
+Two further options are OPT-IN and change nothing when omitted:
+
+- `input.maxToolResultChars` bounds the `tool_result` copy sent to the model
+  (a whole-file or log dump otherwise crowds out the instruction that asked
+  for it) and appends an explicit truncation note telling the model the value
+  was cut and how to recover. The step record keeps the complete tool result.
+- `input.finalSynthesisOnBudgetExhaustion` spends ONE tool-free turn after
+  the `maxSteps` budget is exhausted, so a run that ended on a tool
+  invocation still returns a final answer instead of the budget note. That
+  turn carries the same history, system, model, thinking, cache, streaming
+  and signal settings plus one short generic instruction to answer now from
+  the evidence already gathered (without it a model mid-investigation can
+  keep planning). Its events reach `onEvent`, its usage is metered, and it
+  cannot call tools: a tool request on that turn is never executed and is not
+  accepted as a final answer. If the turn produces no answer text, `run()`
+  rejects with `AgentRunError` instead of returning the budget note, and the
+  message says whether the turn requested another tool or returned no
+  content (e.g. only reasoning).
+
 Failure semantics (how to tell failure modes apart):
 
 - **Tool failure** (throwing `execute()`, unknown tool name) — NON-fatal:
@@ -187,7 +211,10 @@ Failure semantics (how to tell failure modes apart):
   `result.output` means the model genuinely produced no text, not that the
   API failed.
 - **Step budget exhausted** — resolves normally; `output` is the last
-  assistant text or an explicit "step budget exhausted" note.
+  assistant text or an explicit "step budget exhausted" note. With
+  `input.finalSynthesisOnBudgetExhaustion` the output is instead the answer
+  from one final tool-free turn, and a synthesis that produced no answer
+  rejects (as an `AgentRunError`) rather than resolving with the note.
 
 Swappable like any bond: replace this LLM agent with your own
 `AIAgentsProvider` via `bond('ai-agents', myProvider)` — nothing else changes.

package/dist/index.d.ts

@@ -62,6 +62,30 @@
  * INCREMENTAL live hook while streaming — with `stream: false` it fires once
  * per turn with the whole response.
  *
+ * `input.thinking` forwards the core chat contract's native thinking settings
+ * on every turn. Streamed reasoning is retained in `ChatMessage.reasoning`
+ * across tool calls, separately from assistant text and tool arguments.
+ * Omitting the option does not enable thinking or manufacture reasoning.
+ *
+ * Two further options are OPT-IN and change nothing when omitted:
+ *
+ * - `input.maxToolResultChars` bounds the `tool_result` copy sent to the model
+ *   (a whole-file or log dump otherwise crowds out the instruction that asked
+ *   for it) and appends an explicit truncation note telling the model the value
+ *   was cut and how to recover. The step record keeps the complete tool result.
+ * - `input.finalSynthesisOnBudgetExhaustion` spends ONE tool-free turn after
+ *   the `maxSteps` budget is exhausted, so a run that ended on a tool
+ *   invocation still returns a final answer instead of the budget note. That
+ *   turn carries the same history, system, model, thinking, cache, streaming
+ *   and signal settings plus one short generic instruction to answer now from
+ *   the evidence already gathered (without it a model mid-investigation can
+ *   keep planning). Its events reach `onEvent`, its usage is metered, and it
+ *   cannot call tools: a tool request on that turn is never executed and is not
+ *   accepted as a final answer. If the turn produces no answer text, `run()`
+ *   rejects with `AgentRunError` instead of returning the budget note, and the
+ *   message says whether the turn requested another tool or returned no
+ *   content (e.g. only reasoning).
+ *
  * Failure semantics (how to tell failure modes apart):
  * - **Tool failure** (throwing `execute()`, unknown tool name) — NON-fatal:
  *   recorded on the step with `isError: true` and fed back to the model.
@@ -75,7 +99,10 @@
  *   `result.output` means the model genuinely produced no text, not that the
  *   API failed.
  * - **Step budget exhausted** — resolves normally; `output` is the last
- *   assistant text or an explicit "step budget exhausted" note.
+ *   assistant text or an explicit "step budget exhausted" note. With
+ *   `input.finalSynthesisOnBudgetExhaustion` the output is instead the answer
+ *   from one final tool-free turn, and a synthesis that produced no answer
+ *   rejects (as an `AgentRunError`) rather than resolving with the note.
  *
  * Swappable like any bond: replace this LLM agent with your own
  * `AIAgentsProvider` via `bond('ai-agents', myProvider)` — nothing else changes.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -62,6 +62,30 @@
  * INCREMENTAL live hook while streaming — with `stream: false` it fires once
  * per turn with the whole response.
  *
+ * `input.thinking` forwards the core chat contract's native thinking settings
+ * on every turn. Streamed reasoning is retained in `ChatMessage.reasoning`
+ * across tool calls, separately from assistant text and tool arguments.
+ * Omitting the option does not enable thinking or manufacture reasoning.
+ *
+ * Two further options are OPT-IN and change nothing when omitted:
+ *
+ * - `input.maxToolResultChars` bounds the `tool_result` copy sent to the model
+ *   (a whole-file or log dump otherwise crowds out the instruction that asked
+ *   for it) and appends an explicit truncation note telling the model the value
+ *   was cut and how to recover. The step record keeps the complete tool result.
+ * - `input.finalSynthesisOnBudgetExhaustion` spends ONE tool-free turn after
+ *   the `maxSteps` budget is exhausted, so a run that ended on a tool
+ *   invocation still returns a final answer instead of the budget note. That
+ *   turn carries the same history, system, model, thinking, cache, streaming
+ *   and signal settings plus one short generic instruction to answer now from
+ *   the evidence already gathered (without it a model mid-investigation can
+ *   keep planning). Its events reach `onEvent`, its usage is metered, and it
+ *   cannot call tools: a tool request on that turn is never executed and is not
+ *   accepted as a final answer. If the turn produces no answer text, `run()`
+ *   rejects with `AgentRunError` instead of returning the budget note, and the
+ *   message says whether the turn requested another tool or returned no
+ *   content (e.g. only reasoning).
+ *
  * Failure semantics (how to tell failure modes apart):
  * - **Tool failure** (throwing `execute()`, unknown tool name) — NON-fatal:
  *   recorded on the step with `isError: true` and fed back to the model.
@@ -75,7 +99,10 @@
  *   `result.output` means the model genuinely produced no text, not that the
  *   API failed.
  * - **Step budget exhausted** — resolves normally; `output` is the last
- *   assistant text or an explicit "step budget exhausted" note.
+ *   assistant text or an explicit "step budget exhausted" note. With
+ *   `input.finalSynthesisOnBudgetExhaustion` the output is instead the answer
+ *   from one final tool-free turn, and a synthesis that produced no answer
+ *   rejects (as an `AgentRunError`) rather than resolving with the note.
  *
  * Swappable like any bond: replace this LLM agent with your own
  * `AIAgentsProvider` via `bond('ai-agents', myProvider)` — nothing else changes.

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,YAAY,CAAA;AAOnB,OAAO,KAAK,EAKV,gBAAgB,EACjB,MAAM,yBAAyB,CAAA;AAkHhC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,gBA2KtB,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,YAAY,CAAA;AAOnB,OAAO,KAAK,EAKV,gBAAgB,EACjB,MAAM,yBAAyB,CAAA;AAkLhC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,gBA0QtB,CAAA"}

package/dist/provider.js

@@ -11,9 +11,8 @@
  *
  * @module
  */
-// Side-effect import: registers the `stream`/`cacheControl` module
-// augmentation on `AgentRunInput` (see types.ts) so `input.stream` and
-// `input.cacheControl` below are typed, not `any`.
+// Side-effect import: augments AgentRunInput with this bond's typed request
+// options (see types.ts).
 import './types.js';
 import { getProviderByName as getAiProviderByName, requireProvider as requireAiProvider, } from '@molecule/api-ai';
 import { t } from '@molecule/api-i18n';
@@ -56,6 +55,57 @@ function stringifyResult(result) {
         return String(result);
     }
 }
+/**
+ * Bounds a serialized tool result for the MODEL-FACING conversation and, when
+ * it has to cut, appends an explicit truncation + recovery note.
+ *
+ * @remarks
+ * Only the copy sent to the model is bounded: the step record keeps the
+ * complete value (see `AgentToolCall.result`). The note is appended after the
+ * budget, so it is not counted against it, and the cut never splits a
+ * surrogate pair (an unpaired half is not valid text).
+ *
+ * @param serialized - The complete serialized tool result.
+ * @param maxChars - The character budget, or `undefined` for unbounded.
+ * @returns The content for the `tool_result` block.
+ */
+function boundToolResult(serialized, maxChars) {
+    if (maxChars === undefined || serialized.length <= maxChars)
+        return serialized;
+    let end = maxChars;
+    const lastCode = serialized.charCodeAt(end - 1);
+    // Drop a split surrogate pair rather than send half a code point.
+    if (lastCode >= 0xd800 && lastCode <= 0xdbff)
+        end -= 1;
+    return (serialized.slice(0, end) +
+        t('ai-agents.toolResultTruncated', { shown: end, total: serialized.length }, {
+            defaultValue: '\n\n[Truncated: {{shown}} of {{total}} characters shown. The complete result is retained outside this conversation; call the tool again with a narrower range or smaller scope to read the rest.]',
+        }));
+}
+/**
+ * The model-facing instruction appended to the ONE tool-free synthesis turn
+ * after the step budget is exhausted.
+ *
+ * @remarks
+ * A final turn carrying only the loop's own history is indistinguishable from
+ * any other turn — same system prompt, same conversation, no tools — so a model
+ * that was mid-investigation can keep planning (or emit reasoning alone)
+ * instead of answering. A real bounded review hit exactly that: the whole step
+ * budget was spent, the tool-free turn produced no answer text, and the run
+ * failed with nothing to show for the evidence it had gathered.
+ *
+ * The note is deliberately short and generic — it never names a reviewer,
+ * benchmark, project or route — and is a USER message appended AFTER the
+ * recorded history for that one request, so every earlier message (including
+ * retained native `reasoning`) is still sent unchanged.
+ *
+ * @returns The instruction text for the synthesis turn.
+ */
+function finalSynthesisInstruction() {
+    return t('ai-agents.finalSynthesisInstruction', undefined, {
+        defaultValue: 'The step budget is exhausted and no further tool calls are allowed. Do not request more tools. Answer now, using only the evidence already gathered in this conversation, and briefly state anything you had to leave unchecked.',
+    });
+}
 /**
  * Drains a single chat stream, accumulating text and tool calls, forwarding
  * every event to `onEvent`, and summing `done.usage`.
@@ -66,6 +116,7 @@ function stringifyResult(result) {
  */
 async function drainStream(stream, onEvent) {
     let text = '';
+    let reasoning;
     const toolUses = [];
     const usage = { inputTokens: 0, outputTokens: 0 };
     let errorMessage;
@@ -77,6 +128,9 @@ async function drainStream(stream, onEvent) {
             case 'text':
                 text += event.content;
                 break;
+            case 'thinking':
+                reasoning = (reasoning ?? '') + event.content;
+                break;
             case 'tool_use':
                 toolUses.push({ id: event.id, name: event.name, input: event.input });
                 break;
@@ -103,7 +157,7 @@ async function drainStream(stream, onEvent) {
     if (!sawDone && lastSnapshot) {
         addUsage(usage, lastSnapshot);
     }
-    return { text, toolUses, usage, errorMessage };
+    return { text, reasoning, toolUses, usage, errorMessage };
 }
 /**
  * The LLM-backed AI agents provider: a tool-calling loop over the bonded `ai`
@@ -129,6 +183,15 @@ export const provider = {
                 defaultValue: 'AgentRunInput accepts either `task` or `messages`, not both. Put the task in the `messages` history (as the last user message) or drop one of the two.',
             }));
         }
+        // Validate the opt-in tool-result budget up front: a bad number would
+        // otherwise surface mid-loop as a truncation bug instead of a caller error.
+        const toolResultLimit = input.maxToolResultChars === undefined ? undefined : Math.floor(input.maxToolResultChars);
+        if (toolResultLimit !== undefined &&
+            (!Number.isFinite(toolResultLimit) || toolResultLimit < 1)) {
+            throw new Error(t('ai-agents.error.invalidMaxToolResultChars', { value: String(input.maxToolResultChars) }, {
+                defaultValue: '`maxToolResultChars` must be a finite number of at least 1 character (received {{value}}; fractional values are floored).',
+            }));
+        }
         const ai = input.provider ? getAiProviderByName(input.provider) : requireAiProvider();
         if (!ai) {
             throw new Error(t('ai-agents.error.aiProviderNotFound', { name: input.provider ?? '' }, { defaultValue: `AI provider "${input.provider}" is not bonded.` }));
@@ -140,6 +203,57 @@ export const provider = {
         const steps = [];
         const usage = { inputTokens: 0, outputTokens: 0 };
         let lastText = '';
+        /**
+         * Sends ONE model turn over the bonded chat provider, forwarding every
+         * event to `onEvent`, booking its usage, and rejecting on an in-band
+         * provider error (so "the API failed" never looks like an empty answer).
+         *
+         * @param offerTools - When `false` the request carries NO `tools` field,
+         *   so the provider cannot ask for a tool call (the final synthesis turn).
+         * @param trailingMessages - Messages appended AFTER the loop's history for
+         *   this ONE request only; the loop's own `messages` array is untouched, so
+         *   every other turn sends it exactly as before.
+         * @returns The drained turn.
+         */
+        const modelTurn = async (offerTools, trailingMessages = []) => {
+            const requestMessages = trailingMessages.length > 0 ? [...messages, ...trailingMessages] : messages;
+            const turn = await drainStream(ai.chat({
+                messages: requestMessages,
+                system: input.system,
+                ...(offerTools ? { tools: input.tools } : {}),
+                model: input.model,
+                maxTokens: input.maxTokens,
+                temperature: input.temperature,
+                // Keep the caller's native thinking settings on every tool turn.
+                ...(input.thinking === undefined ? {} : { thinking: input.thinking }),
+                // Defaults to streaming (see the `stream` augmentation in
+                // types.ts): onEvent is a LIVE hook, and non-streaming requests
+                // with large outputs (a big tool input at a raised maxTokens) are
+                // exactly what provider docs warn will time out over HTTP.
+                // drainStream already folds streamed events correctly, so there
+                // is no extra cost to defaulting streaming on. Set
+                // `input.stream: false` to force non-streaming.
+                stream: input.stream !== false,
+                // Prompt-cache breakpoint hint: the system+tools prefix is
+                // identical across turns, so passing this through avoids
+                // re-billing the full (growing) prompt on every one of up to
+                // maxSteps turns. Providers without cache support ignore it.
+                cacheControl: input.cacheControl,
+                signal: input.signal,
+            }), input.onEvent);
+            addUsage(usage, turn.usage);
+            // A provider API failure (rate limit, auth, overload, network) arrives
+            // as an in-band `error` ChatEvent — the stream ends without text or
+            // tools. Rejecting here disambiguates "the AI provider failed" from
+            // "the model legitimately answered nothing": the old fall-through
+            // returned { output: '', steps, usage } as if the run succeeded, and
+            // callers debugging the empty output had no signal that the API ever
+            // errored.
+            if (turn.errorMessage !== undefined) {
+                throw new Error(t('ai-agents.error.providerError', { message: turn.errorMessage }, { defaultValue: `AI provider error during agent run: ${turn.errorMessage}` }));
+            }
+            return turn;
+        };
         // Everything below can fail partway through a multi-turn run (a provider
         // API error, an abort, or an unexpected throw from ai.chat() itself —
         // e.g. a signal-aborted fetch). A plain rejection would silently drop
@@ -151,39 +265,7 @@ export const provider = {
         // `instanceof AgentRunError`.
         try {
             for (let step = 0; step < maxSteps; step++) {
-                const turn = await drainStream(ai.chat({
-                    messages,
-                    system: input.system,
-                    tools: input.tools,
-                    model: input.model,
-                    maxTokens: input.maxTokens,
-                    temperature: input.temperature,
-                    // Defaults to streaming (see the `stream` augmentation in
-                    // types.ts): onEvent is a LIVE hook, and non-streaming requests
-                    // with large outputs (a big tool input at a raised maxTokens) are
-                    // exactly what provider docs warn will time out over HTTP.
-                    // drainStream already folds streamed events correctly, so there
-                    // is no extra cost to defaulting streaming on. Set
-                    // `input.stream: false` to force non-streaming.
-                    stream: input.stream !== false,
-                    // Prompt-cache breakpoint hint: the system+tools prefix is
-                    // identical across turns, so passing this through avoids
-                    // re-billing the full (growing) prompt on every one of up to
-                    // maxSteps turns. Providers without cache support ignore it.
-                    cacheControl: input.cacheControl,
-                    signal: input.signal,
-                }), input.onEvent);
-                addUsage(usage, turn.usage);
-                // A provider API failure (rate limit, auth, overload, network) arrives
-                // as an in-band `error` ChatEvent — the stream ends without text or
-                // tools. Rejecting here disambiguates "the AI provider failed" from
-                // "the model legitimately answered nothing": the old fall-through
-                // returned { output: '', steps, usage } as if the run succeeded, and
-                // callers debugging the empty output had no signal that the API ever
-                // errored.
-                if (turn.errorMessage !== undefined) {
-                    throw new Error(t('ai-agents.error.providerError', { message: turn.errorMessage }, { defaultValue: `AI provider error during agent run: ${turn.errorMessage}` }));
-                }
+                const turn = await modelTurn(true);
                 if (turn.text)
                     lastText = turn.text;
                 // Append the assistant turn: a text block (if any) + one tool_use block
@@ -194,7 +276,11 @@ export const provider = {
                 for (const tu of turn.toolUses) {
                     assistantContent.push({ type: 'tool_use', id: tu.id, name: tu.name, input: tu.input });
                 }
-                messages.push({ role: 'assistant', content: assistantContent });
+                messages.push({
+                    role: 'assistant',
+                    content: assistantContent,
+                    ...(turn.reasoning === undefined ? {} : { reasoning: turn.reasoning }),
+                });
                 if (turn.toolUses.length === 0) {
                     // No tools requested — the model is done.
                     return { output: turn.text, steps, usage };
@@ -226,17 +312,57 @@ export const provider = {
                             isError = true;
                         }
                     }
+                    // `result` (above) is retained COMPLETE on the step record; only the
+                    // copy the model reads is bounded when `maxToolResultChars` is set.
                     toolCalls.push({ id: tu.id, name: tu.name, input: tu.input, result, isError });
                     resultBlocks.push({
                         type: 'tool_result',
                         tool_use_id: tu.id,
-                        content: stringifyResult(result),
+                        content: boundToolResult(stringifyResult(result), toolResultLimit),
                     });
                 }
                 messages.push({ role: 'user', content: resultBlocks });
                 steps.push({ text: turn.text || undefined, toolCalls });
             }
-            // Step budget exhausted while the model was still calling tools.
+            // Step budget exhausted while the model was still calling tools. With
+            // `finalSynthesisOnBudgetExhaustion`, buy exactly ONE tool-free turn to
+            // answer from what the run already saw — the loop ended on a tool
+            // invocation, so there is no final assistant text to return otherwise.
+            // The request also carries one short generic instruction saying the
+            // budget is spent and to answer now: without it the turn is just the same
+            // conversation with no tools, and a model mid-investigation can keep
+            // planning (a real bounded review produced no answer text at exactly that
+            // turn). The instruction is appended for this request only; the loop's
+            // history, system prompt, model settings and cache/usage/error contracts
+            // are all unchanged.
+            if (input.finalSynthesisOnBudgetExhaustion === true) {
+                const finalTurn = await modelTurn(false, [
+                    { role: 'user', content: finalSynthesisInstruction() },
+                ]);
+                // A renewed tool request is NOT an answer. That turn offered no tools,
+                // so nothing it asks for can be executed, and a plan to keep going must
+                // not be passed off as the final output — whether or not the turn also
+                // emitted text. Report this cause distinctly from a content-free turn.
+                if (finalTurn.toolUses.length > 0) {
+                    throw new Error(t('ai-agents.error.finalSynthesisToolRequest', undefined, {
+                        defaultValue: 'Agent step budget exhausted and the final synthesis turn requested another tool instead of answering; no further tool calls are allowed.',
+                    }));
+                }
+                // Content-free is its own cause: a turn that emitted only reasoning (or
+                // nothing at all) produced no answer, and the message says which, so a
+                // caller can tell "the model kept thinking" from "the model tried to
+                // call a tool".
+                if (!finalTurn.text.trim()) {
+                    const reasoningOnly = finalTurn.reasoning?.trim()
+                        ? ' It returned only reasoning text and no answer.'
+                        : '';
+                    throw new Error(t('ai-agents.error.finalSynthesisEmpty', undefined, {
+                        defaultValue: 'Agent step budget exhausted and the final synthesis turn produced no answer.' +
+                            reasoningOnly,
+                    }));
+                }
+                return { output: finalTurn.text, steps, usage };
+            }
             const output = lastText ||
                 t('ai-agents.stepBudgetExhausted', undefined, {
                     defaultValue: 'Agent stopped: step budget exhausted before a final answer.',

package/dist/types.d.ts

@@ -1,21 +1,29 @@
 /**
  * Module augmentation: extends the core `@molecule/api-ai-agents` contract's
- * `AgentRunInput` with two options this bond's `run()` honors.
+ * `AgentRunInput` with options this bond's `run()` honors.
  *
  * @remarks
- * Both fields are ADDITIVE ONLY — they never widen or erase an existing
+ * These fields are ADDITIVE ONLY — they never widen or erase an existing
  * `AgentRunInput` field — and are consumed exclusively by this bond's `run()`
  * implementation; a different `AIAgentsProvider` bond is free to ignore them.
  * Any file that imports `@molecule/api-ai-agents-llm` (directly, or
  * transitively by bonding its `provider`) sees the merged `AgentRunInput`
  * type, matching the shape `@molecule/api-ai`'s `ChatParams` already accepts
- * for `stream` and `cacheControl`.
+ * for `stream`, `cacheControl`, and `thinking`.
  *
  * @module
  */
 import '@molecule/api-ai-agents';
+import type { ChatParams } from '@molecule/api-ai';
 declare module '@molecule/api-ai-agents' {
     interface AgentRunInput {
+        /**
+         * Native thinking settings forwarded unchanged on every model turn.
+         * Streamed thinking is retained as `ChatMessage.reasoning` when a tool
+         * call continues, so providers that replay reasoning receive it intact.
+         * Omitting this option does not enable thinking.
+         */
+        thinking?: ChatParams['thinking'];
         /**
          * Whether each model turn streams its response (default `true`).
          *
@@ -42,6 +50,70 @@ declare module '@molecule/api-ai-agents' {
         cacheControl?: {
             type: 'ephemeral';
         };
+        /**
+         * Caps how many characters of a serialized tool result are placed in the
+         * model-facing conversation (default: unbounded).
+         *
+         * A tool that returns a whole file, log, or search dump can consume most
+         * of the context window in one step and crowd out the instruction that
+         * asked for it, so a bounded run can "forget" what it was doing and answer
+         * from the dump instead. When set, each `tool_result` block sent to the
+         * model carries at most this many characters of the serialized result,
+         * followed by an explicit note stating that the value was truncated and
+         * how to recover (re-run the tool with a narrower range or scope). The
+         * step record's `AgentToolCall.result` keeps the COMPLETE value — only the
+         * copy the model sees is bounded, so a caller reading the steps (a report,
+         * a diff, an assertion) still gets everything the tool returned.
+         *
+         * The limit applies to the result body; the truncation note is appended
+         * after it and is not counted against the budget. Results at or under the
+         * limit — including the loop's own error strings — pass through unchanged.
+         * A cut never splits a surrogate pair. Must be a finite number of at least
+         * 1 character (fractional values are floored); any other value rejects the
+         * run before a model call is made. Omit it for the previous unbounded
+         * behavior.
+         */
+        maxToolResultChars?: number;
+        /**
+         * After the `maxSteps` budget is exhausted while the model was still
+         * calling tools, spend ONE final synthesis turn with NO tools and return
+         * its text as `output` (default `false`).
+         *
+         * Without it, a run that ends on a tool invocation has no final assistant
+         * text: `output` falls back to the "step budget exhausted" note and any
+         * report the model was about to write is lost, even though the work that
+         * filled the budget succeeded. Opting in buys the model one tool-free turn
+         * to answer from what it has already seen.
+         *
+         * The synthesis turn preserves everything the loop was using: the full
+         * message history (including retained reasoning), `system`, `model`,
+         * `maxTokens`, `temperature`, `thinking`, `stream`, `cacheControl`,
+         * `provider`, and `signal`. It also carries ONE short, generic instruction
+         * (a user message appended after the history, for that request only)
+         * stating that the step budget is exhausted, that no further tool calls
+         * are allowed, and to answer now from the evidence already gathered.
+         * Without it a tool-free turn is just the same conversation with no tools,
+         * and a model mid-investigation can keep planning instead of answering.
+         * Its events reach `onEvent` and its usage is added to `result.usage`, so
+         * live monitoring and metering see the extra call. The instruction is
+         * never sent on any other turn, so normal runs are byte- and
+         * cost-identical.
+         *
+         * It offers no tools and never executes a tool call: a tool request on that
+         * turn cannot be executed and is NOT accepted as a final answer (even when
+         * the turn also emitted text), because it is a plan to keep going rather
+         * than an answer. The recorded `steps` stay exactly the tool-invoking
+         * rounds — `steps.length >= maxSteps` still means "budget exhausted".
+         *
+         * The response is returned as-is (not trimmed). A turn that produces no
+         * answer text is NOT papered over with the exhausted-budget note: `run()`
+         * rejects with an `AgentRunError` carrying the accumulated `usage`/`steps`,
+         * and the message distinguishes a content-free turn (including one that
+         * returned only reasoning) from a turn that requested another tool. A
+         * provider error on that turn rejects the same way. Only the literal `true`
+         * enables this; omit it for the previous behavior and cost.
+         */
+        finalSynthesisOnBudgetExhaustion?: boolean;
     }
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,yBAAyB,CAAA;AAEhC,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,aAAa;QACrB;;;;;;;;;;;;;;WAcG;QACH,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB;;;;;;WAMG;QACH,YAAY,CAAC,EAAE;YAAE,IAAI,EAAE,WAAW,CAAA;SAAE,CAAA;KACrC;CACF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,yBAAyB,CAAA;AAEhC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,aAAa;QACrB;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAA;QACjC;;;;;;;;;;;;;;WAcG;QACH,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB;;;;;;WAMG;QACH,YAAY,CAAC,EAAE;YAAE,IAAI,EAAE,WAAW,CAAA;SAAE,CAAA;QACpC;;;;;;;;;;;;;;;;;;;;;;WAsBG;QACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAsCG;QACH,gCAAgC,CAAC,EAAE,OAAO,CAAA;KAC3C;CACF"}

package/dist/types.js

@@ -1,15 +1,15 @@
 /**
  * Module augmentation: extends the core `@molecule/api-ai-agents` contract's
- * `AgentRunInput` with two options this bond's `run()` honors.
+ * `AgentRunInput` with options this bond's `run()` honors.
  *
  * @remarks
- * Both fields are ADDITIVE ONLY — they never widen or erase an existing
+ * These fields are ADDITIVE ONLY — they never widen or erase an existing
  * `AgentRunInput` field — and are consumed exclusively by this bond's `run()`
  * implementation; a different `AIAgentsProvider` bond is free to ignore them.
  * Any file that imports `@molecule/api-ai-agents-llm` (directly, or
  * transitively by bonding its `provider`) sees the merged `AgentRunInput`
  * type, matching the shape `@molecule/api-ai`'s `ChatParams` already accepts
- * for `stream` and `cacheControl`.
+ * for `stream`, `cacheControl`, and `thinking`.
  *
  * @module
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-agents-llm",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "LLM-backed AI agents provider for molecule.dev — a tool-calling loop over the swappable @molecule/api-ai chat bond",
   "homepage": "https://www.molecule.dev/packages/api-ai-agents-llm",
   "type": "module",
@@ -41,10 +41,10 @@
     "@molecule/api-i18n": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.3.5",
+    "@molecule/api-ai": "1.4.0",
     "@molecule/api-ai-agents": "1.0.3",
-    "@molecule/api-bond": "1.0.3",
-    "@molecule/api-i18n": "1.0.4",
+    "@molecule/api-bond": "1.0.4",
+    "@molecule/api-i18n": "1.0.5",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",
     "vitest": "4.1.12"