@lowdefy/ai-utils 7.3.0 → 7.4.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.
@@ -244,7 +244,7 @@
244
244
  },
245
245
  generateTitle: {
246
246
  type: 'boolean',
247
- description: 'When true, generate a short conversation title on the first turn from the first user message. Emits a "data-chat-title" data part that fires the block\'s onTitleGenerated event. Off by default.',
247
+ description: 'When true, generate a short conversation title from the first exchange (the first user message and the first reply), once the reply is complete. The title call uses the agent\'s providerOptions without its thinking and reasoning settings. Emits a "data-chat-title" data part that fires the block\'s onTitleGenerated event. Off by default.',
248
248
  errorMessage: {
249
249
  type: 'AISDKAgent agent property "generateTitle" should be a boolean.'
250
250
  }
@@ -0,0 +1,38 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */ // The opening of the reply names the subject; the rest is elaboration the title can't carry,
16
+ // and tokens on a call made for every new conversation.
17
+ const MAX_REPLY_CHARS = 1200;
18
+ // The title is drawn from the first exchange, not the first message alone: a chat that offers
19
+ // suggested prompts opens many conversations with the same canned question, and only the
20
+ // reply says what each one is about.
21
+ function buildChatTitlePrompt({ firstUserText, replyText }) {
22
+ return `Write a title for a chat conversation, given the user's opening message and the assistant's reply.
23
+
24
+ Rules:
25
+ - Name the subject, not the action. The opening message is often a canned prompt such as "Explain this" or "How do I get started?", and those words must not be the title. The subject is usually in the reply: the record, task, feature or question being discussed.
26
+ - 2 to 6 words, in sentence case. Keep established abbreviations as written.
27
+ - No quotation marks, no trailing punctuation, no "chat about" or "discussion of".
28
+ - If the exchange is about nothing specific, describe the ask in 2 or 3 plain words.
29
+ - Reply with only the title.
30
+
31
+ User's opening message:
32
+ ${firstUserText}
33
+
34
+ Assistant's reply:
35
+ ${replyText.slice(0, MAX_REPLY_CHARS)}`;
36
+ }
37
+ export { MAX_REPLY_CHARS };
38
+ export default buildChatTitlePrompt;
@@ -0,0 +1,75 @@
1
+ /*
2
+ Copyright 2020-2026 Lowdefy, Inc
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+ */ import { type } from '@lowdefy/helpers';
16
+ // The provider settings that set how much a model reasons. A provider setting wins over the
17
+ // call-level `reasoning`, so these have to come off for `reasoning: 'none'` to take effect.
18
+ const REASONING_KEYS = {
19
+ anthropic: [
20
+ 'thinking',
21
+ 'effort'
22
+ ],
23
+ google: [
24
+ 'thinkingConfig'
25
+ ],
26
+ openai: [
27
+ 'reasoningEffort',
28
+ 'reasoningSummary'
29
+ ]
30
+ };
31
+ // Room for the reasoning a model does even at `reasoning: 'none'`: some can't turn it off
32
+ // (Anthropic's always-thinking models fall back to low effort, Gemini 2.5 Pro to its minimum
33
+ // budget, the first gpt-5 to its default), and reasoning tokens count against this cap. A
34
+ // model that doesn't reason stops after the few words of the title.
35
+ const MAX_OUTPUT_TOKENS = 1024;
36
+ // Every other provider setting is kept: besides routing and retention in `gateway`, the provider
37
+ // keys carry settings the title call must honour too, such as OpenAI's `store` or Gemini's
38
+ // `safetySettings`. A setting left on by mistake costs tokens; one taken off by mistake could
39
+ // send the conversation somewhere the agent's own calls don't go.
40
+ function buildTitleProviderOptions(providerOptions) {
41
+ if (type.isNone(providerOptions)) return undefined;
42
+ const titleProviderOptions = {
43
+ ...providerOptions
44
+ };
45
+ Object.entries(REASONING_KEYS).forEach(([provider, keys])=>{
46
+ if (!type.isObject(titleProviderOptions[provider])) return;
47
+ const options = {
48
+ ...titleProviderOptions[provider]
49
+ };
50
+ keys.forEach((key)=>delete options[key]);
51
+ titleProviderOptions[provider] = options;
52
+ });
53
+ return titleProviderOptions;
54
+ }
55
+ // generateText takes only the total and step limits; it ignores the streaming chunk limits
56
+ // (and logs an AI SDK warning for them), which would leave the title call unbounded.
57
+ function buildTitleTimeout(timeout) {
58
+ if (type.isNone(timeout)) return undefined;
59
+ if (type.isNumber(timeout)) return timeout;
60
+ const { totalMs, stepMs } = timeout;
61
+ if (type.isNone(totalMs) && type.isNone(stepMs)) return undefined;
62
+ return {
63
+ totalMs,
64
+ stepMs
65
+ };
66
+ }
67
+ function buildTitleCallSettings({ providerOptions, timeout }) {
68
+ return {
69
+ maxOutputTokens: MAX_OUTPUT_TOKENS,
70
+ providerOptions: buildTitleProviderOptions(providerOptions),
71
+ reasoning: 'none',
72
+ timeout: buildTitleTimeout(timeout)
73
+ };
74
+ }
75
+ export default buildTitleCallSettings;
@@ -15,6 +15,8 @@
15
15
  */ import { convertToModelMessages, createAgentUIStream, createUIMessageStream, createUIMessageStreamResponse, generateId, generateText, pruneMessages, toUIMessageStream, validateUIMessages } from 'ai';
16
16
  import { serializer } from '@lowdefy/helpers';
17
17
  import agentErrorForLog, { agentLogIds, stackFramesForLog } from './agentErrorForLog.js';
18
+ import buildChatTitlePrompt from './buildChatTitlePrompt.js';
19
+ import buildTitleCallSettings from './buildTitleCallSettings.js';
18
20
  import createToolLoopAgent from './createToolLoopAgent.js';
19
21
  import createUsageAccumulator from './createUsageAccumulator.js';
20
22
  import handleAgentGenerate from './handleAgentGenerate.js';
@@ -62,12 +64,14 @@ function createClientErrorText(context) {
62
64
  return context.wireErrorMessage(error);
63
65
  };
64
66
  }
65
- // Concatenate the text parts of the first user message — used as the source
66
- // for generateTitle.
67
- function getFirstUserText(messages) {
68
- const firstUser = messages.find((msg)=>msg.role === 'user');
69
- if (!firstUser) return '';
70
- return (firstUser.parts ?? []).filter((part)=>part.type === 'text').map((part)=>part.text).join('');
67
+ // The text parts of a message, which generateTitle titles the conversation from.
68
+ function getMessageText(message) {
69
+ return (message?.parts ?? []).filter((part)=>part.type === 'text').map((part)=>part.text).join('\n');
70
+ }
71
+ // A reply that ends on a tool call waiting for the user's approval, or for the client to run
72
+ // it, is not finished: the next request continues the same assistant message.
73
+ function isWaitingOnClient(message) {
74
+ return (message?.parts ?? []).some((part)=>part.state === 'approval-requested' || part.state === 'input-available');
71
75
  }
72
76
  async function handleAgentChat({ connection, properties, context }) {
73
77
  // Headless run-to-completion mode (CallAgent routine step) — dispatched here
@@ -91,6 +95,9 @@ async function handleAgentChat({ connection, properties, context }) {
91
95
  const hasMcpClients = mcpClients.length > 0;
92
96
  const pruneConfig = agent.properties.prune;
93
97
  const titleEnabled = agent.properties.generateTitle === true;
98
+ // The first exchange is every request until the user sends a second message: a reply that
99
+ // waits on a tool approval or a client tool is continued by a request with no new user message.
100
+ const isFirstExchange = messages.filter((msg)=>msg.role === 'user').length === 1;
94
101
  const clientErrorText = createClientErrorText(context);
95
102
  const logIds = agentLogIds({
96
103
  agent,
@@ -108,6 +115,7 @@ async function handleAgentChat({ connection, properties, context }) {
108
115
  // assistant reply) to the stream-level onEnd. Capture it so onFinish
109
116
  // hooks persist the complete conversation, not just the request input.
110
117
  let capturedMessages;
118
+ let turnFailed = false;
111
119
  function collectStep(stepResult) {
112
120
  usageAccumulator.add(stepResult);
113
121
  steps.push({
@@ -121,35 +129,41 @@ async function handleAgentChat({ connection, properties, context }) {
121
129
  function captureMessages({ messages: finalMessages }) {
122
130
  capturedMessages = finalMessages;
123
131
  }
124
- // Generate a short conversation title from the first user message,
125
- // concurrently with the agent stream. The data-chat-title part fires the
126
- // block's onTitleGenerated event. Only on the first turn; failures are
127
- // non-fatal.
128
- let titlePromise;
129
- const isFirstTurn = !messages.some((msg)=>msg.role === 'assistant');
130
- if (titleEnabled && isFirstTurn) {
131
- const firstUserText = getFirstUserText(messages);
132
- if (firstUserText) {
133
- titlePromise = generateText({
132
+ // The title is cosmetic: a failed title call is logged and the turn ends without one.
133
+ async function writeChatTitle({ firstUserText, replyText }) {
134
+ if (!firstUserText && !replyText) return;
135
+ try {
136
+ const { text, finishReason } = await generateText({
134
137
  model,
135
- maxOutputTokens: 20,
136
- prompt: `Generate a concise 3-6 word title for a conversation that begins with this message. Reply with only the title, no quotes:\n\n${firstUserText}`
137
- }).then(({ text })=>{
138
- const title = text.trim();
139
- if (title) {
140
- writer.write({
141
- type: 'data-chat-title',
142
- data: {
143
- title
144
- }
145
- });
146
- }
147
- }).catch((error)=>{
138
+ prompt: buildChatTitlePrompt({
139
+ firstUserText,
140
+ replyText
141
+ }),
142
+ ...buildTitleCallSettings({
143
+ providerOptions: agent.properties.providerOptions,
144
+ timeout: timeoutConfig.timeout
145
+ })
146
+ });
147
+ const title = text.trim();
148
+ if (!title) {
149
+ // A model that can't turn reasoning off can spend the token cap before any text.
148
150
  context.logger.warn({
149
151
  ...logIds,
150
- error: agentErrorForLog(error)
151
- }, 'generateTitle failed.');
152
+ finishReason
153
+ }, 'generateTitle returned no text.');
154
+ return;
155
+ }
156
+ writer.write({
157
+ type: 'data-chat-title',
158
+ data: {
159
+ title
160
+ }
152
161
  });
162
+ } catch (error) {
163
+ context.logger.warn({
164
+ ...logIds,
165
+ error: agentErrorForLog(error)
166
+ }, 'generateTitle failed.');
153
167
  }
154
168
  }
155
169
  // One try around validation, the agent run and the read: a UIMessage that
@@ -220,6 +234,8 @@ async function handleAgentChat({ connection, properties, context }) {
220
234
  while(true){
221
235
  const { done, value } = await reader.read();
222
236
  if (done) break;
237
+ // An error the agent stream handles itself arrives as a chunk, not a throw.
238
+ if (value.type === 'error' || value.type === 'abort') turnFailed = true;
223
239
  writer.write(value);
224
240
  }
225
241
  } catch (error) {
@@ -235,14 +251,22 @@ async function handleAgentChat({ connection, properties, context }) {
235
251
  ...logIds,
236
252
  stack: stackFramesForLog(error)
237
253
  }, 'Agent stream failed: stack.');
254
+ turnFailed = true;
238
255
  writer.write({
239
256
  type: 'error',
240
257
  errorText: writer.onError(error)
241
258
  });
242
259
  }
243
- // Ensure the title (if any) is written before the stream closes.
244
- if (titlePromise) {
245
- await titlePromise;
260
+ // Title the conversation from its first exchange once the reply is complete. A failed
261
+ // turn gets no title, so a slow or failing model isn't waited on twice; its retry is still
262
+ // the first exchange and is titled then. The title call runs alongside the onFinish hooks.
263
+ const replyMessage = (capturedMessages ?? []).findLast((msg)=>msg.role === 'assistant');
264
+ let titlePromise;
265
+ if (titleEnabled && isFirstExchange && !turnFailed && !isWaitingOnClient(replyMessage)) {
266
+ titlePromise = writeChatTitle({
267
+ firstUserText: getMessageText(messages.find((msg)=>msg.role === 'user')),
268
+ replyText: getMessageText(replyMessage)
269
+ });
246
270
  }
247
271
  // Call onFinish hooks — awaited so dataParts can be written to stream.
248
272
  if (hasOnFinishHooks) {
@@ -276,6 +300,9 @@ async function handleAgentChat({ connection, properties, context }) {
276
300
  }
277
301
  }
278
302
  }
303
+ // Before the stream closes, so the data-chat-title part reaches the block and fires its
304
+ // onTitleGenerated event.
305
+ await titlePromise;
279
306
  if (hasMcpClients) {
280
307
  await Promise.all(mcpClients.map(({ client })=>client.close().catch(()=>{})));
281
308
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lowdefy/ai-utils",
3
- "version": "7.3.0",
3
+ "version": "7.4.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -17,15 +17,15 @@
17
17
  ],
18
18
  "dependencies": {
19
19
  "@ai-sdk/mcp": "2.0.60",
20
- "@lowdefy/errors": "7.3.0",
21
- "@lowdefy/helpers": "7.3.0",
22
- "@lowdefy/node-utils": "7.3.0",
20
+ "@lowdefy/errors": "7.4.0",
21
+ "@lowdefy/helpers": "7.4.0",
22
+ "@lowdefy/node-utils": "7.4.0",
23
23
  "ai": "7.0.116",
24
- "glob": "13.0.6",
24
+ "glob": "14.0.5",
25
25
  "undici": "7.30.1"
26
26
  },
27
27
  "devDependencies": {
28
- "@lowdefy/ajv": "7.3.0",
28
+ "@lowdefy/ajv": "7.4.0",
29
29
  "@swc/cli": "0.8.1",
30
30
  "@swc/core": "1.15.32",
31
31
  "vitest": "4.1.12"