@theoremjs/studio 0.3.4-next.679.gcdf1a3a → 0.3.4-next.711.g78e504a

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 (161) hide show
  1. package/agreement.js +35 -5
  2. package/browser-connection.d.ts +1 -1
  3. package/browser-connection.js +3 -1
  4. package/browser-execution.js +1 -0
  5. package/compile-workspace.js +12 -5
  6. package/compile.d.ts +5 -3
  7. package/compile.js +80 -36
  8. package/cookbooks/catalog.d.ts +2 -2
  9. package/cookbooks/catalog.js +296 -51
  10. package/cookbooks/project.js +1 -0
  11. package/cookbooks/tools.js +64 -0
  12. package/draft.d.ts +23 -4
  13. package/draft.js +25 -2
  14. package/guardrail-probe.d.ts +3 -1
  15. package/guardrail-probe.js +37 -5
  16. package/mod.d.ts +2 -3
  17. package/mod.js +2 -3
  18. package/package.json +4 -4
  19. package/page/assets/Banner-GFaYsfrc.js +3 -0
  20. package/page/assets/Center-CgO0c-qo.js +1 -0
  21. package/page/assets/{ConsoleFrame-BMf3HicW.js → ConsoleFrame-KmyDVQkS.js} +3 -3
  22. package/page/assets/{MenuBottomSheet-sVJMYa4R.js → MenuBottomSheet-BSQO5V7g.js} +1 -1
  23. package/page/assets/{SchemaFields-DYormNVH.js → SchemaFields-CIsMisSq.js} +1 -1
  24. package/page/assets/{ToolResultCharts-Ce4lVdgN.js → ToolResultCharts-95plvcj4.js} +1 -1
  25. package/page/assets/{TraceInspector-DHyj0IHY.js → TraceInspector-D2113s73.js} +1 -1
  26. package/page/assets/{TraceOverview-CeiOIqk9.js → TraceOverview-Bz2EnBzL.js} +3 -3
  27. package/page/assets/{_virtual_studio-type-sources-BwSqfSwd.js → _virtual_studio-type-sources-La9AcR1O.js} +360 -97
  28. package/page/assets/browser-connection-B2a2EaIg.js +3 -0
  29. package/page/assets/browser-engine--lGbAmPM.js +13 -0
  30. package/page/assets/browser-transport-h1KAGUN4.js +45 -0
  31. package/page/assets/{crypto-CD14HeXH.js → crypto-BnoW7FFO.js} +1 -1
  32. package/page/assets/{encode-files-DhoC5hWG.js → encode-files-DoLGXgup.js} +1 -1
  33. package/page/assets/{export-agent-Cs2S0oXB.js → export-agent-CA42Pf8A.js} +3 -3
  34. package/page/assets/{guardrail-tester-IcJWVveC.js → guardrail-tester-fDJlewVB.js} +2 -2
  35. package/page/assets/index-Bd7U_fu_.js +149 -0
  36. package/page/assets/{labels-provider-t4c-5JMk.js → labels-provider-uONlWExD.js} +1 -1
  37. package/page/assets/live-messages-CTL-QEqM.js +1 -0
  38. package/page/assets/people-CIsR0-5R.js +1 -0
  39. package/page/assets/project-address-DjxPZuyn.js +1 -0
  40. package/page/assets/reader-COeSYhdZ.js +5 -0
  41. package/page/assets/{schemas-BQ9Jydzb.js → schemas-D7cgkv3L.js} +1 -1
  42. package/page/assets/shaped-data-7q5Be8sp.js +20 -0
  43. package/page/assets/{stub-nxRsh1jo.js → stub-DJBcKncO.js} +25 -7
  44. package/page/assets/studio-code-pane-MXm30Ppv.js +10 -0
  45. package/page/assets/{studio-console-Cn-v8Vvw.js → studio-console-dHEr6mr5.js} +1 -1
  46. package/page/assets/studio-decision-BoSmTyjn.js +1 -0
  47. package/page/assets/studio-embedding-B5E__vsY.js +2 -0
  48. package/page/assets/studio-host-console-CadL7PPh.js +2 -0
  49. package/page/assets/{studio-labels-CiLuAo3N.js → studio-labels-sxDmOFeL.js} +1 -1
  50. package/page/assets/studio-live-Cgt4zKeL.js +5 -0
  51. package/page/assets/studio-map-BgeqrIh_.js +1 -0
  52. package/page/assets/{studio-session-CjUQSXx0.js → studio-session-ClF2iNCX.js} +1 -1
  53. package/page/assets/studio-trace-replay-BqYGBZ1t.js +3 -0
  54. package/page/assets/{studio-type-checker-BbUSqqOS.js → studio-type-checker-DutkTKte.js} +1 -1
  55. package/page/assets/tool-schema-m1KPujBp.js +17 -0
  56. package/page/assets/{trace-record-DxgSKmYY.js → trace-record-Dm2jEhUR.js} +1 -1
  57. package/page/assets/trace-schema--4IGmLeE.js +1 -0
  58. package/page/assets/tree-5tuw5ISS.js +3 -0
  59. package/page/assets/turn-client-BmadRouD.js +2 -0
  60. package/page/assets/{use-one-call-BZKByPJh.js → use-one-call-IXfdRlUH.js} +1 -1
  61. package/page/assets/use-second-ticker-D6JSf9B3.js +1 -0
  62. package/page/assets/workspace-CMUi6xcQ.js +1 -0
  63. package/page/index.html +22 -20
  64. package/people.d.ts +2 -0
  65. package/people.js +3 -1
  66. package/policy.js +1 -0
  67. package/providers.d.ts +2 -2
  68. package/providers.js +8 -3
  69. package/read-source.js +67 -7
  70. package/registrations.d.ts +32 -4
  71. package/runtime-scope.d.ts +6 -3
  72. package/runtime-scope.js +16 -4
  73. package/runtime.js +15 -2
  74. package/section-notes.d.ts +1 -0
  75. package/section-notes.js +1 -0
  76. package/serve-page.mjs +8 -4
  77. package/server/draft-handler.d.ts +4 -4
  78. package/server/draft-handler.js +3 -2
  79. package/server/draft-probe.d.ts +9 -1
  80. package/server/draft-probe.js +2 -1
  81. package/server/handler.d.ts +0 -3
  82. package/server/handler.js +62 -38
  83. package/server/live.d.ts +7 -2
  84. package/server/live.js +11 -5
  85. package/server/run-traces.d.ts +5 -1
  86. package/server/run-traces.js +7 -3
  87. package/server/save-new.js +5 -5
  88. package/server/save-plan.js +2 -1
  89. package/server/save-session.js +4 -2
  90. package/server/serve.js +2 -1
  91. package/server/test-key.d.ts +2 -2
  92. package/server/test-key.js +1 -1
  93. package/slot-values.d.ts +2 -0
  94. package/slot-values.js +22 -0
  95. package/source.js +11 -4
  96. package/system-markup.d.ts +9 -7
  97. package/system-markup.js +38 -19
  98. package/tool-readers.d.ts +23 -0
  99. package/tool-readers.js +60 -0
  100. package/tools.js +5 -1
  101. package/types.d.ts +6 -1
  102. package/ui/inspector-context.d.ts +1 -8
  103. package/ui/inspector-context.js +0 -7
  104. package/ui/inspector.d.ts +43 -1
  105. package/ui/inspector.js +50 -9
  106. package/ui/lib/entries.d.ts +13 -0
  107. package/ui/lib/entries.js +43 -0
  108. package/ui/lib/project-traces.d.ts +5 -0
  109. package/ui/lib/project-traces.js +11 -1
  110. package/ui/lib/studio-page.d.ts +6 -1
  111. package/ui/lib/studio-page.js +33 -31
  112. package/ui/lib/studio-prefs.d.ts +0 -4
  113. package/ui/lib/studio-prefs.js +0 -7
  114. package/ui/lib/studio-project.d.ts +10 -6
  115. package/ui/lib/studio-project.js +19 -4
  116. package/ui/lib/studio-session.d.ts +2 -0
  117. package/ui/lib/studio-session.js +40 -2
  118. package/ui/lib/studio-store.d.ts +2 -2
  119. package/ui/lib/studio-store.js +9 -5
  120. package/ui/lib/tool-probe.d.ts +2 -0
  121. package/ui/lib/tool-probe.js +3 -2
  122. package/ui/lib/type-icons.d.ts +1 -0
  123. package/ui/lib/type-icons.js +2 -1
  124. package/ui/profile-editor.js +69 -45
  125. package/ui/studio-compare.d.ts +14 -4
  126. package/ui/studio-compare.js +58 -24
  127. package/ui/studio-live.d.ts +1 -1
  128. package/ui/studio-live.js +8 -3
  129. package/ui/studio-runner.d.ts +3 -2
  130. package/ui/studio-runner.js +16 -14
  131. package/ui/studio-screen.d.ts +1 -2
  132. package/ui/studio-screen.js +33 -37
  133. package/ui/studio-settings.js +4 -13
  134. package/ui/studio-trace-replay.js +7 -1
  135. package/workspace.js +3 -2
  136. package/asks.d.ts +0 -54
  137. package/asks.js +0 -69
  138. package/page/assets/Banner-CkcwUyOn.js +0 -4
  139. package/page/assets/Center-nHS1JSux.js +0 -1
  140. package/page/assets/browser-connection-DSUHVCT5.js +0 -3
  141. package/page/assets/browser-engine-BXSD3WU8.js +0 -11
  142. package/page/assets/browser-transport-cp9y8bBz.js +0 -45
  143. package/page/assets/index-JWco7tJJ.js +0 -145
  144. package/page/assets/live-messages-CiLmR89m.js +0 -1
  145. package/page/assets/reader-DrOfMM8I.js +0 -5
  146. package/page/assets/shaped-data-H1miOZm2.js +0 -20
  147. package/page/assets/studio-code-pane-B8MOEW9g.js +0 -8
  148. package/page/assets/studio-decision-CjJ_pqdJ.js +0 -1
  149. package/page/assets/studio-embedding-Cq3ePsfC.js +0 -2
  150. package/page/assets/studio-host-console-D__Of1no.js +0 -2
  151. package/page/assets/studio-live-DvDQbP5V.js +0 -5
  152. package/page/assets/studio-map-BZFYGG_Y.js +0 -1
  153. package/page/assets/studio-trace-replay-D22FgUA5.js +0 -3
  154. package/page/assets/tool-schema-BmRYaywn.js +0 -17
  155. package/page/assets/trace-schema-9CdEyG6Q.js +0 -1
  156. package/page/assets/tree-3N-1RPZz.js +0 -3
  157. package/page/assets/turn-client-DN8PawJr.js +0 -2
  158. package/page/assets/use-second-ticker-CEwOSS-d.js +0 -1
  159. package/page/assets/workspace-CTSW941G.js +0 -1
  160. package/ui/confirm-write.d.ts +0 -12
  161. package/ui/confirm-write.js +0 -45
@@ -34,8 +34,8 @@ export type StudioDraftHandlerOptions = {
34
34
  lent?: LentRuntime;
35
35
  /**
36
36
  * Spends one of `kind` for whoever sent `request`, before it runs. Throw a `TheoremError` to refuse
37
- * it: the screen reads the error's wording. Every decision, host tool call, and agent tool turn on
38
- * the lent keys passes through it. Default: nothing is counted.
37
+ * it: the screen reads the error's wording. Every decision, host tool call, agent tool turn, and
38
+ * passage a tool's reader reads on the lent keys passes through it. Default: nothing is counted.
39
39
  */
40
40
  spend?: (kind: StudioSpend, request: Request) => void | Promise<void>;
41
41
  /**
@@ -64,8 +64,8 @@ export type StudioDraftHandlerOptions = {
64
64
  * whatever the draft says, so no visitor reaches the host's own network.
65
65
  */
66
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;
67
+ /** The project's providers: a key is checked on them, and a probed draft's models name them. */
68
+ projectProviders?: () => readonly RegisteredProvider[];
69
69
  };
70
70
  /**
71
71
  * Answers a request under `STUDIO_BASE`; `defer` keeps work running after the reply (a Worker's
@@ -79,6 +79,7 @@ export function createStudioDraftHandler(options = {}) {
79
79
  execution: boundary.toolExecution,
80
80
  pageExecution: boundary.pageExecution,
81
81
  onAgentCall: agentCall(request),
82
+ onReaderCall: spend && (() => spend('decision', request)),
82
83
  });
83
84
  /** A draft as a run takes it. */
84
85
  const draftRun = (lent, draft, boundary, request) => ({
@@ -199,11 +200,11 @@ export function createStudioDraftHandler(options = {}) {
199
200
  const path = new URL(request.url).pathname;
200
201
  const route = path.startsWith(`${STUDIO_BASE}/`) ? path.slice(STUDIO_BASE.length + 1) : '';
201
202
  const routes = {
202
- probe: (asked) => draftProbe(asked, options.onProbePassed, defer ?? (() => { })),
203
+ probe: (asked) => draftProbe(asked, options.onProbePassed, defer ?? (() => { }), options.projectProviders?.() ?? []),
203
204
  'test-key': (asked) => testKey(asked, {
204
205
  resolveHost,
205
206
  draftNetwork: options.draftNetwork,
206
- projectProvider: options.projectProvider,
207
+ projectProviders: options.projectProviders,
207
208
  }),
208
209
  'test-connection': (asked) => testConnection(asked, { resolveHost, draftNetwork: options.draftNetwork }),
209
210
  ...(lent ? lentRoutes(lent) : {}),
@@ -1,3 +1,11 @@
1
+ /**
2
+ * `POST <base>/probe`: one text sent across every guardrail boundary of the draft, each on a
3
+ * scripted model, so no key is spent and no host is reached. With `only`, the draft reads with that
4
+ * detector alone: what the others would catch passes there.
5
+ *
6
+ * @module
7
+ */
8
+ import { type RegisteredProvider } from '@theoremjs/agents';
1
9
  import { type GuardrailProbeAnswer } from '../guardrail-probe.ts';
2
10
  /** A probed text some boundary let through, and what each boundary's guardrails did with it. */
3
11
  export type ProbeEntry = {
@@ -11,4 +19,4 @@ export type ProbeEntry = {
11
19
  * some boundary passed, run with every detector and not one of the battery's, goes to `onPassed`
12
20
  * through `defer`, after the answer: one that fails never fails a probe.
13
21
  */
14
- export declare function draftProbe(request: Request, onPassed: ((entry: ProbeEntry, at: Date) => Promise<void>) | undefined, defer: (work: Promise<unknown>) => void): Promise<Response>;
22
+ export declare function draftProbe(request: Request, onPassed: ((entry: ProbeEntry, at: Date) => Promise<void>) | undefined, defer: (work: Promise<unknown>) => void, projectProviders: readonly RegisteredProvider[]): Promise<Response>;
@@ -31,7 +31,7 @@ function isBatteryText(text) {
31
31
  * some boundary passed, run with every detector and not one of the battery's, goes to `onPassed`
32
32
  * through `defer`, after the answer: one that fails never fails a probe.
33
33
  */
34
- export async function draftProbe(request, onPassed, defer) {
34
+ export async function draftProbe(request, onPassed, defer, projectProviders) {
35
35
  let labels;
36
36
  try {
37
37
  const body = await readBody(request, probeRequestSchema);
@@ -41,6 +41,7 @@ export async function draftProbe(request, onPassed, defer) {
41
41
  customTools: body.customTools ?? [],
42
42
  structured: body.structured,
43
43
  dependencies: body.dependencies,
44
+ projectProviders,
44
45
  text: body.text,
45
46
  only: body.only,
46
47
  signal: request.signal,
@@ -14,7 +14,6 @@
14
14
  */
15
15
  import { type DecisionAsset, type DecisionQuestion, type Profile, type ProviderHostOptions, type TurnWiring } from '@theoremjs/agents';
16
16
  import { type DecisionQuestionsBuilder } from '@theoremjs/web/server';
17
- import { type StudioAsks } from '../asks.ts';
18
17
  import { type StudioActingAs, type StudioPeople, type StudioPeopleOffer } from '../people.ts';
19
18
  import { type StudioUpgrade } from './live.ts';
20
19
  export { STUDIO_BASE } from './draft-handler.ts';
@@ -57,8 +56,6 @@ export type StudioDescription = {
57
56
  unregistered?: Unregistered[];
58
57
  /** Where the files define each provider the project registered. */
59
58
  providerPlaces?: ProviderPlace[];
60
- /** The tools that write: the ones the studio makes ask before each run, and the ones it cannot. */
61
- asks: StudioAsks;
62
59
  /** What the project printed when its files stopped loading. The page then shows the last load that did. */
63
60
  unloaded?: string;
64
61
  /** The editor the studio command opens files in when the page names none, by its command. */
package/server/handler.js CHANGED
@@ -15,9 +15,8 @@
15
15
  import { checkKey, defineProfile, getStructured, listProfiles, listProviders, listTools, } 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, isQuestionsBuilder, } from '@theoremjs/web/server';
18
+ import { createSealedConversationStore, createTheoremDecisionHandler, createTheoremEmbeddingHandler, createTheoremHandler, createTheoremHostHandler, isQuestionsBuilder, readBody, startConversation, theoremStartRequestSchema, } from '@theoremjs/web/server';
19
19
  import { differingSettings } from "../agreement.js";
20
- import { studioAskStage, studioAsks } from "../asks.js";
21
20
  import { compileWorkspace } from "../compile-workspace.js";
22
21
  import { createBlankDraft } from "../draft.js";
23
22
  import { shownConnection, withoutCredentials } from "../held-credentials.js";
@@ -30,6 +29,7 @@ import { STUDIO_READER } from "../reader.js";
30
29
  import { withPatterns } from "../runtime-scope.js";
31
30
  import { studioSource } from "../source.js";
32
31
  import { createStudioDraftHandler, STUDIO_BASE } from "./draft-handler.js";
32
+ import { errorJson } from "./draft-replies.js";
33
33
  import { createStudioLiveHandler } from "./live.js";
34
34
  export { STUDIO_BASE } from "./draft-handler.js";
35
35
  import { addAgent, agentNodeId, createBlankWorkspace, workspaceFromDraft, } from "../workspace.js";
@@ -75,16 +75,24 @@ export function printableProfile(profile) {
75
75
  : profile;
76
76
  return plainSetting(recording);
77
77
  }
78
+ const registeredShape = (id) => ({
79
+ id,
80
+ spec: { jsonSchema: getStructured(id).jsonSchema },
81
+ });
78
82
  /**
79
- * The schema a profile's replies take, as registered. None when the profile names one nothing
80
- * registers, or one for each slot: the editor holds a single schema.
83
+ * The schemas a profile's replies take, as registered: its one schema, or the fallback beside the
84
+ * shapes a slot picks. None when the profile names one nothing registers.
81
85
  */
82
86
  function replySchema(profile) {
83
- const id = 'outputs' in profile ? profile.outputs?.structured : undefined;
84
- if (typeof id !== 'string')
87
+ const written = 'outputs' in profile ? profile.outputs?.structured : undefined;
88
+ if (!written)
85
89
  return undefined;
86
90
  try {
87
- return { id, spec: { jsonSchema: getStructured(id).jsonSchema } };
91
+ if (typeof written === 'string')
92
+ return registeredShape(written);
93
+ const picked = new Set(Object.values(written.map));
94
+ picked.delete(written.fallback);
95
+ return { ...registeredShape(written.fallback), also: [...picked].map(registeredShape) };
88
96
  }
89
97
  catch {
90
98
  return undefined;
@@ -296,21 +304,8 @@ function describeStudio(project, questions, images) {
296
304
  ...(modelProblems.length ? { modelProblems } : {}),
297
305
  ...(differences.length ? { differences } : {}),
298
306
  ...(unheld.length ? { unheld } : {}),
299
- asks: { asked: [], inside: [] },
300
307
  };
301
308
  }
302
- /**
303
- * Which registered tools ask the builder before each run, whatever their own setting: a run in
304
- * the studio is the project's real code, on whatever it reaches. The question is the studio's own
305
- * stage, so the registrations and the project's files stay as they are.
306
- */
307
- function writesToAsk() {
308
- const profiles = new Map(listProfiles().map((profile) => [profile.id, profile]));
309
- return studioAsks(listTools(), (id) => {
310
- const profile = profiles.get(id);
311
- return profile && 'tools' in profile ? profile.tools.allow : [];
312
- });
313
- }
314
309
  export function json(status, body, headers) {
315
310
  return new Response(JSON.stringify(body), {
316
311
  status,
@@ -451,7 +446,7 @@ export function questionsFault(profileId, questions) {
451
446
  /** Why a live profile is not run: a voice call needs a socket, and the server was given no way to take one. */
452
447
  const NO_SOCKET = 'A live profile runs over a socket, and this server was not given a way to take one (`upgrade`).';
453
448
  /** Each registered profile's own handler, by id; a profile that cannot be served is a problem. */
454
- function profileHandlers(options, problems, ask) {
449
+ function profileHandlers(options, problems) {
455
450
  const served = new Map();
456
451
  // `run` refused a pick it cannot read before any handler is reached, so here it reads.
457
452
  const actingAs = (request) => {
@@ -464,7 +459,6 @@ function profileHandlers(options, problems, ask) {
464
459
  session: (request) => actingAsSession(actingAs(request)),
465
460
  clientEvents: STUDIO_READER,
466
461
  ...(host ? { host: (request) => host(request, actingAs(request)) } : {}),
467
- ...(ask ? { onStage: ask } : {}),
468
462
  };
469
463
  // One store for every chat profile: one key, so any of them opens a ref its session holds.
470
464
  let conversationStore;
@@ -499,7 +493,10 @@ function profileHandlers(options, problems, ask) {
499
493
  }
500
494
  if (profile.type === 'live') {
501
495
  if (options.upgrade) {
502
- served.set(profile.id, createStudioLiveHandler(profile, options.provider ?? {}, options.upgrade, ask));
496
+ served.set(profile.id, createStudioLiveHandler(profile, options.provider ?? {}, options.upgrade, {
497
+ session: shared.session,
498
+ host: shared.host,
499
+ }));
503
500
  }
504
501
  else
505
502
  problems.push({ profile: profile.id, message: NO_SOCKET });
@@ -515,18 +512,22 @@ function profileHandlers(options, problems, ask) {
515
512
  continue;
516
513
  }
517
514
  // The page shows a run's trace, so the profile is served writing its records to the run.
518
- served.set(profile.id, withRunTraces(profile.type === 'host'
519
- ? createTheoremHostHandler({ profile: tracedToPage(profile), ...shared })
520
- : createTheoremHandler({
521
- profile: tracedToPage(profile),
522
- provider: options.provider ?? {},
523
- ...(options.prepare ? { prepare: options.prepare } : {}),
524
- // A stateless profile keeps no conversation, so it takes no store.
525
- ...(profile.providerContinuation?.history === 'stateless'
526
- ? {}
527
- : { conversationStore: chatStore() }),
528
- ...shared,
529
- })));
515
+ if (profile.type === 'host') {
516
+ served.set(profile.id, withRunTraces(createTheoremHostHandler({ profile: tracedToPage(profile), ...shared })));
517
+ continue;
518
+ }
519
+ // A stateless profile keeps no conversation, so it takes no store.
520
+ const isStateless = profile.providerContinuation?.history === 'stateless';
521
+ const chat = createTheoremHandler({
522
+ profile: tracedToPage(profile),
523
+ provider: options.provider ?? {},
524
+ ...(options.prepare ? { prepare: options.prepare } : {}),
525
+ ...(isStateless ? {} : { conversationStore: chatStore() }),
526
+ // The studio's page is the builder's own: its picks choose the prompt lines.
527
+ pageStatesTurn: true,
528
+ ...shared,
529
+ });
530
+ served.set(profile.id, withRunTraces(isStateless ? chat : startsConversations(chat, profile, chatStore(), shared.session)));
530
531
  }
531
532
  catch (error) {
532
533
  problems.push({
@@ -537,6 +538,30 @@ function profileHandlers(options, problems, ask) {
537
538
  }
538
539
  return served;
539
540
  }
541
+ /**
542
+ * `serve`, and `<profile>/conversation/start`: a chat that opens on blocks a trace holds, in the
543
+ * asking person's session, for a replay that goes on live.
544
+ * why: the project's run must open it, on the project's providers, and this server is the
545
+ * builder's alone. `createTheoremHandler` takes no transcript from a browser.
546
+ */
547
+ function startsConversations(serve, profile, store, session) {
548
+ return async (request) => {
549
+ const path = new URL(request.url).pathname;
550
+ if (!path.endsWith('/conversation/start'))
551
+ return serve(request);
552
+ if (request.method !== 'POST')
553
+ return new Response(null, { status: 405 });
554
+ try {
555
+ const { blocks } = await readBody(request, theoremStartRequestSchema);
556
+ const host = { sessionId: session(request), store };
557
+ const { ref, view } = await startConversation(host, profile, blocks);
558
+ return json(200, { conversation: ref, view }, {});
559
+ }
560
+ catch (error) {
561
+ return errorJson(error);
562
+ }
563
+ };
564
+ }
540
565
  /** `answer` with the page's CORS headers on it. */
541
566
  async function withCors(answer, cors) {
542
567
  const response = await answer;
@@ -591,7 +616,6 @@ export function createStudioHandler(options) {
591
616
  const base = STUDIO_BASE;
592
617
  const corsFor = (request) => corsHeaders(request, options.pageOrigins);
593
618
  const description = describeStudio(options.project, options.questions ?? {}, options.images ?? {});
594
- description.asks = writesToAsk();
595
619
  const peopleProblem = options.people === undefined ? undefined : peopleFault(options.people);
596
620
  // People the page cannot be offered are not offered: every run acts as no one, and the page says why.
597
621
  const people = options.people && !peopleProblem ? options.people : undefined;
@@ -600,14 +624,14 @@ export function createStudioHandler(options) {
600
624
  if (peopleProblem)
601
625
  description.peopleProblem = peopleProblem;
602
626
  const handlerOptions = { ...options, people };
603
- const served = profileHandlers(handlerOptions, description.problems, studioAskStage(description.asks.asked));
627
+ const served = profileHandlers(handlerOptions, description.problems);
604
628
  const prefix = `${base}/profiles/`;
605
629
  const peoplePath = `${base}/people`;
606
630
  // The screen's own requests (the guardrail probe, the key and connection tests) need no project.
607
631
  // This server is the builder's alone, so a connection test reaches what the draft's runs reach.
608
632
  const draft = createStudioDraftHandler({
609
633
  draftNetwork: true,
610
- projectProvider: (id) => listProviders().find((provider) => provider.id === id),
634
+ projectProviders: listProviders,
611
635
  });
612
636
  const run = async (request, path) => {
613
637
  const cors = corsFor(request);
package/server/live.d.ts CHANGED
@@ -5,11 +5,16 @@
5
5
  *
6
6
  * @module
7
7
  */
8
- import { type Profile, type ProviderHostOptions, type StageHandler } from '@theoremjs/agents';
8
+ import { type Profile, type ProviderHostOptions } from '@theoremjs/agents';
9
9
  /** The server's end of the page's socket, and the answer that completes the upgrade. */
10
10
  export type StudioUpgrade = (request: Request) => {
11
11
  socket: WebSocket;
12
12
  response: Response;
13
13
  };
14
14
  /** Serves a live profile: a socket upgrade starts a call, and anything else is told to upgrade. */
15
- export declare function createStudioLiveHandler(profile: Profile, provider: ProviderHostOptions, upgrade: StudioUpgrade, ask?: StageHandler): (request: Request) => Promise<Response>;
15
+ export declare function createStudioLiveHandler(profile: Profile, provider: ProviderHostOptions, upgrade: StudioUpgrade, options: {
16
+ /** Who the run acts as, by session, as a chat's is. */
17
+ session: (request: Request) => string;
18
+ /** The application's context for the tools (`ctx.host`), as a chat's turn has it. */
19
+ host?: (request: Request) => unknown;
20
+ }): (request: Request) => Promise<Response>;
package/server/live.js CHANGED
@@ -51,7 +51,7 @@ function openMessage(socket) {
51
51
  });
52
52
  }
53
53
  /** Runs the call until either side ends it. A failure to open reaches the page worded, with its kind. */
54
- async function relay(socket, profile, provider, boundary, ask) {
54
+ async function relay(socket, profile, provider, boundary, { host }) {
55
55
  let session;
56
56
  try {
57
57
  // Listen before anything waits: the page sends its open message as the socket opens.
@@ -59,7 +59,7 @@ async function relay(socket, profile, provider, boundary, ask) {
59
59
  session = await runSession({
60
60
  ...(await boundary.prepareLiveOpen(open)),
61
61
  profile: profile.id,
62
- ...(ask ? { onStage: ask } : {}),
62
+ ...(host === undefined ? {} : { host }),
63
63
  }, { ...provider, execution: boundary.toolExecution, pageExecution: boundary.pageExecution }, pageSink(socket, profile));
64
64
  }
65
65
  catch (error) {
@@ -84,17 +84,23 @@ async function relay(socket, profile, provider, boundary, ask) {
84
84
  });
85
85
  }
86
86
  /** Serves a live profile: a socket upgrade starts a call, and anything else is told to upgrade. */
87
- export function createStudioLiveHandler(profile, provider, upgrade, ask) {
87
+ export function createStudioLiveHandler(profile, provider, upgrade, options) {
88
88
  const sessionStore = createMemorySessionStore();
89
89
  return async (request) => {
90
90
  if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
91
91
  return new Response(null, { status: 426, headers: { upgrade: 'websocket' } });
92
92
  }
93
- const boundary = await createTheoremSessionBoundary({ request, sessionStore });
93
+ const { session, host } = options;
94
+ const boundary = await createTheoremSessionBoundary({
95
+ request,
96
+ sessionStore,
97
+ session,
98
+ pageStatesTurn: true,
99
+ });
94
100
  const { socket, response } = upgrade(request);
95
101
  if (boundary.setCookie)
96
102
  response.headers.append('set-cookie', boundary.setCookie);
97
- void relay(socket, profile, provider, boundary, ask);
103
+ void relay(socket, profile, provider, boundary, { host: host?.(request) });
98
104
  return response;
99
105
  };
100
106
  }
@@ -9,7 +9,11 @@
9
9
  import { type Profile } from '@theoremjs/agents';
10
10
  /** Where a profile served by the studio writes its records. */
11
11
  export declare const STUDIO_RUN_TRACES = "theorem-studio-run";
12
- /** The profile as the studio serves it: one that records writes to the run it is in. */
12
+ /**
13
+ * The profile as the studio serves it: one that records writes to the run it is in.
14
+ * invariant: this agrees with the page, where a block naming no place records to the studio
15
+ * (`STUDIO_POLICY_UNSET`); without it the page offers a trace no run writes.
16
+ */
13
17
  export declare function tracedToPage<P extends Profile>(profile: P): P;
14
18
  /** Serves a profile with each run's records sent behind its events. */
15
19
  export declare function withRunTraces(serve: (request: Request) => Promise<Response>): (request: Request) => Promise<Response>;
@@ -7,15 +7,19 @@
7
7
  * @module
8
8
  */
9
9
  import { AsyncLocalStorage } from 'node:async_hooks';
10
- import { registerTraceDestination, resolveObservabilityPolicy, } from '@theoremjs/agents';
10
+ import { registerTraceDestination } from '@theoremjs/agents';
11
11
  import { eachLine, NDJSON } from "../stream-lines.js";
12
12
  /** Where a profile served by the studio writes its records. */
13
13
  export const STUDIO_RUN_TRACES = 'theorem-studio-run';
14
14
  /** The records of the run in progress. The kernel writes a record inside the run that made it. */
15
15
  const runs = new AsyncLocalStorage();
16
- /** The profile as the studio serves it: one that records writes to the run it is in. */
16
+ /**
17
+ * The profile as the studio serves it: one that records writes to the run it is in.
18
+ * invariant: this agrees with the page, where a block naming no place records to the studio
19
+ * (`STUDIO_POLICY_UNSET`); without it the page offers a trace no run writes.
20
+ */
17
21
  export function tracedToPage(profile) {
18
- if (!resolveObservabilityPolicy(profile.observability).record)
22
+ if (!profile.observability || profile.observability.writeTo === false)
19
23
  return profile;
20
24
  registerTraceDestination(STUDIO_RUN_TRACES, {
21
25
  write: (record) => {
@@ -309,17 +309,17 @@ class NewPlan {
309
309
  this.plan.changes.push({ kind, of, setting: '', status, file });
310
310
  }
311
311
  nowhere(registration) {
312
- this.refuse('tool', registration.name, 'setup', this.ground.project.entry);
312
+ this.refuse('tool', registration.name, 'setup', this.ground.source.fileName);
313
313
  }
314
314
  /** Nothing can be placed: the setup does not show where it registers. */
315
315
  unplaced() {
316
- const { entry } = this.ground.project;
316
+ const { fileName } = this.ground.source;
317
317
  for (const id of this.added.profiles)
318
- this.refuse('profile', id, 'setup', entry);
318
+ this.refuse('profile', id, 'setup', fileName);
319
319
  for (const tool of this.added.tools)
320
- this.refuse('tool', tool.name, 'setup', entry);
320
+ this.refuse('tool', tool.name, 'setup', fileName);
321
321
  for (const provider of this.added.providers)
322
- this.refuse('provider', provider.id, 'setup', entry);
322
+ this.refuse('provider', provider.id, 'setup', fileName);
323
323
  return this.plan;
324
324
  }
325
325
  /** The specifiers a new file at `file` imports the kernel and zod by. */
@@ -419,7 +419,8 @@ class Planner {
419
419
  return;
420
420
  }
421
421
  }
422
- if (!same(value, before)) {
422
+ // A block the file left empty reads as no block once the studio's own fill-ins come out.
423
+ if (!same(value, before) && !(before === undefined && same(value, {}))) {
423
424
  this.note('changed', path, { source, node });
424
425
  return;
425
426
  }
@@ -414,9 +414,11 @@ export function createSaveSession(host, first) {
414
414
  // In turn, so a Save that is still proving its files is not taken for the builder's editor.
415
415
  changed: () => inTurn(() => {
416
416
  const now = held();
417
- if (now === loadedFrom)
417
+ // invariant: files put back after a load that failed are news; the page still says it failed.
418
+ const last = unloaded?.from ?? loadedFrom;
419
+ if (now === last)
418
420
  return Promise.resolve([]);
419
- const [was, is] = [loadedFrom, now].map((text) => new Map(JSON.parse(text)));
421
+ const [was, is] = [last, now].map((text) => new Map(JSON.parse(text)));
420
422
  const files = [...new Set([...(was?.keys() ?? []), ...(is?.keys() ?? [])])];
421
423
  return Promise.resolve(files.filter((file) => was?.get(file) !== is?.get(file)).map(inRoot));
422
424
  }),
package/server/serve.js CHANGED
@@ -141,7 +141,8 @@ async function typeChecks() {
141
141
  const decoder = new TextDecoder();
142
142
  return {
143
143
  ok: success,
144
- output: (decoder.decode(stderr) + decoder.decode(stdout)).trim().slice(-4000),
144
+ // why: a checker told to colour by the builder's shell does so past NO_COLOR.
145
+ output: stripVTControlCharacters(decoder.decode(stderr) + decoder.decode(stdout)).trim(),
145
146
  };
146
147
  }
147
148
  /** A project file's text, or undefined when it is missing or leads outside the project. */
@@ -8,8 +8,8 @@
8
8
  import { type ResolveHost } from '@theoremjs/agents';
9
9
  import { type RegisteredProvider } from '@theoremjs/agents/kernel';
10
10
  export interface TestKeyOptions {
11
- /** A provider the project registers from a definition of its own, by id. */
12
- projectProvider?: (id: string) => RegisteredProvider | undefined;
11
+ /** The providers the project registers, some from definitions of its own. */
12
+ projectProviders?: () => readonly RegisteredProvider[];
13
13
  /** Resolves the provider's host, so a check from a shared server reaches public addresses only. */
14
14
  resolveHost?: ResolveHost;
15
15
  /** The server is the builder's alone: the check reaches whatever the provider names. */
@@ -41,7 +41,7 @@ export async function testKey(request, options = {}) {
41
41
  const definition = kernelDefinition(asked.provider.definition);
42
42
  provider = definition
43
43
  ? registerStudioProvider(createProviderRegistry(), asked.provider, definition)
44
- : options.projectProvider?.(asked.provider.id);
44
+ : options.projectProviders?.().find((each) => each.id === asked.provider.id);
45
45
  }
46
46
  catch (error) {
47
47
  return Response.json(clientError(error), { status: 400 });
@@ -0,0 +1,2 @@
1
+ /** The values a slot's declaration lists, or undefined when it lists none a page could pick. */
2
+ export declare function choiceValues(decl: unknown): string[] | undefined;
package/slot-values.js ADDED
@@ -0,0 +1,22 @@
1
+ /** The values a slot's declaration lists, or undefined when it lists none a page could pick. */
2
+ export function choiceValues(decl) {
3
+ if (Array.isArray(decl) &&
4
+ decl.length > 0 &&
5
+ decl.every((value) => typeof value === 'string' && value.trim() !== '')) {
6
+ return decl;
7
+ }
8
+ const choices = isRecord(decl) ? decl.choices : undefined;
9
+ if (!Array.isArray(choices) || choices.length === 0)
10
+ return undefined;
11
+ const values = [];
12
+ for (const choice of choices) {
13
+ if (!isRecord(choice) || typeof choice.value !== 'string' || choice.value.trim() === '') {
14
+ return undefined;
15
+ }
16
+ values.push(choice.value);
17
+ }
18
+ return values;
19
+ }
20
+ function isRecord(value) {
21
+ return typeof value === 'object' && value !== null;
22
+ }
package/source.js CHANGED
@@ -105,12 +105,15 @@ function withItemChecks(profile, checks) {
105
105
  }
106
106
  /** A tool's registration, as a call; `indent` places it in a function body. */
107
107
  function toolSource(tool, indent = 0) {
108
+ const { inputSchema, outputSchema, ...rawFields } = tool;
109
+ const { stageAgent, stageQuestions: _stageQuestions, ...fields } = rawFields;
108
110
  const call = (fields) => {
109
111
  const pad = ' '.repeat(indent);
110
- return `${pad}registerTool(${literal(fields, indent)});\n`;
112
+ const owed = stageAgent
113
+ ? `${pad}// Your host runs ${stageAgent} on this tool's output, at post_tool.\n`
114
+ : '';
115
+ return `${owed}${pad}registerTool(${literal(fields, indent)});\n`;
111
116
  };
112
- const { inputSchema, outputSchema, ...rawFields } = tool;
113
- const { stageAgent: _stageAgent, ...fields } = rawFields;
114
117
  // The kernel fixes an agent tool's schemas.
115
118
  if (fields.type === 'agent')
116
119
  return call(fields);
@@ -227,7 +230,7 @@ export function studioSource(compiled) {
227
230
  ...providers.code,
228
231
  ...customTools.map((tool) => toolSource(tool)),
229
232
  ...(structured
230
- ? [`registerStructured(${quoteSource(structured.id)}, ${literal(structured.spec, 0)});\n`]
233
+ ? [structured, ...(structured.also ?? [])].map(({ id, spec }) => `registerStructured(${quoteSource(id)}, ${literal(spec, 0)});\n`)
231
234
  : []),
232
235
  `const profile = ${defined.code};\n\nregisterProfile(profile);\n`,
233
236
  ...(compiled.questions
@@ -370,6 +373,10 @@ export function workspaceSource(compiled, project) {
370
373
  }
371
374
  if (agent.structured) {
372
375
  lines.push(`registerStructured(${name}.structured.id, ${name}.structured.spec);\n`);
376
+ for (const at of (agent.structured.also ?? []).keys()) {
377
+ const shape = `${name}.structured.also[${at}]`;
378
+ lines.push(`registerStructured(${shape}.id, ${shape}.spec);\n`);
379
+ }
373
380
  }
374
381
  lines.push(`registerProfile(${name}.profile);\n`);
375
382
  return lines.join('\n');
@@ -1,20 +1,22 @@
1
- import type { SystemPrompt } from '@theoremjs/agents/kernel';
1
+ import type { SystemPart, SystemPrompt } from '@theoremjs/agents/kernel';
2
2
  /**
3
- * The studio's way to write a system prompt with private sections: the
4
- * whole prompt as text, each private section wrapped as `{private: …}`.
3
+ * The studio's way to write a system prompt: the whole prompt as text, a blank
4
+ * line starting a new line, each private section wrapped as `{private: …}`.
5
5
  */
6
6
  type SystemMarkup = {
7
7
  ok: true;
8
- prompt: SystemPrompt | undefined;
8
+ lines: SystemPrompt[];
9
9
  } | {
10
10
  ok: false;
11
11
  message: string;
12
12
  };
13
+ /** A line as the profile holds it, without the white space at its ends. */
14
+ declare function promptLine(parts: readonly SystemPart[]): SystemPrompt | undefined;
13
15
  /**
14
16
  * A section closes at the `}` that balances its `{`, so braces inside it pair
15
- * up as written. Its text is trimmed; the text around it is kept as written,
16
- * apart from the ends of the whole prompt.
17
+ * up as written, and a blank line inside it stays in it. Its text is trimmed;
18
+ * the text around it is kept as written, apart from the ends of each line.
17
19
  */
18
20
  declare function parseSystemMarkup(text: string): SystemMarkup;
19
21
  export type { SystemMarkup };
20
- export { parseSystemMarkup };
22
+ export { parseSystemMarkup, promptLine };