@sprucelabs/sprucebot-llm 18.0.1 → 18.1.0

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/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/package.json

@@ -8,7 +8,7 @@
       "eta"
     ]
   },
-  "version": "18.0.1",
+  "version": "18.1.0",
   "files": [
     "build"
   ],