@sprucelabs/sprucebot-llm 18.0.1 → 18.1.1

package/README.md

@@ -73,7 +73,7 @@ Here are the contents of that file for you to review now, rather than needing to
 import { stdin as input, stdout as output } from 'node:process'
 import * as readline from 'node:readline/promises'
 import dotenv from 'dotenv'
-import OpenAiAdapter from './bots/adapters/OpenAi'
+import OpenAiAdapter from './bots/adapters/OpenAiAdapter'
 import SprucebotLlmFactory from './bots/SprucebotLlmFactory'
 import buildCallbackSkill from './examples/buildCallbackSkill'
 import buildFileTransformerSkill from './examples/buildFileTransformerSkill'
@@ -131,7 +131,7 @@ void (async () => {
 There are two different limits to be aware of:
 
 - `SprucebotLlmBotImpl.messageMemoryLimit` (default: `10`) controls how many messages are kept in the in-memory history on the Bot. Once the limit is hit, old messages are dropped and can no longer be sent to any adapter.
-- `OPENAI_MESSAGE_MEMORY_LIMIT` or `OpenAiAdapter.setMessageMemoryLimit(limit)` controls how many of those tracked messages are included when sending a request to OpenAI. `0` (the default) means "no additional limit" beyond the Bot history.
+- `OPENAI_MESSAGE_MEMORY_LIMIT` or `adapter.setMemoryLimit(limit)` controls how many of those tracked messages are included when sending a request to OpenAI. `0` (the default) means "no additional limit" beyond the Bot history.
 
 To change the Bot history limit:
 
@@ -148,6 +148,28 @@ Additional OpenAI context controls:
 
 ## Adapters
 
+### Custom request headers
+
+You can attach custom HTTP headers to every underlying provider request a bot makes — useful for gateways, request tracing, or provider beta feature flags. Headers are threaded through the Bot's normal `sendMessage(...)` flow, so you set them once on the Bot.
+
+Set them when constructing the bot:
+
+```ts
+const bot = bots.Bot({
+    youAre: 'a helpful assistant',
+    skill: mySkill,
+    headers: { 'x-my-trace-id': '1234' },
+})
+```
+
+Or update them at any time (e.g. to rotate a trace id per conversation):
+
+```ts
+bot.setHeaders({ 'x-my-trace-id': '5678' })
+```
+
+The headers flow through to the underlying OpenAI / Anthropic request on the next `sendMessage`. Adapters also accept them per-call via `SendMessageOptions` if you call `adapter.sendMessage(bot, { model, headers })` directly.
+
 ### OpenAI adapter configuration
 
 Required environment variable:
@@ -178,7 +200,7 @@ const adapter = OpenAiAdapter.Adapter(process.env.OPEN_AI_API_KEY!, {
 
 // Or set after creation
 adapter.setModel('gpt-4o')
-adapter.setMessageMemoryLimit(10)
+adapter.setMemoryLimit(10)
 adapter.setReasoningEffort('low')
 ```
 
@@ -193,7 +215,7 @@ adapter.setReasoningEffort('low')
   - `reasoningEffort` - for reasoning models (`'low'`, `'medium'`, `'high'`)
   - `baseUrl` - custom API endpoint
 - `adapter.setModel(model)`: set a default model for all requests unless a Skill overrides it.
-- `adapter.setMessageMemoryLimit(limit)`: limit how many tracked messages are sent to OpenAI.
+- `adapter.setMemoryLimit(limit)`: limit how many tracked messages are sent to OpenAI.
 - `adapter.setReasoningEffort(effort)`: set `reasoning_effort` for models that support it.
 - `adapter.getTokenUsage()`: returns cumulative [token usage](#tracking-token-usage) for this adapter. The OpenAI adapter currently returns zeros (not yet implemented).
 - `OpenAiAdapter.OpenAI`: assign a custom OpenAI client class (useful for tests).
@@ -230,7 +252,7 @@ const bots = SprucebotLlmFactory.Factory(adapter)
 
 #### Anthropic prompt caching
 
-The Anthropic adapter automatically enables [prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) by inserting an `ephemeral` cache breakpoint after the system prompt. This allows Anthropic to cache the static portion of the prompt (your `youAre` + skill instructions) and only re-process the changing chat history on each turn — reducing latency and cost on long conversations.
+The Anthropic adapter automatically enables [prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) by inserting an `ephemeral` cache breakpoint (with a `1h` TTL) after the system prompt. This allows Anthropic to cache the static portion of the prompt (your `youAre` + skill instructions) and only re-process the changing chat history on each turn — reducing latency and cost on long conversations.
 
 Token usage (including cache creation and cache read tokens) is logged at the `info` level on each request:
 
@@ -689,6 +711,7 @@ skill.unserialize(skillSnapshot)
 | `clearMessageHistory()` | Drop all tracked messages |
 | `updateState(partialState)` | Update state and emit `did-update-state` |
 | `setSkill(skill)` | Swap the active skill |
+| `setHeaders(headers)` | Set custom HTTP headers attached to subsequent provider requests |
 | `serialize()` | Snapshot of bot's current state, skill, and history |
 | `unserialize(serialized)` | Restore state from a previous `serialize()` snapshot |
 
@@ -698,6 +721,7 @@ skill.unserialize(skillSnapshot)
 |--------|-------------|
 | `updateState(partialState)` | Update skill state |
 | `getState()` | Get current state |
+| `updateJobDescription(prompt)` | Change the skill's job description (`yourJobIfYouChooseToAcceptItIs`) |
 | `setModel(model)` | Change the model this skill uses |
 | `serialize()` | Snapshot of skill configuration and state |
 | `unserialize(serialized)` | Restore skill state from a previous `serialize()` snapshot |

package/build/bots/SprucebotLlmBotImpl.d.ts

@@ -11,6 +11,7 @@ export default class SprucebotLlmBotImpl<StateSchema extends Schema = Schema, St
     protected messages: LlmMessage[];
     protected skill?: SprucebotLLmSkill;
     private activeTurn?;
+    private headers?;
     constructor(options: BotOptions<StateSchema, State>);
     clearMessageHistory(): void;
     markAsDone(): void;
@@ -25,4 +26,5 @@ export default class SprucebotLlmBotImpl<StateSchema extends Schema = Schema, St
     getStateSchema(): StateSchema | undefined;
     getState(): Partial<State> | undefined;
     silentlySetState(state: Partial<State>): void;
+    setHeaders(headers: Record<string, string>): void;
 }

package/build/bots/SprucebotLlmBotImpl.js

@@ -10,7 +10,7 @@ const InternalStateUpdater_1 = __importDefault(require("./InternalStateUpdater")
 const TurnRequest_1 = __importDefault(require("./TurnRequest"));
 class SprucebotLlmBotImpl extends mercury_event_emitter_1.AbstractEventEmitter {
     constructor(options) {
-        const { adapter, youAre, stateSchema, state, skill } = options;
+        const { adapter, youAre, stateSchema, state, skill, headers } = options;
         super(llm_types_1.llmEventContract);
         this.isDone = false;
         this.messages = [];
@@ -18,6 +18,7 @@ class SprucebotLlmBotImpl extends mercury_event_emitter_1.AbstractEventEmitter {
         this.youAre = youAre;
         this.stateSchema = stateSchema;
         this.skill = skill;
+        this.headers = headers;
         this.state = stateSchema
             ? {
                 ...(0, schema_1.defaultSchemaValues)(stateSchema),
@@ -72,6 +73,7 @@ class SprucebotLlmBotImpl extends mercury_event_emitter_1.AbstractEventEmitter {
             setDone: (isDone) => (this.isDone = isDone),
             skill: this.skill,
             trackMessage: this.trackMessage.bind(this),
+            headers: this.headers,
         });
         return this.activeTurn.sendMessage(llmMessage, cb);
     }
@@ -105,6 +107,9 @@ class SprucebotLlmBotImpl extends mercury_event_emitter_1.AbstractEventEmitter {
     silentlySetState(state) {
         this.state = state;
     }
+    setHeaders(headers) {
+        this.headers = headers;
+    }
 }
 SprucebotLlmBotImpl.messageMemoryLimit = 10;
 exports.default = SprucebotLlmBotImpl;

package/build/bots/TurnRequest.d.ts

@@ -7,6 +7,7 @@ export default class TurnRequest {
     private optionallyUpdateState;
     private bot;
     private isCancelled;
+    private headers?;
     constructor(options: {
         trackMessage: (message: LlmMessage) => void;
         setDone: (isDone: boolean) => void;
@@ -14,6 +15,7 @@ export default class TurnRequest {
         skill?: SprucebotLLmSkill;
         adapter: LlmAdapter;
         optionallyUpdateState: (state?: Record<string, any>) => Promise<void>;
+        headers?: Record<string, string>;
     });
     cancel(): void;
     sendMessage(llmMessage: LlmMessage, cb?: MessageResponseCallback): Promise<string | null>;

package/build/bots/TurnRequest.js

@@ -8,13 +8,14 @@ const ResponseParserFactory_1 = __importDefault(require("../parsingResponses/Res
 class TurnRequest {
     constructor(options) {
         this.isCancelled = false;
-        const { trackMessage, skill, bot, adapter, setDone, optionallyUpdateState, } = options;
+        const { trackMessage, skill, bot, adapter, setDone, optionallyUpdateState, headers, } = options;
         this.trackMessage = trackMessage;
         this.skill = skill;
         this.adapter = adapter;
         this.setDone = setDone;
         this.bot = bot;
         this.optionallyUpdateState = optionallyUpdateState;
+        this.headers = headers;
     }
     cancel() {
         this.isCancelled = true;
@@ -85,11 +86,18 @@ class TurnRequest {
         return parsedMessage;
     }
     async sendMessageToAdapter(model) {
-        return await this.adapter.sendMessage(this.bot, model
-            ? {
+        let options = undefined;
+        if (model) {
+            options = {
                 model,
-            }
-            : undefined);
+            };
+        }
+        if (this.headers) {
+            options = options
+                ? { ...options, headers: this.headers }
+                : { headers: this.headers };
+        }
+        return await this.adapter.sendMessage(this.bot, options);
     }
     async parseResponse(response, callbacks) {
         const parser = ResponseParserFactory_1.default.getInstance();

package/build/bots/adapters/MessageSender.d.ts

@@ -35,4 +35,5 @@ export type MessageSenderSendMessageOptions = SendMessageOptions & {
     memoryLimit?: number;
     reasoningEffort?: ReasoningEffort;
     model: string;
+    headers?: Record<string, string>;
 };

package/build/bots/adapters/MessageSender.js

@@ -45,16 +45,20 @@ class MessageSenderImpl {
         }
     }
     async send(options) {
-        const { abortController, reasoningEffort, ...restOptions } = options;
+        const { abortController, reasoningEffort, headers, ...restOptions } = options;
         const params = {
             ...restOptions,
         };
         if (reasoningEffort) {
             params.reasoning_effort = reasoningEffort;
         }
-        const response = await this.sendHandler(params, {
+        const request = {
             signal: abortController.signal,
-        });
+        };
+        if (headers) {
+            request.headers = headers;
+        }
+        const response = await this.sendHandler(params, request);
         return response;
     }
 }

package/build/esm/bots/SprucebotLlmBotImpl.d.ts

@@ -11,6 +11,7 @@ export default class SprucebotLlmBotImpl<StateSchema extends Schema = Schema, St
     protected messages: LlmMessage[];
     protected skill?: SprucebotLLmSkill;
     private activeTurn?;
+    private headers?;
     constructor(options: BotOptions<StateSchema, State>);
     clearMessageHistory(): void;
     markAsDone(): void;
@@ -25,4 +26,5 @@ export default class SprucebotLlmBotImpl<StateSchema extends Schema = Schema, St
     getStateSchema(): StateSchema | undefined;
     getState(): Partial<State> | undefined;
     silentlySetState(state: Partial<State>): void;
+    setHeaders(headers: Record<string, string>): void;
 }

package/build/esm/bots/SprucebotLlmBotImpl.js

@@ -14,7 +14,7 @@ import InternalStateUpdater from './InternalStateUpdater.js';
 import TurnRequest from './TurnRequest.js';
 class SprucebotLlmBotImpl extends AbstractEventEmitter {
     constructor(options) {
-        const { adapter, youAre, stateSchema, state, skill } = options;
+        const { adapter, youAre, stateSchema, state, skill, headers } = options;
         super(llmEventContract);
         this.isDone = false;
         this.messages = [];
@@ -22,6 +22,7 @@ class SprucebotLlmBotImpl extends AbstractEventEmitter {
         this.youAre = youAre;
         this.stateSchema = stateSchema;
         this.skill = skill;
+        this.headers = headers;
         this.state = stateSchema
             ? Object.assign(Object.assign({}, defaultSchemaValues(stateSchema)), state)
             : undefined;
@@ -77,6 +78,7 @@ class SprucebotLlmBotImpl extends AbstractEventEmitter {
                 setDone: (isDone) => (this.isDone = isDone),
                 skill: this.skill,
                 trackMessage: this.trackMessage.bind(this),
+                headers: this.headers,
             });
             return this.activeTurn.sendMessage(llmMessage, cb);
         });
@@ -116,6 +118,9 @@ class SprucebotLlmBotImpl extends AbstractEventEmitter {
     silentlySetState(state) {
         this.state = state;
     }
+    setHeaders(headers) {
+        this.headers = headers;
+    }
 }
 SprucebotLlmBotImpl.messageMemoryLimit = 10;
 export default SprucebotLlmBotImpl;

package/build/esm/bots/TurnRequest.d.ts

@@ -7,6 +7,7 @@ export default class TurnRequest {
     private optionallyUpdateState;
     private bot;
     private isCancelled;
+    private headers?;
     constructor(options: {
         trackMessage: (message: LlmMessage) => void;
         setDone: (isDone: boolean) => void;
@@ -14,6 +15,7 @@ export default class TurnRequest {
         skill?: SprucebotLLmSkill;
         adapter: LlmAdapter;
         optionallyUpdateState: (state?: Record<string, any>) => Promise<void>;
+        headers?: Record<string, string>;
     });
     cancel(): void;
     sendMessage(llmMessage: LlmMessage, cb?: MessageResponseCallback): Promise<string | null>;

package/build/esm/bots/TurnRequest.js

@@ -12,13 +12,14 @@ import ResponseParserFactory from '../parsingResponses/ResponseParserFactory.js'
 export default class TurnRequest {
     constructor(options) {
         this.isCancelled = false;
-        const { trackMessage, skill, bot, adapter, setDone, optionallyUpdateState, } = options;
+        const { trackMessage, skill, bot, adapter, setDone, optionallyUpdateState, headers, } = options;
         this.trackMessage = trackMessage;
         this.skill = skill;
         this.adapter = adapter;
         this.setDone = setDone;
         this.bot = bot;
         this.optionallyUpdateState = optionallyUpdateState;
+        this.headers = headers;
     }
     cancel() {
         this.isCancelled = true;
@@ -93,11 +94,17 @@ export default class TurnRequest {
     }
     sendMessageToAdapter(model) {
         return __awaiter(this, void 0, void 0, function* () {
-            return yield this.adapter.sendMessage(this.bot, model
-                ? {
+            let options = undefined;
+            if (model) {
+                options = {
                     model,
-                }
-                : undefined);
+                };
+            }
+            if (this.headers) {
+                options = options
+                    ? Object.assign(Object.assign({}, options), { headers: this.headers }) : { headers: this.headers };
+            }
+            return yield this.adapter.sendMessage(this.bot, options);
         });
     }
     parseResponse(response, callbacks) {

package/build/esm/bots/adapters/MessageSender.d.ts

@@ -35,4 +35,5 @@ export type MessageSenderSendMessageOptions = SendMessageOptions & {
     memoryLimit?: number;
     reasoningEffort?: ReasoningEffort;
     model: string;
+    headers?: Record<string, string>;
 };

package/build/esm/bots/adapters/MessageSender.js

@@ -61,14 +61,18 @@ class MessageSenderImpl {
     }
     send(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { abortController, reasoningEffort } = options, restOptions = __rest(options, ["abortController", "reasoningEffort"]);
+            const { abortController, reasoningEffort, headers } = options, restOptions = __rest(options, ["abortController", "reasoningEffort", "headers"]);
             const params = Object.assign({}, restOptions);
             if (reasoningEffort) {
                 params.reasoning_effort = reasoningEffort;
             }
-            const response = yield this.sendHandler(params, {
+            const request = {
                 signal: abortController.signal,
-            });
+            };
+            if (headers) {
+                request.headers = headers;
+            }
+            const response = yield this.sendHandler(params, request);
             return response;
         });
     }

package/build/esm/llm.types.d.ts

@@ -5,6 +5,7 @@ export interface BotOptions<StateSchema extends Schema = Schema, State extends S
     adapter: LlmAdapter;
     Class?: new (...opts: any[]) => SprucebotLlmBot<Schema, State>;
     skill?: SprucebotLLmSkill<Schema>;
+    headers?: Record<string, string>;
 }
 export interface SprucebotLlmBot<StateSchema extends Schema = Schema, State extends SchemaValues<StateSchema> = SchemaValues<StateSchema>> extends MercuryEventEmitter<LlmEventContract> {
     markAsDone(): void;
@@ -14,6 +15,7 @@ export interface SprucebotLlmBot<StateSchema extends Schema = Schema, State exte
     unserialize(serialized: SerializedBot<StateSchema, State>): void;
     updateState(state: Partial<State>): Promise<void>;
     setSkill(skill: SprucebotLLmSkill<any>): void;
+    setHeaders(headers: Record<string, string>): void;
     clearMessageHistory(): void;
 }
 export interface LlmAdapter {
@@ -41,6 +43,7 @@ export interface PromptOptions<StateSchema extends Schema, State extends SchemaV
 }
 export interface SendMessageOptions {
     model?: string;
+    headers?: Record<string, string>;
 }
 export interface SerializedBot<StateSchema extends Schema = Schema, State extends SchemaValues<StateSchema> = SchemaValues<StateSchema>> extends PromptOptions<Schema, State> {
     messages: LlmMessage[];

package/build/esm/parsingResponses/ResponseParserV2.d.ts

@@ -1,4 +1,10 @@
 import { ResponseParser, LlmCallbackMap, ParsedResponse } from '../llm.types';
+/**
+ * Always produce a serializable error representation for @results.
+ * Plain Error becomes its message (never {}). Schema-like errors with enumerable
+ * payload fall back to message string for a stable wire format.
+ */
+export declare function serializeCallbackError(err: unknown): string;
 export default class ResponseParserV2 implements ResponseParser {
     parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
     private invokeCallbacks;

package/build/esm/parsingResponses/ResponseParserV2.js

@@ -9,14 +9,186 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { DONE_TOKEN } from '../bots/templates.js';
 import validateAndNormalizeCallbackOptions from './validateAndNormalizeCallbackOptions.js';
+const RESERVED_CALLBACK_NAMES = new Set(['updateState', 'results']);
+/**
+ * Always produce a serializable error representation for @results.
+ * Plain Error becomes its message (never {}). Schema-like errors with enumerable
+ * payload fall back to message string for a stable wire format.
+ */
+export function serializeCallbackError(err) {
+    if (err instanceof Error) {
+        return err.message && err.message.length > 0 ? err.message : 'Error';
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (err === null) {
+        return 'null';
+    }
+    if (err === undefined) {
+        return 'undefined';
+    }
+    if (typeof err === 'symbol') {
+        return String(err);
+    }
+    try {
+        const json = JSON.stringify(err);
+        if (json && json !== '{}') {
+            return json;
+        }
+    }
+    catch (_a) {
+        // fall through
+    }
+    try {
+        return String(err);
+    }
+    catch (_b) {
+        return 'Unknown error';
+    }
+}
+/** Find matching closing brace for a JSON object starting at openIdx ('{'). */
+function findMatchingBrace(text, openIdx) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = openIdx; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escape = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Extract @name(...) call spans. Supports multi-line JSON objects via brace-depth
+ * scanning and optional leading/trailing whitespace on the call line.
+ */
+function extractCallbackSpans(message) {
+    const spans = [];
+    const re = /^[ \t]*@([A-Za-z_]\w*)\(/gm;
+    let m;
+    while ((m = re.exec(message)) !== null) {
+        const name = m[1];
+        const start = m.index;
+        const openParen = m.index + m[0].length - 1;
+        let i = openParen + 1;
+        while (i < message.length && /[ \t\r\n]/.test(message[i])) {
+            i++;
+        }
+        let argsJson;
+        let closeParen;
+        if (i < message.length && message[i] === ')') {
+            closeParen = i;
+            argsJson = undefined;
+        }
+        else if (i < message.length && message[i] === '{') {
+            const braceEnd = findMatchingBrace(message, i);
+            if (braceEnd < 0) {
+                spans.push({
+                    name,
+                    fullMatch: message.slice(start),
+                    start,
+                    end: message.length,
+                });
+                break;
+            }
+            argsJson = message.slice(i, braceEnd + 1);
+            let j = braceEnd + 1;
+            while (j < message.length && /[ \t\r\n]/.test(message[j])) {
+                j++;
+            }
+            if (j >= message.length || message[j] !== ')') {
+                spans.push({
+                    name,
+                    fullMatch: message.slice(start, braceEnd + 1),
+                    argsJson,
+                    start,
+                    end: braceEnd + 1,
+                });
+                re.lastIndex = braceEnd + 1;
+                continue;
+            }
+            closeParen = j;
+        }
+        else {
+            re.lastIndex = openParen + 1;
+            continue;
+        }
+        let end = closeParen + 1;
+        // Include trailing newline after the call when present (common LLM layout)
+        if (message[end] === '\r') {
+            end++;
+        }
+        if (message[end] === '\n') {
+            end++;
+        }
+        // Leading newline is part of fullMatch when start points after prior content;
+        // also absorb a single leading newline just before the match for strip parity
+        // with historic `\n@name(...)\n` fixtures.
+        let matchStart = start;
+        if (matchStart > 0 && message[matchStart - 1] === '\n') {
+            matchStart--;
+            if (matchStart > 0 && message[matchStart - 1] === '\r') {
+                matchStart--;
+            }
+        }
+        spans.push({
+            name,
+            fullMatch: message.slice(matchStart, end),
+            argsJson,
+            start: matchStart,
+            end,
+        });
+        re.lastIndex = end;
+    }
+    return spans;
+}
+function stripCallFromMessage(message, fullMatch) {
+    // Historic behavior: remove the call span and glue surrounding text without
+    // injecting separators (trim each side after split).
+    return message
+        .split(fullMatch)
+        .map((s) => s.trim())
+        .join('')
+        .trim();
+}
 export default class ResponseParserV2 {
     parse(response, callbacks) {
         return __awaiter(this, void 0, void 0, function* () {
             let message = response.replace(DONE_TOKEN, '').trim();
             let state = undefined;
             let callbackResults = undefined;
-            const hasCallbacks = callbacks != null &&
+            // Enter the pass when any @name( call shape is present (incl. typos)
+            // or when a registered callback name appears as a call prefix.
+            const hasCallShape = message != null && /^[ \t]*@\w+\(/m.test(message);
+            const hasRegisteredName = callbacks != null &&
                 Object.keys(callbacks).some((name) => message.includes(`@${name}(`));
+            const hasCallbacks = hasCallShape || hasRegisteredName;
             if (hasCallbacks) {
                 const { callbackResults: c, message: m } = yield this.invokeCallbacks(message, callbacks);
                 callbackResults = c;
@@ -53,26 +225,36 @@ export default class ResponseParserV2 {
     }
     invokeCallbacks(message, callbacks) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             let callbackStrippedMessage = message;
             let callbackResults = '';
-            const reserved = new Set(['updateState', 'results']);
-            const matches = [...message.matchAll(/^@(\w+)\(({.*})?\)$/gm)];
-            for (const match of matches) {
-                if (reserved.has(match[1])) {
+            const spans = extractCallbackSpans(message);
+            for (const span of spans) {
+                if (RESERVED_CALLBACK_NAMES.has(span.name)) {
+                    continue;
+                }
+                const name = span.name;
+                // Always strip the call from the user-facing message once recognized.
+                callbackStrippedMessage = stripCallFromMessage(callbackStrippedMessage, span.fullMatch);
+                let options;
+                try {
+                    options = span.argsJson ? JSON.parse(span.argsJson) : undefined;
+                }
+                catch (err) {
+                    callbackResults += this.renderCallbackResults({
+                        name,
+                        error: `Invalid JSON arguments for @${name}: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : String(err)}. Arguments must be valid JSON object.`,
+                    });
                     continue;
                 }
-                const parsed = match[2] ? JSON.parse(match[2]) : undefined;
-                const name = match[1];
-                const options = parsed;
                 const callback = callbacks === null || callbacks === void 0 ? void 0 : callbacks[name];
                 if (!callback) {
+                    callbackResults += this.renderCallbackResults({
+                        name,
+                        error: `Unknown callback @${name} — not registered.`,
+                    });
                     continue;
                 }
-                const parts = callbackStrippedMessage.split(match[0]);
-                callbackStrippedMessage = parts
-                    .map((s) => s.trim())
-                    .join('')
-                    .trim();
                 try {
                     if (callback === null || callback === void 0 ? void 0 : callback.parameters) {
                         validateAndNormalizeCallbackOptions(callback.parameters, options);
@@ -89,7 +271,7 @@ export default class ResponseParserV2 {
             }
             callbackResults = callbackResults.trim();
             return {
-                callbackResults,
+                callbackResults: callbackResults.length > 0 ? callbackResults : undefined,
                 message: callbackStrippedMessage.length > 0
                     ? callbackStrippedMessage
                     : null,
@@ -97,35 +279,45 @@ export default class ResponseParserV2 {
         });
     }
     renderCallbackResults(callbackOptions) {
-        return `@results ${JSON.stringify(callbackOptions)}\n`;
+        const { name, results, error } = callbackOptions;
+        if (error !== undefined) {
+            return `@results ${JSON.stringify({
+                name,
+                error: serializeCallbackError(error),
+            })}\n`;
+        }
+        // Multiline string results: header only + raw body (real newlines).
+        // Trailing newline separates blocks when multiple callbacks run.
+        if (typeof results === 'string') {
+            return `@results ${JSON.stringify({ name })}\n${results}\n`;
+        }
+        // undefined results: omit results key (historic wire shape).
+        if (results === undefined) {
+            return `@results ${JSON.stringify({ name })}\n`;
+        }
+        return `@results ${JSON.stringify({ name, results })}\n`;
     }
     getStateUpdateInstructions() {
         return `Updating state works similar to all function calls. Use the following syntax:
 @updateState({ "field1": "value1", "field2": "value2" })
-Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. Multi-line JSON objects are accepted (pretty-printed objects are parsed). IMPORTANT: Prefer a single JSON object argument; do not omit braces.
 Your user-facing message is always sent to the user, even if @updateState fails. If @updateState fails later, do not repeat the same message. Only send the specific @updateState needed to fix the missing state change.
 Good example:
 @updateState({ "favoriteColor": "blue", "firstName": "Taylor" })
 Bad examples:
 @updateState
 { "favoriteColor": "blue" }
-@updateState({
-  "favoriteColor": "blue"
-})
 @updateState({ favoriteColor: "blue" })`;
     }
     getFunctionCallInstructions() {
         return `A function call is done using the following syntax:
 @callbackName({ "key": "value" })
-Make sure to json encode the options. You can call as many callbacks as you want in a single response by including multiple @functionName() lines. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Make sure to json encode the options. You can call as many callbacks as you want in a single response by including multiple @functionName() lines. Multi-line JSON arguments are accepted (pretty-printed objects are parsed). Failed callbacks always return a serializable error string in @results — never silence failures and never return an empty error object.
 Your user-facing message is always sent to the user, even if a callback fails. Successful callbacks have already run successfully. If a callback fails later, do not repeat the same message and do not repeat successful callbacks. Only call the specific callback needed to fix the failed gap.
 Good example:
 @lookupWeather({ "zip": "80524" })
 Bad examples:
 @lookupWeather { "zip": "80524" }
-@lookupWeather(
-{ "zip": "80524" }
-)
 @lookupWeather({ zip: "80524" })`;
     }
 }

package/build/llm.types.d.ts

@@ -5,6 +5,7 @@ export interface BotOptions<StateSchema extends Schema = Schema, State extends S
     adapter: LlmAdapter;
     Class?: new (...opts: any[]) => SprucebotLlmBot<Schema, State>;
     skill?: SprucebotLLmSkill<Schema>;
+    headers?: Record<string, string>;
 }
 export interface SprucebotLlmBot<StateSchema extends Schema = Schema, State extends SchemaValues<StateSchema> = SchemaValues<StateSchema>> extends MercuryEventEmitter<LlmEventContract> {
     markAsDone(): void;
@@ -14,6 +15,7 @@ export interface SprucebotLlmBot<StateSchema extends Schema = Schema, State exte
     unserialize(serialized: SerializedBot<StateSchema, State>): void;
     updateState(state: Partial<State>): Promise<void>;
     setSkill(skill: SprucebotLLmSkill<any>): void;
+    setHeaders(headers: Record<string, string>): void;
     clearMessageHistory(): void;
 }
 export interface LlmAdapter {
@@ -41,6 +43,7 @@ export interface PromptOptions<StateSchema extends Schema, State extends SchemaV
 }
 export interface SendMessageOptions {
     model?: string;
+    headers?: Record<string, string>;
 }
 export interface SerializedBot<StateSchema extends Schema = Schema, State extends SchemaValues<StateSchema> = SchemaValues<StateSchema>> extends PromptOptions<Schema, State> {
     messages: LlmMessage[];

package/build/parsingResponses/ResponseParserV2.d.ts

@@ -1,4 +1,10 @@
 import { ResponseParser, LlmCallbackMap, ParsedResponse } from '../llm.types';
+/**
+ * Always produce a serializable error representation for @results.
+ * Plain Error becomes its message (never {}). Schema-like errors with enumerable
+ * payload fall back to message string for a stable wire format.
+ */
+export declare function serializeCallbackError(err: unknown): string;
 export default class ResponseParserV2 implements ResponseParser {
     parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
     private invokeCallbacks;

package/build/parsingResponses/ResponseParserV2.js

@@ -3,15 +3,188 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeCallbackError = serializeCallbackError;
 const templates_1 = require("../bots/templates");
 const validateAndNormalizeCallbackOptions_1 = __importDefault(require("./validateAndNormalizeCallbackOptions"));
+const RESERVED_CALLBACK_NAMES = new Set(['updateState', 'results']);
+/**
+ * Always produce a serializable error representation for @results.
+ * Plain Error becomes its message (never {}). Schema-like errors with enumerable
+ * payload fall back to message string for a stable wire format.
+ */
+function serializeCallbackError(err) {
+    if (err instanceof Error) {
+        return err.message && err.message.length > 0 ? err.message : 'Error';
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (err === null) {
+        return 'null';
+    }
+    if (err === undefined) {
+        return 'undefined';
+    }
+    if (typeof err === 'symbol') {
+        return String(err);
+    }
+    try {
+        const json = JSON.stringify(err);
+        if (json && json !== '{}') {
+            return json;
+        }
+    }
+    catch {
+        // fall through
+    }
+    try {
+        return String(err);
+    }
+    catch {
+        return 'Unknown error';
+    }
+}
+/** Find matching closing brace for a JSON object starting at openIdx ('{'). */
+function findMatchingBrace(text, openIdx) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = openIdx; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escape = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Extract @name(...) call spans. Supports multi-line JSON objects via brace-depth
+ * scanning and optional leading/trailing whitespace on the call line.
+ */
+function extractCallbackSpans(message) {
+    const spans = [];
+    const re = /^[ \t]*@([A-Za-z_]\w*)\(/gm;
+    let m;
+    while ((m = re.exec(message)) !== null) {
+        const name = m[1];
+        const start = m.index;
+        const openParen = m.index + m[0].length - 1;
+        let i = openParen + 1;
+        while (i < message.length && /[ \t\r\n]/.test(message[i])) {
+            i++;
+        }
+        let argsJson;
+        let closeParen;
+        if (i < message.length && message[i] === ')') {
+            closeParen = i;
+            argsJson = undefined;
+        }
+        else if (i < message.length && message[i] === '{') {
+            const braceEnd = findMatchingBrace(message, i);
+            if (braceEnd < 0) {
+                spans.push({
+                    name,
+                    fullMatch: message.slice(start),
+                    start,
+                    end: message.length,
+                });
+                break;
+            }
+            argsJson = message.slice(i, braceEnd + 1);
+            let j = braceEnd + 1;
+            while (j < message.length && /[ \t\r\n]/.test(message[j])) {
+                j++;
+            }
+            if (j >= message.length || message[j] !== ')') {
+                spans.push({
+                    name,
+                    fullMatch: message.slice(start, braceEnd + 1),
+                    argsJson,
+                    start,
+                    end: braceEnd + 1,
+                });
+                re.lastIndex = braceEnd + 1;
+                continue;
+            }
+            closeParen = j;
+        }
+        else {
+            re.lastIndex = openParen + 1;
+            continue;
+        }
+        let end = closeParen + 1;
+        // Include trailing newline after the call when present (common LLM layout)
+        if (message[end] === '\r') {
+            end++;
+        }
+        if (message[end] === '\n') {
+            end++;
+        }
+        // Leading newline is part of fullMatch when start points after prior content;
+        // also absorb a single leading newline just before the match for strip parity
+        // with historic `\n@name(...)\n` fixtures.
+        let matchStart = start;
+        if (matchStart > 0 && message[matchStart - 1] === '\n') {
+            matchStart--;
+            if (matchStart > 0 && message[matchStart - 1] === '\r') {
+                matchStart--;
+            }
+        }
+        spans.push({
+            name,
+            fullMatch: message.slice(matchStart, end),
+            argsJson,
+            start: matchStart,
+            end,
+        });
+        re.lastIndex = end;
+    }
+    return spans;
+}
+function stripCallFromMessage(message, fullMatch) {
+    // Historic behavior: remove the call span and glue surrounding text without
+    // injecting separators (trim each side after split).
+    return message
+        .split(fullMatch)
+        .map((s) => s.trim())
+        .join('')
+        .trim();
+}
 class ResponseParserV2 {
     async parse(response, callbacks) {
         let message = response.replace(templates_1.DONE_TOKEN, '').trim();
         let state = undefined;
         let callbackResults = undefined;
-        const hasCallbacks = callbacks != null &&
+        // Enter the pass when any @name( call shape is present (incl. typos)
+        // or when a registered callback name appears as a call prefix.
+        const hasCallShape = message != null && /^[ \t]*@\w+\(/m.test(message);
+        const hasRegisteredName = callbacks != null &&
             Object.keys(callbacks).some((name) => message.includes(`@${name}(`));
+        const hasCallbacks = hasCallShape || hasRegisteredName;
         if (hasCallbacks) {
             const { callbackResults: c, message: m } = await this.invokeCallbacks(message, callbacks);
             callbackResults = c;
@@ -48,24 +221,33 @@ class ResponseParserV2 {
     async invokeCallbacks(message, callbacks) {
         let callbackStrippedMessage = message;
         let callbackResults = '';
-        const reserved = new Set(['updateState', 'results']);
-        const matches = [...message.matchAll(/^@(\w+)\(({.*})?\)$/gm)];
-        for (const match of matches) {
-            if (reserved.has(match[1])) {
+        const spans = extractCallbackSpans(message);
+        for (const span of spans) {
+            if (RESERVED_CALLBACK_NAMES.has(span.name)) {
+                continue;
+            }
+            const name = span.name;
+            // Always strip the call from the user-facing message once recognized.
+            callbackStrippedMessage = stripCallFromMessage(callbackStrippedMessage, span.fullMatch);
+            let options;
+            try {
+                options = span.argsJson ? JSON.parse(span.argsJson) : undefined;
+            }
+            catch (err) {
+                callbackResults += this.renderCallbackResults({
+                    name,
+                    error: `Invalid JSON arguments for @${name}: ${err?.message ?? String(err)}. Arguments must be valid JSON object.`,
+                });
                 continue;
             }
-            const parsed = match[2] ? JSON.parse(match[2]) : undefined;
-            const name = match[1];
-            const options = parsed;
             const callback = callbacks?.[name];
             if (!callback) {
+                callbackResults += this.renderCallbackResults({
+                    name,
+                    error: `Unknown callback @${name} — not registered.`,
+                });
                 continue;
             }
-            const parts = callbackStrippedMessage.split(match[0]);
-            callbackStrippedMessage = parts
-                .map((s) => s.trim())
-                .join('')
-                .trim();
             try {
                 if (callback?.parameters) {
                     (0, validateAndNormalizeCallbackOptions_1.default)(callback.parameters, options);
@@ -82,42 +264,52 @@ class ResponseParserV2 {
         }
         callbackResults = callbackResults.trim();
         return {
-            callbackResults,
+            callbackResults: callbackResults.length > 0 ? callbackResults : undefined,
             message: callbackStrippedMessage.length > 0
                 ? callbackStrippedMessage
                 : null,
         };
     }
     renderCallbackResults(callbackOptions) {
-        return `@results ${JSON.stringify(callbackOptions)}\n`;
+        const { name, results, error } = callbackOptions;
+        if (error !== undefined) {
+            return `@results ${JSON.stringify({
+                name,
+                error: serializeCallbackError(error),
+            })}\n`;
+        }
+        // Multiline string results: header only + raw body (real newlines).
+        // Trailing newline separates blocks when multiple callbacks run.
+        if (typeof results === 'string') {
+            return `@results ${JSON.stringify({ name })}\n${results}\n`;
+        }
+        // undefined results: omit results key (historic wire shape).
+        if (results === undefined) {
+            return `@results ${JSON.stringify({ name })}\n`;
+        }
+        return `@results ${JSON.stringify({ name, results })}\n`;
     }
     getStateUpdateInstructions() {
         return `Updating state works similar to all function calls. Use the following syntax:
 @updateState({ "field1": "value1", "field2": "value2" })
-Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. Multi-line JSON objects are accepted (pretty-printed objects are parsed). IMPORTANT: Prefer a single JSON object argument; do not omit braces.
 Your user-facing message is always sent to the user, even if @updateState fails. If @updateState fails later, do not repeat the same message. Only send the specific @updateState needed to fix the missing state change.
 Good example:
 @updateState({ "favoriteColor": "blue", "firstName": "Taylor" })
 Bad examples:
 @updateState
 { "favoriteColor": "blue" }
-@updateState({
-  "favoriteColor": "blue"
-})
 @updateState({ favoriteColor: "blue" })`;
     }
     getFunctionCallInstructions() {
         return `A function call is done using the following syntax:
 @callbackName({ "key": "value" })
-Make sure to json encode the options. You can call as many callbacks as you want in a single response by including multiple @functionName() lines. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Make sure to json encode the options. You can call as many callbacks as you want in a single response by including multiple @functionName() lines. Multi-line JSON arguments are accepted (pretty-printed objects are parsed). Failed callbacks always return a serializable error string in @results — never silence failures and never return an empty error object.
 Your user-facing message is always sent to the user, even if a callback fails. Successful callbacks have already run successfully. If a callback fails later, do not repeat the same message and do not repeat successful callbacks. Only call the specific callback needed to fix the failed gap.
 Good example:
 @lookupWeather({ "zip": "80524" })
 Bad examples:
 @lookupWeather { "zip": "80524" }
-@lookupWeather(
-{ "zip": "80524" }
-)
 @lookupWeather({ zip: "80524" })`;
     }
 }

package/package.json

@@ -8,7 +8,7 @@
       "eta"
     ]
   },
-  "version": "18.0.1",
+  "version": "18.1.1",
   "files": [
     "build"
   ],
@@ -26,7 +26,8 @@
         "types": "./build/index.d.ts",
         "default": "./build/index.js"
       }
-    }
+    },
+    "./package.json": "./package.json"
   },
   "keywords": [
     "llm",