@terreno/ai 57.12.0 → 57.14.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/dist/index.d.ts CHANGED
@@ -36,10 +36,12 @@ export { addGptRoutes } from "./routes/gpt";
36
36
  export { addGptHistoryRoutes } from "./routes/gptHistories";
37
37
  export { addMcpRoutes } from "./routes/mcp";
38
38
  export { addProjectRoutes } from "./routes/projects";
39
+ export { findAgentBlock } from "./service/agentBlocks";
39
40
  export type { RegisteredDataset } from "./service/aiDatasets";
40
41
  export { configureAiDatasets, registerAiDataset } from "./service/aiDatasets";
41
42
  export { AIService, TemperaturePresets } from "./service/aiService";
42
43
  export { createAskTools } from "./service/asks";
44
+ export { runBufferedChatTurn } from "./service/chatTurn";
43
45
  export { FileStorageService } from "./service/fileStorage";
44
46
  export type { ListGeminiApiModelsOptions } from "./service/gemini";
45
47
  export { GEMINI_API_BASE_URL, listGeminiApiModels, normalizeGeminiModelId, } from "./service/gemini";
@@ -48,6 +50,8 @@ export { MCPService } from "./service/mcpService";
48
50
  export type { ParseFailure, ParseResult, ParseSuccess } from "./service/parseAiJson";
49
51
  export { normalizeLlmJsonTextForStructuredOutput, parseAiJson, } from "./service/parseAiJson";
50
52
  export { COMPACT_SURFACE_SYSTEM_PROMPT, CONTENT_SUMMARY_PROMPT, DEFAULT_GPT_MEMORY, JSON_VALUE_SYSTEM_PROMPT, REMIX_PROMPT, TERRENO_ASKS_SYSTEM_PROMPT, TITLE_GENERATION_PROMPT, TRANSLATION_PROMPT, } from "./service/prompts";
53
+ export { scaleStepperHostAction } from "./service/scaleStepper";
54
+ export { toggleChecklistHostAction } from "./service/toggleChecklist";
51
55
  export type { CreateVertexProviderOptions, ListEnabledVertexModelsOptions, TerrenoVertexProvider, VerifyVertexModelsOptions, VertexLanguageModelProvider, VertexModelAvailability, } from "./service/vertex";
52
56
  export { assertVertexModelsEnabled, createVertexProvider, DEFAULT_VERTEX_LOCATION, isVertexModelAllowed, listEnabledVertexModels, normalizeVertexModelId, verifyVertexModelsEnabled, } from "./service/vertex";
53
57
  export type { WebSearchProvider, WebSearchResult } from "./service/webSearchTool";
package/dist/index.js CHANGED
@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
17
  exports.validateObservabilityConfig = exports.resolveObservabilityControl = exports.DEFAULT_OBSERVABILITY_CONTROL = exports.isLocalObservabilityPluginOn = exports.buildPlaygroundAiStatus = exports.buildObservabilityStatus = exports.resetObservabilityApp = exports.ObservabilityApp = exports.getObservabilityApp = exports.MemoryTraceSink = exports.MemoryScoreSink = exports.LocalTraceStore = exports.LocalTraceSink = exports.LocalScoreSink = exports.LocalReviewStore = exports.LocalPromptStore = exports.createLocalObservabilityPlugin = exports.createLocalObservabilityBundle = exports.LocalExperimentRunner = exports.LocalEvaluatorStore = exports.LocalDatasetStore = exports.observabilityAdminScreens = exports.AI_OBSERVABILITY_GROUP = exports.Project = exports.getProjectModel = exports.GptHistory = exports.FileAttachment = exports.AIRequest = exports.AIDataset = exports.preparePromptForAI = exports.createTelemetryConfig = exports.shutdownTracing = exports.initTracing = exports.invalidatePromptCache = exports.getPrompt = exports.createPrompt = exports.compilePrompt = exports.shutdownLangfuseClient = exports.isLangfuseInitialized = exports.initLangfuseClient = exports.getLangfuseClient = exports.setCached = exports.LangfuseCache = exports.invalidateCache = exports.getCached = exports.LangfuseApp = exports.AiApp = exports.AIAdminApp = exports.Output = exports.jsonSchema = void 0;
18
- exports.verifyVertexModelsEnabled = exports.normalizeVertexModelId = exports.listEnabledVertexModels = exports.isVertexModelAllowed = exports.DEFAULT_VERTEX_LOCATION = exports.createVertexProvider = exports.assertVertexModelsEnabled = exports.TRANSLATION_PROMPT = exports.TITLE_GENERATION_PROMPT = exports.TERRENO_ASKS_SYSTEM_PROMPT = exports.REMIX_PROMPT = exports.JSON_VALUE_SYSTEM_PROMPT = exports.DEFAULT_GPT_MEMORY = exports.CONTENT_SUMMARY_PROMPT = exports.COMPACT_SURFACE_SYSTEM_PROMPT = exports.parseAiJson = exports.normalizeLlmJsonTextForStructuredOutput = exports.MCPService = exports.getMCPTools = exports.normalizeGeminiModelId = exports.listGeminiApiModels = exports.GEMINI_API_BASE_URL = exports.FileStorageService = exports.createAskTools = exports.TemperaturePresets = exports.AIService = exports.registerAiDataset = exports.configureAiDatasets = exports.addProjectRoutes = exports.addMcpRoutes = exports.addGptHistoryRoutes = exports.addGptRoutes = exports.addFileRoutes = exports.addAiRequestsExplorerRoutes = void 0;
18
+ exports.verifyVertexModelsEnabled = exports.normalizeVertexModelId = exports.listEnabledVertexModels = exports.isVertexModelAllowed = exports.DEFAULT_VERTEX_LOCATION = exports.createVertexProvider = exports.assertVertexModelsEnabled = exports.toggleChecklistHostAction = exports.scaleStepperHostAction = exports.TRANSLATION_PROMPT = exports.TITLE_GENERATION_PROMPT = exports.TERRENO_ASKS_SYSTEM_PROMPT = exports.REMIX_PROMPT = exports.JSON_VALUE_SYSTEM_PROMPT = exports.DEFAULT_GPT_MEMORY = exports.CONTENT_SUMMARY_PROMPT = exports.COMPACT_SURFACE_SYSTEM_PROMPT = exports.parseAiJson = exports.normalizeLlmJsonTextForStructuredOutput = exports.MCPService = exports.getMCPTools = exports.normalizeGeminiModelId = exports.listGeminiApiModels = exports.GEMINI_API_BASE_URL = exports.FileStorageService = exports.runBufferedChatTurn = exports.createAskTools = exports.TemperaturePresets = exports.AIService = exports.registerAiDataset = exports.configureAiDatasets = exports.findAgentBlock = exports.addProjectRoutes = exports.addMcpRoutes = exports.addGptHistoryRoutes = exports.addGptRoutes = exports.addFileRoutes = exports.addAiRequestsExplorerRoutes = void 0;
19
19
  var ai_1 = require("ai");
20
20
  Object.defineProperty(exports, "jsonSchema", { enumerable: true, get: function () { return ai_1.jsonSchema; } });
21
21
  Object.defineProperty(exports, "Output", { enumerable: true, get: function () { return ai_1.Output; } });
@@ -103,6 +103,8 @@ var mcp_1 = require("./routes/mcp");
103
103
  Object.defineProperty(exports, "addMcpRoutes", { enumerable: true, get: function () { return mcp_1.addMcpRoutes; } });
104
104
  var projects_1 = require("./routes/projects");
105
105
  Object.defineProperty(exports, "addProjectRoutes", { enumerable: true, get: function () { return projects_1.addProjectRoutes; } });
106
+ var agentBlocks_1 = require("./service/agentBlocks");
107
+ Object.defineProperty(exports, "findAgentBlock", { enumerable: true, get: function () { return agentBlocks_1.findAgentBlock; } });
106
108
  var aiDatasets_1 = require("./service/aiDatasets");
107
109
  Object.defineProperty(exports, "configureAiDatasets", { enumerable: true, get: function () { return aiDatasets_1.configureAiDatasets; } });
108
110
  Object.defineProperty(exports, "registerAiDataset", { enumerable: true, get: function () { return aiDatasets_1.registerAiDataset; } });
@@ -111,6 +113,8 @@ Object.defineProperty(exports, "AIService", { enumerable: true, get: function ()
111
113
  Object.defineProperty(exports, "TemperaturePresets", { enumerable: true, get: function () { return aiService_1.TemperaturePresets; } });
112
114
  var asks_1 = require("./service/asks");
113
115
  Object.defineProperty(exports, "createAskTools", { enumerable: true, get: function () { return asks_1.createAskTools; } });
116
+ var chatTurn_1 = require("./service/chatTurn");
117
+ Object.defineProperty(exports, "runBufferedChatTurn", { enumerable: true, get: function () { return chatTurn_1.runBufferedChatTurn; } });
114
118
  var fileStorage_1 = require("./service/fileStorage");
115
119
  Object.defineProperty(exports, "FileStorageService", { enumerable: true, get: function () { return fileStorage_1.FileStorageService; } });
116
120
  var gemini_1 = require("./service/gemini");
@@ -133,6 +137,10 @@ Object.defineProperty(exports, "REMIX_PROMPT", { enumerable: true, get: function
133
137
  Object.defineProperty(exports, "TERRENO_ASKS_SYSTEM_PROMPT", { enumerable: true, get: function () { return prompts_1.TERRENO_ASKS_SYSTEM_PROMPT; } });
134
138
  Object.defineProperty(exports, "TITLE_GENERATION_PROMPT", { enumerable: true, get: function () { return prompts_1.TITLE_GENERATION_PROMPT; } });
135
139
  Object.defineProperty(exports, "TRANSLATION_PROMPT", { enumerable: true, get: function () { return prompts_1.TRANSLATION_PROMPT; } });
140
+ var scaleStepper_1 = require("./service/scaleStepper");
141
+ Object.defineProperty(exports, "scaleStepperHostAction", { enumerable: true, get: function () { return scaleStepper_1.scaleStepperHostAction; } });
142
+ var toggleChecklist_1 = require("./service/toggleChecklist");
143
+ Object.defineProperty(exports, "toggleChecklistHostAction", { enumerable: true, get: function () { return toggleChecklist_1.toggleChecklistHostAction; } });
136
144
  var vertex_1 = require("./service/vertex");
137
145
  Object.defineProperty(exports, "assertVertexModelsEnabled", { enumerable: true, get: function () { return vertex_1.assertVertexModelsEnabled; } });
138
146
  Object.defineProperty(exports, "createVertexProvider", { enumerable: true, get: function () { return vertex_1.createVertexProvider; } });
@@ -25,6 +25,11 @@ const payloadFields = (issues) => {
25
25
  }
26
26
  return fields;
27
27
  };
28
+ /** With `logResponse: false`, only a numeric `payload.value` joins the ids in the log. */
29
+ const loggedValue = (payload) => {
30
+ const value = payload?.value;
31
+ return typeof value === "number" ? { value } : {};
32
+ };
28
33
  const withTimeout = async (work, timeoutMs) => {
29
34
  let timer;
30
35
  try {
@@ -147,7 +152,15 @@ const addGptActionRoutes = (router, options) => {
147
152
  parsedPayload = parsed.data;
148
153
  }
149
154
  const started = luxon_1.DateTime.now();
150
- const prompt = JSON.stringify({ blockId, elementId, historyId, messageId, name });
155
+ const isResponseLogged = action.logResponse !== false;
156
+ const prompt = JSON.stringify({
157
+ blockId,
158
+ elementId,
159
+ historyId,
160
+ messageId,
161
+ name,
162
+ ...(isResponseLogged ? {} : loggedValue(parsedPayload)),
163
+ });
151
164
  let result;
152
165
  try {
153
166
  result = await withTimeout(Promise.resolve(action.handler({
@@ -202,7 +215,7 @@ const addGptActionRoutes = (router, options) => {
202
215
  };
203
216
  await logAction({
204
217
  prompt,
205
- response: JSON.stringify(data),
218
+ response: isResponseLogged ? JSON.stringify(data) : undefined,
206
219
  responseTime: luxon_1.DateTime.now().toMillis() - started.toMillis(),
207
220
  userId,
208
221
  });
@@ -0,0 +1,20 @@
1
+ import { type Block, type BlocksDocument } from "@terreno/blocks";
2
+ import type { GptHistoryDocument } from "../types";
3
+ /**
4
+ * A `{v: 1, blocks}` document. Built by assignment so `v` stays the first key, which
5
+ * `validateBlocks` requires (`KEY_ORDER`).
6
+ */
7
+ export declare const blocksDocument: (blocks: Block[]) => BlocksDocument;
8
+ /**
9
+ * Loads the block the agent wrote, from the stored history rather than from the client.
10
+ * `msg-<n>` reads `history.prompts[n]` (stored prompts have no ids). Otherwise the only assistant
11
+ * prompt holding a block of that type and id is used: 409 when several do, 404 when none does.
12
+ */
13
+ export declare const findAgentBlock: <T extends Block["type"]>({ blockId, history, messageId, type, }: {
14
+ blockId: string;
15
+ history: GptHistoryDocument;
16
+ messageId: string;
17
+ type: T;
18
+ }) => Extract<Block, {
19
+ type: T;
20
+ }>;
@@ -0,0 +1,92 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.findAgentBlock = exports.blocksDocument = void 0;
4
+ const api_1 = require("@terreno/api");
5
+ const blocks_1 = require("@terreno/blocks");
6
+ const MESSAGE_INDEX_PATTERN = /^msg-(\d+)$/;
7
+ /**
8
+ * A `{v: 1, blocks}` document. Built by assignment so `v` stays the first key, which
9
+ * `validateBlocks` requires (`KEY_ORDER`).
10
+ */
11
+ const blocksDocument = (blocks) => {
12
+ const doc = { v: 1 };
13
+ doc.blocks = blocks;
14
+ return doc;
15
+ };
16
+ exports.blocksDocument = blocksDocument;
17
+ const isMapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
18
+ /** Depth-first search of a parsed document's blocks, including card and columns children. */
19
+ const findRawBlock = (blocks, type, blockId) => {
20
+ if (!Array.isArray(blocks)) {
21
+ return undefined;
22
+ }
23
+ for (const block of blocks) {
24
+ if (!isMapping(block)) {
25
+ continue;
26
+ }
27
+ if (block.type === type && block.id === blockId) {
28
+ return block;
29
+ }
30
+ const nested = findRawBlock(block.children, type, blockId);
31
+ if (nested !== undefined) {
32
+ return nested;
33
+ }
34
+ }
35
+ return undefined;
36
+ };
37
+ /**
38
+ * The block from one stored assistant prompt. The block is checked on its own, so a sibling
39
+ * that needs host options (html, https images) does not hide it.
40
+ */
41
+ const blockInPrompt = (prompt, type, blockId) => {
42
+ if (prompt?.type !== "assistant" || typeof prompt.text !== "string") {
43
+ return undefined;
44
+ }
45
+ const parsed = (0, blocks_1.parseBlocks)(prompt.text);
46
+ if (!parsed.ok || !isMapping(parsed.value)) {
47
+ return undefined;
48
+ }
49
+ const raw = findRawBlock(parsed.value.blocks, type, blockId);
50
+ if (raw === undefined) {
51
+ return undefined;
52
+ }
53
+ const validated = (0, blocks_1.validateBlocks)((0, exports.blocksDocument)([raw]));
54
+ if (!validated.ok) {
55
+ return undefined;
56
+ }
57
+ return validated.doc.blocks[0];
58
+ };
59
+ /**
60
+ * Loads the block the agent wrote, from the stored history rather than from the client.
61
+ * `msg-<n>` reads `history.prompts[n]` (stored prompts have no ids). Otherwise the only assistant
62
+ * prompt holding a block of that type and id is used: 409 when several do, 404 when none does.
63
+ */
64
+ const findAgentBlock = ({ blockId, history, messageId, type, }) => {
65
+ const indexMatch = MESSAGE_INDEX_PATTERN.exec(messageId);
66
+ if (indexMatch?.[1] !== undefined) {
67
+ const direct = blockInPrompt(history.prompts[Number(indexMatch[1])], type, blockId);
68
+ if (direct !== undefined) {
69
+ return direct;
70
+ }
71
+ }
72
+ const matches = history.prompts
73
+ .map((prompt) => blockInPrompt(prompt, type, blockId))
74
+ .filter((block) => block !== undefined);
75
+ if (matches.length > 1) {
76
+ throw new api_1.APIError({
77
+ detail: `${matches.length} replies hold a ${type} with id ${blockId}.`,
78
+ status: 409,
79
+ title: "Block is ambiguous",
80
+ });
81
+ }
82
+ const [only] = matches;
83
+ if (only === undefined) {
84
+ throw new api_1.APIError({
85
+ detail: `No reply holds a ${type} with id ${blockId}.`,
86
+ status: 404,
87
+ title: "Block not found",
88
+ });
89
+ }
90
+ return only;
91
+ };
92
+ exports.findAgentBlock = findAgentBlock;
@@ -116,7 +116,9 @@ export declare const runChatTurn: ({ body, options, req, sink, }: {
116
116
  /**
117
117
  * Runs a turn to completion and returns it as one JSON result, for clients that do not read
118
118
  * server-sent events. Nothing is written to the response while the turn runs, so a client that
119
- * disconnects does not stop it: the turn still finishes and saves.
119
+ * disconnects does not stop it: the turn still finishes and saves. Scripts that need a real turn
120
+ * without HTTP (such as a model smoke test) call it with the `req.user` and headers a route would
121
+ * pass, so the system prompt, tools, and block checks are the ones chat uses.
120
122
  */
121
123
  export declare const runBufferedChatTurn: ({ body, options, req, }: {
122
124
  body: Record<string, unknown> & {
@@ -756,14 +756,30 @@ const withTurnSystemPrompt = ({ askKinds, blocksPrompt, surface, systemPrompt, }
756
756
  }
757
757
  return [systemPrompt, ...sections].filter(Boolean).join("\n\n");
758
758
  };
759
- const checkBlockDocument = (text, hostActions, allowHtml, imageHosts) => {
759
+ /**
760
+ * The callback allowlists for validation and the prompt. Stepper and checklist callbacks must name
761
+ * an action that handles that block. With no `hostActions`, callback names are not checked.
762
+ */
763
+ const blockCallbackNames = (uiBlocks) => {
764
+ if (uiBlocks?.hostActions === undefined) {
765
+ return {};
766
+ }
767
+ const entries = Object.entries(uiBlocks.hostActions);
768
+ const handling = (block) => entries.filter(([, action]) => action.handles === block).map(([name]) => name);
769
+ return {
770
+ checklistActions: handling("checklist"),
771
+ hostActions: entries.map(([name]) => name),
772
+ stepperActions: handling("stepper"),
773
+ };
774
+ };
775
+ const checkBlockDocument = (text, callbackNames, allowHtml, imageHosts) => {
760
776
  const parsed = (0, blocks_1.parseBlocks)(text);
761
777
  if (!parsed.ok) {
762
778
  return { errors: parsed.errors, ok: false, warnings: [] };
763
779
  }
764
780
  const validated = (0, blocks_1.validateBlocks)(parsed.value, {
765
781
  ...(allowHtml ? { allowHtml: true } : {}),
766
- ...(hostActions ? { hostActions } : {}),
782
+ ...callbackNames,
767
783
  ...(imageHosts ? { imageHosts } : {}),
768
784
  });
769
785
  return {
@@ -1168,10 +1184,18 @@ const runChatTurn = async ({ body, options, req, sink, }) => {
1168
1184
  surface,
1169
1185
  });
1170
1186
  const uiBlocks = resolveUiBlocks(options.uiBlocks);
1187
+ const callbackNames = blockCallbackNames(uiBlocks);
1171
1188
  const system = withTurnSystemPrompt({
1172
1189
  askKinds: offeredAskKinds,
1173
1190
  blocksPrompt: uiBlocks
1174
- ? (0, prompts_1.uiBlocksSystemPrompt)(Object.keys(uiBlocks.hostActions ?? {}), uiBlocks.html === true, uiBlocks.imageHosts ?? [])
1191
+ ? (0, prompts_1.uiBlocksSystemPrompt)({
1192
+ allowHtml: uiBlocks.html === true,
1193
+ checklistActions: callbackNames.checklistActions,
1194
+ hostActions: callbackNames.hostActions ?? [],
1195
+ imageHosts: uiBlocks.imageHosts ?? [],
1196
+ richBlocks: uiBlocks.richBlocks !== false,
1197
+ stepperActions: callbackNames.stepperActions,
1198
+ })
1175
1199
  : undefined,
1176
1200
  surface,
1177
1201
  systemPrompt: effectiveSystemPrompt,
@@ -1420,7 +1444,6 @@ const runChatTurn = async ({ body, options, req, sink, }) => {
1420
1444
  const { askCalls, generatedImages } = record;
1421
1445
  let { fullResponse } = record;
1422
1446
  const streamedResponse = fullResponse;
1423
- const hostActionNames = uiBlocks?.hostActions === undefined ? undefined : Object.keys(uiBlocks.hostActions);
1424
1447
  const allowHtml = uiBlocks?.html === true;
1425
1448
  const imageHosts = uiBlocks?.imageHosts;
1426
1449
  if (uiBlocks && fullResponse.trim() !== "") {
@@ -1430,7 +1453,7 @@ const runChatTurn = async ({ body, options, req, sink, }) => {
1430
1453
  }
1431
1454
  }
1432
1455
  let blocksCheck = uiBlocks && fullResponse.trim() !== ""
1433
- ? checkBlockDocument(fullResponse, hostActionNames, allowHtml, imageHosts)
1456
+ ? checkBlockDocument(fullResponse, callbackNames, allowHtml, imageHosts)
1434
1457
  : undefined;
1435
1458
  let repaired = false;
1436
1459
  if (blocksCheck && !blocksCheck.ok && uiBlocks?.repair === true) {
@@ -1442,14 +1465,14 @@ const runChatTurn = async ({ body, options, req, sink, }) => {
1442
1465
  if (next !== undefined) {
1443
1466
  fullResponse = next;
1444
1467
  repaired = true;
1445
- blocksCheck = checkBlockDocument(fullResponse, hostActionNames, allowHtml, imageHosts);
1468
+ blocksCheck = checkBlockDocument(fullResponse, callbackNames, allowHtml, imageHosts);
1446
1469
  }
1447
1470
  }
1448
1471
  if (allowHtml && blocksCheck?.ok) {
1449
1472
  const sanitized = (0, sanitizeHtml_1.sanitizeBlocksText)(fullResponse);
1450
1473
  if (sanitized.changed) {
1451
1474
  fullResponse = sanitized.text;
1452
- blocksCheck = checkBlockDocument(fullResponse, hostActionNames, allowHtml, imageHosts);
1475
+ blocksCheck = checkBlockDocument(fullResponse, callbackNames, allowHtml, imageHosts);
1453
1476
  }
1454
1477
  }
1455
1478
  const storedResponse = blocksCheck && !blocksCheck.ok
@@ -1630,7 +1653,9 @@ exports.runChatTurn = runChatTurn;
1630
1653
  /**
1631
1654
  * Runs a turn to completion and returns it as one JSON result, for clients that do not read
1632
1655
  * server-sent events. Nothing is written to the response while the turn runs, so a client that
1633
- * disconnects does not stop it: the turn still finishes and saves.
1656
+ * disconnects does not stop it: the turn still finishes and saves. Scripts that need a real turn
1657
+ * without HTTP (such as a model smoke test) call it with the `req.user` and headers a route would
1658
+ * pass, so the system prompt, tools, and block checks are the ones chat uses.
1634
1659
  */
1635
1660
  const runBufferedChatTurn = async ({ body, options, req, }) => {
1636
1661
  const turn = { errors: [], texts: [] };
@@ -5,8 +5,18 @@
5
5
  export declare const TERRENO_UI_BLOCKS_SYSTEM_PROMPT: string;
6
6
  /** Tells the model to return only a corrected document. The failed document and its errors are the user prompt. */
7
7
  export declare const UI_BLOCKS_REPAIR_SYSTEM_PROMPT = "The document you wrote failed validation. Reply with only the corrected document. Do not explain the changes.";
8
- /** The blocks prompt for this host's callback names. */
9
- export declare const uiBlocksSystemPrompt: (hostActions: readonly string[], allowHtml?: boolean, imageHosts?: readonly string[]) => string;
8
+ /**
9
+ * The blocks prompt for this host's callbacks, html and image settings, and rich-block opt-out.
10
+ * Runtime values are injected here because they are host configuration, not user data.
11
+ */
12
+ export declare const uiBlocksSystemPrompt: ({ allowHtml, checklistActions, hostActions, imageHosts, richBlocks, stepperActions, }: {
13
+ allowHtml?: boolean;
14
+ checklistActions?: readonly string[];
15
+ hostActions: readonly string[];
16
+ imageHosts?: readonly string[];
17
+ richBlocks?: boolean;
18
+ stepperActions?: readonly string[];
19
+ }) => string;
10
20
  /**
11
21
  * Appended to the chat system prompt when a route enables asks. The enabled ask tools and their
12
22
  * limits follow it at call time (`askPromptSection` from @terreno/blocks), so the numbers stay in
@@ -9,12 +9,28 @@ const blocks_1 = require("@terreno/blocks");
9
9
  exports.TERRENO_UI_BLOCKS_SYSTEM_PROMPT = (0, blocks_1.blocksPromptSection)();
10
10
  /** Tells the model to return only a corrected document. The failed document and its errors are the user prompt. */
11
11
  exports.UI_BLOCKS_REPAIR_SYSTEM_PROMPT = "The document you wrote failed validation. Reply with only the corrected document. Do not explain the changes.";
12
- /** The blocks prompt for this host's callback names. */
13
- const uiBlocksSystemPrompt = (hostActions, allowHtml = false, imageHosts = []) => {
14
- if (hostActions.length === 0 && !allowHtml && imageHosts.length === 0) {
12
+ /**
13
+ * The blocks prompt for this host's callbacks, html and image settings, and rich-block opt-out.
14
+ * Runtime values are injected here because they are host configuration, not user data.
15
+ */
16
+ const uiBlocksSystemPrompt = ({ allowHtml = false, checklistActions = [], hostActions, imageHosts = [], richBlocks = true, stepperActions = [], }) => {
17
+ const isDefault = richBlocks &&
18
+ hostActions.length === 0 &&
19
+ !allowHtml &&
20
+ imageHosts.length === 0 &&
21
+ stepperActions.length === 0 &&
22
+ checklistActions.length === 0;
23
+ if (isDefault) {
15
24
  return exports.TERRENO_UI_BLOCKS_SYSTEM_PROMPT;
16
25
  }
17
- return (0, blocks_1.blocksPromptSection)({ allowHtml, hostActions, imageHosts });
26
+ return (0, blocks_1.blocksPromptSection)({
27
+ allowHtml,
28
+ checklistActions,
29
+ hostActions,
30
+ imageHosts,
31
+ richBlocks,
32
+ stepperActions,
33
+ });
18
34
  };
19
35
  exports.uiBlocksSystemPrompt = uiBlocksSystemPrompt;
20
36
  /**
@@ -0,0 +1,8 @@
1
+ import type { HostAction } from "../types";
2
+ /**
3
+ * Opt-in `stepper` host action. Register it as `uiBlocks.hostActions.scaleStepper`. It reads the
4
+ * stepper the agent wrote from the stored history and scales every item linearly from it, so
5
+ * rounding never drifts tap after tap. Stored prompts are owner-writable: an app whose numbers
6
+ * matter (prices, stock) should register its own `handles: "stepper"` action over its own data.
7
+ */
8
+ export declare const scaleStepperHostAction: HostAction;
@@ -0,0 +1,29 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.scaleStepperHostAction = void 0;
4
+ const api_1 = require("@terreno/api");
5
+ const blocks_1 = require("@terreno/blocks");
6
+ const agentBlocks_1 = require("./agentBlocks");
7
+ /**
8
+ * Opt-in `stepper` host action. Register it as `uiBlocks.hostActions.scaleStepper`. It reads the
9
+ * stepper the agent wrote from the stored history and scales every item linearly from it, so
10
+ * rounding never drifts tap after tap. Stored prompts are owner-writable: an app whose numbers
11
+ * matter (prices, stock) should register its own `handles: "stepper"` action over its own data.
12
+ */
13
+ exports.scaleStepperHostAction = {
14
+ handler: ({ blockId, history, messageId, payload }) => {
15
+ const { value } = payload;
16
+ const stepper = (0, agentBlocks_1.findAgentBlock)({ blockId, history, messageId, type: "stepper" });
17
+ if (!(0, blocks_1.isStepperValueAllowed)(stepper, value)) {
18
+ throw new api_1.APIError({
19
+ detail: `value must be between ${stepper.min} and ${stepper.max} in steps of ${stepper.step ?? 1} from ${stepper.value}.`,
20
+ status: 400,
21
+ title: "Invalid stepper value",
22
+ });
23
+ }
24
+ return { blocks: (0, agentBlocks_1.blocksDocument)([(0, blocks_1.scaleStepperBlock)(stepper, value)]), replace: "block" };
25
+ },
26
+ handles: "stepper",
27
+ logResponse: false,
28
+ payload: api_1.z.object({ value: api_1.z.number() }).passthrough(),
29
+ };
@@ -0,0 +1,9 @@
1
+ import type { HostAction } from "../types";
2
+ /**
3
+ * Opt-in `checklist` host action. Register it as `uiBlocks.hostActions.toggleChecklist`. It reads
4
+ * the checklist the agent wrote from the stored history and returns it with every item's
5
+ * `checked` taken from `state`. An item missing from `state` is unchecked, and the ticked item
6
+ * always takes `checked`. Nothing is saved: an app that records progress should register its own
7
+ * `handles: "checklist"` action.
8
+ */
9
+ export declare const toggleChecklistHostAction: HostAction;
@@ -0,0 +1,37 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.toggleChecklistHostAction = void 0;
4
+ const api_1 = require("@terreno/api");
5
+ const blocks_1 = require("@terreno/blocks");
6
+ const agentBlocks_1 = require("./agentBlocks");
7
+ const unknownItemError = (itemIds, checklist) => new api_1.APIError({
8
+ detail: `${checklist.id} has no item ${itemIds.join(", ")}. Its items are ${checklist.items
9
+ .map((item) => item.id)
10
+ .join(", ")}.`,
11
+ status: 400,
12
+ title: "Unknown checklist item",
13
+ });
14
+ /**
15
+ * Opt-in `checklist` host action. Register it as `uiBlocks.hostActions.toggleChecklist`. It reads
16
+ * the checklist the agent wrote from the stored history and returns it with every item's
17
+ * `checked` taken from `state`. An item missing from `state` is unchecked, and the ticked item
18
+ * always takes `checked`. Nothing is saved: an app that records progress should register its own
19
+ * `handles: "checklist"` action.
20
+ */
21
+ exports.toggleChecklistHostAction = {
22
+ handler: ({ blockId, history, messageId, payload }) => {
23
+ const tick = payload;
24
+ const checklist = (0, agentBlocks_1.findAgentBlock)({ blockId, history, messageId, type: "checklist" });
25
+ const unknownIds = (0, blocks_1.unknownChecklistItemIds)(checklist, tick);
26
+ if (unknownIds.length > 0) {
27
+ throw unknownItemError(unknownIds, checklist);
28
+ }
29
+ const ticked = (0, blocks_1.applyChecklistState)(checklist, tick);
30
+ return { blocks: (0, agentBlocks_1.blocksDocument)([ticked]), replace: "block" };
31
+ },
32
+ handles: "checklist",
33
+ logResponse: false,
34
+ payload: api_1.z
35
+ .object({ checked: api_1.z.boolean(), itemId: api_1.z.string(), state: api_1.z.record(api_1.z.string(), api_1.z.boolean()) })
36
+ .passthrough(),
37
+ };
@@ -314,6 +314,18 @@ export interface HostActionContext {
314
314
  _id?: mongoose.Types.ObjectId;
315
315
  };
316
316
  }
317
+ /** One host callback that `POST /gpt/actions` runs for a block button. */
318
+ export interface HostAction {
319
+ handler?: (context: HostActionContext) => Promise<HostActionResult | undefined> | HostActionResult | undefined;
320
+ /** The interactive block this action serves. `scaleStepperHostAction` sets `stepper`. */
321
+ handles?: "stepper" | "checklist";
322
+ /**
323
+ * When `false`, the `ui_action` `AIRequest` row keeps the ids-only prompt plus a numeric
324
+ * `payload.value`, and leaves out the returned document. Default `true` logs the response.
325
+ */
326
+ logResponse?: boolean;
327
+ payload?: HostPayloadSchema;
328
+ }
317
329
  /** `addGptRoutes` `uiBlocks`. `true` checks every assistant reply. `hostActions` names the callbacks the model may emit. */
318
330
  export interface UiBlocksOptions {
319
331
  /** Milliseconds before a host callback returns 504. Default 10 seconds. */
@@ -326,11 +338,14 @@ export interface UiBlocksOptions {
326
338
  html?: boolean;
327
339
  /** Hostnames allowed on `https` image sources. Empty rejects every https image. */
328
340
  imageHosts?: readonly string[];
329
- hostActions?: Record<string, {
330
- handler?: (context: HostActionContext) => Promise<HostActionResult | undefined> | HostActionResult | undefined;
331
- payload?: HostPayloadSchema;
332
- }>;
341
+ hostActions?: Record<string, HostAction>;
333
342
  repair?: boolean;
343
+ /**
344
+ * Default `true`: the prompt offers the rich blocks, and the stepper when a host action has
345
+ * `handles: "stepper"`. `false` keeps the prompt as it was before them, for clients that cannot
346
+ * render them yet. Validation accepts the rich blocks either way.
347
+ */
348
+ richBlocks?: boolean;
334
349
  }
335
350
  export interface GptRouteOptions {
336
351
  /** Pre-configured AIService. Optional when using per-request keys or demo mode. */
package/package.json CHANGED
@@ -10,7 +10,7 @@
10
10
  "@langfuse/otel": "^5.0.1",
11
11
  "@opentelemetry/api": "^1.9.0",
12
12
  "@opentelemetry/sdk-node": "0.217.0",
13
- "@terreno/blocks": "57.12.0",
13
+ "@terreno/blocks": "57.14.0",
14
14
  "ai": "^6.0.97",
15
15
  "ajv": "8.20.0",
16
16
  "csv-parse": "^6.1.0",
@@ -22,10 +22,10 @@
22
22
  "description": "Provider-agnostic AI service with streaming chat, request logging, and admin tools — part of Terreno, the batteries-included TypeScript framework for universal apps.",
23
23
  "devDependencies": {
24
24
  "@biomejs/biome": "^2.3.6",
25
- "@terreno/admin-backend": "57.12.0",
26
- "@terreno/api": "57.12.0",
27
- "@terreno/jobs": "57.12.0",
28
- "@terreno/test": "57.12.0",
25
+ "@terreno/admin-backend": "57.14.0",
26
+ "@terreno/api": "57.14.0",
27
+ "@terreno/jobs": "57.14.0",
28
+ "@terreno/test": "57.14.0",
29
29
  "@types/bun": "^1.4.0",
30
30
  "@types/express": "^5.0.6",
31
31
  "@types/luxon": "^3.7.1",
@@ -136,8 +136,8 @@
136
136
  "name": "@terreno/ai",
137
137
  "peerDependencies": {
138
138
  "@ai-sdk/google-vertex": "^4.0.142",
139
- "@terreno/api": "57.12.0",
140
- "@terreno/jobs": "57.12.0",
139
+ "@terreno/api": "57.14.0",
140
+ "@terreno/jobs": "57.14.0",
141
141
  "mongoose": "^8.0.0 || ^9.0.0"
142
142
  },
143
143
  "peerDependenciesMeta": {
@@ -168,5 +168,5 @@
168
168
  "test:coverage": "bun run ../scripts/check-coverage.ts"
169
169
  },
170
170
  "types": "dist/index.d.ts",
171
- "version": "57.12.0"
171
+ "version": "57.14.0"
172
172
  }
package/src/index.test.ts CHANGED
@@ -23,6 +23,7 @@ describe("@terreno/ai public exports", () => {
23
23
  "createPrompt",
24
24
  "createTelemetryConfig",
25
25
  "createVertexProvider",
26
+ "findAgentBlock",
26
27
  "getCached",
27
28
  "getMCPTools",
28
29
  "getLangfuseClient",
@@ -44,6 +45,7 @@ describe("@terreno/ai public exports", () => {
44
45
  "getObservabilityApp",
45
46
  "resetObservabilityApp",
46
47
  "resolveObservabilityControl",
48
+ "runBufferedChatTurn",
47
49
  "validateObservabilityConfig",
48
50
  "setCached",
49
51
  "shutdownLangfuseClient",
@@ -78,7 +80,9 @@ describe("@terreno/ai public exports", () => {
78
80
  "Output",
79
81
  "REMIX_PROMPT",
80
82
  "TERRENO_ASKS_SYSTEM_PROMPT",
83
+ "scaleStepperHostAction",
81
84
  "TITLE_GENERATION_PROMPT",
85
+ "toggleChecklistHostAction",
82
86
  "TRANSLATION_PROMPT",
83
87
  "TemperaturePresets",
84
88
  ] as const;
package/src/index.ts CHANGED
@@ -103,10 +103,12 @@ export {addGptRoutes} from "./routes/gpt";
103
103
  export {addGptHistoryRoutes} from "./routes/gptHistories";
104
104
  export {addMcpRoutes} from "./routes/mcp";
105
105
  export {addProjectRoutes} from "./routes/projects";
106
+ export {findAgentBlock} from "./service/agentBlocks";
106
107
  export type {RegisteredDataset} from "./service/aiDatasets";
107
108
  export {configureAiDatasets, registerAiDataset} from "./service/aiDatasets";
108
109
  export {AIService, TemperaturePresets} from "./service/aiService";
109
110
  export {createAskTools} from "./service/asks";
111
+ export {runBufferedChatTurn} from "./service/chatTurn";
110
112
  export {FileStorageService} from "./service/fileStorage";
111
113
  export type {ListGeminiApiModelsOptions} from "./service/gemini";
112
114
  export {
@@ -131,6 +133,8 @@ export {
131
133
  TITLE_GENERATION_PROMPT,
132
134
  TRANSLATION_PROMPT,
133
135
  } from "./service/prompts";
136
+ export {scaleStepperHostAction} from "./service/scaleStepper";
137
+ export {toggleChecklistHostAction} from "./service/toggleChecklist";
134
138
  export type {
135
139
  CreateVertexProviderOptions,
136
140
  ListEnabledVertexModelsOptions,