@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/replay.js CHANGED
@@ -40,6 +40,46 @@ const byStart = (a, b) => {
40
40
  const order = startOf(a) - startOf(b);
41
41
  return order === 0n ? 0 : order < 0n ? -1 : 1;
42
42
  };
43
+ /**
44
+ * Wall-clock start/end (epoch ms) of a finished span. Live tool phases and
45
+ * `stampWorked` use the same clocks; recordings read them from the span.
46
+ */
47
+ function boundsOf(span) {
48
+ const endRaw = span.endTimeUnixNano;
49
+ if (!endRaw)
50
+ return undefined;
51
+ const start = startOf(span);
52
+ const end = BigInt(String(endRaw));
53
+ if (end <= start)
54
+ return undefined;
55
+ const startedAt = Number(start / 1000000n);
56
+ const endedAt = Number(end / 1000000n);
57
+ if (!Number.isFinite(startedAt) || !Number.isFinite(endedAt) || endedAt <= startedAt) {
58
+ return undefined;
59
+ }
60
+ return { startedAt, endedAt };
61
+ }
62
+ /**
63
+ * How long the turn worked on the wall clock, from the root span's start/end.
64
+ * Live chats stamp this on `turn-done` via `stampWorked`; recordings must too
65
+ * or the opener only says "Worked".
66
+ */
67
+ function workedOf(root) {
68
+ const bounds = boundsOf(root);
69
+ if (!bounds)
70
+ return undefined;
71
+ return { workedMs: bounds.endedAt - bounds.startedAt, endedAt: bounds.endedAt };
72
+ }
73
+ /** `blocks` with its last `turn-done` carrying the root span's work (same as live `stampWorked`). */
74
+ function stampOpeningWork(blocks, root) {
75
+ const worked = workedOf(root);
76
+ if (!worked)
77
+ return blocks;
78
+ const last = blocks.findLastIndex((block) => block.kind === 'turn-done');
79
+ if (last < 0)
80
+ return blocks;
81
+ return blocks.map((block, index) => (index === last ? { ...block, ...worked } : block));
82
+ }
43
83
  /** A part whose content the record does not hold keeps its hash. */
44
84
  const unrecorded = (part) => 'content_sha256' in part || 'json_sha256' in part;
45
85
  /** A tool call's arguments, as the model sent them. */
@@ -219,7 +259,12 @@ function toolEvents(record, name, callId, args, toolSpan) {
219
259
  const made = { type: 'tool', tool: { name, callId, arguments: args } };
220
260
  if (!span)
221
261
  return [made];
222
- const at = Number(startOf(span) / 1000000n);
262
+ // why: Live emits running then settle with `at` clocks; the fold only sets
263
+ // startedAt on running. Recordings hold the same clocks on the execute_tool
264
+ // span — emit both phases or the chat hides tool duration.
265
+ const bounds = boundsOf(span);
266
+ const startedAt = bounds?.startedAt ?? Number(startOf(span) / 1000000n);
267
+ const endedAt = bounds?.endedAt ?? startedAt;
223
268
  const result = contentText(record, span, 'gen_ai.tool.call.result');
224
269
  const failed = stringAttribute(span, 'theorem.tool.outcome') === 'error';
225
270
  // why: historyFromTranscriptBlocks replays settled calls via `readBack`; a live turn sets it on
@@ -237,7 +282,8 @@ function toolEvents(record, name, callId, args, toolSpan) {
237
282
  : { phase: 'complete', output: parsed(result), readBack: result };
238
283
  return [
239
284
  made,
240
- { type: 'tool', tool: { name, callId, at, ...settled } },
285
+ { type: 'tool', tool: { name, callId, phase: 'running', at: startedAt } },
286
+ { type: 'tool', tool: { name, callId, at: endedAt, ...settled } },
241
287
  ...groundingSources(record, span),
242
288
  ];
243
289
  }
@@ -278,9 +324,9 @@ export function replayScript(records) {
278
324
  ...sent,
279
325
  calls,
280
326
  results,
281
- blocks: foldConversationTurn({ text: sent.text }, shownEvents(record, root), {
327
+ blocks: stampOpeningWork(foldConversationTurn({ text: sent.text }, shownEvents(record, root), {
282
328
  idPrefix: `recorded-${String(index)}`,
283
- }),
329
+ }), root),
284
330
  });
285
331
  });
286
332
  return { agent, turns, ...(recordedAt === undefined ? {} : { recordedAt }) };
@@ -406,7 +452,9 @@ export function recordedTranscript(script) {
406
452
  /**
407
453
  * The conversation a recording opens as history: the same blocks Replay exchange shows and
408
454
  * Continue live seeds. Goals and any host that starts on a `.trace.json` use this, not a second
409
- * hand-written exchange.
455
+ * hand-written exchange. Each assistant `turn-done` carries `workedMs` / `endedAt` from its root
456
+ * span, as a live chat's `stampWorked` would. Each settled tool carries `startedAt` / `endedAt`
457
+ * from its `execute_tool` span (via running then settle), as a live turn would.
410
458
  */
411
459
  export function openingFromRecords(records) {
412
460
  return recordedTranscript(replayScript(records));
package/requirements.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  /** Shared by the compiler and the editor so both agree; mirrors the kernel's `PROFILE_FIELD_PRESENCE`. */
2
2
  import type { InputsDraft, ModelBindingDraft, StudioDraft } from './draft.ts';
3
+ import { type StudioProvider } from './providers.ts';
3
4
  export declare function defaultModelRequired(draft: StudioDraft): boolean;
4
5
  /**
5
6
  * Whether a model other than a local one reads no vault slot: not its own, its provider's, or the
@@ -18,5 +19,7 @@ export declare function bindingSlots(draft: StudioDraft, binding: ModelBindingDr
18
19
  fallbackKeySlot: boolean;
19
20
  };
20
21
  };
22
+ /** The providers whose models read `slot`, first or as fallback: the ones a key there is for. */
23
+ export declare function slotProviders(draft: StudioDraft, slot: string): StudioProvider[];
21
24
  export declare function defaultEffortRequired(binding: ModelBindingDraft): boolean;
22
25
  export declare function inputLimitsRequired(inputs: InputsDraft): boolean;
package/requirements.js CHANGED
@@ -29,6 +29,16 @@ export function bindingSlots(draft, binding) {
29
29
  },
30
30
  };
31
31
  }
32
+ /** The providers whose models read `slot`, first or as fallback: the ones a key there is for. */
33
+ export function slotProviders(draft, slot) {
34
+ const ids = new Set(draft.modelBindings
35
+ .filter((binding) => {
36
+ const read = bindingSlots(draft, binding);
37
+ return read.keySlot === slot || read.fallbackKeySlot === slot;
38
+ })
39
+ .map((binding) => binding.provider));
40
+ return draft.providers.filter((provider) => ids.has(provider.id));
41
+ }
32
42
  export function defaultEffortRequired(binding) {
33
43
  const aliases = binding.efforts.map(({ alias }) => alias.trim()).filter(Boolean);
34
44
  return new Set(aliases).size > 1;
@@ -0,0 +1,23 @@
1
+ /**
2
+ * What the studio command prints when a project opens: what it loaded and from where, each thing
3
+ * the page would flag, one line each, and what each provider said of its key, so a builder sees it
4
+ * without opening the page. `--quiet` turns it off.
5
+ *
6
+ * @module
7
+ */
8
+ import type { KeyCheck } from '@theoremjs/agents';
9
+ import type { StudioDescription } from './handler.ts';
10
+ /**
11
+ * What the project loaded, and from where, as the lines the command prints first. `keys` is
12
+ * what the checks said, once they have.
13
+ */
14
+ export declare function loadedText(description: StudioDescription, at: {
15
+ entry?: string;
16
+ keys: 'checking' | 'offline' | readonly string[];
17
+ }): string;
18
+ /** What one provider said of its key, as a line for the terminal. Never the key. */
19
+ export declare function keyLine(check: KeyCheck): string;
20
+ /** Each thing about the project the builder should look at, as a line for the terminal. */
21
+ export declare function alertLines(description: StudioDescription): string[];
22
+ /** The lines as one message for the terminal, or undefined when there is nothing to look at. */
23
+ export declare function alertText(description: StudioDescription): string | undefined;
@@ -0,0 +1,82 @@
1
+ /**
2
+ * What the studio command prints when a project opens: what it loaded and from where, each thing
3
+ * the page would flag, one line each, and what each provider said of its key, so a builder sees it
4
+ * without opening the page. `--quiet` turns it off.
5
+ *
6
+ * @module
7
+ */
8
+ /**
9
+ * What the project loaded, and from where, as the lines the command prints first. `keys` is
10
+ * what the checks said, once they have.
11
+ */
12
+ export function loadedText(description, at) {
13
+ const { agents, toolSpecs } = description.workspace;
14
+ const agentList = agents.map((agent) => {
15
+ const providers = [...new Set(agent.modelBindings.map((binding) => binding.provider))];
16
+ const type = agent.identity.profileType || 'no type';
17
+ return `${agent.identity.agentId || agent.key} (${[type, ...providers].join(', ')})`;
18
+ });
19
+ const kinds = new Map();
20
+ for (const tool of toolSpecs)
21
+ kinds.set(tool.toolType, (kinds.get(tool.toolType) ?? 0) + 1);
22
+ const tools = [...kinds].map(([kind, count]) => `${count} ${kind}`).join(', ');
23
+ const named = new Set(agents.flatMap((agent) => agent.modelBindings.map((b) => b.provider)));
24
+ const keys = named.size === 0
25
+ ? 'no model names a provider'
26
+ : at.keys === 'offline'
27
+ ? 'not checked (--offline)'
28
+ : at.keys === 'checking'
29
+ ? `checking ${[...named].join(', ')}…`
30
+ : at.keys.join('\n ');
31
+ return [
32
+ `theorem studio: ${description.project}`,
33
+ ` setup ${description.setup ?? 'none'}${at.entry ? ` → entry ${at.entry}` : ''}`,
34
+ ` agents ${agentList.join('; ') || 'none'}`,
35
+ ` tools ${tools || 'none'}`,
36
+ ` keys ${keys}`,
37
+ ].join('\n');
38
+ }
39
+ /** What one provider said of its key, as a line for the terminal. Never the key. */
40
+ export function keyLine(check) {
41
+ const slot = check.slot ? ` (${check.slot})` : '';
42
+ const status = check.status === undefined ? '' : ` ${check.status}`;
43
+ const said = check.said ? `: ${check.said.replaceAll('\n', ' ')}` : '';
44
+ const what = {
45
+ accepted: 'works',
46
+ refused: `refused${status}${said}`,
47
+ unreachable: `could not be checked${status}${said || ': no answer'}`,
48
+ empty: check.slot ? 'is empty' : 'is in no slot: no model or registration names one',
49
+ unchecked: check.said ? `could not be checked${said}` : 'has no check to ask',
50
+ }[check.state];
51
+ return `key for ${check.provider}${slot} ${what}`;
52
+ }
53
+ /** How many of a difference's settings a line names before it says how many more. */
54
+ const NAMED_SETTINGS = 3;
55
+ function settingsList(settings) {
56
+ const named = settings.slice(0, NAMED_SETTINGS).join(', ');
57
+ const more = settings.length - NAMED_SETTINGS;
58
+ return more > 0 ? `${named} and ${more} more` : named;
59
+ }
60
+ /** Each thing about the project the builder should look at, as a line for the terminal. */
61
+ export function alertLines(description) {
62
+ const { problems, modelProblems = [], differences = [], unheld = [], unregistered = [], unloaded, peopleProblem, } = description;
63
+ return [
64
+ ...(unloaded === undefined
65
+ ? []
66
+ : [`The files stopped loading; the studio shows the last load that did:\n${unloaded}`]),
67
+ ...unheld.map((message) => `The project does not compile as the studio opened it: ${message}`),
68
+ ...problems.map(({ profile, message }) => `${profile}: ${message}`),
69
+ ...modelProblems.map(({ profile, model, message }) => `${profile}, model ${model}: ${message}`),
70
+ ...differences.map(({ kind, of, settings }) => `${kind} ${of} opens differently from what the project registered, in ${settings.length} ${settings.length === 1 ? 'setting' : 'settings'}: ${settingsList(settings)}`),
71
+ ...unregistered.map(({ kind, name, file, line }) => `${kind} ${name} is defined at ${file}:${line} but the project did not register it`),
72
+ ...(peopleProblem === undefined ? [] : [`people: ${peopleProblem}`]),
73
+ ];
74
+ }
75
+ /** The lines as one message for the terminal, or undefined when there is nothing to look at. */
76
+ export function alertText(description) {
77
+ const lines = alertLines(description);
78
+ if (lines.length === 0)
79
+ return undefined;
80
+ const heading = `theorem studio: ${lines.length} ${lines.length === 1 ? 'thing' : 'things'} to look at in ${description.project}`;
81
+ return [heading, ...lines.map((line) => ` - ${line.replaceAll('\n', '\n ')}`)].join('\n');
82
+ }
@@ -13,6 +13,7 @@
13
13
  */
14
14
  import { type ResolveHost } from '@theoremjs/agents';
15
15
  import type { TranscriptBlock } from '@theoremjs/agents/interface';
16
+ import type { RegisteredProvider } from '@theoremjs/agents/kernel';
16
17
  import { type PageToolBroker, type SteerInbox, type TheoremSessionStore } from '@theoremjs/web/server';
17
18
  import type { LentKeys } from '../lent-keys.ts';
18
19
  import type { StudioRuntime } from '../runtime-scope.ts';
@@ -63,6 +64,8 @@ export type StudioDraftHandlerOptions = {
63
64
  * whatever the draft says, so no visitor reaches the host's own network.
64
65
  */
65
66
  draftNetwork?: boolean;
67
+ /** A provider the project registers from a definition of its own, so its key can be checked. */
68
+ projectProvider?: (id: string) => RegisteredProvider | undefined;
66
69
  };
67
70
  /**
68
71
  * Answers a request under `STUDIO_BASE`; `defer` keeps work running after the reply (a Worker's
@@ -200,7 +200,11 @@ export function createStudioDraftHandler(options = {}) {
200
200
  const route = path.startsWith(`${STUDIO_BASE}/`) ? path.slice(STUDIO_BASE.length + 1) : '';
201
201
  const routes = {
202
202
  probe: (asked) => draftProbe(asked, options.onProbePassed, defer ?? (() => { })),
203
- 'test-key': testKey,
203
+ 'test-key': (asked) => testKey(asked, {
204
+ resolveHost,
205
+ draftNetwork: options.draftNetwork,
206
+ projectProvider: options.projectProvider,
207
+ }),
204
208
  'test-connection': (asked) => testConnection(asked, { resolveHost, draftNetwork: options.draftNetwork }),
205
209
  ...(lent ? lentRoutes(lent) : {}),
206
210
  };
@@ -0,0 +1,38 @@
1
+ /**
2
+ * What happened in a studio run that the builder, or an agent beside them, should know of: what
3
+ * the project has to look at, what each provider said of its key, a run that failed, and an error
4
+ * in the page. The last 200 are kept, so `theorem-studio errors` can read them, and a follower is
5
+ * told each new one. A run that ends well is not one.
6
+ *
7
+ * @module
8
+ */
9
+ /** One thing that happened. */
10
+ export interface StudioEvent {
11
+ /** When, as an ISO time. */
12
+ at: string;
13
+ /** What it is about: what the project has to look at, a key, a run, or the page. */
14
+ kind: 'look' | 'key' | 'run' | 'page';
15
+ text: string;
16
+ /** How many times in a row it happened, when more than once. */
17
+ repeated?: number;
18
+ }
19
+ /** How many events the log keeps. */
20
+ export declare const EVENTS_KEPT = 200;
21
+ export interface StudioEventLog {
22
+ /** Keeps the event and tells followers. False when it repeats the last one, which is only counted. */
23
+ add(kind: StudioEvent['kind'], text: string): boolean;
24
+ list(): StudioEvent[];
25
+ /** The events as server-sent events: the ones kept, then each new one. */
26
+ follow(headers: Record<string, string>): Response;
27
+ }
28
+ export declare function createEventLog(now?: () => Date): StudioEventLog;
29
+ /**
30
+ * What a failed run said, from a line of its stream: an `error` event's detail, else its wording,
31
+ * else its kind. Undefined for any other line.
32
+ */
33
+ export declare function failureIn(line: string): string | undefined;
34
+ /**
35
+ * `response` as it was, with each failure in its stream told to `failed` as it passes. Only a
36
+ * stream of JSON lines is read; the reply reaches the page unchanged and as fast.
37
+ */
38
+ export declare function watchRun(response: Response, failed: (said: string) => void): Response;
@@ -0,0 +1,95 @@
1
+ /**
2
+ * What happened in a studio run that the builder, or an agent beside them, should know of: what
3
+ * the project has to look at, what each provider said of its key, a run that failed, and an error
4
+ * in the page. The last 200 are kept, so `theorem-studio errors` can read them, and a follower is
5
+ * told each new one. A run that ends well is not one.
6
+ *
7
+ * @module
8
+ */
9
+ import { createEventFeed } from "./watch.js";
10
+ /** How many events the log keeps. */
11
+ export const EVENTS_KEPT = 200;
12
+ /** The longest text an event keeps, so a page cannot fill the log with one. */
13
+ const TEXT_CAP = 2000;
14
+ export function createEventLog(now = () => new Date()) {
15
+ const events = [];
16
+ const feed = createEventFeed();
17
+ return {
18
+ add: (kind, said) => {
19
+ const text = said.slice(0, TEXT_CAP);
20
+ const last = events.at(-1);
21
+ if (last?.kind === kind && last.text === text) {
22
+ last.repeated = (last.repeated ?? 1) + 1;
23
+ return false;
24
+ }
25
+ const event = { at: now().toISOString(), kind, text };
26
+ events.push(event);
27
+ if (events.length > EVENTS_KEPT)
28
+ events.shift();
29
+ feed.tell(event);
30
+ return true;
31
+ },
32
+ list: () => [...events],
33
+ follow: (headers) => feed.subscribe(headers, events),
34
+ };
35
+ }
36
+ /**
37
+ * What a failed run said, from a line of its stream: an `error` event's detail, else its wording,
38
+ * else its kind. Undefined for any other line.
39
+ */
40
+ export function failureIn(line) {
41
+ let event;
42
+ try {
43
+ event = JSON.parse(line);
44
+ }
45
+ catch {
46
+ return undefined;
47
+ }
48
+ if (typeof event !== 'object' || event === null)
49
+ return undefined;
50
+ const { type, errorInternal, error, errorKind } = event;
51
+ if (type !== 'error')
52
+ return undefined;
53
+ const said = [errorInternal, error, errorKind].find((each) => typeof each === 'string' && each);
54
+ return typeof said === 'string' ? said : 'failed';
55
+ }
56
+ /**
57
+ * `response` as it was, with each failure in its stream told to `failed` as it passes. Only a
58
+ * stream of JSON lines is read; the reply reaches the page unchanged and as fast.
59
+ */
60
+ export function watchRun(response, failed) {
61
+ if (!response.ok) {
62
+ response
63
+ .clone()
64
+ .text()
65
+ .then((body) => failed(`answered ${response.status}${body ? `: ${body.slice(0, 300)}` : ''}`), () => failed(`answered ${response.status}`));
66
+ return response;
67
+ }
68
+ if (!response.body || !/ndjson/.test(response.headers.get('content-type') ?? ''))
69
+ return response;
70
+ const decoder = new TextDecoder();
71
+ let rest = '';
72
+ const read = (text) => {
73
+ const lines = (rest + text).split('\n');
74
+ rest = lines.pop() ?? '';
75
+ for (const line of lines) {
76
+ const said = failureIn(line);
77
+ if (said !== undefined)
78
+ failed(said);
79
+ }
80
+ };
81
+ const body = response.body.pipeThrough(new TransformStream({
82
+ transform(chunk, controller) {
83
+ controller.enqueue(chunk);
84
+ read(decoder.decode(chunk, { stream: true }));
85
+ },
86
+ flush() {
87
+ read(`${decoder.decode()}\n`);
88
+ },
89
+ }));
90
+ return new Response(body, {
91
+ status: response.status,
92
+ statusText: response.statusText,
93
+ headers: response.headers,
94
+ });
95
+ }
@@ -12,7 +12,8 @@
12
12
  *
13
13
  * @module
14
14
  */
15
- import { type DecisionAsset, type DecisionQuestion, type Profile, type ProviderHostOptions } from '@theoremjs/agents';
15
+ import { type DecisionAsset, type DecisionQuestion, type Profile, type ProviderHostOptions, type TurnWiring } from '@theoremjs/agents';
16
+ import { type DecisionQuestionsBuilder } from '@theoremjs/web/server';
16
17
  import { type StudioAsks } from '../asks.ts';
17
18
  import { type StudioActingAs, type StudioPeople, type StudioPeopleOffer } from '../people.ts';
18
19
  import { type StudioUpgrade } from './live.ts';
@@ -86,6 +87,8 @@ export type StudioHandlerOptions = {
86
87
  people?: StudioPeople;
87
88
  /** How the project's registered providers find their keys. Default: as the project registered them. */
88
89
  provider?: ProviderHostOptions;
90
+ /** The application's own turn, from the one a chat builds: its entry's `theorem.prepare`. */
91
+ prepare?: TurnWiring['prepare'];
89
92
  /** What each decision profile asks, by the profile's id: the questions the application passes when it decides. */
90
93
  questions?: ProjectQuestions;
91
94
  /** The pictures each decision profile sends, by the profile's id: the images the application passes when it decides. */
@@ -98,8 +101,11 @@ export type StudioHandlerOptions = {
98
101
  */
99
102
  conversationKey: string;
100
103
  };
101
- /** A project's decision questions: for each decision profile's id, its questions by their ids. */
102
- export type ProjectQuestions = Record<string, Record<string, DecisionQuestion>>;
104
+ /**
105
+ * A project's decision questions: for each decision profile's id, its questions by their ids, or
106
+ * a builder that makes them for each decision.
107
+ */
108
+ export type ProjectQuestions = Record<string, Record<string, DecisionQuestion> | DecisionQuestionsBuilder<unknown>>;
103
109
  /** A project's decision pictures: for each decision profile's id, its images by reference. */
104
110
  export type ProjectImages = Record<string, Record<string, DecisionAsset>>;
105
111
  /**
@@ -130,4 +136,6 @@ export declare function questionsFault(profileId: string, questions: unknown): s
130
136
  * Serves the studio for the tools and profiles registered when it is called.
131
137
  * Register the project first.
132
138
  */
139
+ /** Where the studio asks the project's keys: one check for each provider an agent's models name. */
140
+ export declare const KEYS_PATH = "/api/studio/keys";
133
141
  export declare function createStudioHandler(options: StudioHandlerOptions): (request: Request) => Promise<Response>;
package/server/handler.js CHANGED
@@ -12,10 +12,10 @@
12
12
  *
13
13
  * @module
14
14
  */
15
- import { defineProfile, getStructured, listProfiles, listProviders, listTools, registerTool, } from '@theoremjs/agents';
15
+ import { checkKey, defineProfile, getStructured, listProfiles, listProviders, listTools, registerTool, } from '@theoremjs/agents';
16
16
  import { compileDetect } from '@theoremjs/agents/guardrails/compile';
17
17
  import { createProviderRegistry } from '@theoremjs/agents/kernel';
18
- import { createSealedConversationStore, createTheoremDecisionHandler, createTheoremEmbeddingHandler, createTheoremHandler, createTheoremHostHandler, } from '@theoremjs/web/server';
18
+ import { createSealedConversationStore, createTheoremDecisionHandler, createTheoremEmbeddingHandler, createTheoremHandler, createTheoremHostHandler, isQuestionsBuilder, } from '@theoremjs/web/server';
19
19
  import { differingSettings } from "../agreement.js";
20
20
  import { studioAsks } from "../asks.js";
21
21
  import { compileWorkspace } from "../compile-workspace.js";
@@ -24,7 +24,7 @@ import { shownConnection, withoutCredentials } from "../held-credentials.js";
24
24
  import { ON_OWN_KEYS } from "../lent-keys.js";
25
25
  import { ACTING_AS_HEADER, actingAsSession, peopleFault, peopleOffer, readActingAs, readPerson, readPlace, } from "../people.js";
26
26
  import { STUDIO_TRACE_DESTINATION } from "../policy.js";
27
- import { kernelDefinition, registerStudioProvider } from "../providers.js";
27
+ import { kernelDefinition, modelSlots, registerStudioProvider, } from "../providers.js";
28
28
  import { readStudioSource } from "../read-source.js";
29
29
  import { STUDIO_READER } from "../reader.js";
30
30
  import { withPatterns } from "../runtime-scope.js";
@@ -114,7 +114,7 @@ function registeredProviders() {
114
114
  });
115
115
  }
116
116
  /** One registered profile as the draft the editor shows, read from the source the studio prints for it. */
117
- function readProfile(profile, tools, questions, images) {
117
+ function readProfile(profile, tools, questions, images, built = false) {
118
118
  try {
119
119
  const structured = replySchema(profile);
120
120
  const source = studioSource({
@@ -129,7 +129,10 @@ function readProfile(profile, tools, questions, images) {
129
129
  const read = readStudioSource(source, createBlankDraft());
130
130
  if (!read.ok)
131
131
  return { ok: false, message: read.errors.map((error) => error.message).join(' ') };
132
- return { ok: true, draft: read.draft, registered: read.registered };
132
+ const draft = built
133
+ ? { ...read.draft, decision: { ...read.draft.decision, questionsBuilt: true } }
134
+ : read.draft;
135
+ return { ok: true, draft, registered: read.registered };
133
136
  }
134
137
  catch (error) {
135
138
  return { ok: false, message: error instanceof Error ? error.message : String(error) };
@@ -223,7 +226,8 @@ function describeStudio(project, questions, images) {
223
226
  problems.push({ profile: profile.id, message: fault });
224
227
  continue;
225
228
  }
226
- const read = readProfile(profile, tools, asked, images[profile.id]);
229
+ const built = isQuestionsBuilder(asked);
230
+ const read = readProfile(profile, tools, built ? undefined : asked, images[profile.id], built);
227
231
  if (!read.ok) {
228
232
  problems.push({ profile: profile.id, message: read.message });
229
233
  continue;
@@ -384,7 +388,7 @@ export function corsHeaders(request, pageOrigins) {
384
388
  }
385
389
  /** Why a decision profile is not run: the setup file does not name its questions. */
386
390
  export function noQuestions(profileId) {
387
- return `The studio does not know what ${profileId} asks. Export the questions your application passes it from the setup file: export const questions = { '${profileId}': { ... } }.`;
391
+ return `The studio does not know what ${profileId} asks. Export the questions your application passes it from the setup file: export const questions = { '${profileId}': { ... } }, or, when they change with each decision, the builder that makes them: { '${profileId}': { input, build } }.`;
388
392
  }
389
393
  const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
390
394
  /** What each kind of question needs of its criteria, and what is wrong when it lacks it. */
@@ -434,6 +438,13 @@ function questionFault(question) {
434
438
  * type-checked, so the studio reads what it exports before it trusts it.
435
439
  */
436
440
  export function questionsFault(profileId, questions) {
441
+ if (isQuestionsBuilder(questions)) {
442
+ const { input } = questions;
443
+ const zod = isRecord(input) && typeof input.safeParse === 'function';
444
+ return input === undefined || zod
445
+ ? undefined
446
+ : `The questions the setup file exports for ${profileId} build from an \`input\` that is not a zod schema.`;
447
+ }
437
448
  if (!isRecord(questions) || !Object.keys(questions).length)
438
449
  return noQuestions(profileId);
439
450
  for (const [id, question] of Object.entries(questions)) {
@@ -514,6 +525,7 @@ function profileHandlers(options, problems) {
514
525
  : createTheoremHandler({
515
526
  profile: tracedToPage(profile),
516
527
  provider: options.provider ?? {},
528
+ ...(options.prepare ? { prepare: options.prepare } : {}),
517
529
  // A stateless profile keeps no conversation, so it takes no store.
518
530
  ...(profile.providerContinuation?.history === 'stateless'
519
531
  ? {}
@@ -542,6 +554,44 @@ async function withCors(answer, cors) {
542
554
  * Serves the studio for the tools and profiles registered when it is called.
543
555
  * Register the project first.
544
556
  */
557
+ /** Where the studio asks the project's keys: one check for each provider an agent's models name. */
558
+ export const KEYS_PATH = `${STUDIO_BASE}/keys`;
559
+ /**
560
+ * The key check of each slot a model of `workspace` reads, first or as fallback, on the registered
561
+ * provider that serves it, with the vault the project's turns read. A provider whose check cannot
562
+ * be sent is `unchecked`, with why.
563
+ */
564
+ async function keyChecks(workspace, provider = {}) {
565
+ const registered = new Map(listProviders().map((each) => [each.id, each]));
566
+ const read = new Map();
567
+ for (const agent of workspace.agents) {
568
+ for (const binding of agent.modelBindings) {
569
+ const on = registered.get(binding.provider);
570
+ if (!on)
571
+ continue;
572
+ const slots = modelSlots(workspace.providers, {
573
+ provider: binding.provider,
574
+ keySlot: binding.keySlot || agent.models.key,
575
+ fallbackKeySlot: binding.fallbackKeySlot || agent.models.fallbackKey,
576
+ });
577
+ const named = [slots.keySlot, slots.fallbackKeySlot].filter(Boolean);
578
+ for (const slot of named.length ? named : [undefined]) {
579
+ read.set(`${on.id}\u0000${slot ?? ''}`, { on, slot });
580
+ }
581
+ }
582
+ }
583
+ const { vault, fetch } = provider;
584
+ return await Promise.all([...read.values()].map(({ on, slot }) => checkKey(on, {
585
+ ...(slot ? { slot } : {}),
586
+ ...(vault ? { vault } : {}),
587
+ ...(fetch ? { fetch } : {}),
588
+ }).catch((error) => ({
589
+ provider: on.id,
590
+ ...(slot ? { slot } : {}),
591
+ state: 'unchecked',
592
+ said: error instanceof Error ? error.message : String(error),
593
+ }))));
594
+ }
545
595
  export function createStudioHandler(options) {
546
596
  const base = STUDIO_BASE;
547
597
  const corsFor = (request) => corsHeaders(request, options.pageOrigins);
@@ -561,7 +611,10 @@ export function createStudioHandler(options) {
561
611
  const peoplePath = `${base}/people`;
562
612
  // The screen's own requests (the guardrail probe, the key and connection tests) need no project.
563
613
  // This server is the builder's alone, so a connection test reaches what the draft's runs reach.
564
- const draft = createStudioDraftHandler({ draftNetwork: true });
614
+ const draft = createStudioDraftHandler({
615
+ draftNetwork: true,
616
+ projectProvider: (id) => listProviders().find((provider) => provider.id === id),
617
+ });
565
618
  const run = async (request, path) => {
566
619
  const cors = corsFor(request);
567
620
  const id = decodeURIComponent(path.slice(prefix.length).split('/')[0] ?? '');
@@ -586,6 +639,9 @@ export function createStudioHandler(options) {
586
639
  const path = new URL(request.url).pathname;
587
640
  if (path === base && request.method === 'GET')
588
641
  return json(200, description, cors);
642
+ if (path === KEYS_PATH && request.method === 'GET') {
643
+ return keyChecks(description.workspace, options.provider).then((checks) => json(200, checks, cors));
644
+ }
589
645
  if (path.startsWith(prefix))
590
646
  return run(request, path);
591
647
  if (path === peoplePath && request.method === 'GET')
@@ -59,7 +59,7 @@ export declare function isInside(root: string, path: string): boolean;
59
59
  /** What the setup module exports for each decision, by profile id: its questions, or its pictures. */
60
60
  export type SetupExport = 'questions' | 'images';
61
61
  /** The setup module's `export const <name>`, when it writes one. */
62
- export declare function setupExport(source: ts.SourceFile, name: SetupExport): ts.VariableDeclaration | undefined;
62
+ export declare function setupExport(source: ts.SourceFile, name: SetupExport | 'entry'): ts.VariableDeclaration | undefined;
63
63
  /** `expression` without the wrappers that do not change its value. */
64
64
  export declare function unwrapped(expression: ts.Expression): ts.Expression;
65
65
  /** The name a property is written under, when it is a plain one. */
@@ -197,9 +197,12 @@ export interface FileStep {
197
197
  file: string;
198
198
  from?: string;
199
199
  }
200
+ /** The application entry the setup at `setupFile` names, as a path, read from the file as it is now. */
201
+ export declare function entryOf(setupFile: string): string | undefined;
200
202
  /**
201
- * Walks the project's files from `entry`, the setup module, following each import. Yields each
202
- * file as it is read, so a caller can say where the walk is. Returns every file read.
203
+ * Walks the project's files from `entry`, the setup module, following each import and the
204
+ * application entry the setup names. Yields each file as it is read, so a caller can say where
205
+ * the walk is. Returns every file read.
203
206
  */
204
207
  export declare function walkProject(entry: string, root: string, read: ReadFile): Generator<FileStep, Map<string, ts.SourceFile>>;
205
208
  /** Reads the project from `entry`, the setup module. `read` returns a file's text, or undefined. */