@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
@@ -27,7 +27,7 @@ import type mongoose from "mongoose";
27
27
  import {createTelemetryConfig, preparePromptForAI} from "../langfuseVercelAi";
28
28
  import {AIRequest} from "../models/aiRequest";
29
29
  import {GptHistory} from "../models/gptHistory";
30
- import {Project} from "../models/project";
30
+ import {getProjectModel} from "../models/project";
31
31
  import type {SpanRecord} from "../observability/types";
32
32
  import type {
33
33
  AskOrigin,
@@ -36,6 +36,7 @@ import type {
36
36
  GptHistoryPendingAsk,
37
37
  GptHistoryPrompt,
38
38
  GptRouteOptions,
39
+ HostAction,
39
40
  MessageContentPart,
40
41
  UiBlocksOptions,
41
42
  } from "../types";
@@ -1120,7 +1121,7 @@ const buildSystemPrompt = async ({
1120
1121
  let effectiveSystemPrompt = systemPrompt as string | undefined;
1121
1122
  if (effectiveProjectId) {
1122
1123
  try {
1123
- const project = await Project.findById(effectiveProjectId);
1124
+ const project = await getProjectModel().findById(effectiveProjectId);
1124
1125
  if (project && project.userId.toString() === userId?.toString()) {
1125
1126
  const parts: string[] = [];
1126
1127
  if (project.systemContext) {
@@ -1233,9 +1234,33 @@ const withTurnSystemPrompt = ({
1233
1234
  return [systemPrompt, ...sections].filter(Boolean).join("\n\n");
1234
1235
  };
1235
1236
 
1237
+ interface BlockCallbackNames {
1238
+ checklistActions?: readonly string[];
1239
+ hostActions?: readonly string[];
1240
+ stepperActions?: readonly string[];
1241
+ }
1242
+
1243
+ /**
1244
+ * The callback allowlists for validation and the prompt. Stepper and checklist callbacks must name
1245
+ * an action that handles that block. With no `hostActions`, callback names are not checked.
1246
+ */
1247
+ const blockCallbackNames = (uiBlocks: UiBlocksOptions | undefined): BlockCallbackNames => {
1248
+ if (uiBlocks?.hostActions === undefined) {
1249
+ return {};
1250
+ }
1251
+ const entries = Object.entries(uiBlocks.hostActions);
1252
+ const handling = (block: HostAction["handles"]): string[] =>
1253
+ entries.filter(([, action]) => action.handles === block).map(([name]) => name);
1254
+ return {
1255
+ checklistActions: handling("checklist"),
1256
+ hostActions: entries.map(([name]) => name),
1257
+ stepperActions: handling("stepper"),
1258
+ };
1259
+ };
1260
+
1236
1261
  const checkBlockDocument = (
1237
1262
  text: string,
1238
- hostActions: readonly string[] | undefined,
1263
+ callbackNames: BlockCallbackNames,
1239
1264
  allowHtml: boolean,
1240
1265
  imageHosts?: readonly string[]
1241
1266
  ): {errors: BlockError[]; ok: boolean; warnings: BlockError[]} => {
@@ -1245,7 +1270,7 @@ const checkBlockDocument = (
1245
1270
  }
1246
1271
  const validated = validateBlocks(parsed.value, {
1247
1272
  ...(allowHtml ? {allowHtml: true} : {}),
1248
- ...(hostActions ? {hostActions} : {}),
1273
+ ...callbackNames,
1249
1274
  ...(imageHosts ? {imageHosts} : {}),
1250
1275
  });
1251
1276
  return {
@@ -1736,14 +1761,18 @@ export const runChatTurn = async ({
1736
1761
  surface,
1737
1762
  });
1738
1763
  const uiBlocks = resolveUiBlocks(options.uiBlocks);
1764
+ const callbackNames = blockCallbackNames(uiBlocks);
1739
1765
  const system = withTurnSystemPrompt({
1740
1766
  askKinds: offeredAskKinds,
1741
1767
  blocksPrompt: uiBlocks
1742
- ? uiBlocksSystemPrompt(
1743
- Object.keys(uiBlocks.hostActions ?? {}),
1744
- uiBlocks.html === true,
1745
- uiBlocks.imageHosts ?? []
1746
- )
1768
+ ? uiBlocksSystemPrompt({
1769
+ allowHtml: uiBlocks.html === true,
1770
+ checklistActions: callbackNames.checklistActions,
1771
+ hostActions: callbackNames.hostActions ?? [],
1772
+ imageHosts: uiBlocks.imageHosts ?? [],
1773
+ richBlocks: uiBlocks.richBlocks !== false,
1774
+ stepperActions: callbackNames.stepperActions,
1775
+ })
1747
1776
  : undefined,
1748
1777
  surface,
1749
1778
  systemPrompt: effectiveSystemPrompt,
@@ -2009,8 +2038,6 @@ export const runChatTurn = async ({
2009
2038
  const {askCalls, generatedImages} = record;
2010
2039
  let {fullResponse} = record;
2011
2040
  const streamedResponse = fullResponse;
2012
- const hostActionNames =
2013
- uiBlocks?.hostActions === undefined ? undefined : Object.keys(uiBlocks.hostActions);
2014
2041
  const allowHtml = uiBlocks?.html === true;
2015
2042
  const imageHosts = uiBlocks?.imageHosts;
2016
2043
  if (uiBlocks && fullResponse.trim() !== "") {
@@ -2021,7 +2048,7 @@ export const runChatTurn = async ({
2021
2048
  }
2022
2049
  let blocksCheck =
2023
2050
  uiBlocks && fullResponse.trim() !== ""
2024
- ? checkBlockDocument(fullResponse, hostActionNames, allowHtml, imageHosts)
2051
+ ? checkBlockDocument(fullResponse, callbackNames, allowHtml, imageHosts)
2025
2052
  : undefined;
2026
2053
  let repaired = false;
2027
2054
  if (blocksCheck && !blocksCheck.ok && uiBlocks?.repair === true) {
@@ -2033,14 +2060,14 @@ export const runChatTurn = async ({
2033
2060
  if (next !== undefined) {
2034
2061
  fullResponse = next;
2035
2062
  repaired = true;
2036
- blocksCheck = checkBlockDocument(fullResponse, hostActionNames, allowHtml, imageHosts);
2063
+ blocksCheck = checkBlockDocument(fullResponse, callbackNames, allowHtml, imageHosts);
2037
2064
  }
2038
2065
  }
2039
2066
  if (allowHtml && blocksCheck?.ok) {
2040
2067
  const sanitized = sanitizeBlocksText(fullResponse);
2041
2068
  if (sanitized.changed) {
2042
2069
  fullResponse = sanitized.text;
2043
- blocksCheck = checkBlockDocument(fullResponse, hostActionNames, allowHtml, imageHosts);
2070
+ blocksCheck = checkBlockDocument(fullResponse, callbackNames, allowHtml, imageHosts);
2044
2071
  }
2045
2072
  }
2046
2073
  const storedResponse =
@@ -2239,7 +2266,9 @@ interface BufferedTurn {
2239
2266
  /**
2240
2267
  * Runs a turn to completion and returns it as one JSON result, for clients that do not read
2241
2268
  * server-sent events. Nothing is written to the response while the turn runs, so a client that
2242
- * disconnects does not stop it: the turn still finishes and saves.
2269
+ * disconnects does not stop it: the turn still finishes and saves. Scripts that need a real turn
2270
+ * without HTTP (such as a model smoke test) call it with the `req.user` and headers a route would
2271
+ * pass, so the system prompt, tools, and block checks are the ones chat uses.
2243
2272
  */
2244
2273
  export const runBufferedChatTurn = async ({
2245
2274
  body,
@@ -1,4 +1,5 @@
1
1
  import {describe, expect, it} from "bun:test";
2
+ import {blocksPromptSection} from "@terreno/blocks";
2
3
 
3
4
  import {
4
5
  askFileHeading,
@@ -6,9 +7,11 @@ import {
6
7
  DEFAULT_GPT_MEMORY,
7
8
  JSON_VALUE_SYSTEM_PROMPT,
8
9
  REMIX_PROMPT,
10
+ TERRENO_UI_BLOCKS_SYSTEM_PROMPT,
9
11
  TITLE_GENERATION_PROMPT,
10
12
  TRANSLATION_PROMPT,
11
13
  truncatedAskFileNote,
14
+ uiBlocksSystemPrompt,
12
15
  unloadedAskUploadsNote,
13
16
  } from "./prompts";
14
17
 
@@ -40,4 +43,22 @@ describe("AI prompt constants", () => {
40
43
  'Uploads not loaded here: [{"fileId":"f1","filename":"a.png"}]'
41
44
  );
42
45
  });
46
+
47
+ it("honours the rich-block opt-out when nothing else is configured", () => {
48
+ expect(uiBlocksSystemPrompt({hostActions: [], richBlocks: false})).toBe(
49
+ blocksPromptSection({richBlocks: false})
50
+ );
51
+ expect(uiBlocksSystemPrompt({hostActions: []})).toBe(TERRENO_UI_BLOCKS_SYSTEM_PROMPT);
52
+ expect(TERRENO_UI_BLOCKS_SYSTEM_PROMPT).toContain("checklist requires");
53
+ expect(uiBlocksSystemPrompt({hostActions: [], richBlocks: false})).not.toContain("checklist");
54
+ });
55
+
56
+ it("names the checklist action in the prompt when the host registers one", () => {
57
+ const section = uiBlocksSystemPrompt({
58
+ checklistActions: ["toggleChecklist"],
59
+ hostActions: ["toggleChecklist"],
60
+ });
61
+ expect(section).toContain("Set a checklist callback name to one of: toggleChecklist.");
62
+ expect(uiBlocksSystemPrompt({hostActions: []})).toContain("Leave callback out of a checklist");
63
+ });
43
64
  });
@@ -10,16 +10,43 @@ export const TERRENO_UI_BLOCKS_SYSTEM_PROMPT = blocksPromptSection();
10
10
  export const UI_BLOCKS_REPAIR_SYSTEM_PROMPT =
11
11
  "The document you wrote failed validation. Reply with only the corrected document. Do not explain the changes.";
12
12
 
13
- /** The blocks prompt for this host's callback names. */
14
- export const uiBlocksSystemPrompt = (
15
- hostActions: readonly string[],
13
+ /**
14
+ * The blocks prompt for this host's callbacks, html and image settings, and rich-block opt-out.
15
+ * Runtime values are injected here because they are host configuration, not user data.
16
+ */
17
+ export const uiBlocksSystemPrompt = ({
16
18
  allowHtml = false,
17
- imageHosts: readonly string[] = []
18
- ): string => {
19
- if (hostActions.length === 0 && !allowHtml && imageHosts.length === 0) {
19
+ checklistActions = [],
20
+ hostActions,
21
+ imageHosts = [],
22
+ richBlocks = true,
23
+ stepperActions = [],
24
+ }: {
25
+ allowHtml?: boolean;
26
+ checklistActions?: readonly string[];
27
+ hostActions: readonly string[];
28
+ imageHosts?: readonly string[];
29
+ richBlocks?: boolean;
30
+ stepperActions?: readonly string[];
31
+ }): string => {
32
+ const isDefault =
33
+ richBlocks &&
34
+ hostActions.length === 0 &&
35
+ !allowHtml &&
36
+ imageHosts.length === 0 &&
37
+ stepperActions.length === 0 &&
38
+ checklistActions.length === 0;
39
+ if (isDefault) {
20
40
  return TERRENO_UI_BLOCKS_SYSTEM_PROMPT;
21
41
  }
22
- return blocksPromptSection({allowHtml, hostActions, imageHosts});
42
+ return blocksPromptSection({
43
+ allowHtml,
44
+ checklistActions,
45
+ hostActions,
46
+ imageHosts,
47
+ richBlocks,
48
+ stepperActions,
49
+ });
23
50
  };
24
51
 
25
52
  /**
@@ -0,0 +1,105 @@
1
+ import {describe, expect, it} from "bun:test";
2
+ import {isAPIError} from "@terreno/api";
3
+ import {type StepperBlock, validateBlocks} from "@terreno/blocks";
4
+
5
+ import {GptHistory} from "../models/gptHistory";
6
+ import type {GptHistoryDocument, HostActionContext} from "../types";
7
+ import {scaleStepperHostAction} from "./scaleStepper";
8
+
9
+ const ROAST = `v: 1
10
+ blocks:
11
+ - type: stepper
12
+ id: guests
13
+ label: Number of people
14
+ unit: People
15
+ value: 5
16
+ min: 1
17
+ max: 20
18
+ callback:
19
+ name: scaleStepper
20
+ payload:
21
+ recipe: roast
22
+ items:
23
+ - {label: Lamb, amount: 2, unit: kg, decimals: 1}
24
+ - {label: Parsnips, amount: 7, round: up}
25
+ - {label: Broccoli, amount: 625, unit: g}
26
+ note: Generous portions.
27
+ `;
28
+
29
+ const history = new GptHistory({
30
+ prompts: [
31
+ {text: "Plan a roast", type: "user"},
32
+ {text: ROAST, type: "assistant"},
33
+ ],
34
+ userId: "000000000000000000000001",
35
+ }) as unknown as GptHistoryDocument;
36
+
37
+ const run = async (payload: unknown, blockId = "guests"): Promise<unknown> => {
38
+ const context: HostActionContext = {
39
+ blockId,
40
+ elementId: `${blockId}_increase`,
41
+ history,
42
+ messageId: "msg-1",
43
+ payload,
44
+ user: {},
45
+ };
46
+ return scaleStepperHostAction.handler?.(context);
47
+ };
48
+
49
+ const statusOf = async (work: () => Promise<unknown>): Promise<number | undefined> => {
50
+ try {
51
+ await work();
52
+ } catch (error) {
53
+ if (isAPIError(error)) {
54
+ return error.status;
55
+ }
56
+ throw error;
57
+ }
58
+ return undefined;
59
+ };
60
+
61
+ describe("scaleStepperHostAction", () => {
62
+ it("declares a stepper action that keeps the block out of the log", () => {
63
+ expect(scaleStepperHostAction.handles).toBe("stepper");
64
+ expect(scaleStepperHostAction.logResponse).toBe(false);
65
+ });
66
+
67
+ it("accepts extra agent payload keys and rejects a non-number value", () => {
68
+ const schema = scaleStepperHostAction.payload;
69
+ expect(schema?.safeParse({recipe: "roast", value: 6}).success).toBe(true);
70
+ expect(schema?.safeParse({value: "6"}).success).toBe(false);
71
+ expect(schema?.safeParse({}).success).toBe(false);
72
+ });
73
+
74
+ it("scales every item from the agent's stepper by its decimals and rounding", async () => {
75
+ const result = (await run({recipe: "roast", value: 6})) as {
76
+ blocks: {blocks: StepperBlock[]; v: 1};
77
+ replace: string;
78
+ };
79
+ expect(result.replace).toBe("block");
80
+ expect(validateBlocks(result.blocks).ok).toBe(true);
81
+ expect(result.blocks.v).toBe(1);
82
+ expect(result.blocks.blocks).toHaveLength(1);
83
+ const stepper = result.blocks.blocks[0];
84
+ expect(stepper?.value).toBe(6);
85
+ expect(stepper?.items?.map((item) => item.amount)).toEqual([2.4, 9, 750]);
86
+ expect(stepper?.note).toBe("Generous portions.");
87
+ expect(stepper?.callback).toEqual({name: "scaleStepper", payload: {recipe: "roast"}});
88
+ });
89
+
90
+ it("scales from the stored original, not from the previous tap", async () => {
91
+ const result = (await run({value: 1})) as {blocks: {blocks: StepperBlock[]}};
92
+ expect(result.blocks.blocks[0]?.items?.map((item) => item.amount)).toEqual([0.4, 2, 125]);
93
+ });
94
+
95
+ it("returns 400 for a value outside min and max or off the step grid", async () => {
96
+ expect(await statusOf(() => run({value: 21}))).toBe(400);
97
+ expect(await statusOf(() => run({value: 0}))).toBe(400);
98
+ expect(await statusOf(() => run({value: 5.5}))).toBe(400);
99
+ expect(await statusOf(() => run({value: Number.NaN}))).toBe(400);
100
+ });
101
+
102
+ it("returns 404 when the agent wrote no stepper with that id", async () => {
103
+ expect(await statusOf(() => run({value: 6}, "missing"))).toBe(404);
104
+ });
105
+ });
@@ -0,0 +1,29 @@
1
+ import {APIError, z} from "@terreno/api";
2
+ import {isStepperValueAllowed, scaleStepperBlock} from "@terreno/blocks";
3
+
4
+ import type {HostAction, HostActionResult} from "../types";
5
+ import {blocksDocument, findAgentBlock} from "./agentBlocks";
6
+
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
+ export const scaleStepperHostAction: HostAction = {
14
+ handler: ({blockId, history, messageId, payload}): HostActionResult => {
15
+ const {value} = payload as {value: number};
16
+ const stepper = findAgentBlock({blockId, history, messageId, type: "stepper"});
17
+ if (!isStepperValueAllowed(stepper, value)) {
18
+ throw new 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: blocksDocument([scaleStepperBlock(stepper, value)]), replace: "block"};
25
+ },
26
+ handles: "stepper",
27
+ logResponse: false,
28
+ payload: z.object({value: z.number()}).passthrough(),
29
+ };
@@ -0,0 +1,126 @@
1
+ import {describe, expect, it} from "bun:test";
2
+ import {isAPIError} from "@terreno/api";
3
+ import {type ChecklistBlock, validateBlocks} from "@terreno/blocks";
4
+
5
+ import {GptHistory} from "../models/gptHistory";
6
+ import type {GptHistoryDocument, HostActionContext} from "../types";
7
+ import {toggleChecklistHostAction} from "./toggleChecklist";
8
+
9
+ const ROAST = `v: 1
10
+ blocks:
11
+ - type: checklist
12
+ id: cook
13
+ title: Cooking plan
14
+ callback:
15
+ name: toggleChecklist
16
+ payload:
17
+ recipe: roast
18
+ items:
19
+ - {id: preheat, text: Preheat the oven, meta: "12:00"}
20
+ - {id: lamb, text: Lamb in, meta: "12:15", detail: Fat side up, checked: true}
21
+ - {id: rest, text: Rest the lamb, meta: "13:45"}
22
+ `;
23
+
24
+ const history = new GptHistory({
25
+ prompts: [
26
+ {text: "Plan a roast", type: "user"},
27
+ {text: ROAST, type: "assistant"},
28
+ ],
29
+ userId: "000000000000000000000001",
30
+ }) as unknown as GptHistoryDocument;
31
+
32
+ const run = async (payload: unknown, blockId = "cook"): Promise<unknown> => {
33
+ const itemId = (payload as {itemId?: string}).itemId ?? "preheat";
34
+ const context: HostActionContext = {
35
+ blockId,
36
+ elementId: `${blockId}_${itemId}`,
37
+ history,
38
+ messageId: "msg-1",
39
+ payload,
40
+ user: {},
41
+ };
42
+ return toggleChecklistHostAction.handler?.(context);
43
+ };
44
+
45
+ const statusOf = async (work: () => Promise<unknown>): Promise<number | undefined> => {
46
+ try {
47
+ await work();
48
+ } catch (error) {
49
+ if (isAPIError(error)) {
50
+ return error.status;
51
+ }
52
+ throw error;
53
+ }
54
+ return undefined;
55
+ };
56
+
57
+ const checkedOf = (result: unknown): Record<string, boolean | undefined> => {
58
+ const checklist = (result as {blocks: {blocks: ChecklistBlock[]}}).blocks.blocks[0];
59
+ return Object.fromEntries((checklist?.items ?? []).map((item) => [item.id, item.checked]));
60
+ };
61
+
62
+ describe("toggleChecklistHostAction", () => {
63
+ it("declares a checklist action that keeps the block out of the log", () => {
64
+ expect(toggleChecklistHostAction.handles).toBe("checklist");
65
+ expect(toggleChecklistHostAction.logResponse).toBe(false);
66
+ });
67
+
68
+ it("accepts extra agent payload keys and rejects a malformed tick", () => {
69
+ const schema = toggleChecklistHostAction.payload;
70
+ const tick = {
71
+ checked: true,
72
+ itemId: "preheat",
73
+ state: {lamb: true, preheat: true, rest: false},
74
+ };
75
+ expect(schema?.safeParse({...tick, recipe: "roast"}).success).toBe(true);
76
+ expect(schema?.safeParse({...tick, checked: "yes"}).success).toBe(false);
77
+ expect(schema?.safeParse({...tick, state: {preheat: "yes"}}).success).toBe(false);
78
+ expect(schema?.safeParse({checked: true, state: {}}).success).toBe(false);
79
+ expect(schema?.safeParse({checked: true, itemId: "preheat"}).success).toBe(false);
80
+ });
81
+
82
+ it("returns the agent's checklist with checked set from state", async () => {
83
+ const result = (await run({
84
+ checked: true,
85
+ itemId: "preheat",
86
+ recipe: "roast",
87
+ state: {lamb: false, preheat: true, rest: true},
88
+ })) as {blocks: {blocks: ChecklistBlock[]; v: 1}; replace: string};
89
+ expect(result.replace).toBe("block");
90
+ expect(validateBlocks(result.blocks).ok).toBe(true);
91
+ expect(result.blocks.v).toBe(1);
92
+ expect(result.blocks.blocks).toHaveLength(1);
93
+ const checklist = result.blocks.blocks[0];
94
+ expect(checklist?.id).toBe("cook");
95
+ expect(checklist?.title).toBe("Cooking plan");
96
+ expect(checklist?.callback).toEqual({name: "toggleChecklist", payload: {recipe: "roast"}});
97
+ expect(checklist?.items.map((item) => item.text)).toEqual([
98
+ "Preheat the oven",
99
+ "Lamb in",
100
+ "Rest the lamb",
101
+ ]);
102
+ expect(checklist?.items[1]?.detail).toBe("Fat side up");
103
+ expect(checkedOf(result)).toEqual({lamb: false, preheat: true, rest: true});
104
+ });
105
+
106
+ it("treats items missing from state as unchecked and keeps the ticked item as sent", async () => {
107
+ const result = await run({checked: true, itemId: "rest", state: {}});
108
+ expect(checkedOf(result)).toEqual({lamb: false, preheat: false, rest: true});
109
+
110
+ const unticked = await run({checked: false, itemId: "lamb", state: {lamb: true}});
111
+ expect(checkedOf(unticked)).toEqual({lamb: false, preheat: false, rest: false});
112
+ });
113
+
114
+ it("returns 400 for an item id or state key the checklist does not have", async () => {
115
+ expect(await statusOf(() => run({checked: true, itemId: "carve", state: {}}))).toBe(400);
116
+ expect(
117
+ await statusOf(() => run({checked: true, itemId: "preheat", state: {carve: true}}))
118
+ ).toBe(400);
119
+ });
120
+
121
+ it("returns 404 when the agent wrote no checklist with that id", async () => {
122
+ expect(
123
+ await statusOf(() => run({checked: true, itemId: "preheat", state: {}}, "missing"))
124
+ ).toBe(404);
125
+ });
126
+ });
@@ -0,0 +1,44 @@
1
+ import {APIError, z} from "@terreno/api";
2
+ import {
3
+ applyChecklistState,
4
+ type ChecklistBlock,
5
+ type ChecklistTick,
6
+ unknownChecklistItemIds,
7
+ } from "@terreno/blocks";
8
+
9
+ import type {HostAction, HostActionResult} from "../types";
10
+ import {blocksDocument, findAgentBlock} from "./agentBlocks";
11
+
12
+ const unknownItemError = (itemIds: string[], checklist: ChecklistBlock): APIError =>
13
+ new APIError({
14
+ detail: `${checklist.id} has no item ${itemIds.join(", ")}. Its items are ${checklist.items
15
+ .map((item) => item.id)
16
+ .join(", ")}.`,
17
+ status: 400,
18
+ title: "Unknown checklist item",
19
+ });
20
+
21
+ /**
22
+ * Opt-in `checklist` host action. Register it as `uiBlocks.hostActions.toggleChecklist`. It reads
23
+ * the checklist the agent wrote from the stored history and returns it with every item's
24
+ * `checked` taken from `state`. An item missing from `state` is unchecked, and the ticked item
25
+ * always takes `checked`. Nothing is saved: an app that records progress should register its own
26
+ * `handles: "checklist"` action.
27
+ */
28
+ export const toggleChecklistHostAction: HostAction = {
29
+ handler: ({blockId, history, messageId, payload}): HostActionResult => {
30
+ const tick = payload as ChecklistTick;
31
+ const checklist = findAgentBlock({blockId, history, messageId, type: "checklist"});
32
+ const unknownIds = unknownChecklistItemIds(checklist, tick);
33
+ if (unknownIds.length > 0) {
34
+ throw unknownItemError(unknownIds, checklist);
35
+ }
36
+ const ticked = applyChecklistState(checklist, tick);
37
+ return {blocks: blocksDocument([ticked]), replace: "block"};
38
+ },
39
+ handles: "checklist",
40
+ logResponse: false,
41
+ payload: z
42
+ .object({checked: z.boolean(), itemId: z.string(), state: z.record(z.string(), z.boolean())})
43
+ .passthrough(),
44
+ };
@@ -4,6 +4,26 @@ import type {Duration, DurationLike} from "luxon";
4
4
  import type mongoose from "mongoose";
5
5
 
6
6
  import type {ExecutionEnv} from "../harness/executionEnv";
7
+ import type {ObsPromptRef} from "./observability";
8
+
9
+ /**
10
+ * A prompt version a task used, recorded on its `ObsTrace.prompts`. A `PromptVersionRef`
11
+ * from `promptRegistry.get` fits as-is; its `body` is ignored.
12
+ */
13
+ export type HarnessPromptRef = ObsPromptRef;
14
+
15
+ /** A registry prompt passed as instructions: its `body` is used and its version recorded. */
16
+ export interface HarnessPromptInstructions extends HarnessPromptRef {
17
+ body: string;
18
+ }
19
+
20
+ /** Fields written onto the task's `ObsTrace`, shared by every child task and subagent. */
21
+ export interface HarnessTraceOptions {
22
+ /** App-defined scope (tenant, workspace) for metering; indexed with `created`. */
23
+ scope?: string;
24
+ /** App-defined labels for grouping traces. */
25
+ tags?: string[];
26
+ }
7
27
 
8
28
  /** Every lifecycle status a harness task can hold. */
9
29
  export const HARNESS_TASK_STATUSES = {
@@ -374,8 +394,13 @@ export interface HarnessMemo {
374
394
  export interface HarnessRunAgentOptions<Result> {
375
395
  /** The subagent's user message. A non-string value is sent as JSON. */
376
396
  input: unknown;
377
- /** Replaces the agent's instructions for this subagent conversation only. */
378
- instructions?: string;
397
+ /**
398
+ * Replaces the agent's instructions for this subagent conversation only. A registry
399
+ * prompt (`promptRegistry.get`) is used by its `body` and recorded on the trace.
400
+ */
401
+ instructions?: HarnessPromptInstructions | string;
402
+ /** Prompt versions this subagent used, recorded on the task's `ObsTrace.prompts`. */
403
+ prompts?: HarnessPromptRef[];
379
404
  /**
380
405
  * Structured output schema; defaults to the agent's own `output`. Requested through the
381
406
  * AI SDK's `Output.object`, then validated with this schema before it is returned.
@@ -442,8 +467,12 @@ export interface HarnessAbortOptions {
442
467
  }
443
468
 
444
469
  export interface HarnessCreateTaskOptions {
470
+ /** Prompt versions the task uses, recorded on its `ObsTrace.prompts`. */
471
+ prompts?: HarnessPromptRef[];
445
472
  /** Idempotency key: a second create with the same id returns the existing task. */
446
473
  requestId?: string;
474
+ /** Scope and tags for the task's `ObsTrace`; child tasks and subagents share it. */
475
+ trace?: HarnessTraceOptions;
447
476
  userId?: mongoose.Types.ObjectId | string;
448
477
  }
449
478
 
@@ -374,6 +374,21 @@ export interface HostActionContext {
374
374
  user: {_id?: mongoose.Types.ObjectId};
375
375
  }
376
376
 
377
+ /** One host callback that `POST /gpt/actions` runs for a block button. */
378
+ export interface HostAction {
379
+ handler?: (
380
+ context: HostActionContext
381
+ ) => Promise<HostActionResult | undefined> | HostActionResult | undefined;
382
+ /** The interactive block this action serves. `scaleStepperHostAction` sets `stepper`. */
383
+ handles?: "stepper" | "checklist";
384
+ /**
385
+ * When `false`, the `ui_action` `AIRequest` row keeps the ids-only prompt plus a numeric
386
+ * `payload.value`, and leaves out the returned document. Default `true` logs the response.
387
+ */
388
+ logResponse?: boolean;
389
+ payload?: HostPayloadSchema;
390
+ }
391
+
377
392
  /** `addGptRoutes` `uiBlocks`. `true` checks every assistant reply. `hostActions` names the callbacks the model may emit. */
378
393
  export interface UiBlocksOptions {
379
394
  /** Milliseconds before a host callback returns 504. Default 10 seconds. */
@@ -386,16 +401,14 @@ export interface UiBlocksOptions {
386
401
  html?: boolean;
387
402
  /** Hostnames allowed on `https` image sources. Empty rejects every https image. */
388
403
  imageHosts?: readonly string[];
389
- hostActions?: Record<
390
- string,
391
- {
392
- handler?: (
393
- context: HostActionContext
394
- ) => Promise<HostActionResult | undefined> | HostActionResult | undefined;
395
- payload?: HostPayloadSchema;
396
- }
397
- >;
404
+ hostActions?: Record<string, HostAction>;
398
405
  repair?: boolean;
406
+ /**
407
+ * Default `true`: the prompt offers the rich blocks, and the stepper when a host action has
408
+ * `handles: "stepper"`. `false` keeps the prompt as it was before them, for clients that cannot
409
+ * render them yet. Validation accepts the rich blocks either way.
410
+ */
411
+ richBlocks?: boolean;
399
412
  }
400
413
 
401
414
  export interface GptRouteOptions {
@@ -89,10 +89,13 @@ export interface ObsTraceDocument extends mongoose.Document<mongoose.Types.Objec
89
89
  name: string;
90
90
  output?: unknown;
91
91
  prompts: ObsPromptRef[];
92
+ /** App-defined scope (tenant, workspace) set by `harness.createTask({trace: {scope}})`. */
93
+ scope?: string;
92
94
  sensitive: boolean;
93
95
  sessionId?: string;
94
96
  startedAt: Date;
95
97
  status: "error" | "ok";
98
+ tags: string[];
96
99
  updated: Date;
97
100
  usage?: ObsPromptUsage;
98
101
  userId?: mongoose.Types.ObjectId;