@charivo/llm 0.6.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -51,6 +51,84 @@ const manager = createLLMManager(client, {
51
51
 
52
52
  Use `maxHistoryTurns: null` to opt out and keep unbounded history.
53
53
 
54
+ ## Tool Calling
55
+
56
+ `LLMManager` can run a tool-calling loop instead of a plain `call(...)` when
57
+ both sides opt in: at least one tool is registered *and* the injected
58
+ `LLMClient` implements the optional `callWithTools(messages, tools)` method.
59
+ Otherwise `generateResponse(...)` falls back to the plain `call(...)` path.
60
+
61
+ ```ts
62
+ import { createLLMManager } from "@charivo/llm";
63
+ import { createRemoteLLMClient } from "@charivo/llm/remote";
64
+ import {
65
+ buildAvatarControlInstructions,
66
+ createAvatarControlTools,
67
+ createAvatarResultProjector,
68
+ } from "@charivo/avatar";
69
+
70
+ const catalog = { expressions: ["Smile"], motions: { Idle: 2 } };
71
+
72
+ const manager = createLLMManager(
73
+ createRemoteLLMClient({ apiEndpoint: "/api/chat" }),
74
+ {
75
+ tools: createAvatarControlTools(catalog),
76
+ resultProjectors: [createAvatarResultProjector()],
77
+ toolInstructions: buildAvatarControlInstructions(catalog),
78
+ },
79
+ );
80
+ ```
81
+
82
+ `LLMManagerOptions` tool fields:
83
+
84
+ - `tools?: ToolRegistration[]` — registered at construction; also available
85
+ after construction via `registerTool(tool)` / `unregisterTool(name)`
86
+ - `resultProjectors?: ToolResultProjector[]` — run after a successful tool
87
+ call, when an event emitter is attached (`Charivo.attachLLM(...)` wires one
88
+ automatically). A projector throwing turns into an `error` event
89
+ (`Error` message: `` LLM result projector failed for tool "<name>": <cause> ``)
90
+ instead of failing the reply.
91
+ - `toolInstructions?: string` — appended to the character system prompt, but
92
+ only on the tools path (registered tools + a tool-capable client); it has no
93
+ effect on the plain `call(...)` path.
94
+
95
+ Tools are `ToolRegistration` values from `@charivo/core` — the same contract
96
+ `@charivo/realtime` uses, so tool builders such as `@charivo/avatar`'s
97
+ `createAvatarControlTools(...)` work with both managers. Tool arguments are
98
+ validated against each definition's schema, and results are timed out
99
+ (`defaultToolTimeoutMs`, 10s default, overridable per tool via
100
+ `timeoutMs`) and asserted to be plain objects before a projector runs. Any
101
+ failure — unknown tool, invalid arguments, handler throw/timeout, non-object
102
+ result — becomes a `{ success: false, error }` tool output so the reply
103
+ always continues instead of throwing.
104
+
105
+ ### Round Cap
106
+
107
+ The tool loop executes at most 3 tool-calling rounds. After the third round,
108
+ the manager makes one more `callWithTools(...)` call with an **empty tools
109
+ array** so the model is forced to answer in text instead of requesting another
110
+ tool call; that terminal response's `content` becomes the reply.
111
+
112
+ ### Remote Protocol
113
+
114
+ `@charivo/llm/remote`'s `callWithTools(messages, tools)` posts
115
+ `{ messages, tools }` (tools included as-is, even when empty) to your chat
116
+ route and expects `{ success: true, message: string, toolCalls?: LLMToolCall[] }`
117
+ back. `toolCalls` is omitted (or empty) when the model didn't call a tool.
118
+ On the wire, `tools: []` is a valid, distinct request from omitting `tools`
119
+ entirely — server routes typically treat any request carrying `tools` (even
120
+ empty) or a tool-call/tool-result turn in `messages` as needing the
121
+ tool-calling provider path, and only map an empty tools array to "no tools"
122
+ when calling the underlying model.
123
+
124
+ ### History Exclusion
125
+
126
+ Only the final assistant text is added to `LLMManager`'s history. Intermediate
127
+ assistant `toolCalls` turns and `role: "tool"` result turns exist only inside
128
+ one `generateResponse(...)` call's tool loop — `getHistory()` and the stored
129
+ conversation always stay a plain user/character transcript that other
130
+ modalities can reuse.
131
+
54
132
  ## Exports
55
133
 
56
134
  - `createLLMManager(client, options?)`
@@ -73,3 +151,6 @@ Use `maxHistoryTurns: null` to opt out and keep unbounded history.
73
151
  - `generateResponse(message)`
74
152
  - `getHistory()`
75
153
  - `clearHistory()`
154
+ - `setEventEmitter(eventEmitter)` — wired automatically by `Charivo.attachLLM(...)`
155
+ - `registerTool(tool)` / `unregisterTool(name)` / `getRegisteredTools()`
156
+ - `setToolInstructions(instructions | null)`
@@ -0,0 +1,107 @@
1
+ import { CharivoProviderError } from '@charivo/core';
2
+
3
+ // src/openai-tool-format.ts
4
+ function toOpenAIChatMessages(messages) {
5
+ return messages.map((message) => {
6
+ switch (message.role) {
7
+ case "tool":
8
+ return {
9
+ role: "tool",
10
+ tool_call_id: message.toolCallId,
11
+ content: message.content
12
+ };
13
+ case "assistant":
14
+ return {
15
+ role: "assistant",
16
+ content: message.content,
17
+ ...message.toolCalls && message.toolCalls.length > 0 ? { tool_calls: message.toolCalls.map(toOpenAIToolCall) } : {}
18
+ };
19
+ case "system":
20
+ case "user":
21
+ return { role: message.role, content: message.content };
22
+ }
23
+ });
24
+ }
25
+ function toOpenAITools(tools) {
26
+ if (tools.length === 0) {
27
+ return void 0;
28
+ }
29
+ return tools.map((tool) => ({
30
+ type: "function",
31
+ function: {
32
+ name: tool.name,
33
+ description: tool.description,
34
+ parameters: tool.parameters
35
+ }
36
+ }));
37
+ }
38
+ function toLLMToolResponse(message) {
39
+ const toolCalls = readToolCalls(message);
40
+ return {
41
+ content: message?.content ?? "",
42
+ ...toolCalls.length > 0 ? { toolCalls } : {}
43
+ };
44
+ }
45
+ function readToolCalls(message) {
46
+ const rawToolCalls = message?.tool_calls;
47
+ if (!rawToolCalls || rawToolCalls.length === 0) {
48
+ return [];
49
+ }
50
+ return rawToolCalls.map(toLLMToolCall);
51
+ }
52
+ function toOpenAIToolCall(toolCall) {
53
+ return {
54
+ id: toolCall.id,
55
+ type: "function",
56
+ function: {
57
+ name: toolCall.name,
58
+ arguments: JSON.stringify(toolCall.arguments)
59
+ }
60
+ };
61
+ }
62
+ function toLLMToolCall(raw) {
63
+ if (!isPlainObject(raw)) {
64
+ throw new CharivoProviderError("LLM tool call must be an object");
65
+ }
66
+ const id = raw.id;
67
+ if (typeof id !== "string" || id.length === 0) {
68
+ throw new CharivoProviderError(
69
+ 'LLM tool call is missing a non-empty string "id"'
70
+ );
71
+ }
72
+ const name = raw.function?.name;
73
+ if (typeof name !== "string" || name.length === 0) {
74
+ throw new CharivoProviderError(
75
+ `LLM tool call "${id}" is missing a non-empty string "function.name"`
76
+ );
77
+ }
78
+ return {
79
+ id,
80
+ name,
81
+ arguments: parseToolArguments(name, raw.function.arguments)
82
+ };
83
+ }
84
+ function parseToolArguments(name, rawArguments) {
85
+ let parsed;
86
+ try {
87
+ parsed = JSON.parse(rawArguments);
88
+ } catch (error) {
89
+ throw new CharivoProviderError(
90
+ `LLM tool call "${name}" has unparsable "function.arguments"`,
91
+ { cause: error instanceof Error ? error : void 0 }
92
+ );
93
+ }
94
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
95
+ throw new CharivoProviderError(
96
+ `LLM tool call "${name}" has "function.arguments" that are not a JSON object`
97
+ );
98
+ }
99
+ return parsed;
100
+ }
101
+ function isPlainObject(value) {
102
+ return typeof value === "object" && value !== null && !Array.isArray(value);
103
+ }
104
+
105
+ export { toLLMToolResponse, toOpenAIChatMessages, toOpenAITools };
106
+ //# sourceMappingURL=chunk-N2ILPUIF.mjs.map
107
+ //# sourceMappingURL=chunk-N2ILPUIF.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/openai-tool-format.ts"],"names":[],"mappings":"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","file":"chunk-N2ILPUIF.mjs","sourcesContent":["/**\n * Mapping between the neutral LLM tool contracts and the OpenAI\n * chat.completions wire format. Shared by the OpenAI provider and the OpenClaw\n * gateway provider, which speaks the same API.\n */\nimport {\n CharivoProviderError,\n type LLMMessage,\n type LLMToolCall,\n type LLMToolResponse,\n type ToolDefinition,\n} from \"@charivo/core\";\nimport type OpenAI from \"openai\";\n\nexport function toOpenAIChatMessages(\n messages: LLMMessage[],\n): OpenAI.ChatCompletionMessageParam[] {\n return messages.map((message) => {\n switch (message.role) {\n case \"tool\":\n return {\n role: \"tool\",\n tool_call_id: message.toolCallId,\n content: message.content,\n };\n case \"assistant\":\n return {\n role: \"assistant\",\n content: message.content,\n ...(message.toolCalls && message.toolCalls.length > 0\n ? { tool_calls: message.toolCalls.map(toOpenAIToolCall) }\n : {}),\n };\n case \"system\":\n case \"user\":\n return { role: message.role, content: message.content };\n }\n });\n}\n\n/**\n * Returns undefined for an empty list so callers can spread the result and\n * leave the `tools` param out entirely: an empty array would still switch the\n * model into tool mode.\n */\nexport function toOpenAITools(\n tools: ToolDefinition[],\n): OpenAI.ChatCompletionTool[] | undefined {\n if (tools.length === 0) {\n return undefined;\n }\n\n return tools.map((tool) => ({\n type: \"function\",\n function: {\n name: tool.name,\n description: tool.description,\n parameters: tool.parameters,\n },\n }));\n}\n\n/**\n * Builds the neutral tool response from a completion message. Shared by the\n * OpenAI and OpenClaw providers, which both read from the same wire shape.\n */\nexport function toLLMToolResponse(\n message: OpenAI.ChatCompletionMessage | undefined,\n): LLMToolResponse {\n const toolCalls = readToolCalls(message);\n\n return {\n content: message?.content ?? \"\",\n ...(toolCalls.length > 0 ? { toolCalls } : {}),\n };\n}\n\n/**\n * Read the tool calls off a completion message. The SDK types promise more than\n * the wire delivers - especially through a gateway - so every field is checked\n * before it reaches the neutral contract.\n */\nfunction readToolCalls(\n message: OpenAI.ChatCompletionMessage | undefined,\n): LLMToolCall[] {\n const rawToolCalls = message?.tool_calls;\n if (!rawToolCalls || rawToolCalls.length === 0) {\n return [];\n }\n\n return rawToolCalls.map(toLLMToolCall);\n}\n\nfunction toOpenAIToolCall(\n toolCall: LLMToolCall,\n): OpenAI.ChatCompletionMessageToolCall {\n return {\n id: toolCall.id,\n type: \"function\",\n function: {\n name: toolCall.name,\n arguments: JSON.stringify(toolCall.arguments),\n },\n };\n}\n\nfunction toLLMToolCall(raw: OpenAI.ChatCompletionMessageToolCall): LLMToolCall {\n if (!isPlainObject(raw)) {\n throw new CharivoProviderError(\"LLM tool call must be an object\");\n }\n\n const id = raw.id;\n if (typeof id !== \"string\" || id.length === 0) {\n throw new CharivoProviderError(\n 'LLM tool call is missing a non-empty string \"id\"',\n );\n }\n\n const name = raw.function?.name;\n if (typeof name !== \"string\" || name.length === 0) {\n throw new CharivoProviderError(\n `LLM tool call \"${id}\" is missing a non-empty string \"function.name\"`,\n );\n }\n\n return {\n id,\n name,\n arguments: parseToolArguments(name, raw.function.arguments),\n };\n}\n\nfunction parseToolArguments(\n name: string,\n rawArguments: string,\n): Record<string, unknown> {\n let parsed: unknown;\n\n try {\n parsed = JSON.parse(rawArguments);\n } catch (error) {\n throw new CharivoProviderError(\n `LLM tool call \"${name}\" has unparsable \"function.arguments\"`,\n { cause: error instanceof Error ? error : undefined },\n );\n }\n\n if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n throw new CharivoProviderError(\n `LLM tool call \"${name}\" has \"function.arguments\" that are not a JSON object`,\n );\n }\n\n return parsed as Record<string, unknown>;\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n"]}
package/dist/index.d.mts CHANGED
@@ -1,11 +1,16 @@
1
- import { LLMClient, LLMManager } from '@charivo/core';
1
+ import { LLMClient, ToolRegistration, ToolResultProjector, LLMManagerWithTools } from '@charivo/core';
2
2
 
3
3
  interface LLMManagerOptions {
4
4
  maxHistoryTurns?: number | null;
5
+ tools?: ToolRegistration[];
6
+ resultProjectors?: ToolResultProjector[];
7
+ /** Appended to the character system prompt, tools path only. */
8
+ toolInstructions?: string;
9
+ defaultToolTimeoutMs?: number;
5
10
  }
6
11
  /**
7
12
  * Helper function to create an LLM Manager
8
13
  */
9
- declare function createLLMManager(llmClient: LLMClient, options?: LLMManagerOptions): LLMManager;
14
+ declare function createLLMManager(llmClient: LLMClient, options?: LLMManagerOptions): LLMManagerWithTools;
10
15
 
11
16
  export { type LLMManagerOptions, createLLMManager };
package/dist/index.d.ts CHANGED
@@ -1,11 +1,16 @@
1
- import { LLMClient, LLMManager } from '@charivo/core';
1
+ import { LLMClient, ToolRegistration, ToolResultProjector, LLMManagerWithTools } from '@charivo/core';
2
2
 
3
3
  interface LLMManagerOptions {
4
4
  maxHistoryTurns?: number | null;
5
+ tools?: ToolRegistration[];
6
+ resultProjectors?: ToolResultProjector[];
7
+ /** Appended to the character system prompt, tools path only. */
8
+ toolInstructions?: string;
9
+ defaultToolTimeoutMs?: number;
5
10
  }
6
11
  /**
7
12
  * Helper function to create an LLM Manager
8
13
  */
9
- declare function createLLMManager(llmClient: LLMClient, options?: LLMManagerOptions): LLMManager;
14
+ declare function createLLMManager(llmClient: LLMClient, options?: LLMManagerOptions): LLMManagerWithTools;
10
15
 
11
16
  export { type LLMManagerOptions, createLLMManager };
package/dist/index.js CHANGED
@@ -130,8 +130,62 @@ var ResponseMessageBuilder = class {
130
130
  }
131
131
  };
132
132
 
133
+ // src/tool-execution.ts
134
+ var LLMToolRegistry = class {
135
+ tools = /* @__PURE__ */ new Map();
136
+ register(tool) {
137
+ this.tools.set(tool.definition.name, tool);
138
+ }
139
+ unregister(name) {
140
+ this.tools.delete(name);
141
+ }
142
+ get(name) {
143
+ return this.tools.get(name);
144
+ }
145
+ size() {
146
+ return this.tools.size;
147
+ }
148
+ getDefinitions() {
149
+ return Array.from(this.tools.values(), (tool) => ({
150
+ ...tool.definition,
151
+ parameters: {
152
+ ...tool.definition.parameters,
153
+ properties: { ...tool.definition.parameters.properties },
154
+ required: tool.definition.parameters.required ? [...tool.definition.parameters.required] : void 0
155
+ }
156
+ }));
157
+ }
158
+ };
159
+ function createFailureOutput(error) {
160
+ return {
161
+ success: false,
162
+ error: error.message
163
+ };
164
+ }
165
+ async function withTimeout(promise, timeoutMs, toolName) {
166
+ let timeoutId;
167
+ try {
168
+ return await Promise.race([
169
+ promise,
170
+ new Promise((_, reject) => {
171
+ timeoutId = setTimeout(() => {
172
+ reject(
173
+ new Error(`LLM tool "${toolName}" timed out after ${timeoutMs}ms`)
174
+ );
175
+ }, timeoutMs);
176
+ })
177
+ ]);
178
+ } finally {
179
+ if (timeoutId !== void 0) {
180
+ clearTimeout(timeoutId);
181
+ }
182
+ }
183
+ }
184
+
133
185
  // src/llm-manager.ts
134
186
  var DEFAULT_MAX_HISTORY_TURNS = 40;
187
+ var DEFAULT_TOOL_TIMEOUT_MS = 1e4;
188
+ var MAX_TOOL_ROUNDS = 3;
135
189
  var LLMManager = class {
136
190
  constructor(llmClient, options = {}) {
137
191
  this.llmClient = llmClient;
@@ -140,10 +194,40 @@ var LLMManager = class {
140
194
  maxMessages: this.maxHistoryMessages,
141
195
  pruneBatchSize: 2
142
196
  });
197
+ this.resultProjectors = options.resultProjectors ?? [];
198
+ this.defaultToolTimeoutMs = options.defaultToolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
199
+ this.toolInstructions = options.toolInstructions ?? null;
200
+ for (const tool of options.tools ?? []) {
201
+ this.registerTool(tool);
202
+ }
143
203
  }
144
204
  historyManager;
145
205
  maxHistoryMessages;
206
+ toolRegistry = new LLMToolRegistry();
207
+ resultProjectors;
208
+ defaultToolTimeoutMs;
146
209
  character = null;
210
+ eventEmitter;
211
+ toolInstructions;
212
+ setEventEmitter(eventEmitter) {
213
+ this.eventEmitter = eventEmitter;
214
+ }
215
+ registerTool(tool) {
216
+ this.toolRegistry.register(tool);
217
+ }
218
+ unregisterTool(name) {
219
+ this.toolRegistry.unregister(name);
220
+ }
221
+ getRegisteredTools() {
222
+ return this.toolRegistry.getDefinitions();
223
+ }
224
+ /**
225
+ * Set the tool instructions appended to the system prompt.
226
+ * Pass null to clear them.
227
+ */
228
+ setToolInstructions(instructions) {
229
+ this.toolInstructions = instructions;
230
+ }
147
231
  /**
148
232
  * Set the character
149
233
  * Clears the history only when the character changes.
@@ -186,7 +270,7 @@ var LLMManager = class {
186
270
  const historyMessages = this.getHistoryForApiCall();
187
271
  const apiMessages = this.prepareApiMessages(historyMessages);
188
272
  try {
189
- const assistantMessage = await this.llmClient.call(apiMessages);
273
+ const assistantMessage = this.shouldUseToolLoop() ? await this.runToolLoop(apiMessages) : await this.llmClient.call(apiMessages);
190
274
  const responseMessage = ResponseMessageBuilder.create(
191
275
  assistantMessage,
192
276
  this.character.id
@@ -200,6 +284,128 @@ var LLMManager = class {
200
284
  throw core.toCharivoError("provider", error);
201
285
  }
202
286
  }
287
+ /**
288
+ * Tools engage only when both sides opt in: at least one registered tool and
289
+ * a client that implements the optional tool-calling variant.
290
+ */
291
+ shouldUseToolLoop() {
292
+ return this.toolRegistry.size() > 0 && typeof this.llmClient.callWithTools === "function";
293
+ }
294
+ /**
295
+ * Run the tool-calling conversation until the model answers with text or the
296
+ * round cap is reached.
297
+ */
298
+ async runToolLoop(apiMessages) {
299
+ const callWithTools = this.llmClient.callWithTools.bind(this.llmClient);
300
+ const definitions = this.getRegisteredTools();
301
+ const working = this.buildToolLoopMessages(apiMessages);
302
+ let response = await callWithTools(working, definitions);
303
+ for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
304
+ const toolCalls = response.toolCalls ?? [];
305
+ if (toolCalls.length === 0) {
306
+ return response.content;
307
+ }
308
+ working.push({
309
+ role: "assistant",
310
+ content: response.content,
311
+ toolCalls
312
+ });
313
+ for (const toolCall of toolCalls) {
314
+ working.push({
315
+ role: "tool",
316
+ content: await this.executeToolCall(toolCall),
317
+ toolCallId: toolCall.id
318
+ });
319
+ }
320
+ const isFinalRound = round === MAX_TOOL_ROUNDS - 1;
321
+ response = await callWithTools(working, isFinalRound ? [] : definitions);
322
+ }
323
+ return response.content;
324
+ }
325
+ /**
326
+ * Seed the tool conversation, appending the tool instructions to the system
327
+ * prompt. generateResponse validates the character first, so the tools path
328
+ * always starts with a system message.
329
+ */
330
+ buildToolLoopMessages(apiMessages) {
331
+ const messages = [...apiMessages];
332
+ const systemMessage = messages[0];
333
+ if (this.toolInstructions && systemMessage.role === "system") {
334
+ messages[0] = {
335
+ role: "system",
336
+ content: `${systemMessage.content}
337
+
338
+ ${this.toolInstructions}`
339
+ };
340
+ }
341
+ return messages;
342
+ }
343
+ /**
344
+ * Execute one tool call and return the serialized output for its tool turn.
345
+ * Every failure - unknown tool, invalid arguments, handler throw/timeout,
346
+ * non-object result, unserializable output - becomes a failure output so the
347
+ * reply always continues.
348
+ */
349
+ async executeToolCall(toolCall) {
350
+ let output;
351
+ let serialized;
352
+ try {
353
+ const tool = this.toolRegistry.get(toolCall.name);
354
+ if (!tool) {
355
+ throw new Error(`No LLM tool registered for "${toolCall.name}"`);
356
+ }
357
+ core.validateToolArguments(tool.definition, toolCall.arguments, "LLM tool");
358
+ const result = await withTimeout(
359
+ tool.handler(toolCall.arguments, {
360
+ character: this.character,
361
+ callId: toolCall.id
362
+ }),
363
+ tool.timeoutMs ?? this.defaultToolTimeoutMs,
364
+ tool.definition.name
365
+ );
366
+ core.assertToolResultObject(result, tool.definition.name, "LLM tool");
367
+ const stringified = JSON.stringify(result);
368
+ if (typeof stringified !== "string") {
369
+ throw new Error(
370
+ `LLM tool "${tool.definition.name}" result could not be serialized to JSON`
371
+ );
372
+ }
373
+ serialized = stringified;
374
+ output = result;
375
+ } catch (error) {
376
+ return JSON.stringify(createFailureOutput(toError(error)));
377
+ }
378
+ this.projectToolResult(toolCall.name, output, toolCall.id);
379
+ return serialized;
380
+ }
381
+ /**
382
+ * Turn a successful tool result into avatar-style events. Projection is
383
+ * skipped entirely without an event emitter.
384
+ */
385
+ projectToolResult(name, output, callId) {
386
+ const eventEmitter = this.eventEmitter;
387
+ if (!eventEmitter) {
388
+ return;
389
+ }
390
+ for (const projector of this.resultProjectors) {
391
+ try {
392
+ projector({
393
+ name,
394
+ output,
395
+ callId,
396
+ emit: (event, payload) => {
397
+ eventEmitter.emit(event, payload);
398
+ }
399
+ });
400
+ } catch (error) {
401
+ eventEmitter.emit("error", {
402
+ error: new Error(
403
+ `LLM result projector failed for tool "${name}": ${toError(error).message}`
404
+ )
405
+ });
406
+ }
407
+ }
408
+ }
203
409
  /**
204
410
  * Prepare messages for the LLM API call
205
411
  */
@@ -225,6 +431,9 @@ var LLMManager = class {
225
431
  function createLLMManager(llmClient, options) {
226
432
  return new LLMManager(llmClient, options);
227
433
  }
434
+ function toError(error) {
435
+ return error instanceof Error ? error : new Error(String(error));
436
+ }
228
437
  function resolveMaxHistoryMessages(options) {
229
438
  if (options.maxHistoryTurns === null) {
230
439
  return void 0;
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/message-history-manager.ts","../src/character-prompt-builder.ts","../src/message-converter.ts","../src/validators.ts","../src/response-message-builder.ts","../src/llm-manager.ts"],"names":["toCharivoError"],"mappings":"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","file":"index.js","sourcesContent":["import { Message } from \"@charivo/core\";\n\nexport interface MessageHistoryManagerOptions {\n maxMessages?: number | null;\n pruneBatchSize?: number;\n}\n\nexport interface AddMessageOptions {\n /**\n * Internal escape hatch for workflows that need multiple appends to become\n * visible as one pruning boundary, such as user/assistant turn pairs.\n */\n prune?: boolean;\n}\n\n/**\n * Message history management\n */\nexport class MessageHistoryManager {\n private history: Message[] = [];\n private readonly maxMessages?: number;\n private readonly pruneBatchSize: number;\n\n constructor(options: MessageHistoryManagerOptions = {}) {\n if (\n options.maxMessages !== undefined &&\n options.maxMessages !== null &&\n (!Number.isInteger(options.maxMessages) || options.maxMessages <= 0)\n ) {\n throw new TypeError(\"maxMessages must be a positive integer or null\");\n }\n\n if (\n options.pruneBatchSize !== undefined &&\n (!Number.isInteger(options.pruneBatchSize) || options.pruneBatchSize <= 0)\n ) {\n throw new TypeError(\"pruneBatchSize must be a positive integer\");\n }\n\n this.maxMessages =\n options.maxMessages === null ? undefined : options.maxMessages;\n this.pruneBatchSize = options.pruneBatchSize ?? 1;\n }\n\n add(message: Message, options: AddMessageOptions = {}): void {\n this.history.push(message);\n\n if (options.prune !== false) {\n this.pruneToMax();\n }\n }\n\n removeLast(): Message | undefined {\n return this.history.pop();\n }\n\n clear(): void {\n this.history = [];\n }\n\n getAll(): Message[] {\n return [...this.history]; // Return a copy\n }\n\n getRecent(maxMessages?: number): Message[] {\n if (\n maxMessages !== undefined &&\n (!Number.isInteger(maxMessages) || maxMessages <= 0)\n ) {\n throw new TypeError(\"maxMessages must be a positive integer\");\n }\n\n if (maxMessages === undefined || this.history.length <= maxMessages) {\n return this.getAll();\n }\n\n return this.history.slice(-maxMessages);\n }\n\n size(): number {\n return this.history.length;\n }\n\n pruneToMax(): void {\n if (this.maxMessages === undefined) {\n return;\n }\n\n while (this.history.length > this.maxMessages) {\n const excess = this.history.length - this.maxMessages;\n const removeCount = Math.min(\n Math.ceil(excess / this.pruneBatchSize) * this.pruneBatchSize,\n this.history.length,\n );\n this.history.splice(0, removeCount);\n }\n }\n}\n","import { Character } from \"@charivo/core\";\n\n/**\n * Utility for converting character information into a system prompt\n */\nexport class CharacterPromptBuilder {\n static buildSystemPrompt(character: Character): string {\n const name = character.name;\n const description = character.description || \"\";\n const personality = character.personality || \"\";\n\n return `You are ${name}. ${description} ${personality}\n\nRespond naturally in plain text with no bracketed emotion tags or control markup.`.trim();\n }\n\n static buildSystemPromptOrDefault(character?: Character): string {\n if (character) {\n return this.buildSystemPrompt(character);\n }\n return `You are a helpful assistant.\n\nRespond naturally in plain text with no bracketed emotion tags or control markup.`.trim();\n }\n}\n","import { Message } from \"@charivo/core\";\n\n/**\n * Message format conversion utility\n */\nexport class MessageConverter {\n /**\n * Convert a Charivo Message to the OpenAI format\n */\n static toOpenAIFormat(\n messages: Message[],\n ): Array<{ role: string; content: string }> {\n return messages.map((msg) => ({\n role: msg.type === \"user\" ? \"user\" : \"assistant\",\n content: msg.content,\n }));\n }\n\n /**\n * Combine the system prompt and messages into the OpenAI format\n */\n static combineWithSystemPrompt(\n systemPrompt: string,\n messages: Message[],\n ): Array<{ role: string; content: string }> {\n return [\n { role: \"system\", content: systemPrompt },\n ...this.toOpenAIFormat(messages),\n ];\n }\n}\n","import { Character, Message } from \"@charivo/core\";\n\n/**\n * LLM-related validation utilities\n */\nexport class LLMValidators {\n static validateCharacterSet(\n character: Character | null,\n ): asserts character is Character {\n if (!character) {\n throw new Error(\"Character must be set before generating response\");\n }\n }\n\n static validateMessage(message: Message): void {\n if (!message.content || typeof message.content !== \"string\") {\n throw new Error(\"Message content must be a non-empty string\");\n }\n }\n}\n","import { Message } from \"@charivo/core\";\n\n/**\n * Helper for building AI response messages\n */\nexport class ResponseMessageBuilder {\n static create(\n content: string,\n characterId: string,\n messageId?: string,\n ): Message {\n return {\n id: messageId || \"ai-\" + Date.now(),\n content,\n timestamp: new Date(),\n type: \"character\",\n characterId,\n };\n }\n}\n","import {\n LLMClient,\n Message,\n Character,\n toCharivoError,\n type LLMManager as CoreLLMManager,\n} from \"@charivo/core\";\nimport { MessageHistoryManager } from \"./message-history-manager\";\nimport { CharacterPromptBuilder } from \"./character-prompt-builder\";\nimport { MessageConverter } from \"./message-converter\";\nimport { LLMValidators } from \"./validators\";\nimport { ResponseMessageBuilder } from \"./response-message-builder\";\n\nconst DEFAULT_MAX_HISTORY_TURNS = 40;\n\nexport interface LLMManagerOptions {\n maxHistoryTurns?: number | null;\n}\n\n/**\n * LLM Manager - Class responsible for managing the state of an LLM session\n *\n * Responsibilities:\n * - Character configuration and management\n * - Message history management\n * - Communication with the LLM client\n * - Message format conversion\n * - Prompt generation\n */\nexport class LLMManager {\n private readonly historyManager: MessageHistoryManager;\n private readonly maxHistoryMessages?: number;\n private character: Character | null = null;\n\n constructor(\n private llmClient: LLMClient,\n options: LLMManagerOptions = {},\n ) {\n this.maxHistoryMessages = resolveMaxHistoryMessages(options);\n this.historyManager = new MessageHistoryManager({\n maxMessages: this.maxHistoryMessages,\n pruneBatchSize: 2,\n });\n }\n\n /**\n * Set the character\n * Clears the history only when the character changes.\n */\n setCharacter(character: Character): void {\n // Clear the history only when the character changes\n if (this.character?.id !== character.id) {\n this.historyManager.clear();\n }\n this.character = character;\n }\n\n /**\n * Return the currently configured character\n */\n getCharacter(): Character | null {\n return this.character;\n }\n\n /**\n * Clear the history\n */\n clearHistory(): void {\n this.historyManager.clear();\n }\n\n /**\n * Return the current history\n */\n getHistory(): Message[] {\n return this.historyManager.getAll();\n }\n\n /**\n * Generate a response to a message\n */\n async generateResponse(message: Message): Promise<string> {\n try {\n LLMValidators.validateCharacterSet(this.character);\n LLMValidators.validateMessage(message);\n } catch (error) {\n throw toCharivoError(\"state\", error);\n }\n\n // Defer pruning until the assistant message is appended. On failure we\n // only removeLast() the in-flight user message, so older history must\n // remain intact during the API call.\n this.historyManager.add(message, { prune: false });\n\n // Get the history messages\n const historyMessages = this.getHistoryForApiCall();\n\n // Convert to LLM API format (including the system prompt)\n const apiMessages = this.prepareApiMessages(historyMessages);\n\n try {\n // Generate a response via the LLM client\n const assistantMessage = await this.llmClient.call(apiMessages);\n\n // Build the AI response message and add it to the history\n const responseMessage = ResponseMessageBuilder.create(\n assistantMessage,\n this.character!.id, // character is guaranteed non-null after validateCharacterSet\n );\n this.historyManager.add(responseMessage, { prune: false });\n this.historyManager.pruneToMax();\n\n return assistantMessage;\n } catch (error) {\n // On error, remove the last message from the history\n this.historyManager.removeLast();\n throw toCharivoError(\"provider\", error);\n }\n }\n\n /**\n * Prepare messages for the LLM API call\n */\n private prepareApiMessages(\n messages: Message[],\n ): Array<{ role: string; content: string }> {\n if (!this.character) {\n return MessageConverter.toOpenAIFormat(messages);\n }\n\n const systemPrompt = CharacterPromptBuilder.buildSystemPrompt(\n this.character,\n );\n return MessageConverter.combineWithSystemPrompt(systemPrompt, messages);\n }\n\n private getHistoryForApiCall(): Message[] {\n const historyMessages = this.historyManager.getRecent(\n this.maxHistoryMessages,\n );\n\n if (historyMessages[0]?.type === \"character\") {\n return historyMessages.slice(1);\n }\n\n return historyMessages;\n }\n}\n\n/**\n * Helper function to create an LLM Manager\n */\nexport function createLLMManager(\n llmClient: LLMClient,\n options?: LLMManagerOptions,\n): CoreLLMManager {\n return new LLMManager(llmClient, options);\n}\n\nfunction resolveMaxHistoryMessages(\n options: LLMManagerOptions,\n): number | undefined {\n if (options.maxHistoryTurns === null) {\n return undefined;\n }\n\n const maxHistoryTurns = options.maxHistoryTurns ?? DEFAULT_MAX_HISTORY_TURNS;\n\n if (!Number.isInteger(maxHistoryTurns) || maxHistoryTurns <= 0) {\n throw new TypeError(\"maxHistoryTurns must be a positive integer or null\");\n }\n\n return maxHistoryTurns * 2;\n}\n"]}
1
+ {"version":3,"sources":["../src/message-history-manager.ts","../src/character-prompt-builder.ts","../src/message-converter.ts","../src/validators.ts","../src/response-message-builder.ts","../src/tool-execution.ts","../src/llm-manager.ts"],"names":["toCharivoError","validateToolArguments","assertToolResultObject"],"mappings":"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","file":"index.js","sourcesContent":["import { Message } from \"@charivo/core\";\n\nexport interface MessageHistoryManagerOptions {\n maxMessages?: number | null;\n pruneBatchSize?: number;\n}\n\nexport interface AddMessageOptions {\n /**\n * Internal escape hatch for workflows that need multiple appends to become\n * visible as one pruning boundary, such as user/assistant turn pairs.\n */\n prune?: boolean;\n}\n\n/**\n * Message history management\n */\nexport class MessageHistoryManager {\n private history: Message[] = [];\n private readonly maxMessages?: number;\n private readonly pruneBatchSize: number;\n\n constructor(options: MessageHistoryManagerOptions = {}) {\n if (\n options.maxMessages !== undefined &&\n options.maxMessages !== null &&\n (!Number.isInteger(options.maxMessages) || options.maxMessages <= 0)\n ) {\n throw new TypeError(\"maxMessages must be a positive integer or null\");\n }\n\n if (\n options.pruneBatchSize !== undefined &&\n (!Number.isInteger(options.pruneBatchSize) || options.pruneBatchSize <= 0)\n ) {\n throw new TypeError(\"pruneBatchSize must be a positive integer\");\n }\n\n this.maxMessages =\n options.maxMessages === null ? undefined : options.maxMessages;\n this.pruneBatchSize = options.pruneBatchSize ?? 1;\n }\n\n add(message: Message, options: AddMessageOptions = {}): void {\n this.history.push(message);\n\n if (options.prune !== false) {\n this.pruneToMax();\n }\n }\n\n removeLast(): Message | undefined {\n return this.history.pop();\n }\n\n clear(): void {\n this.history = [];\n }\n\n getAll(): Message[] {\n return [...this.history]; // Return a copy\n }\n\n getRecent(maxMessages?: number): Message[] {\n if (\n maxMessages !== undefined &&\n (!Number.isInteger(maxMessages) || maxMessages <= 0)\n ) {\n throw new TypeError(\"maxMessages must be a positive integer\");\n }\n\n if (maxMessages === undefined || this.history.length <= maxMessages) {\n return this.getAll();\n }\n\n return this.history.slice(-maxMessages);\n }\n\n size(): number {\n return this.history.length;\n }\n\n pruneToMax(): void {\n if (this.maxMessages === undefined) {\n return;\n }\n\n while (this.history.length > this.maxMessages) {\n const excess = this.history.length - this.maxMessages;\n const removeCount = Math.min(\n Math.ceil(excess / this.pruneBatchSize) * this.pruneBatchSize,\n this.history.length,\n );\n this.history.splice(0, removeCount);\n }\n }\n}\n","import { Character } from \"@charivo/core\";\n\n/**\n * Utility for converting character information into a system prompt\n */\nexport class CharacterPromptBuilder {\n static buildSystemPrompt(character: Character): string {\n const name = character.name;\n const description = character.description || \"\";\n const personality = character.personality || \"\";\n\n return `You are ${name}. ${description} ${personality}\n\nRespond naturally in plain text with no bracketed emotion tags or control markup.`.trim();\n }\n\n static buildSystemPromptOrDefault(character?: Character): string {\n if (character) {\n return this.buildSystemPrompt(character);\n }\n return `You are a helpful assistant.\n\nRespond naturally in plain text with no bracketed emotion tags or control markup.`.trim();\n }\n}\n","import { Message } from \"@charivo/core\";\n\n/**\n * Converted message shape. The role is a literal union so the result is also\n * assignable to the tool-calling `LLMMessage` union without casts.\n */\nexport interface LLMApiMessage {\n role: \"system\" | \"user\" | \"assistant\";\n content: string;\n}\n\n/**\n * Message format conversion utility\n */\nexport class MessageConverter {\n /**\n * Convert a Charivo Message to the OpenAI format\n */\n static toOpenAIFormat(messages: Message[]): LLMApiMessage[] {\n return messages.map((msg) => ({\n role: msg.type === \"user\" ? \"user\" : \"assistant\",\n content: msg.content,\n }));\n }\n\n /**\n * Combine the system prompt and messages into the OpenAI format\n */\n static combineWithSystemPrompt(\n systemPrompt: string,\n messages: Message[],\n ): LLMApiMessage[] {\n return [\n { role: \"system\", content: systemPrompt },\n ...this.toOpenAIFormat(messages),\n ];\n }\n}\n","import { Character, Message } from \"@charivo/core\";\n\n/**\n * LLM-related validation utilities\n */\nexport class LLMValidators {\n static validateCharacterSet(\n character: Character | null,\n ): asserts character is Character {\n if (!character) {\n throw new Error(\"Character must be set before generating response\");\n }\n }\n\n static validateMessage(message: Message): void {\n if (!message.content || typeof message.content !== \"string\") {\n throw new Error(\"Message content must be a non-empty string\");\n }\n }\n}\n","import { Message } from \"@charivo/core\";\n\n/**\n * Helper for building AI response messages\n */\nexport class ResponseMessageBuilder {\n static create(\n content: string,\n characterId: string,\n messageId?: string,\n ): Message {\n return {\n id: messageId || \"ai-\" + Date.now(),\n content,\n timestamp: new Date(),\n type: \"character\",\n characterId,\n };\n }\n}\n","import type { ToolDefinition, ToolRegistration } from \"@charivo/core\";\n\n/**\n * Tool registry for LLM sessions.\n *\n * Mirrors the realtime registry but stays local to this package so `@charivo/llm`\n * keeps depending only on `@charivo/core`.\n */\nexport class LLMToolRegistry {\n private readonly tools = new Map<string, ToolRegistration>();\n\n register(tool: ToolRegistration): void {\n this.tools.set(tool.definition.name, tool);\n }\n\n unregister(name: string): void {\n this.tools.delete(name);\n }\n\n get(name: string): ToolRegistration | undefined {\n return this.tools.get(name);\n }\n\n size(): number {\n return this.tools.size;\n }\n\n getDefinitions(): ToolDefinition[] {\n return Array.from(this.tools.values(), (tool) => ({\n ...tool.definition,\n parameters: {\n ...tool.definition.parameters,\n properties: { ...tool.definition.parameters.properties },\n required: tool.definition.parameters.required\n ? [...tool.definition.parameters.required]\n : undefined,\n },\n }));\n }\n}\n\n/** Always-serializable output handed back to the model when a tool call fails. */\nexport function createFailureOutput(error: Error): Record<string, unknown> {\n return {\n success: false,\n error: error.message,\n };\n}\n\nexport async function withTimeout<T>(\n promise: Promise<T>,\n timeoutMs: number,\n toolName: string,\n): Promise<T> {\n let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n try {\n return await Promise.race([\n promise,\n new Promise<never>((_, reject) => {\n timeoutId = setTimeout(() => {\n reject(\n new Error(`LLM tool \"${toolName}\" timed out after ${timeoutMs}ms`),\n );\n }, timeoutMs);\n }),\n ]);\n } finally {\n if (timeoutId !== undefined) {\n clearTimeout(timeoutId);\n }\n }\n}\n","import {\n LLMClient,\n Message,\n Character,\n assertToolResultObject,\n toCharivoError,\n validateToolArguments,\n type CharivoEventEmitter,\n type LLMManagerWithTools,\n type LLMMessage,\n type LLMToolCall,\n type ToolDefinition,\n type ToolRegistration,\n type ToolResultProjector,\n} from \"@charivo/core\";\nimport { MessageHistoryManager } from \"./message-history-manager\";\nimport { CharacterPromptBuilder } from \"./character-prompt-builder\";\nimport { MessageConverter, type LLMApiMessage } from \"./message-converter\";\nimport { LLMValidators } from \"./validators\";\nimport { ResponseMessageBuilder } from \"./response-message-builder\";\nimport {\n createFailureOutput,\n LLMToolRegistry,\n withTimeout,\n} from \"./tool-execution\";\n\nconst DEFAULT_MAX_HISTORY_TURNS = 40;\nconst DEFAULT_TOOL_TIMEOUT_MS = 10_000;\n/** Tool rounds actually executed before the reply is forced to finish. */\nconst MAX_TOOL_ROUNDS = 3;\n\nexport interface LLMManagerOptions {\n maxHistoryTurns?: number | null;\n tools?: ToolRegistration[];\n resultProjectors?: ToolResultProjector[];\n /** Appended to the character system prompt, tools path only. */\n toolInstructions?: string;\n defaultToolTimeoutMs?: number;\n}\n\n/**\n * LLM Manager - Class responsible for managing the state of an LLM session\n *\n * Responsibilities:\n * - Character configuration and management\n * - Message history management\n * - Communication with the LLM client\n * - Message format conversion\n * - Prompt generation\n */\nexport class LLMManager {\n private readonly historyManager: MessageHistoryManager;\n private readonly maxHistoryMessages?: number;\n private readonly toolRegistry = new LLMToolRegistry();\n private readonly resultProjectors: ToolResultProjector[];\n private readonly defaultToolTimeoutMs: number;\n private character: Character | null = null;\n private eventEmitter?: CharivoEventEmitter;\n private toolInstructions: string | null;\n\n constructor(\n private llmClient: LLMClient,\n options: LLMManagerOptions = {},\n ) {\n this.maxHistoryMessages = resolveMaxHistoryMessages(options);\n this.historyManager = new MessageHistoryManager({\n maxMessages: this.maxHistoryMessages,\n pruneBatchSize: 2,\n });\n this.resultProjectors = options.resultProjectors ?? [];\n this.defaultToolTimeoutMs =\n options.defaultToolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;\n this.toolInstructions = options.toolInstructions ?? null;\n\n for (const tool of options.tools ?? []) {\n this.registerTool(tool);\n }\n }\n\n setEventEmitter(eventEmitter: CharivoEventEmitter): void {\n this.eventEmitter = eventEmitter;\n }\n\n registerTool(tool: ToolRegistration): void {\n this.toolRegistry.register(tool);\n }\n\n unregisterTool(name: string): void {\n this.toolRegistry.unregister(name);\n }\n\n getRegisteredTools(): ToolDefinition[] {\n return this.toolRegistry.getDefinitions();\n }\n\n /**\n * Set the tool instructions appended to the system prompt.\n * Pass null to clear them.\n */\n setToolInstructions(instructions: string | null): void {\n this.toolInstructions = instructions;\n }\n\n /**\n * Set the character\n * Clears the history only when the character changes.\n */\n setCharacter(character: Character): void {\n // Clear the history only when the character changes\n if (this.character?.id !== character.id) {\n this.historyManager.clear();\n }\n this.character = character;\n }\n\n /**\n * Return the currently configured character\n */\n getCharacter(): Character | null {\n return this.character;\n }\n\n /**\n * Clear the history\n */\n clearHistory(): void {\n this.historyManager.clear();\n }\n\n /**\n * Return the current history\n */\n getHistory(): Message[] {\n return this.historyManager.getAll();\n }\n\n /**\n * Generate a response to a message\n */\n async generateResponse(message: Message): Promise<string> {\n try {\n LLMValidators.validateCharacterSet(this.character);\n LLMValidators.validateMessage(message);\n } catch (error) {\n throw toCharivoError(\"state\", error);\n }\n\n // Defer pruning until the assistant message is appended. On failure we\n // only removeLast() the in-flight user message, so older history must\n // remain intact during the API call.\n this.historyManager.add(message, { prune: false });\n\n // Get the history messages\n const historyMessages = this.getHistoryForApiCall();\n\n // Convert to LLM API format (including the system prompt)\n const apiMessages = this.prepareApiMessages(historyMessages);\n\n try {\n // Generate a response via the LLM client\n const assistantMessage = this.shouldUseToolLoop()\n ? await this.runToolLoop(apiMessages)\n : await this.llmClient.call(apiMessages);\n\n // Build the AI response message and add it to the history.\n // Only the final assistant text is persisted: tool-call and tool-result\n // turns stay inside the loop so the stored history remains a plain\n // user/character transcript that other modalities can reuse.\n const responseMessage = ResponseMessageBuilder.create(\n assistantMessage,\n this.character!.id, // character is guaranteed non-null after validateCharacterSet\n );\n this.historyManager.add(responseMessage, { prune: false });\n this.historyManager.pruneToMax();\n\n return assistantMessage;\n } catch (error) {\n // On error, remove the last message from the history\n this.historyManager.removeLast();\n throw toCharivoError(\"provider\", error);\n }\n }\n\n /**\n * Tools engage only when both sides opt in: at least one registered tool and\n * a client that implements the optional tool-calling variant.\n */\n private shouldUseToolLoop(): boolean {\n return (\n this.toolRegistry.size() > 0 &&\n typeof this.llmClient.callWithTools === \"function\"\n );\n }\n\n /**\n * Run the tool-calling conversation until the model answers with text or the\n * round cap is reached.\n */\n private async runToolLoop(apiMessages: LLMApiMessage[]): Promise<string> {\n // Guarded by shouldUseToolLoop(): callWithTools exists on this path\n const callWithTools = this.llmClient.callWithTools!.bind(this.llmClient);\n const definitions = this.getRegisteredTools();\n const working = this.buildToolLoopMessages(apiMessages);\n\n let response = await callWithTools(working, definitions);\n\n for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {\n const toolCalls = response.toolCalls ?? [];\n if (toolCalls.length === 0) {\n return response.content;\n }\n\n working.push({\n role: \"assistant\",\n content: response.content,\n toolCalls,\n });\n\n for (const toolCall of toolCalls) {\n working.push({\n role: \"tool\",\n content: await this.executeToolCall(toolCall),\n toolCallId: toolCall.id,\n });\n }\n\n // Terminal call offers no tools so the reply is text, not an unexecuted tool request.\n const isFinalRound = round === MAX_TOOL_ROUNDS - 1;\n response = await callWithTools(working, isFinalRound ? [] : definitions);\n }\n\n // Round cap reached: return the model's text instead of executing more tools\n return response.content;\n }\n\n /**\n * Seed the tool conversation, appending the tool instructions to the system\n * prompt. generateResponse validates the character first, so the tools path\n * always starts with a system message.\n */\n private buildToolLoopMessages(apiMessages: LLMApiMessage[]): LLMMessage[] {\n const messages: LLMMessage[] = [...apiMessages];\n const systemMessage = messages[0];\n\n if (this.toolInstructions && systemMessage.role === \"system\") {\n messages[0] = {\n role: \"system\",\n content: `${systemMessage.content}\\n\\n${this.toolInstructions}`,\n };\n }\n\n return messages;\n }\n\n /**\n * Execute one tool call and return the serialized output for its tool turn.\n * Every failure - unknown tool, invalid arguments, handler throw/timeout,\n * non-object result, unserializable output - becomes a failure output so the\n * reply always continues.\n */\n private async executeToolCall(toolCall: LLMToolCall): Promise<string> {\n let output: Record<string, unknown>;\n let serialized: string;\n\n try {\n const tool = this.toolRegistry.get(toolCall.name);\n if (!tool) {\n throw new Error(`No LLM tool registered for \"${toolCall.name}\"`);\n }\n\n validateToolArguments(tool.definition, toolCall.arguments, \"LLM tool\");\n\n const result = await withTimeout(\n tool.handler(toolCall.arguments, {\n character: this.character,\n callId: toolCall.id,\n }),\n tool.timeoutMs ?? this.defaultToolTimeoutMs,\n tool.definition.name,\n );\n\n assertToolResultObject(result, tool.definition.name, \"LLM tool\");\n\n // Serialize inside the failure boundary: outputs that cannot be\n // stringified (bigint values, circular references) degrade to a failure\n // output instead of aborting the reply. JSON.stringify's declared return\n // type is `string`, but a `toJSON()` that returns `undefined` makes it\n // return the value `undefined` at runtime, so that case is checked\n // explicitly rather than relying on a thrown error.\n const stringified: unknown = JSON.stringify(result);\n if (typeof stringified !== \"string\") {\n throw new Error(\n `LLM tool \"${tool.definition.name}\" result could not be serialized to JSON`,\n );\n }\n serialized = stringified;\n output = result;\n } catch (error) {\n return JSON.stringify(createFailureOutput(toError(error)));\n }\n\n this.projectToolResult(toolCall.name, output, toolCall.id);\n\n return serialized;\n }\n\n /**\n * Turn a successful tool result into avatar-style events. Projection is\n * skipped entirely without an event emitter.\n */\n private projectToolResult(\n name: string,\n output: Record<string, unknown>,\n callId: string,\n ): void {\n const eventEmitter = this.eventEmitter;\n if (!eventEmitter) {\n return;\n }\n\n for (const projector of this.resultProjectors) {\n try {\n projector({\n name,\n output,\n callId,\n emit: (event, payload) => {\n eventEmitter.emit(event, payload);\n },\n });\n } catch (error) {\n eventEmitter.emit(\"error\", {\n error: new Error(\n `LLM result projector failed for tool \"${name}\": ${toError(error).message}`,\n ),\n });\n }\n }\n }\n\n /**\n * Prepare messages for the LLM API call\n */\n private prepareApiMessages(messages: Message[]): LLMApiMessage[] {\n if (!this.character) {\n return MessageConverter.toOpenAIFormat(messages);\n }\n\n const systemPrompt = CharacterPromptBuilder.buildSystemPrompt(\n this.character,\n );\n return MessageConverter.combineWithSystemPrompt(systemPrompt, messages);\n }\n\n private getHistoryForApiCall(): Message[] {\n const historyMessages = this.historyManager.getRecent(\n this.maxHistoryMessages,\n );\n\n if (historyMessages[0]?.type === \"character\") {\n return historyMessages.slice(1);\n }\n\n return historyMessages;\n }\n}\n\n/**\n * Helper function to create an LLM Manager\n */\nexport function createLLMManager(\n llmClient: LLMClient,\n options?: LLMManagerOptions,\n): LLMManagerWithTools {\n return new LLMManager(llmClient, options);\n}\n\nfunction toError(error: unknown): Error {\n return error instanceof Error ? error : new Error(String(error));\n}\n\nfunction resolveMaxHistoryMessages(\n options: LLMManagerOptions,\n): number | undefined {\n if (options.maxHistoryTurns === null) {\n return undefined;\n }\n\n const maxHistoryTurns = options.maxHistoryTurns ?? DEFAULT_MAX_HISTORY_TURNS;\n\n if (!Number.isInteger(maxHistoryTurns) || maxHistoryTurns <= 0) {\n throw new TypeError(\"maxHistoryTurns must be a positive integer or null\");\n }\n\n return maxHistoryTurns * 2;\n}\n"]}