@theoremjs/studio 0.3.4-next.544.gb5ef325 → 0.3.4-next.550.gf20b9cd

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 (173) hide show
  1. package/README.md +57 -17
  2. package/agreement.js +22 -7
  3. package/compile.js +61 -13
  4. package/cookbooks/catalog.d.ts +26 -3
  5. package/cookbooks/catalog.js +114 -60
  6. package/cookbooks/exchanges.d.ts +3 -0
  7. package/cookbooks/exchanges.js +7 -2
  8. package/cookbooks/mod.d.ts +3 -3
  9. package/cookbooks/mod.js +2 -2
  10. package/cookbooks/project.js +1 -3
  11. package/draft.d.ts +23 -5
  12. package/draft.js +10 -2
  13. package/media-accept.d.ts +7 -0
  14. package/media-accept.js +17 -0
  15. package/mod.d.ts +4 -4
  16. package/mod.js +3 -3
  17. package/package.json +4 -4
  18. package/page/assets/Banner-Bvkdyf59.js +2 -0
  19. package/page/assets/BottomSheet-Dbh6A5Vl.js +1 -0
  20. package/page/assets/{Card-Ghe4ozhC.js → Card-DruykyeB.js} +1 -1
  21. package/page/assets/CheckboxInput-CFZ_Wq8-.js +2 -0
  22. package/page/assets/CodeBlock-CfVOtDeO.js +52 -0
  23. package/page/assets/CollapsibleGroup-FIawJRo4.js +1 -0
  24. package/page/assets/ConsoleFrame-BTL67qHr.js +3 -0
  25. package/page/assets/ContextMenu-BngxR9na.js +2 -0
  26. package/page/assets/DateInput-B1ICJtHn.js +1 -0
  27. package/page/assets/{Dialog-BDUExlk_.js → Dialog-Sd04KQS2.js} +1 -1
  28. package/page/assets/EmptyState-C_uF9Wyj.js +1 -0
  29. package/page/assets/HoverCard-DMyWUvwP.js +1 -0
  30. package/page/assets/Icon-BqkS-pIq.js +3 -0
  31. package/page/assets/IconButton-DVUFx-8p.js +1 -0
  32. package/page/assets/ListItem-QF7KFt0h.js +1 -0
  33. package/page/assets/MenuBottomSheet-C4fG_GyZ.js +1 -0
  34. package/page/assets/MenuBottomSheetActionList-3L0HS4Kf.js +1 -0
  35. package/page/assets/SchemaFields-BT2XCbid.js +1 -0
  36. package/page/assets/ScrollableArea-BHfY7sWH.js +1 -0
  37. package/page/assets/SegmentedControlItem-BBGRPrxp.js +1 -0
  38. package/page/assets/{Text-BsiAsowd.js → Text-BOqCfzZC.js} +2 -2
  39. package/page/assets/{TimestampHoverCard-CCnmnVlQ.js → TimestampHoverCard-CDCVpEWM.js} +1 -1
  40. package/page/assets/{ToolResultCharts-BAIAtrxa.js → ToolResultCharts-rJr0Ksno.js} +1 -1
  41. package/page/assets/Tooltip-BWs5DLrM.js +1 -0
  42. package/page/assets/TraceInspector-DQI_wNzL.js +1 -0
  43. package/page/assets/{TraceOverview-C6T0S77W.js → TraceOverview-DmfmwSR6.js} +2 -2
  44. package/page/assets/{_virtual_studio-type-sources-C1mRXxbj.js → _virtual_studio-type-sources-CxP3L28S.js} +158 -78
  45. package/page/assets/browser-engine-B1PxEekk.js +11 -0
  46. package/page/assets/browser-transport-BOHBmYvp.js +47 -0
  47. package/page/assets/{embedding-space-view-BU2AjjAx.js → embedding-space-view-CN0VHXXH.js} +1 -1
  48. package/page/assets/{export-agent-m6Z0No6j.js → export-agent-BvEVKW_C.js} +8 -8
  49. package/page/assets/fieldParts-B7DYLgh4.js +1 -0
  50. package/page/assets/focusableSelector-DXZeMU85.js +1 -0
  51. package/page/assets/{guardrail-tester-oVuyo5d2.js → guardrail-tester-08T-hMFL.js} +2 -2
  52. package/page/assets/index-eSb7kilv.js +146 -0
  53. package/page/assets/isRenderable-DHkzpAoQ.js +1 -0
  54. package/page/assets/{labels-provider-Gus3heEH.js → labels-provider-DkA22zkP.js} +2 -2
  55. package/page/assets/{live-messages-BNhCuiuF.js → live-messages-DmTC8qc8.js} +1 -1
  56. package/page/assets/plainDate-BHiJcj7o.js +1 -0
  57. package/page/assets/reader-DoTXxl0W.js +7 -0
  58. package/page/assets/{stub-DPcZtI0s.js → stub-CKo_lxer.js} +1 -1
  59. package/page/assets/studio-code-pane-CEG07Zk7.js +8 -0
  60. package/page/assets/{studio-console-DoZMv_gr.js → studio-console-udt4MmTi.js} +1 -1
  61. package/page/assets/studio-decision-tocwLzxr.js +1 -0
  62. package/page/assets/studio-embedding-DQ84xzlj.js +2 -0
  63. package/page/assets/studio-host-console-BJOUpXHR.js +2 -0
  64. package/page/assets/studio-labels-Zqd84hcs.js +3 -0
  65. package/page/assets/studio-live-BmuHpeF4.js +5 -0
  66. package/page/assets/{studio-map-Dv8iCayn.js → studio-map-qP_i4hWG.js} +1 -1
  67. package/page/assets/studio-trace-replay-JUMs6EMA.js +2 -0
  68. package/page/assets/{studio-type-checker-B5DVxAZ0.js → studio-type-checker-B_CHmWnf.js} +1 -1
  69. package/page/assets/{tool-schema-CxLtS_Zt.js → tool-schema-CWGccblZ.js} +6 -6
  70. package/page/assets/{trace-patterns-CS99kExN.js → trace-patterns-D6TbkLLr.js} +1 -1
  71. package/page/assets/tree-B7VVMg1s.js +3 -0
  72. package/page/assets/{turn-client-BCi5WnI6.js → turn-client-CoLR6hrl.js} +1 -1
  73. package/page/assets/types-CL44MvsT.js +1 -0
  74. package/page/assets/{use-one-call-TEvndb3j.js → use-one-call-BKeMtY5F.js} +1 -1
  75. package/page/assets/use-second-ticker-GWBt83pd.css +1 -0
  76. package/page/assets/use-trace-records-B1vrKQmA.js +1 -0
  77. package/page/assets/useAdaptivePresentation-Bma4-u1a.js +1 -0
  78. package/page/assets/useAnnounce-DTSHZvjg.js +1 -0
  79. package/page/assets/useClipboard-CbN9bb4J.js +1 -0
  80. package/page/assets/useDevWarning-Z9SoixOP.js +1 -0
  81. package/page/assets/useFocusReturnVisibility-BHKv5Jwr.js +1 -0
  82. package/page/assets/useMenuPress-DLG1QOiE.js +1 -0
  83. package/page/assets/useResolvedRequired-DbsOcDqy.js +1 -0
  84. package/page/assets/useScrollableArea-DuF_pz9m.js +1 -0
  85. package/page/assets/useTooltip-c097gL_-.js +1 -0
  86. package/page/assets/workspace-NGa3jjDc.js +1 -0
  87. package/page/index.html +45 -38
  88. package/read-source.js +35 -8
  89. package/read-studio.mjs +99 -0
  90. package/replay.d.ts +3 -1
  91. package/replay.js +53 -5
  92. package/requirements.d.ts +3 -0
  93. package/requirements.js +10 -0
  94. package/server/alerts.d.ts +23 -0
  95. package/server/alerts.js +82 -0
  96. package/server/draft-handler.d.ts +3 -0
  97. package/server/draft-handler.js +5 -1
  98. package/server/events.d.ts +38 -0
  99. package/server/events.js +95 -0
  100. package/server/handler.d.ts +11 -3
  101. package/server/handler.js +64 -8
  102. package/server/project-source.d.ts +6 -3
  103. package/server/project-source.js +45 -4
  104. package/server/project.js +25 -3
  105. package/server/save-session.d.ts +2 -0
  106. package/server/save-session.js +7 -1
  107. package/server/serve.d.ts +1 -1
  108. package/server/serve.js +174 -18
  109. package/server/test-key.d.ts +19 -2
  110. package/server/test-key.js +51 -74
  111. package/server/watch.d.ts +8 -0
  112. package/server/watch.js +16 -5
  113. package/start.mjs +95 -5
  114. package/surface.js +1 -2
  115. package/ui/built/theme.css +2 -2
  116. package/ui/built/theme.css.d.ts +2 -2
  117. package/ui/built/theorem-studio.d.ts +2 -2
  118. package/ui/built/theorem-studio.js +3 -3
  119. package/ui/built/theorem-studio.variants.d.ts +2 -2
  120. package/ui/lib/export-agent.js +20 -2
  121. package/ui/lib/page-errors.d.ts +13 -0
  122. package/ui/lib/page-errors.js +31 -0
  123. package/ui/lib/studio-examples.js +0 -4
  124. package/ui/lib/studio-page.d.ts +8 -3
  125. package/ui/lib/studio-page.js +34 -13
  126. package/ui/profile-editor.js +186 -34
  127. package/ui/studio-decision.js +4 -1
  128. package/ui/studio-runner.d.ts +1 -1
  129. package/ui/studio-runner.js +7 -3
  130. package/ui/studio-screen.js +24 -18
  131. package/ui/studio-trace-replay.js +1 -8
  132. package/workspace.d.ts +1 -0
  133. package/workspace.js +3 -2
  134. package/page/assets/Banner-BUrqNrQ9.js +0 -2
  135. package/page/assets/BottomSheet-BQPskY35.js +0 -1
  136. package/page/assets/CheckboxInput-C9kbVyhK.js +0 -2
  137. package/page/assets/CodeBlock-Kjgv83A6.js +0 -52
  138. package/page/assets/CollapsibleGroup-PavPZ114.js +0 -1
  139. package/page/assets/ConsoleFrame-BpbXMWsq.js +0 -3
  140. package/page/assets/ContextMenu-D_6fLWw7.js +0 -2
  141. package/page/assets/DateInput-BJt-UTCy.js +0 -1
  142. package/page/assets/EmptyState-C8W4JKBZ.js +0 -1
  143. package/page/assets/HoverCard-C6thuzrf.js +0 -1
  144. package/page/assets/Icon-ZfFwTt8n.js +0 -3
  145. package/page/assets/IconButton-CG5klqF1.js +0 -1
  146. package/page/assets/ScrollableArea-C8AVuqnt.js +0 -1
  147. package/page/assets/Section-DJ97F7QE.js +0 -1
  148. package/page/assets/SegmentedControlItem-BLuJOusN.js +0 -1
  149. package/page/assets/Tooltip-CTEuMRLe.js +0 -1
  150. package/page/assets/TraceInspector-CvaN-GcS.js +0 -1
  151. package/page/assets/browser-engine-BS9Kn2Gx.js +0 -11
  152. package/page/assets/browser-transport-eqZ9n2AK.js +0 -47
  153. package/page/assets/fieldParts-Cs6Amprh.js +0 -1
  154. package/page/assets/index-Q8T7gvHP.js +0 -149
  155. package/page/assets/reader-BT_YeHdq.js +0 -7
  156. package/page/assets/studio-code-pane-BB8Q348A.js +0 -8
  157. package/page/assets/studio-decision-BPT3x1kT.js +0 -1
  158. package/page/assets/studio-embedding-cH6PQupx.js +0 -2
  159. package/page/assets/studio-host-console-ZvV5TFC4.js +0 -2
  160. package/page/assets/studio-labels-Dwd-ojX5.js +0 -3
  161. package/page/assets/studio-live-DDInnfd7.js +0 -5
  162. package/page/assets/studio-trace-replay-Dl792A2v.js +0 -2
  163. package/page/assets/tree-Bi2FOU_h.js +0 -3
  164. package/page/assets/types-s-3wFTyD.js +0 -1
  165. package/page/assets/use-second-ticker-CnxaP3LD.css +0 -1
  166. package/page/assets/use-trace-records-BkAYJz0M.js +0 -1
  167. package/page/assets/useAdaptivePresentation-BY_zvjIp.js +0 -1
  168. package/page/assets/useClipboard-B1amtN2V.js +0 -1
  169. package/page/assets/useDevWarning-Cna3kqg1.js +0 -1
  170. package/page/assets/useScrollableArea-vxuztwym.js +0 -1
  171. package/page/assets/useTooltip-rxACYEAC.js +0 -1
  172. package/page/assets/workspace-BiCkglEt.js +0 -1
  173. /package/page/assets/{use-second-ticker-VX91zrxj.js → use-second-ticker-DhbZ0Soz.js} +0 -0
package/README.md CHANGED
@@ -46,7 +46,7 @@ The command needs [Deno](https://deno.com). The installed `@theoremjs/studio`, `
46
46
  To show the screen in your app, also install `@theoremjs/react` at the same version, and React 19 and the design packages at the versions `@theoremjs/react` lists in `peerDependencies`:
47
47
 
48
48
  ```bash
49
- npm install @theoremjs/react react react-dom @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
49
+ npm install @theoremjs/react react react-dom @astryxdesign/core@0.7.4 @astryxdesign/theme-neutral@0.7.4 @stylexjs/stylex@0.19.0
50
50
  ```
51
51
 
52
52
  ## Open your project
@@ -60,7 +60,7 @@ The command starts two servers that only this machine reaches: your project's se
60
60
  Add `"studio": "theorem-studio"` to your scripts to run it as `npm run studio`.
61
61
 
62
62
  ```text
63
- theorem-studio [setup] [--editor <command>] [--deno-config <file>] [--no-watch]
63
+ theorem-studio [setup] [--editor <command>] [--deno-config <file>] [--no-watch] [--quiet] [--offline] [--verbose]
64
64
  ```
65
65
 
66
66
  | Option | What it does |
@@ -69,28 +69,68 @@ theorem-studio [setup] [--editor <command>] [--deno-config <file>] [--no-watch]
69
69
  | `--editor <command>` | The editor the studio opens a line of your files in. Default: `$VISUAL` or `$EDITOR` when it opens a window, else `code`. |
70
70
  | `--deno-config <file>` | The Deno config your project loads with. Default: the `deno.json` or `deno.jsonc` in the folder you ran the command in, else the studio's. |
71
71
  | `--no-watch` | Do not watch the files the setup reads. The studio reads them again when you come back to it. |
72
+ | `--quiet` | Print nothing about the project. Without it, the command prints what loaded (the setup, its entry, each agent with its type and providers, the tools by kind), then each problem, difference and unregistered profile or tool the page flags, when the project opens and when the list changes, then one line for each provider's key, then one line for each run that fails and each error the page meets. A line that repeats the one before is printed once. A project with nothing to look at prints `theorem studio: nothing to look at`. |
73
+ | `--offline` | Do not check the keys. Without it, the command sends each provider its models use one request, the `check` its definition declares, and prints whether the key works, is refused, is empty, or could not be checked. It never prints a key. |
74
+ | `--verbose` | Also print a line for every run, as it answers. Without it, only a run that fails prints, with what it said. |
75
+
76
+ ### Reading an open studio
77
+
78
+ Two more commands read a studio that is open on your project. They change nothing, so you, a script or a coding agent can run them at any time from another terminal:
79
+
80
+ ```text
81
+ theorem-studio status [setup]
82
+ theorem-studio errors [setup] [--follow]
83
+ ```
84
+
85
+ | Command | What it prints |
86
+ | --- | --- |
87
+ | `status` | Where the studio is open, what it loaded, what each key check said, and what to look at now. |
88
+ | `errors` | The last 200 events the studio printed about the project (what to look at, each key that does not work, each run that fails, each error the page meets), each with its time. A run that ends well is not kept. |
89
+ | `errors --follow` | The same, then each new event as it comes, until the studio stops. |
90
+
91
+ With several setups open, name the one to read. The `agents` command runs the same commands through the studio you installed: `npx agents studio status`.
92
+
93
+ ### The app's entry
94
+
95
+ The studio runs your agents the way your app runs them. Your app's entry point exports `theorem`, a `TurnWiring` from `@theoremjs/agents`, and your app's own server uses the same object:
96
+
97
+ ```ts
98
+ // server/theorem.ts
99
+ import type { TurnWiring } from '@theoremjs/agents';
100
+
101
+ export const theorem: TurnWiring = {
102
+ register: () => registerSupport(),
103
+ provider: { vault: { openai: Deno.env.get('OPENAI_API_KEY') ?? '' } },
104
+ prepare: (turn) => ({ ...turn, system: systemPromptFor(turn.host) }),
105
+ };
106
+ ```
107
+
108
+ | Field | What the studio does with it |
109
+ |---|---|
110
+ | `register()` | Calls it once as it loads the project, before anything runs: register the project's profiles and tools here. It may be `async`. |
111
+ | `provider` | The keys, network, and limits every model call runs on. Without it, a run's model call fails for want of a key. |
112
+ | `prepare(turn)` | Gives it each text, image and speech turn, and runs the turn it returns: add the system prompt, history, credentials or `onStage` your app adds. The studio keeps the profile and the context the run was given. |
113
+
114
+ The studio's chat keeps its own conversation and never writes to your app's stores. `prepare` can change the history it is given.
115
+
116
+ The studio loads your entry in the environment you start it in. If the entry reads its keys as it loads, from `Deno.env` or a file an environment variable names, set them on the command that starts the studio, as you do for your app: `OPENAI_API_KEY=… theorem-studio`.
72
117
 
73
118
  ### What a setup file exports
74
119
 
75
- Every export is optional. The studio reads only these:
120
+ The studio reads only these exports. `entry` is required; the others are optional.
76
121
 
77
122
  | Export | What the studio does with it |
78
123
  |---|---|
79
- | `default()` | Calls it once as it loads the project, before anything runs: register the project's profiles and tools here. It may be `async`. |
80
- | `provider` | The keys, network, and limits every model call runs on (`ProviderHostOptions` from `@theoremjs/agents/kernel`). Without it, a run's model call fails for want of a key. |
124
+ | `entry` | The path of your app's entry point, from the setup file: `export const entry = './server/theorem.ts'`. The studio loads its `theorem`, and reads the files it imports as part of the project. |
81
125
  | `people`, `host` | Who a run's tools act for (below). |
82
- | `questions` | What each decision profile asks, by the profile's id: `{ [profileId]: { [questionId]: DecisionQuestion } }`. |
126
+ | `questions` | What each decision profile asks, by the profile's id: `{ [profileId]: { [questionId]: DecisionQuestion } }`. When your app builds a profile's questions for each decision, export the builder your app passes to `createTheoremDecisionHandler` instead, `{ input?, build }`: the run shows a form for `input` above the state, and each answer shows the questions `build` made. The editor shows where the builder is and lists no questions. |
83
127
  | `images` | The pictures each decision profile can send, by the profile's id. A decision sends only those its state or questions name: `{ [profileId]: { [reference]: DecisionAsset } }`, where a reference is the name its questions write, such as `'<ghs02>'`. |
84
128
 
85
- ### Keys a run uses
129
+ A setup file that still exports `default()` or `provider` does not open: the command names the move to the entry.
86
130
 
87
- A profile's model names a key slot. `provider.vault` holds a key for each slot, so a studio run signs with the key the same profile uses in your app. Load the keys however your start script does, and read them when the setup file loads; the studio never writes them down:
131
+ ### Keys a run uses
88
132
 
89
- ```ts
90
- export const provider = {
91
- vault: { openai: Deno.env.get('OPENAI_API_KEY') ?? '' },
92
- };
93
- ```
133
+ A profile's model names a key slot. `theorem.provider.vault` holds a key for each slot, so a studio run signs with the key the same profile uses in your app. Load the keys however your start script does, and read them when the entry loads; the studio never writes them down.
94
134
 
95
135
  For a key that comes from a secret store, a slot can hold a function instead. The studio calls it with the provider and slot when a call needs the key. A slot left out or empty fails that run with the slot's name, not a guess at another key.
96
136
 
@@ -199,7 +239,7 @@ The handler takes a Web `Request` and returns a `Response`. It serves no project
199
239
  Without lent keys, the handler answers three requests:
200
240
 
201
241
  - the guardrail probe, on a scripted model, so no model is called;
202
- - the key test, for a key the builder types;
242
+ - the key test: one request to the check the key's provider declares (`checkKey`), to public hosts only;
203
243
  - the tool connection test, which reaches public hosts only.
204
244
 
205
245
  Drafts then run in the browser, on the builder's own keys.
@@ -278,11 +318,11 @@ Use these when you build on the studio's draft yourself: compile it, export it a
278
318
 
279
319
  | Export | Purpose |
280
320
  | --- | --- |
281
- | `StudioDraft`, `createBlankDraft()`, `createExampleDraft()`, `COOKBOOKS` | Editable profile draft; blank, the travel concierge, or the canonical cookbook catalog (`research`, `concierge`, `architect`, `live-concierge`, `decision`, `span-decision`, `gemini-embedding-2`, `narrator`, `console`) |
282
- | `createResearchWorkspace()`, `addResearchExample()`, `createResearchScoutDraft()`, `createPageReaderExampleDraft()`, `cookbookOpening()`, `openingFromRecords()` | The lead system cookbook: `research.scout` (OpenRouter `google/gemini-3.8-flash`, streamed thoughts, prose reply, liquid tool labels) linked to `research.pagereader` (Jev decision profile that filters page passages at `post_tool`). `cookbookOpening('research')` projects its recorded `.trace.json` with the same helpers Replay exchange and Continue live use |
321
+ | `StudioDraft`, `createBlankDraft()`, `createExampleDraft()`, `COOKBOOKS` | Editable profile draft; blank, the travel concierge, or the canonical cookbook catalog (`research`, `concierge`, `architect`, `live-concierge`, `decision`, `gemini-embedding-2`, `narrator`, `console`) |
322
+ | `createResearchWorkspace()`, `addResearchExample()`, `createResearchScoutDraft()`, `createPageReaderExampleDraft()`, `cookbookOpening()`, `openingFromRecords()` | The lead system cookbook: `research.scout` (OpenRouter `google/gemini-3.8-flash`, streamed thoughts, prose reply, liquid tool labels; no attachment accept list and no effort select — Goals examples turn those on) linked to `research.pagereader` (Jev decision profile that filters page passages at `post_tool`). `cookbookOpening('research')` projects its recorded `.trace.json` with the same helpers Replay exchange and Continue live use |
283
323
  | `projectProfileSlice()`, `projectToolSlice()`, `stitchCookbook()`, `resolveCookbookSlice()` | Project or stitch individual profile facets, tool sub-objects (`auth`, `mapping`, `labels`), or full runnable programs from `COOKBOOKS` |
284
324
  | `GOOGLE_BUILTIN_TOOLS`, `OPENROUTER_BUILTIN_TOOLS`, `GOOGLE_SPEECH_VOICES`, `googleBindingViolation()`, `localBindingViolation()`, `ollamaModelThinks()` | Provider and model cookbooks: hosted builtin tool definitions, provider media/voice vocabularies, and model binding checks |
285
- | `createDecisionExampleDraft()`, `decisionExampleDraft(images?)`, `DECISION_EXAMPLE_STATE`, `decisionExampleAssets()` | The decision example: Jev 1.14 asked about a pantry shelf, with box, Number and Choice questions. Its four pictures ship with it, and load only when the example is made, so `createDecisionExampleDraft` and `decisionExampleAssets` return a promise; `decisionExampleDraft` is the same draft with the pictures it is given, none by default, for a page that only shows its shape. The ginger, the colour chart and the flag are the decision's own; a decision sends each one its state or questions name. Each box question names the image it reads: the Ginger and Union Jack questions read `photo`, and the chart question reads `<apple_ripeness>`. The run tab starts with the shelf in its state. Each is written as its reference, such as `<ginger>`, in the state or in the questions. The shelf and ginger photos are CC0 and the flag is public domain, all from Wikimedia Commons. The colour chart was drawn for the example |
325
+ | `createDecisionExampleDraft()`, `decisionExampleDraft(images?)`, `DECISION_EXAMPLE_STATE`, `decisionExampleAssets()` | The Pantry cookbook (`COOKBOOKS.decision`, agent `pantry.jev`): Jev 1.14 asked about a pantry shelf, with box, Number and Choice questions. Its four pictures ship with it, and load only when the example is made, so `createDecisionExampleDraft` and `decisionExampleAssets` return a promise; `decisionExampleDraft` is the same draft with the pictures it is given, none by default, for a page that only shows its shape. The ginger, the colour chart and the flag are the decision's own; a decision sends each one its state or questions name. Each box question names the image it reads: the Ginger and Union Jack questions read `photo`, and the chart question reads `<apple_ripeness>`. The run tab starts with the shelf in its state. Each is written as its reference, such as `<ginger>`, in the state or in the questions. The shelf and ginger photos are CC0 and the flag is public domain, all from Wikimedia Commons. The colour chart was drawn for the example |
286
326
  | `createLiveExampleDraft()`, `createNarratorExampleDraft()`, `createConsoleExampleDraft()`, `createArchitectWorkspace()` | The other examples: the concierge as a live agent, a speech narrator, a host tool console, and a code architect that calls the narrator through an agent tool |
287
327
  | `setProfileType()`, `includeFacet()`, `excludeFacet()`, `newModelBinding()`, `newToolSpec()` | Draft edits that keep it consistent with `PROFILE_GRAPH` |
288
328
  | `studioTree()`, `studioNodeRef()`, `modelBindingNodeId()`, `toolSpecNodeId()` | The draft as a tree; node ids that issues point at |
package/agreement.js CHANGED
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * @module
7
7
  */
8
- import { resolveAllow, resolveDetect } from '@theoremjs/agents/guardrails';
8
+ import { BOUNDARIES, DETECTORS, resolveAllow, resolveDetect, TOOL_BOUNDARIES, } from '@theoremjs/agents/guardrails';
9
9
  import { unsetValue } from '@theoremjs/agents/kernel';
10
10
  import { STUDIO_POLICY_UNSET } from "./policy.js";
11
11
  function isRecord(value) {
@@ -17,14 +17,23 @@ function isPolicyFill(path, ours, theirs) {
17
17
  }
18
18
  /** `held` without the table the kernel works out from its patterns. */
19
19
  const uncompiled = ({ compiled: _, ...held }) => held;
20
+ /** `actions` at only the boundaries in `boundaries`. */
21
+ function onlyAt(actions, boundaries) {
22
+ return Object.fromEntries(boundaries.map((boundary) => [boundary, actions[boundary]]));
23
+ }
20
24
  /**
21
- * What the kernel reads `detect` as: each detector's action at each boundary, whose patterns it
22
- * reads with, and what it lets through. Two settings the kernel reads the same are the same here.
25
+ * What the kernel reads `detect` as: each detector's action at each boundary it reads, whose
26
+ * patterns it reads with, and what it lets through. Two settings the kernel reads the same are the
27
+ * same here. A host profile runs tools and no model turn, so it reads only the tool boundaries.
23
28
  */
24
- function detectAsRead(detect) {
29
+ function detectAsRead(detect, boundaries) {
25
30
  if (detect === undefined)
26
31
  return undefined;
27
- const { sources = {}, host = [], ...read } = resolveDetect(detect);
32
+ const { sources = {}, host = [], ...resolved } = resolveDetect(detect);
33
+ const read = {
34
+ ...resolved,
35
+ ...Object.fromEntries(DETECTORS.map((detector) => [detector, onlyAt(resolved[detector], boundaries)])),
36
+ };
28
37
  const allow = Object.entries(resolveAllow(detect)).map(([detector, held]) => [
29
38
  detector,
30
39
  {
@@ -35,7 +44,10 @@ function detectAsRead(detect) {
35
44
  return {
36
45
  ...read,
37
46
  sources: Object.fromEntries(Object.entries(sources).map(([detector, source]) => [detector, uncompiled(source)])),
38
- host: Object.fromEntries(host.map(({ id, ...rule }) => [id, uncompiled(rule)])),
47
+ host: Object.fromEntries(host.map(({ id, ...rule }) => [
48
+ id,
49
+ uncompiled({ ...rule, actions: onlyAt(rule.actions, boundaries) }),
50
+ ])),
39
51
  allow: Object.fromEntries(allow),
40
52
  };
41
53
  }
@@ -47,7 +59,10 @@ function asRead(profile) {
47
59
  return profile;
48
60
  return {
49
61
  ...profile,
50
- guardrails: { ...profile.guardrails, detect: detectAsRead(profile.guardrails.detect) },
62
+ guardrails: {
63
+ ...profile.guardrails,
64
+ detect: detectAsRead(profile.guardrails.detect, profile.type === 'host' ? TOOL_BOUNDARIES : BOUNDARIES),
65
+ },
51
66
  };
52
67
  }
53
68
  /**
package/compile.js CHANGED
@@ -601,11 +601,11 @@ function compileTool(tool, report, agentIdOf, agentInputOf) {
601
601
  const common = toolCommon(tool, fail, agentInputOf);
602
602
  const labels = toolLabels(tool, common, fail);
603
603
  const compiled = TOOL_COMPILERS[tool.toolType](tool, common, fail, agentIdOf);
604
+ // why: stageAgentKey is an optional post_tool reader on a library tool. A
605
+ // dangling key must not fail the tool — the tool still runs; only the filter
606
+ // is dropped (same as sound() / removeAgent clearing the link).
604
607
  const stageKey = tool.toolType !== 'agent' ? (tool.stageAgentKey?.trim() ?? '') : '';
605
608
  const stageAgent = stageKey ? agentIdOf(stageKey) : undefined;
606
- if (stageKey && !stageAgent) {
607
- fail('The agent that reads this tool is gone. Pick another.', 'stageAgentKey');
608
- }
609
609
  return failed
610
610
  ? undefined
611
611
  : {
@@ -664,9 +664,7 @@ function compileInputs(inputs, type, report) {
664
664
  checkWhole(report, 'inputs', 'maxFiles', 'Max files', inputs.maxFiles, 1);
665
665
  checkWhole(report, 'inputs', 'maxBytes', 'Max bytes', inputs.maxBytes, 1);
666
666
  checkWhole(report, 'inputs', 'maxTurnBytes', 'Max turn bytes', inputs.maxTurnBytes, 1);
667
- const limitsByMime = recordField(inputs.limitsByMimeJson, isPositiveWhole, () => {
668
- report('inputs', 'Limits by type must be a JSON object of positive whole numbers.', 'limitsByMimeJson');
669
- });
667
+ const limitsByMime = compileLimitsByMime(inputs, report);
670
668
  const slots = compileSlots(inputs, report);
671
669
  const context = compileContext(inputs, report);
672
670
  return {
@@ -693,10 +691,62 @@ function compileContext(inputs, report) {
693
691
  checkWhole(report, 'inputs', 'contextMaxChars', 'Max characters', inputs.contextMaxChars, 1);
694
692
  return { from: [...inputs.contextFrom], maxChars: inputs.contextMaxChars ?? 0 };
695
693
  }
694
+ /** Each type's largest file; a type left blank keeps `maxBytes`. */
695
+ function compileLimitsByMime(inputs, report) {
696
+ const entries = Object.entries(inputs.limitsByMime);
697
+ for (const [mime, bytes] of entries) {
698
+ if (Number.isInteger(bytes) && bytes >= 1)
699
+ continue;
700
+ report('inputs', `Max size for ${mime} must be a whole number of at least 1.`, 'limitsByMime');
701
+ }
702
+ return entries.length ? { ...inputs.limitsByMime } : undefined;
703
+ }
704
+ /** One slot's problems, each on its row: a missing or repeated name or value. */
705
+ function slotProblems(slot, at, slots) {
706
+ const name = slot.name.trim();
707
+ const problems = [];
708
+ if (!name)
709
+ problems.push('Name this slot.');
710
+ else if (slots.findIndex((other) => other.name.trim() === name) < at) {
711
+ problems.push(`Another slot is called ${name}.`);
712
+ }
713
+ const values = slot.choices.map((choice) => choice.value.trim());
714
+ if (!values.some(Boolean))
715
+ problems.push('Give this slot a choice.');
716
+ if (slot.choices.some((choice, index) => !values[index] && choice.description.trim())) {
717
+ problems.push('Every choice with a description needs a value.');
718
+ }
719
+ const repeated = values.filter((value, index) => value && values.indexOf(value) < index);
720
+ for (const value of new Set(repeated))
721
+ problems.push(`${value} is a choice twice.`);
722
+ return problems;
723
+ }
724
+ /**
725
+ * Each slot by name. A slot with no label and no descriptions is its list of values; any other
726
+ * is `{ label?, choices }`. A choice left blank is left out.
727
+ */
696
728
  function compileSlots(inputs, report) {
697
- return recordField(inputs.slotsJson, isValueList, () => {
698
- report('inputs', 'Slots must be a JSON object of lists of text.', 'slotsJson');
729
+ if (!inputs.slots.length)
730
+ return undefined;
731
+ inputs.slots.forEach((slot, at) => {
732
+ for (const problem of slotProblems(slot, at, inputs.slots)) {
733
+ report('inputs', problem, 'slots', at);
734
+ }
699
735
  });
736
+ return Object.fromEntries(inputs.slots.map((slot) => {
737
+ const label = slot.label.trim();
738
+ const choices = slot.choices
739
+ .filter((choice) => choice.value.trim())
740
+ .map((choice) => ({ value: choice.value.trim(), description: choice.description.trim() }));
741
+ const plain = !label && choices.every((choice) => !choice.description);
742
+ const decl = plain
743
+ ? choices.map((choice) => choice.value)
744
+ : {
745
+ ...(label ? { label } : {}),
746
+ choices: choices.map(({ value, description }) => description ? { value, description } : { value }),
747
+ };
748
+ return [slot.name.trim(), decl];
749
+ }));
700
750
  }
701
751
  /** A call profile's inputs are its slots and context, and are left out when it has neither. */
702
752
  function compileLiveInputs(inputs, report) {
@@ -706,10 +756,6 @@ function compileLiveInputs(inputs, report) {
706
756
  return {};
707
757
  return { inputs: { ...(slots ? { slots } : {}), ...(context ? { context } : {}) } };
708
758
  }
709
- const isPositiveWhole = (value) => typeof value === 'number' && Number.isInteger(value) && value > 0;
710
- const isValueList = (value) => Array.isArray(value) &&
711
- value.length > 0 &&
712
- value.every((item) => typeof item === 'string' && item.trim() !== '');
713
759
  /** `shaped`: the type takes a structured reply and its validation (text only). */
714
760
  function compileOutputs(outputs, shaped, report) {
715
761
  let structured;
@@ -1313,6 +1359,8 @@ function omitOutOfScope(profile) {
1313
1359
  /** The draft's decision questions, each problem reported on the Decision facet. */
1314
1360
  function compileQuestions(decision, report) {
1315
1361
  const questions = Object.create(null);
1362
+ if (decision.questionsBuilt)
1363
+ return questions;
1316
1364
  if (!decision.questions.length) {
1317
1365
  report('decision', 'Add at least one question.', 'questions');
1318
1366
  }
@@ -1546,7 +1594,7 @@ function compileDecision(draft, report, on) {
1546
1594
  return {
1547
1595
  profile,
1548
1596
  customTools: [],
1549
- questions,
1597
+ ...(decision.questionsBuilt ? {} : { questions }),
1550
1598
  ...(Object.keys(images).length ? { images: { ...images } } : {}),
1551
1599
  };
1552
1600
  }
@@ -26,12 +26,17 @@ export declare function decisionExampleAssets(): Promise<{
26
26
  export declare function createDecisionExampleDraft(): Promise<StudioDraft>;
27
27
  /** The decision example with the pictures given: none for a page that only shows its shape. */
28
28
  export declare function decisionExampleDraft(images?: DecisionImageDraft[]): StudioDraft;
29
- /** A tool-call safety decision using the free Span model and its Number question shape. */
30
- export declare function createSpanExampleDraft(): StudioDraft;
31
29
  /** A multimodal embedding profile using Gemini Embeddings 2's free preview model, taking every file type it does. */
32
30
  export declare function createGeminiEmbeddingExampleDraft(): StudioDraft;
33
31
  /** The demo tools named, in the library's order. */
34
32
  export declare function exampleTools(names: readonly string[]): ToolSpecDraft[];
33
+ /** The agent id the research page-reader opens under. */
34
+ export declare const RESEARCH_PAGE_READER_AGENT_ID = "research.pagereader";
35
+ /**
36
+ * What the page-reader's questions are asked about: a research `question` and a
37
+ * `passage` cut from a tool result — not the blank decision's tool-call stub.
38
+ */
39
+ export declare const RESEARCH_PAGE_READER_STATE: string;
35
40
  /** The decision page-reader (`research.pagereader`) that filters passages for `research.scout` at `post_tool`. */
36
41
  export declare function createPageReaderExampleDraft(): StudioDraft;
37
42
  /** The research scout on its own: searches papers, models, datasets, repos, and docs. */
@@ -52,12 +57,30 @@ export declare function createConsoleExampleDraft(): StudioDraft;
52
57
  export declare function addArchitectExample(workspace: StudioWorkspace): StudioWorkspace;
53
58
  /** A workspace of the code architect and its narrator, with the architect in the chat. */
54
59
  export declare function createArchitectWorkspace(): StudioWorkspace;
55
- export type CookbookId = 'research' | 'concierge' | 'architect' | 'live-concierge' | 'decision' | 'span-decision' | 'gemini-embedding-2' | 'narrator' | 'console';
60
+ export type CookbookId = 'research' | 'concierge' | 'architect' | 'live-concierge' | 'decision' | 'gemini-embedding-2' | 'narrator' | 'console';
61
+ /**
62
+ * Searchable pieces a cookbook recipe includes. Closed for chips and search.
63
+ * The cookbook screen shows the build kind (`system` → multi-agent, `agent` →
64
+ * agent) plus a short slice of these, with the rest collapsed as `+N`.
65
+ */
66
+ export type CookbookIncludeTag = 'text' | 'decision' | 'live' | 'speech' | 'embedding' | 'host' | 'http-tools' | 'mcp-tools' | 'agent-tools' | 'function-tools' | 'guardrails' | 'post-tool';
67
+ /** Tags the cookbook screen and search project; do not invent chips in the UI. */
68
+ export interface CookbookTags {
69
+ includes: readonly CookbookIncludeTag[];
70
+ }
56
71
  export interface CookbookEntry {
57
72
  id: CookbookId;
58
73
  kind: 'agent' | 'system';
74
+ /** Short phrase that grounds the recipe on the cookbook screen (e.g. verified research). */
75
+ verb: string;
59
76
  label: string;
60
77
  description: string;
78
+ tags: CookbookTags;
79
+ /**
80
+ * What this recipe actually demonstrates in its workspace — for MCP paste briefs.
81
+ * Only patterns present in the draft; do not invent.
82
+ */
83
+ teaches: readonly string[];
61
84
  question?: string;
62
85
  createWorkspace: () => StudioWorkspace | Promise<StudioWorkspace>;
63
86
  addToWorkspace: (workspace: StudioWorkspace) => StudioWorkspace | Promise<StudioWorkspace>;
@@ -198,7 +198,7 @@ export function decisionExampleDraft(images = []) {
198
198
  const binding = draft.modelBindings[0];
199
199
  return {
200
200
  ...draft,
201
- identity: { ...draft.identity, agentId: DECISION_EXAMPLE_AGENT_ID, handle: 'jev' },
201
+ identity: { ...draft.identity, agentId: DECISION_EXAMPLE_AGENT_ID, handle: 'pantry' },
202
202
  modelBindings: binding ? [{ ...binding, apiId: 'jev-1.14.0', options: { images: true } }] : [],
203
203
  decision: {
204
204
  ...draft.decision,
@@ -226,44 +226,6 @@ export function decisionExampleDraft(images = []) {
226
226
  },
227
227
  };
228
228
  }
229
- /** A tool-call safety decision using the free Span model and its Number question shape. */
230
- export function createSpanExampleDraft() {
231
- const draft = setProfileType(createBlankDraft(), 'decision', EXAMPLE_PICKS);
232
- return {
233
- ...draft,
234
- identity: { ...draft.identity, agentId: 'guardrails.tool_call.span', handle: 'span' },
235
- modelBindings: [
236
- {
237
- ...draft.modelBindings[0],
238
- ...firstServed('openrouter', 'decision'),
239
- apiId: 'respan/span-01-lite:free',
240
- },
241
- ],
242
- decision: {
243
- ...draft.decision,
244
- questions: [
245
- {
246
- key: draftKey('question'),
247
- id: 'verdict',
248
- type: 'noul',
249
- instructions: 'Is this tool call unsafe or beyond what the user asked for?',
250
- criteria: [
251
- {
252
- key: draftKey('criterion'),
253
- label: 'true',
254
- text: 'The call is unsafe or beyond the user request.',
255
- },
256
- {
257
- key: draftKey('criterion'),
258
- label: 'false',
259
- text: 'The call is safe and within the user request.',
260
- },
261
- ],
262
- },
263
- ],
264
- },
265
- };
266
- }
267
229
  const GEMINI_EMBEDDING = {
268
230
  protocol: firstServed('gemini', 'embedding').protocol,
269
231
  apiId: 'gemini-embedding-2-preview',
@@ -403,8 +365,8 @@ function exampleTextDraft(identity, tools) {
403
365
  maxFiles: inputs.maxFiles,
404
366
  maxBytes: inputs.maxBytes,
405
367
  maxTurnBytes: inputs.maxTurnBytes,
406
- limitsByMimeJson: '',
407
- slotsJson: '',
368
+ limitsByMime: {},
369
+ slots: [],
408
370
  contextFrom: [],
409
371
  contextMaxChars: null,
410
372
  },
@@ -416,13 +378,28 @@ function exampleTextDraft(identity, tools) {
416
378
  },
417
379
  };
418
380
  }
381
+ /** The agent id the research page-reader opens under. */
382
+ export const RESEARCH_PAGE_READER_AGENT_ID = 'research.pagereader';
383
+ /**
384
+ * What the page-reader's questions are asked about: a research `question` and a
385
+ * `passage` cut from a tool result — not the blank decision's tool-call stub.
386
+ */
387
+ export const RESEARCH_PAGE_READER_STATE = JSON.stringify({
388
+ question: 'What write path do recent systems use to store episodic memory for language-model agents?',
389
+ passage: 'MemGPT (Packer et al.) pages conversational history into an external store and reloads ' +
390
+ 'relevant spans on later turns, treating context as a virtual memory hierarchy rather than a single prompt window.',
391
+ }, null, 2);
419
392
  /** The decision page-reader (`research.pagereader`) that filters passages for `research.scout` at `post_tool`. */
420
393
  export function createPageReaderExampleDraft() {
421
394
  const draft = setProfileType(createBlankDraft(), 'decision', EXAMPLE_PICKS);
422
395
  const binding = draft.modelBindings[0];
423
396
  return {
424
397
  ...draft,
425
- identity: { ...draft.identity, agentId: 'research.pagereader', handle: 'pagereader' },
398
+ identity: {
399
+ ...draft.identity,
400
+ agentId: RESEARCH_PAGE_READER_AGENT_ID,
401
+ handle: 'pagereader',
402
+ },
426
403
  modelBindings: binding ? [{ ...binding, apiId: 'jev-latest' }] : [],
427
404
  decision: {
428
405
  ...draft.decision,
@@ -445,6 +422,15 @@ export function createResearchScoutDraft() {
445
422
  const base = exampleTextDraft({ agentId: 'research.scout', handle: 'scout', system: DEMO_RESEARCH_SYSTEM }, { tools: { t2Loader: '', parallel: true }, toolSpecs: exampleTools(DEMO_RESEARCH_TOOLS) });
446
423
  return {
447
424
  ...base,
425
+ // Goals starts here: leave attachments and effort select off so examples earn them.
426
+ inputs: {
427
+ ...base.inputs,
428
+ attachmentsAccept: [],
429
+ voiceAccept: [],
430
+ maxFiles: null,
431
+ maxBytes: null,
432
+ maxTurnBytes: null,
433
+ },
448
434
  models: {
449
435
  defaultModel: 'gemini',
450
436
  allowModelSelect: false,
@@ -462,7 +448,7 @@ export function createResearchScoutDraft() {
462
448
  { alias: 'deep', level: 'high' },
463
449
  ],
464
450
  defaultEffort: 'normal',
465
- allowEffortSelect: true,
451
+ allowEffortSelect: false,
466
452
  summaries: true,
467
453
  }),
468
454
  ],
@@ -612,8 +598,19 @@ export const COOKBOOKS = {
612
598
  research: {
613
599
  id: 'research',
614
600
  kind: 'system',
601
+ verb: 'every claim checked',
615
602
  label: 'Research scout',
616
- description: 'Searches papers, repos, and model cards; Jev filters pages and a check verifies quotes.',
603
+ description: 'Ask a hard question about models, papers, or memory. It searches the Hub, arXiv, and GitHub, cuts each page to the passages that bear on the question, and will not let a quote through unchecked.',
604
+ tags: {
605
+ includes: ['text', 'decision', 'http-tools', 'mcp-tools', 'guardrails', 'post-tool'],
606
+ },
607
+ teaches: [
608
+ 'A multi-agent system: text agent `research.scout` plus decision agent `research.pagereader` (Jev).',
609
+ 'Staging page-read tools at `post_tool` via `stageAgentKey`: `read_pages`, `read_model_card`, `read_dataset_card`, `read_readme`, and `read_library_docs` are filtered by the page-reader before the scout sees them.',
610
+ 'Parallel tool calls (`tools.parallel: true`) across HTTP tools (arXiv, GitHub, Hub cards) and MCP tools (Exa `search_web` / `read_pages`, Context7 library docs, DeepWiki `ask_repo_docs`).',
611
+ 'Guardrails that flag every detector on untrusted page text, with `allowedHosts` limited to the research hosts.',
612
+ 'Turn behaviour with resume, auto-continue on length / stream_incomplete / provider_error, and steering.',
613
+ ],
617
614
  question: RESEARCH_FIRST_TURN_PROMPT,
618
615
  createWorkspace: createResearchWorkspace,
619
616
  addToWorkspace: addResearchExample,
@@ -621,64 +618,121 @@ export const COOKBOOKS = {
621
618
  concierge: {
622
619
  id: 'concierge',
623
620
  kind: 'agent',
621
+ verb: 'travel from the facts',
624
622
  label: 'Travel concierge',
625
- description: 'Text agent with weather, places, currency, and trip tools.',
623
+ description: 'Hand it a destination, a ticket, or a photo of your boarding pass. It checks weather, places, and currency before it plans — and never invents a forecast.',
624
+ tags: {
625
+ includes: ['text', 'http-tools', 'mcp-tools', 'function-tools', 'guardrails'],
626
+ },
627
+ teaches: [
628
+ 'A text agent that takes attachments (images, PDF, text) and optional voice, then grounds weather, places, and currency in tools before it answers.',
629
+ 'A turn-time tool loader (`t2Loader: discover_tools`) that can pull in extra demo tools during the turn.',
630
+ 'Mixing HTTP tools (geocode, weather, currency, Wikipedia), MCP (`search_web`), and local function tools (distances, day plan, packing, budget).',
631
+ 'Silent tool use in the system prompt: no narrating tool names; findings land in the reply.',
632
+ 'Reply-side detect set to block sensitive and injection phrasing, with `allowedHosts` for the travel hosts.',
633
+ ],
626
634
  createWorkspace: workspaceOf(createExampleDraft),
627
635
  addToWorkspace: addsDraft(createExampleDraft),
628
636
  },
629
637
  architect: {
630
638
  id: 'architect',
631
639
  kind: 'system',
640
+ verb: 'advise from the repo',
632
641
  label: 'Code architect',
633
- description: 'Reads repos and docs. Brings a Narrator it calls for audio.',
642
+ description: 'Point it at a repository or a library. It reads the docs and the code before it advises, then can send a Narrator to record a short spoken briefing of what it found.',
643
+ tags: {
644
+ includes: ['text', 'speech', 'http-tools', 'mcp-tools', 'agent-tools', 'guardrails'],
645
+ },
646
+ teaches: [
647
+ 'A multi-agent system: text agent `code.architect` plus speech agent `studio.narrator`.',
648
+ 'An agent tool (`narrate`) that lets the architect call the narrator and get audio back.',
649
+ 'Grounding advice in repo and package tools before answering (`ask_repo_docs`, `read_repo_file`, `lookup_package`, Context7 `find_library` / `read_library_docs`).',
650
+ 'Vendor docs over MCP (Microsoft, Cloudflare, AWS, Hugging Face, Astro) alongside web search.',
651
+ 'A speech profile with a fixed spoken style for briefings.',
652
+ ],
634
653
  createWorkspace: createArchitectWorkspace,
635
654
  addToWorkspace: addArchitectExample,
636
655
  },
637
656
  'live-concierge': {
638
657
  id: 'live-concierge',
639
658
  kind: 'agent',
659
+ verb: 'travel on the call',
640
660
  label: 'Live concierge',
641
- description: 'The concierge as a voice call, with the same tools.',
661
+ description: 'The same concierge, on a voice call. It still grounds weather, places, and money in the tools — it just answers out loud, in short sentences.',
662
+ tags: {
663
+ includes: ['live', 'http-tools', 'mcp-tools', 'function-tools', 'guardrails'],
664
+ },
665
+ teaches: [
666
+ 'The travel concierge tools on a `live` profile instead of text.',
667
+ 'Spoken replies: short sentences, no markdown lists, still grounded in the same weather / places / currency tools.',
668
+ ],
642
669
  createWorkspace: workspaceOf(createLiveExampleDraft),
643
670
  addToWorkspace: addsDraft(createLiveExampleDraft),
644
671
  },
645
672
  decision: {
646
673
  id: 'decision',
647
674
  kind: 'agent',
648
- label: 'Jev decision',
649
- description: 'Asks Jev about a pantry photo: finds things in it and answers questions.',
675
+ verb: 'ask the photograph',
676
+ label: 'Pantry',
677
+ description: 'Show Jev a pantry shelf. It draws boxes around what it finds and answers brunch questions from what is actually there — not from what it remembers.',
678
+ tags: {
679
+ includes: ['decision', 'guardrails'],
680
+ },
681
+ teaches: [
682
+ 'A `decision` profile on TypeSafe Jev 1.14 with `images: true`.',
683
+ 'Question kinds in one contract (`pantry.v1`): `box`, `noul`, and `choice`.',
684
+ 'State image `photo` (the shelf) plus decision-owned reference images (`<ginger>`, `<apple_ripeness>`, `<union_jack>`) named from questions.',
685
+ 'Box questions that locate things in `photo` or on a reference chart; choice for brunch from what is on the shelf.',
686
+ ],
650
687
  createWorkspace: workspaceOf(createDecisionExampleDraft),
651
688
  addToWorkspace: addsDraft(createDecisionExampleDraft),
652
689
  },
653
- 'span-decision': {
654
- id: 'span-decision',
655
- kind: 'agent',
656
- label: 'Span guardrail',
657
- description: 'Checks whether a proposed tool call is safe on the free Span decision model.',
658
- createWorkspace: workspaceOf(createSpanExampleDraft),
659
- addToWorkspace: addsDraft(createSpanExampleDraft),
660
- },
661
690
  'gemini-embedding-2': {
662
691
  id: 'gemini-embedding-2',
663
692
  kind: 'agent',
693
+ verb: 'embed what you see',
664
694
  label: 'Gemini Embeddings 2',
665
- description: 'Multimodal embedding preview with Gemini Embeddings 2.',
695
+ description: 'Drop in text, images, or files. Gemini Embeddings 2 turns them into vectors you can search and compare — multimodal, on the free preview.',
696
+ tags: {
697
+ includes: ['embedding'],
698
+ },
699
+ teaches: [
700
+ 'An `embedding` profile on Gemini Embeddings 2 preview.',
701
+ 'Multimodal inputs: every media kind that model accepts, capped at six files.',
702
+ 'Output dimensionality set on the binding (`outputDimensionality: 768`).',
703
+ ],
666
704
  createWorkspace: workspaceOf(createGeminiEmbeddingExampleDraft),
667
705
  addToWorkspace: addsDraft(createGeminiEmbeddingExampleDraft),
668
706
  },
669
707
  narrator: {
670
708
  id: 'narrator',
671
709
  kind: 'agent',
710
+ verb: 'hear the briefing',
672
711
  label: 'Narrator',
673
- description: 'Reads a script aloud.',
712
+ description: 'Give it a short script in plain sentences. It reads the briefing aloud — warm, unhurried, as if it were speaking to one listener.',
713
+ tags: {
714
+ includes: ['speech', 'guardrails'],
715
+ },
716
+ teaches: [
717
+ 'A standalone `speech` profile with guardrails included.',
718
+ 'A fixed speech style string for how the briefing should sound.',
719
+ ],
674
720
  createWorkspace: workspaceOf(createNarratorExampleDraft),
675
721
  addToWorkspace: addsDraft(createNarratorExampleDraft),
676
722
  },
677
723
  console: {
678
724
  id: 'console',
679
725
  kind: 'agent',
726
+ verb: 'tools, no model',
680
727
  label: 'Tool console',
681
- description: 'No model. Run its tools by hand.',
728
+ description: 'No language model in the loop. Press a tool, watch the result — HTTP, MCP, and functions side by side, for when you want the wiring without the chat.',
729
+ tags: {
730
+ includes: ['host', 'http-tools', 'mcp-tools', 'function-tools'],
731
+ },
732
+ teaches: [
733
+ 'A `host` profile with no model — tools only.',
734
+ 'A small set of demo tools spanning HTTP and other result shapes, run by hand from the console.',
735
+ ],
682
736
  createWorkspace: workspaceOf(createConsoleExampleDraft),
683
737
  addToWorkspace: addsDraft(createConsoleExampleDraft),
684
738
  },