@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.
@@ -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";
@@ -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
+ };
@@ -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 {