@terreno/ai 57.11.0 → 57.13.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.
Files changed (69) hide show
  1. package/dist/aiApp.d.ts +5 -0
  2. package/dist/aiApp.js +4 -2
  3. package/dist/harness/commit.d.ts +17 -1
  4. package/dist/harness/commit.js +86 -2
  5. package/dist/harness/routes/approvals.js +2 -2
  6. package/dist/harness/routes/conversations.js +1 -1
  7. package/dist/harness/routes/tasks.js +85 -3
  8. package/dist/harness/runtime.js +7 -1
  9. package/dist/harness/subagent.d.ts +17 -2
  10. package/dist/harness/subagent.js +26 -2
  11. package/dist/index.d.ts +5 -1
  12. package/dist/index.js +11 -2
  13. package/dist/models/project.d.ts +13 -0
  14. package/dist/models/project.js +32 -2
  15. package/dist/observability/local/models/obsTrace.js +16 -2
  16. package/dist/observability/local/traceStore.d.ts +5 -0
  17. package/dist/observability/local/traceStore.js +5 -0
  18. package/dist/observability/routes/traces.js +2 -0
  19. package/dist/routes/gptActions.js +15 -2
  20. package/dist/routes/projects.js +3 -3
  21. package/dist/service/agentBlocks.d.ts +20 -0
  22. package/dist/service/agentBlocks.js +92 -0
  23. package/dist/service/chatTurn.d.ts +3 -1
  24. package/dist/service/chatTurn.js +34 -9
  25. package/dist/service/prompts.d.ts +12 -2
  26. package/dist/service/prompts.js +20 -4
  27. package/dist/service/scaleStepper.d.ts +8 -0
  28. package/dist/service/scaleStepper.js +29 -0
  29. package/dist/service/toggleChecklist.d.ts +9 -0
  30. package/dist/service/toggleChecklist.js +37 -0
  31. package/dist/types/harness.d.ts +28 -2
  32. package/dist/types/index.d.ts +19 -4
  33. package/dist/types/observability.d.ts +3 -0
  34. package/package.json +56 -8
  35. package/src/aiApp.test.ts +15 -0
  36. package/src/aiApp.ts +9 -1
  37. package/src/harness/commit.ts +103 -1
  38. package/src/harness/routes/approvals.ts +2 -2
  39. package/src/harness/routes/conversations.ts +1 -1
  40. package/src/harness/routes/tasks.test.ts +34 -0
  41. package/src/harness/routes/tasks.ts +98 -3
  42. package/src/harness/runtime.ts +8 -1
  43. package/src/harness/subagent.test.ts +124 -3
  44. package/src/harness/subagent.ts +43 -1
  45. package/src/index.test.ts +4 -0
  46. package/src/index.ts +5 -1
  47. package/src/isolated/lazyProjectModel.isolated.ts +25 -0
  48. package/src/models/project.ts +31 -1
  49. package/src/observability/local/models/obsTrace.ts +22 -5
  50. package/src/observability/local/traceStore.test.ts +7 -0
  51. package/src/observability/local/traceStore.ts +12 -0
  52. package/src/observability/routes/traces.test.ts +15 -0
  53. package/src/observability/routes/traces.ts +2 -0
  54. package/src/routes/gpt.test.ts +90 -1
  55. package/src/routes/gptActions.test.ts +282 -1
  56. package/src/routes/gptActions.ts +16 -2
  57. package/src/routes/projects.ts +4 -4
  58. package/src/service/agentBlocks.test.ts +95 -0
  59. package/src/service/agentBlocks.ts +114 -0
  60. package/src/service/chatTurn.ts +44 -15
  61. package/src/service/prompts.test.ts +21 -0
  62. package/src/service/prompts.ts +34 -7
  63. package/src/service/scaleStepper.test.ts +105 -0
  64. package/src/service/scaleStepper.ts +29 -0
  65. package/src/service/toggleChecklist.test.ts +126 -0
  66. package/src/service/toggleChecklist.ts +44 -0
  67. package/src/types/harness.ts +31 -2
  68. package/src/types/index.ts +22 -9
  69. package/src/types/observability.ts +3 -0
@@ -24,13 +24,18 @@ const obsTraceSchema = new mongoose_1.default.Schema({
24
24
  default: [],
25
25
  description: "Prompt versions used during this trace",
26
26
  type: [
27
- {
27
+ // No subdocument _id, so `$addToSet` dedupes repeated refs from replayed phases.
28
+ new mongoose_1.default.Schema({
28
29
  label: { description: "Label resolved at call time", type: String },
29
30
  name: { description: "Prompt name", required: true, type: String },
30
31
  version: { description: "Prompt version number", required: true, type: Number },
31
- },
32
+ }, { _id: false }),
32
33
  ],
33
34
  },
35
+ scope: {
36
+ description: "App-defined scope (tenant, workspace) for metering and filtering traces",
37
+ type: String,
38
+ },
34
39
  sensitive: {
35
40
  default: false,
36
41
  description: "When true, admin I/O disclosures start collapsed",
@@ -44,6 +49,11 @@ const obsTraceSchema = new mongoose_1.default.Schema({
44
49
  required: true,
45
50
  type: String,
46
51
  },
52
+ tags: {
53
+ default: [],
54
+ description: "App-defined labels for grouping traces",
55
+ type: [String],
56
+ },
47
57
  usage: {
48
58
  description: "Aggregated token and cost usage for the trace",
49
59
  type: mongoose_1.default.Schema.Types.Mixed,
@@ -80,6 +90,10 @@ const traceIndexSpecs = [
80
90
  ["flaggedForDataset", 1],
81
91
  ["created", -1],
82
92
  ],
93
+ [
94
+ ["scope", 1],
95
+ ["created", -1],
96
+ ],
83
97
  ];
84
98
  for (const spec of traceIndexSpecs) {
85
99
  obsTraceSchema.index(Object.fromEntries(spec));
@@ -7,6 +7,7 @@ export interface TraceListQuery {
7
7
  page?: number;
8
8
  prompt?: string;
9
9
  promptVersion?: number;
10
+ scope?: string;
10
11
  sensitive?: boolean;
11
12
  sessionId?: string;
12
13
  status?: "error" | "ok";
@@ -39,12 +40,14 @@ export interface TraceDetail {
39
40
  name: string;
40
41
  output?: unknown;
41
42
  prompts: TraceRecord["prompts"];
43
+ scope?: string;
42
44
  scores: ScoreRecord[];
43
45
  sensitive: boolean;
44
46
  sessionId?: string;
45
47
  spans: TraceSpanNode[];
46
48
  startedAt: string;
47
49
  status: "error" | "ok";
50
+ tags: string[];
48
51
  usage?: TraceRecord["usage"];
49
52
  userId?: string;
50
53
  }
@@ -55,12 +58,14 @@ export interface TraceListItem {
55
58
  id: string;
56
59
  name: string;
57
60
  prompts: TraceRecord["prompts"];
61
+ scope?: string;
58
62
  scoreCount: number;
59
63
  sensitive: boolean;
60
64
  sessionId?: string;
61
65
  spanCount: number;
62
66
  startedAt: string;
63
67
  status: "error" | "ok";
68
+ tags: string[];
64
69
  usage?: TraceRecord["usage"];
65
70
  userId?: string;
66
71
  }
@@ -140,6 +140,9 @@ class LocalTraceStore {
140
140
  if (query.sessionId) {
141
141
  filter.sessionId = query.sessionId;
142
142
  }
143
+ if (query.scope) {
144
+ filter.scope = query.scope;
145
+ }
143
146
  if (query.promptVersion !== undefined && !query.prompt) {
144
147
  throw new api_1.APIError({ status: 400, title: "prompt is required when promptVersion is set" });
145
148
  }
@@ -243,12 +246,14 @@ class LocalTraceStore {
243
246
  id: String(row._id),
244
247
  name: row.name,
245
248
  prompts: row.prompts,
249
+ scope: row.scope,
246
250
  scoreCount: counts.scoreCount,
247
251
  sensitive: row.sensitive,
248
252
  sessionId: row.sessionId,
249
253
  spanCount: counts.spanCount,
250
254
  startedAt: toIso(row.startedAt) ?? "",
251
255
  status: row.status,
256
+ tags: row.tags ?? [],
252
257
  usage: usageWithoutUndefinedCost(row.usage),
253
258
  userId: row.userId ? String(row.userId) : undefined,
254
259
  };
@@ -50,6 +50,7 @@ const addObservabilityTraceRoutes = (router, options) => {
50
50
  .withSummary("List observability traces")
51
51
  .withQueryParameter("prompt", { type: "string" }, { required: false })
52
52
  .withQueryParameter("promptVersion", { type: "number" }, { required: false })
53
+ .withQueryParameter("scope", { type: "string" }, { required: false })
53
54
  .withResponse(200, { data: { type: "array" } })
54
55
  .build()), (0, api_1.asyncHandler)(async (req, res) => {
55
56
  const prompt = typeof req.query.prompt === "string" ? req.query.prompt : undefined;
@@ -61,6 +62,7 @@ const addObservabilityTraceRoutes = (router, options) => {
61
62
  page: parsePositiveInt(req.query.page, 1),
62
63
  prompt,
63
64
  promptVersion: parsePromptVersion(req.query.promptVersion, prompt),
65
+ scope: typeof req.query.scope === "string" ? req.query.scope : undefined,
64
66
  sensitive: parseBoolean(req.query.sensitive),
65
67
  sessionId: typeof req.query.sessionId === "string" ? req.query.sessionId : undefined,
66
68
  status: req.query.status === "ok" || req.query.status === "error" ? req.query.status : undefined,
@@ -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
  });
@@ -24,7 +24,7 @@ const addProjectRoutes = (router, options) => {
24
24
  if (!text || typeof text !== "string") {
25
25
  throw new api_1.APIError({ status: 400, title: "text is required" });
26
26
  }
27
- const project = await project_1.Project.findById(id);
27
+ const project = await (0, project_1.getProjectModel)().findById(id);
28
28
  if (!project) {
29
29
  throw new api_1.APIError({ status: 404, title: "Project not found" });
30
30
  }
@@ -48,7 +48,7 @@ const addProjectRoutes = (router, options) => {
48
48
  ], (0, api_1.asyncHandler)(async (req, res) => {
49
49
  const { id, memoryId } = req.params;
50
50
  const userId = req.user?._id;
51
- const project = await project_1.Project.findById(id);
51
+ const project = await (0, project_1.getProjectModel)().findById(id);
52
52
  if (!project) {
53
53
  throw new api_1.APIError({ status: 404, title: "Project not found" });
54
54
  }
@@ -63,7 +63,7 @@ const addProjectRoutes = (router, options) => {
63
63
  await project.save();
64
64
  return res.json({ data: { deleted: true } });
65
65
  }));
66
- router.use("/gpt/projects", (0, api_1.modelRouter)(project_1.Project, {
66
+ router.use("/gpt/projects", (0, api_1.modelRouter)((0, project_1.getProjectModel)(), {
67
67
  ...options?.openApiOptions,
68
68
  permissions: {
69
69
  create: [api_1.Permissions.IsAuthenticated],
@@ -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> & {
@@ -670,7 +670,7 @@ const buildSystemPrompt = async ({ history, options, projectId, systemPrompt, us
670
670
  let effectiveSystemPrompt = systemPrompt;
671
671
  if (effectiveProjectId) {
672
672
  try {
673
- const project = await project_1.Project.findById(effectiveProjectId);
673
+ const project = await (0, project_1.getProjectModel)().findById(effectiveProjectId);
674
674
  if (project && project.userId.toString() === userId?.toString()) {
675
675
  const parts = [];
676
676
  if (project.systemContext) {
@@ -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
+ };
@@ -3,6 +3,23 @@ import type { LanguageModel, ModelMessage } from "ai";
3
3
  import type { Duration, DurationLike } from "luxon";
4
4
  import type mongoose from "mongoose";
5
5
  import type { ExecutionEnv } from "../harness/executionEnv";
6
+ import type { ObsPromptRef } from "./observability";
7
+ /**
8
+ * A prompt version a task used, recorded on its `ObsTrace.prompts`. A `PromptVersionRef`
9
+ * from `promptRegistry.get` fits as-is; its `body` is ignored.
10
+ */
11
+ export type HarnessPromptRef = ObsPromptRef;
12
+ /** A registry prompt passed as instructions: its `body` is used and its version recorded. */
13
+ export interface HarnessPromptInstructions extends HarnessPromptRef {
14
+ body: string;
15
+ }
16
+ /** Fields written onto the task's `ObsTrace`, shared by every child task and subagent. */
17
+ export interface HarnessTraceOptions {
18
+ /** App-defined scope (tenant, workspace) for metering; indexed with `created`. */
19
+ scope?: string;
20
+ /** App-defined labels for grouping traces. */
21
+ tags?: string[];
22
+ }
6
23
  /** Every lifecycle status a harness task can hold. */
7
24
  export declare const HARNESS_TASK_STATUSES: {
8
25
  readonly aborted: "aborted";
@@ -319,8 +336,13 @@ export interface HarnessMemo {
319
336
  export interface HarnessRunAgentOptions<Result> {
320
337
  /** The subagent's user message. A non-string value is sent as JSON. */
321
338
  input: unknown;
322
- /** Replaces the agent's instructions for this subagent conversation only. */
323
- instructions?: string;
339
+ /**
340
+ * Replaces the agent's instructions for this subagent conversation only. A registry
341
+ * prompt (`promptRegistry.get`) is used by its `body` and recorded on the trace.
342
+ */
343
+ instructions?: HarnessPromptInstructions | string;
344
+ /** Prompt versions this subagent used, recorded on the task's `ObsTrace.prompts`. */
345
+ prompts?: HarnessPromptRef[];
324
346
  /**
325
347
  * Structured output schema; defaults to the agent's own `output`. Requested through the
326
348
  * AI SDK's `Output.object`, then validated with this schema before it is returned.
@@ -383,8 +405,12 @@ export interface HarnessAbortOptions {
383
405
  userId?: mongoose.Types.ObjectId | string;
384
406
  }
385
407
  export interface HarnessCreateTaskOptions {
408
+ /** Prompt versions the task uses, recorded on its `ObsTrace.prompts`. */
409
+ prompts?: HarnessPromptRef[];
386
410
  /** Idempotency key: a second create with the same id returns the existing task. */
387
411
  requestId?: string;
412
+ /** Scope and tags for the task's `ObsTrace`; child tasks and subagents share it. */
413
+ trace?: HarnessTraceOptions;
388
414
  userId?: mongoose.Types.ObjectId | string;
389
415
  }
390
416
  /** How an interrupted task is resolved by an operator. */
@@ -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. */