@theoremjs/studio 0.3.4-next.677.g14b70fe → 0.3.4-next.693.g4ab1526

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 (141) hide show
  1. package/asks.d.ts +9 -2
  2. package/asks.js +19 -10
  3. package/browser-connection.d.ts +1 -1
  4. package/browser-connection.js +3 -1
  5. package/browser-execution.js +1 -0
  6. package/compile-workspace.js +12 -5
  7. package/compile.d.ts +4 -2
  8. package/compile.js +58 -37
  9. package/cookbooks/catalog.d.ts +2 -2
  10. package/cookbooks/catalog.js +300 -53
  11. package/cookbooks/project.js +1 -0
  12. package/cookbooks/tools.js +64 -0
  13. package/draft.d.ts +21 -5
  14. package/draft.js +25 -2
  15. package/guardrail-probe.d.ts +3 -1
  16. package/guardrail-probe.js +37 -5
  17. package/mod.d.ts +2 -2
  18. package/mod.js +2 -2
  19. package/package.json +4 -4
  20. package/page/assets/Banner-DrRNC3MG.js +4 -0
  21. package/page/assets/Center-CgO0c-qo.js +1 -0
  22. package/page/assets/{ConsoleFrame-BFCYCApu.js → ConsoleFrame-BvgFGqp2.js} +3 -3
  23. package/page/assets/{MenuBottomSheet-CezET_qZ.js → MenuBottomSheet-BZecY8fw.js} +1 -1
  24. package/page/assets/{SchemaFields-CIF3WtC0.js → SchemaFields-BNNkvyyO.js} +1 -1
  25. package/page/assets/{ToolResultCharts-D3pQGTH1.js → ToolResultCharts-C3CPsfXl.js} +1 -1
  26. package/page/assets/{TraceInspector-Bx3j_185.js → TraceInspector-36e6ozKD.js} +1 -1
  27. package/page/assets/{TraceOverview-ChpCMZRa.js → TraceOverview-CSdJ_cYY.js} +3 -3
  28. package/page/assets/{_virtual_studio-type-sources-BwSqfSwd.js → _virtual_studio-type-sources-DSpwr3WK.js} +143 -13
  29. package/page/assets/browser-connection-dads1eyK.js +3 -0
  30. package/page/assets/browser-engine-CugH58NS.js +13 -0
  31. package/page/assets/browser-transport-GzhRiBdm.js +45 -0
  32. package/page/assets/{crypto-CD14HeXH.js → crypto-B8dqEoWf.js} +1 -1
  33. package/page/assets/{encode-files-DhoC5hWG.js → encode-files-CHeRLBO8.js} +1 -1
  34. package/page/assets/{export-agent-nlvsxs9-.js → export-agent-botXSyoH.js} +3 -3
  35. package/page/assets/{guardrail-tester-C7r03f5Z.js → guardrail-tester-DYR7EPIy.js} +2 -2
  36. package/page/assets/index-B7sK7d-l.js +153 -0
  37. package/page/assets/live-messages-DN_q2nBN.js +1 -0
  38. package/page/assets/project-address-DjxPZuyn.js +1 -0
  39. package/page/assets/reader-DHN96tSr.js +5 -0
  40. package/page/assets/{schemas-BQ9Jydzb.js → schemas-D7cgkv3L.js} +1 -1
  41. package/page/assets/shaped-data-CJQ3W_RE.js +20 -0
  42. package/page/assets/{stub-nxRsh1jo.js → stub-U6wDGe3P.js} +25 -7
  43. package/page/assets/studio-code-pane-Boy63AK2.js +8 -0
  44. package/page/assets/{studio-console-BgymsByi.js → studio-console-B7zL133d.js} +1 -1
  45. package/page/assets/studio-decision-CbRjfbvG.js +1 -0
  46. package/page/assets/studio-embedding-DQ0QrEsu.js +2 -0
  47. package/page/assets/{studio-host-console-DtepSA77.js → studio-host-console-DDA2Um2-.js} +2 -2
  48. package/page/assets/{studio-labels-BZbz7-uL.js → studio-labels-jYWBoEyP.js} +1 -1
  49. package/page/assets/studio-live-D0YRu2zQ.js +5 -0
  50. package/page/assets/studio-map-C4Ra1QqL.js +1 -0
  51. package/page/assets/studio-session-CPnJaHc-.js +1 -0
  52. package/page/assets/studio-trace-replay-D-f2p7k9.js +3 -0
  53. package/page/assets/{studio-type-checker-BbUSqqOS.js → studio-type-checker-CVNPnko-.js} +1 -1
  54. package/page/assets/tool-schema-BDG2_rlP.js +17 -0
  55. package/page/assets/{trace-record-DxgSKmYY.js → trace-record-DoXjxrmJ.js} +1 -1
  56. package/page/assets/trace-schema--4IGmLeE.js +1 -0
  57. package/page/assets/tree-CcEbNvms.js +3 -0
  58. package/page/assets/turn-client-BmOSpCgw.js +2 -0
  59. package/page/assets/{use-one-call-DE5HvQsv.js → use-one-call-B3t-kfc5.js} +1 -1
  60. package/page/assets/{use-second-ticker-CEwOSS-d.js → use-second-ticker-CWjCHLG6.js} +1 -1
  61. package/page/assets/workspace-DUfaxr-g.js +1 -0
  62. package/page/index.html +20 -19
  63. package/people.d.ts +2 -0
  64. package/people.js +3 -1
  65. package/policy.js +1 -0
  66. package/providers.d.ts +2 -2
  67. package/providers.js +8 -3
  68. package/read-source.js +34 -7
  69. package/registrations.d.ts +23 -3
  70. package/runtime-scope.d.ts +6 -3
  71. package/runtime-scope.js +16 -4
  72. package/runtime.js +14 -2
  73. package/server/draft-handler.d.ts +4 -4
  74. package/server/draft-handler.js +3 -2
  75. package/server/draft-probe.d.ts +9 -1
  76. package/server/draft-probe.js +2 -1
  77. package/server/handler.js +71 -25
  78. package/server/live.d.ts +7 -1
  79. package/server/live.js +11 -4
  80. package/server/run-traces.d.ts +5 -1
  81. package/server/run-traces.js +7 -3
  82. package/server/save-new.js +5 -5
  83. package/server/save-session.js +4 -2
  84. package/server/serve.js +2 -1
  85. package/server/test-key.d.ts +2 -2
  86. package/server/test-key.js +1 -1
  87. package/slot-values.d.ts +2 -0
  88. package/slot-values.js +22 -0
  89. package/source.js +11 -4
  90. package/tool-readers.d.ts +23 -0
  91. package/tool-readers.js +60 -0
  92. package/tools.js +4 -1
  93. package/types.d.ts +3 -1
  94. package/ui/inspector-context.js +1 -1
  95. package/ui/lib/project-traces.d.ts +5 -0
  96. package/ui/lib/project-traces.js +21 -3
  97. package/ui/lib/studio-page.d.ts +6 -1
  98. package/ui/lib/studio-page.js +33 -31
  99. package/ui/lib/studio-project.d.ts +8 -1
  100. package/ui/lib/studio-project.js +19 -1
  101. package/ui/lib/studio-session.d.ts +2 -0
  102. package/ui/lib/studio-session.js +40 -2
  103. package/ui/lib/studio-store.d.ts +2 -2
  104. package/ui/lib/studio-store.js +9 -5
  105. package/ui/lib/tool-probe.d.ts +2 -0
  106. package/ui/lib/tool-probe.js +3 -2
  107. package/ui/lib/type-icons.d.ts +1 -0
  108. package/ui/lib/type-icons.js +2 -1
  109. package/ui/profile-editor.js +57 -21
  110. package/ui/studio-compare.d.ts +14 -4
  111. package/ui/studio-compare.js +58 -24
  112. package/ui/studio-live.d.ts +1 -1
  113. package/ui/studio-live.js +8 -3
  114. package/ui/studio-runner.d.ts +3 -2
  115. package/ui/studio-runner.js +16 -14
  116. package/ui/studio-screen.d.ts +1 -1
  117. package/ui/studio-screen.js +26 -20
  118. package/ui/studio-settings.js +3 -1
  119. package/ui/studio-trace-replay.js +7 -1
  120. package/workspace.js +3 -2
  121. package/page/assets/Banner-BkgdSxW_.js +0 -4
  122. package/page/assets/Center-nHS1JSux.js +0 -1
  123. package/page/assets/browser-connection-DSUHVCT5.js +0 -3
  124. package/page/assets/browser-engine-D1mbS8b9.js +0 -11
  125. package/page/assets/browser-transport-C8PD0IJk.js +0 -45
  126. package/page/assets/index-B7om06iO.js +0 -145
  127. package/page/assets/live-messages-CiLmR89m.js +0 -1
  128. package/page/assets/reader-DrOfMM8I.js +0 -5
  129. package/page/assets/shaped-data-H1miOZm2.js +0 -20
  130. package/page/assets/studio-code-pane-DA_z5w6h.js +0 -8
  131. package/page/assets/studio-decision-DWnr99n-.js +0 -1
  132. package/page/assets/studio-embedding-DCvI007w.js +0 -2
  133. package/page/assets/studio-live-CnyzlN29.js +0 -5
  134. package/page/assets/studio-map-DduCJzK7.js +0 -1
  135. package/page/assets/studio-session-CjUQSXx0.js +0 -1
  136. package/page/assets/studio-trace-replay-C0UPMVSt.js +0 -3
  137. package/page/assets/tool-schema-BmRYaywn.js +0 -17
  138. package/page/assets/trace-schema-9CdEyG6Q.js +0 -1
  139. package/page/assets/tree-3N-1RPZz.js +0 -3
  140. package/page/assets/turn-client-DN8PawJr.js +0 -2
  141. package/page/assets/workspace-CTSW941G.js +0 -1
package/server/handler.js CHANGED
@@ -12,12 +12,13 @@
12
12
  *
13
13
  * @module
14
14
  */
15
+ import { AsyncLocalStorage } from 'node:async_hooks';
15
16
  import { checkKey, defineProfile, getStructured, listProfiles, listProviders, listTools, } from '@theoremjs/agents';
16
17
  import { compileDetect } from '@theoremjs/agents/guardrails/compile';
17
18
  import { createProviderRegistry } from '@theoremjs/agents/kernel';
18
- import { createSealedConversationStore, createTheoremDecisionHandler, createTheoremEmbeddingHandler, createTheoremHandler, createTheoremHostHandler, isQuestionsBuilder, } from '@theoremjs/web/server';
19
+ import { createSealedConversationStore, createTheoremDecisionHandler, createTheoremEmbeddingHandler, createTheoremHandler, createTheoremHostHandler, isQuestionsBuilder, readBody, startConversation, theoremStartRequestSchema, } from '@theoremjs/web/server';
19
20
  import { differingSettings } from "../agreement.js";
20
- import { studioAskStage, studioAsks } from "../asks.js";
21
+ import { ASK_WRITES_HEADER, ASK_WRITES_PARAM, studioAskStage, studioAsks, } from "../asks.js";
21
22
  import { compileWorkspace } from "../compile-workspace.js";
22
23
  import { createBlankDraft } from "../draft.js";
23
24
  import { shownConnection, withoutCredentials } from "../held-credentials.js";
@@ -30,6 +31,7 @@ import { STUDIO_READER } from "../reader.js";
30
31
  import { withPatterns } from "../runtime-scope.js";
31
32
  import { studioSource } from "../source.js";
32
33
  import { createStudioDraftHandler, STUDIO_BASE } from "./draft-handler.js";
34
+ import { errorJson } from "./draft-replies.js";
33
35
  import { createStudioLiveHandler } from "./live.js";
34
36
  export { STUDIO_BASE } from "./draft-handler.js";
35
37
  import { addAgent, agentNodeId, createBlankWorkspace, workspaceFromDraft, } from "../workspace.js";
@@ -75,16 +77,24 @@ export function printableProfile(profile) {
75
77
  : profile;
76
78
  return plainSetting(recording);
77
79
  }
80
+ const registeredShape = (id) => ({
81
+ id,
82
+ spec: { jsonSchema: getStructured(id).jsonSchema },
83
+ });
78
84
  /**
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.
85
+ * The schemas a profile's replies take, as registered: its one schema, or the fallback beside the
86
+ * shapes a slot picks. None when the profile names one nothing registers.
81
87
  */
82
88
  function replySchema(profile) {
83
- const id = 'outputs' in profile ? profile.outputs?.structured : undefined;
84
- if (typeof id !== 'string')
89
+ const written = 'outputs' in profile ? profile.outputs?.structured : undefined;
90
+ if (!written)
85
91
  return undefined;
86
92
  try {
87
- return { id, spec: { jsonSchema: getStructured(id).jsonSchema } };
93
+ if (typeof written === 'string')
94
+ return registeredShape(written);
95
+ const picked = new Set(Object.values(written.map));
96
+ picked.delete(written.fallback);
97
+ return { ...registeredShape(written.fallback), also: [...picked].map(registeredShape) };
88
98
  }
89
99
  catch {
90
100
  return undefined;
@@ -296,9 +306,11 @@ function describeStudio(project, questions, images) {
296
306
  ...(modelProblems.length ? { modelProblems } : {}),
297
307
  ...(differences.length ? { differences } : {}),
298
308
  ...(unheld.length ? { unheld } : {}),
299
- asks: { asked: [], inside: [] },
309
+ asks: { asked: [], destructive: [], inside: [] },
300
310
  };
301
311
  }
312
+ /** Which tools that write the running request's builder said should ask. */
313
+ const runAsks = new AsyncLocalStorage();
302
314
  /**
303
315
  * Which registered tools ask the builder before each run, whatever their own setting: a run in
304
316
  * the studio is the project's real code, on whatever it reaches. The question is the studio's own
@@ -375,7 +387,7 @@ async function freshPerson(people, request, cors) {
375
387
  export function corsHeaders(request, pageOrigins) {
376
388
  return {
377
389
  'access-control-allow-origin': request.headers.get('origin') ?? pageOrigins[0] ?? '',
378
- 'access-control-allow-headers': `content-type, ${ACTING_AS_HEADER}`,
390
+ 'access-control-allow-headers': `content-type, ${ACTING_AS_HEADER}, ${ASK_WRITES_HEADER}`,
379
391
  'access-control-allow-methods': 'GET, POST, OPTIONS',
380
392
  vary: 'origin',
381
393
  };
@@ -499,7 +511,11 @@ function profileHandlers(options, problems, ask) {
499
511
  }
500
512
  if (profile.type === 'live') {
501
513
  if (options.upgrade) {
502
- served.set(profile.id, createStudioLiveHandler(profile, options.provider ?? {}, options.upgrade, ask));
514
+ served.set(profile.id, createStudioLiveHandler(profile, options.provider ?? {}, options.upgrade, {
515
+ ask,
516
+ session: shared.session,
517
+ host: shared.host,
518
+ }));
503
519
  }
504
520
  else
505
521
  problems.push({ profile: profile.id, message: NO_SOCKET });
@@ -515,18 +531,22 @@ function profileHandlers(options, problems, ask) {
515
531
  continue;
516
532
  }
517
533
  // 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
- })));
534
+ if (profile.type === 'host') {
535
+ served.set(profile.id, withRunTraces(createTheoremHostHandler({ profile: tracedToPage(profile), ...shared })));
536
+ continue;
537
+ }
538
+ // A stateless profile keeps no conversation, so it takes no store.
539
+ const isStateless = profile.providerContinuation?.history === 'stateless';
540
+ const chat = createTheoremHandler({
541
+ profile: tracedToPage(profile),
542
+ provider: options.provider ?? {},
543
+ ...(options.prepare ? { prepare: options.prepare } : {}),
544
+ ...(isStateless ? {} : { conversationStore: chatStore() }),
545
+ // The studio's page is the builder's own: its picks choose the prompt lines.
546
+ pageStatesTurn: true,
547
+ ...shared,
548
+ });
549
+ served.set(profile.id, withRunTraces(isStateless ? chat : startsConversations(chat, profile, chatStore(), shared.session)));
530
550
  }
531
551
  catch (error) {
532
552
  problems.push({
@@ -537,6 +557,30 @@ function profileHandlers(options, problems, ask) {
537
557
  }
538
558
  return served;
539
559
  }
560
+ /**
561
+ * `serve`, and `<profile>/conversation/start`: a chat that opens on blocks a trace holds, in the
562
+ * asking person's session, for a replay that goes on live.
563
+ * why: the project's run must open it, on the project's providers, and this server is the
564
+ * builder's alone. `createTheoremHandler` takes no transcript from a browser.
565
+ */
566
+ function startsConversations(serve, profile, store, session) {
567
+ return async (request) => {
568
+ const path = new URL(request.url).pathname;
569
+ if (!path.endsWith('/conversation/start'))
570
+ return serve(request);
571
+ if (request.method !== 'POST')
572
+ return new Response(null, { status: 405 });
573
+ try {
574
+ const { blocks } = await readBody(request, theoremStartRequestSchema);
575
+ const host = { sessionId: session(request), store };
576
+ const { ref, view } = await startConversation(host, profile, blocks);
577
+ return json(200, { conversation: ref, view }, {});
578
+ }
579
+ catch (error) {
580
+ return errorJson(error);
581
+ }
582
+ };
583
+ }
540
584
  /** `answer` with the page's CORS headers on it. */
541
585
  async function withCors(answer, cors) {
542
586
  const response = await answer;
@@ -600,14 +644,14 @@ export function createStudioHandler(options) {
600
644
  if (peopleProblem)
601
645
  description.peopleProblem = peopleProblem;
602
646
  const handlerOptions = { ...options, people };
603
- const served = profileHandlers(handlerOptions, description.problems, studioAskStage(description.asks.asked));
647
+ const served = profileHandlers(handlerOptions, description.problems, studioAskStage(description.asks, () => runAsks.getStore() === 'destructive'));
604
648
  const prefix = `${base}/profiles/`;
605
649
  const peoplePath = `${base}/people`;
606
650
  // The screen's own requests (the guardrail probe, the key and connection tests) need no project.
607
651
  // This server is the builder's alone, so a connection test reaches what the draft's runs reach.
608
652
  const draft = createStudioDraftHandler({
609
653
  draftNetwork: true,
610
- projectProvider: (id) => listProviders().find((provider) => provider.id === id),
654
+ projectProviders: listProviders,
611
655
  });
612
656
  const run = async (request, path) => {
613
657
  const cors = corsFor(request);
@@ -618,7 +662,9 @@ export function createStudioHandler(options) {
618
662
  const read = readActingAs(request, people);
619
663
  if (!read.ok)
620
664
  return json(400, { message: read.message }, cors);
621
- const response = await serve(request);
665
+ const asks = request.headers.get(ASK_WRITES_HEADER) ??
666
+ new URL(request.url).searchParams.get(ASK_WRITES_PARAM);
667
+ const response = await runAsks.run(asks, () => serve(request));
622
668
  // A socket's answer goes back as it is: it is not a response the page reads.
623
669
  if (response.status === 101)
624
670
  return response;
package/server/live.d.ts CHANGED
@@ -12,4 +12,10 @@ export type StudioUpgrade = (request: Request) => {
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
+ ask?: StageHandler;
17
+ /** Who the run acts as, by session, as a chat's is. */
18
+ session: (request: Request) => string;
19
+ /** The application's context for the tools (`ctx.host`), as a chat's turn has it. */
20
+ host?: (request: Request) => unknown;
21
+ }): (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, { ask, host }) {
55
55
  let session;
56
56
  try {
57
57
  // Listen before anything waits: the page sends its open message as the socket opens.
@@ -60,6 +60,7 @@ async function relay(socket, profile, provider, boundary, ask) {
60
60
  ...(await boundary.prepareLiveOpen(open)),
61
61
  profile: profile.id,
62
62
  ...(ask ? { onStage: ask } : {}),
63
+ ...(host === undefined ? {} : { host }),
63
64
  }, { ...provider, execution: boundary.toolExecution, pageExecution: boundary.pageExecution }, pageSink(socket, profile));
64
65
  }
65
66
  catch (error) {
@@ -84,17 +85,23 @@ async function relay(socket, profile, provider, boundary, ask) {
84
85
  });
85
86
  }
86
87
  /** 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) {
88
+ export function createStudioLiveHandler(profile, provider, upgrade, options) {
88
89
  const sessionStore = createMemorySessionStore();
89
90
  return async (request) => {
90
91
  if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
91
92
  return new Response(null, { status: 426, headers: { upgrade: 'websocket' } });
92
93
  }
93
- const boundary = await createTheoremSessionBoundary({ request, sessionStore });
94
+ const { ask, session, host } = options;
95
+ const boundary = await createTheoremSessionBoundary({
96
+ request,
97
+ sessionStore,
98
+ session,
99
+ pageStatesTurn: true,
100
+ });
94
101
  const { socket, response } = upgrade(request);
95
102
  if (boundary.setCookie)
96
103
  response.headers.append('set-cookie', boundary.setCookie);
97
- void relay(socket, profile, provider, boundary, ask);
104
+ void relay(socket, profile, provider, boundary, { ask, host: host?.(request) });
98
105
  return response;
99
106
  };
100
107
  }
@@ -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. */
@@ -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');
@@ -0,0 +1,23 @@
1
+ /**
2
+ * A tool's reader: a decision agent that keeps the passages of the tool's output that bear on the
3
+ * model's question, so the model reads less. The kernel has no such setting. A host writes it at
4
+ * `post_tool`, and this is the studio's.
5
+ */
6
+ import type { DecisionQuestion, DecisionResult, StageHandler } from '@theoremjs/agents';
7
+ import type { ToolRegistration } from './registrations.ts';
8
+ /** The decision agent that reads a tool's output, and what it asks of each passage. */
9
+ export interface ToolReader {
10
+ profile: string;
11
+ questions: Record<string, DecisionQuestion>;
12
+ }
13
+ /** Runs a reader on one passage. */
14
+ export type ReadPassage = (reader: ToolReader, state: {
15
+ question: string;
16
+ passage: string;
17
+ }) => Promise<DecisionResult>;
18
+ /** Each tool with a reader, by the tool's name. */
19
+ export declare function toolReaders(tools: readonly ToolRegistration[]): Map<string, ToolReader>;
20
+ /** Runs each tool's reader on its finished output. */
21
+ export declare function toolReaderStage(readers: ReadonlyMap<string, ToolReader>, read: ReadPassage): StageHandler;
22
+ /** One handler for a turn: `steer` keeps its stages, and `readers` adds what it asks. */
23
+ export declare function bothStages(steer: StageHandler, readers: StageHandler): StageHandler;
@@ -0,0 +1,60 @@
1
+ /**
2
+ * A tool's reader: a decision agent that keeps the passages of the tool's output that bear on the
3
+ * model's question, so the model reads less. The kernel has no such setting. A host writes it at
4
+ * `post_tool`, and this is the studio's.
5
+ */
6
+ /** Each tool with a reader, by the tool's name. */
7
+ export function toolReaders(tools) {
8
+ return new Map(tools.flatMap((tool) => tool.type !== 'agent' && tool.stageAgent && tool.stageQuestions
9
+ ? [
10
+ [tool.name, { profile: tool.stageAgent, questions: tool.stageQuestions }],
11
+ ]
12
+ : []));
13
+ }
14
+ /** Every choice question came out on its first choice, which keeps the passage. */
15
+ function kept(reader, result) {
16
+ return Object.entries(reader.questions).every(([id, question]) => {
17
+ if (question.type !== 'choice')
18
+ return true;
19
+ const answer = result.answers[id];
20
+ return answer?.type === 'choice' && answer.choice === Object.keys(question.criteria)[0];
21
+ });
22
+ }
23
+ async function readOutput(reader, ctx, read) {
24
+ const { outputRaw: output, input } = ctx;
25
+ const question = input?.question;
26
+ if (typeof output !== 'string' || typeof question !== 'string')
27
+ return undefined;
28
+ const passages = output
29
+ .split(/\n\s*\n/)
30
+ .map((passage) => passage.trim())
31
+ .filter(Boolean);
32
+ try {
33
+ const results = await Promise.all(passages.map((passage) => read(reader, { question, passage })));
34
+ const left = passages.filter((_, at) => {
35
+ const result = results[at];
36
+ return result !== undefined && kept(reader, result);
37
+ });
38
+ return left.length === passages.length ? undefined : { mutate: { output: left.join('\n\n') } };
39
+ }
40
+ catch {
41
+ // why: A filter that failed drops nothing: the model reads the page whole.
42
+ return undefined;
43
+ }
44
+ }
45
+ /** Runs each tool's reader on its finished output. */
46
+ export function toolReaderStage(readers, read) {
47
+ return (ctx) => {
48
+ if (ctx.stage !== 'post_tool' || ctx.failure || ctx.callNotStarted || ctx.awaiting)
49
+ return;
50
+ const reader = ctx.tool ? readers.get(ctx.tool) : undefined;
51
+ return reader && readOutput(reader, ctx, read);
52
+ };
53
+ }
54
+ /** One handler for a turn: `steer` keeps its stages, and `readers` adds what it asks. */
55
+ export function bothStages(steer, readers) {
56
+ return async (ctx) => {
57
+ const [steered, filtered] = await Promise.all([steer(ctx), readers(ctx)]);
58
+ return steered || filtered ? { ...steered, ...filtered } : undefined;
59
+ };
60
+ }
package/tools.js CHANGED
@@ -22,6 +22,7 @@ export function registerCustomTool(tools, tool, handlers = {}) {
22
22
  loadTier: tool.loadTier,
23
23
  permission: tool.permission,
24
24
  ...(tool.labels ? { labels: tool.labels } : {}),
25
+ ...(tool.after ? { after: true } : {}),
25
26
  };
26
27
  if (tool.type === 'agent') {
27
28
  tools.register({
@@ -93,7 +94,9 @@ export function registerStudioTools(tools, customTools, handlers) {
93
94
  export function registerDefined(registry, profile, customTools, structured, handlers) {
94
95
  registerStudioTools(registry.tools, customTools, handlers);
95
96
  if (structured && profile.type !== 'live') {
96
- registry.schemas.register(structured.id, structured.spec);
97
+ for (const { id, spec } of [structured, ...(structured.also ?? [])]) {
98
+ registry.schemas.register(id, spec);
99
+ }
97
100
  }
98
101
  registry.profiles.register(profile);
99
102
  return profile;
package/types.d.ts CHANGED
@@ -24,6 +24,8 @@ export type StudioToolSpecSeed = {
24
24
  stubOutputJson?: string;
25
25
  /** A function tool the page answers; the studio's page answers with the stub. */
26
26
  answeredBy?: 'page';
27
+ /** The model can name tools of its step that finish before this one starts. */
28
+ after?: boolean;
27
29
  endpoint?: string;
28
30
  method?: HttpMethod;
29
31
  headersJson?: string;
@@ -40,7 +42,7 @@ export type StudioToolSpecSeed = {
40
42
  sessionMax?: number | null;
41
43
  /** An agent tool's agent, by its workspace key. */
42
44
  agentKey?: string;
43
- /** A decision or text agent that filters this tool's output at `post_tool`, by its workspace key. */
45
+ /** A decision agent that filters this tool's output at `post_tool`, by its workspace key. */
44
46
  stageAgentKey?: string;
45
47
  /** An agent tool's calls in one turn of its caller; `null` or absent: no cap but max steps. */
46
48
  maxCallsPerTurn?: number | null;
@@ -29,7 +29,7 @@ export const RowOrigins = createContext(null);
29
29
  */
30
30
  export const ConfirmWrite = createContext(() => Promise.resolve(false));
31
31
  /** The project's tools that write: the ones the studio makes ask, and the ones it cannot. */
32
- export const ProjectAsks = createContext({ asked: [], inside: [] });
32
+ export const ProjectAsks = createContext({ asked: [], destructive: [], inside: [] });
33
33
  /** The origin a section around a row has already named, so the row does not name it again. */
34
34
  export const SaidOrigin = createContext(undefined);
35
35
  /**
@@ -8,6 +8,11 @@ export declare function recordsTraces(payload: StudioRunPayload | null): boolean
8
8
  * trace panel reads them: the same panel a draft's run fills in the playground. Each run carries
9
9
  * who it acts as, so the project's tools act for that person.
10
10
  */
11
+ /**
12
+ * A live call's socket on `endpoint`, carrying what a run's headers carry.
13
+ * why: a browser's `WebSocket` sends no headers.
14
+ */
15
+ export declare function liveSocketAddress(endpoint: string, actingAs: StudioActingAs | undefined): string;
11
16
  export declare function tracedTransport<T extends object>(make: (options: {
12
17
  endpoint: string;
13
18
  fetch: typeof fetch;
@@ -1,7 +1,9 @@
1
1
  import { resolveObservabilityPolicy } from '@theoremjs/agents';
2
- import { actingAsHeaders } from "../../people.js";
2
+ import { ASK_WRITES_HEADER, ASK_WRITES_PARAM } from "../../asks.js";
3
+ import { ACTING_AS_PARAM, actingAsHeader, actingAsHeaders, } from "../../people.js";
3
4
  import { eachLine, NDJSON } from "../../stream-lines.js";
4
5
  import { studioTraceLine } from "../../transport.js";
6
+ import { getPref } from "./studio-prefs.js";
5
7
  /** Whether the agent records traces, so the page can offer them: the rule every view reads. */
6
8
  export function recordsTraces(payload) {
7
9
  return payload !== null && resolveObservabilityPolicy(payload.profile.observability).record;
@@ -28,10 +30,15 @@ function withoutTraces(traces) {
28
30
  send(line);
29
31
  });
30
32
  }
31
- /** `fetch` for a project's runs: the studio's local server sends each run's trace behind its events. */
33
+ /**
34
+ * `fetch` for a project's runs: the studio's local server sends each run's trace behind its events.
35
+ * Each run says which tools that write ask, as the builder's setting stands when it starts.
36
+ */
32
37
  function tracedFetch(traces) {
33
38
  return async (input, init) => {
34
- const response = await fetch(input, init);
39
+ const headers = new Headers(init?.headers);
40
+ headers.set(ASK_WRITES_HEADER, getPref('askWrites'));
41
+ const response = await fetch(input, { ...init, headers });
35
42
  if (!response.body || !response.headers.get('content-type')?.startsWith(NDJSON))
36
43
  return response;
37
44
  return new Response(response.body.pipeThrough(withoutTraces(traces)), {
@@ -46,6 +53,17 @@ function tracedFetch(traces) {
46
53
  * trace panel reads them: the same panel a draft's run fills in the playground. Each run carries
47
54
  * who it acts as, so the project's tools act for that person.
48
55
  */
56
+ /**
57
+ * A live call's socket on `endpoint`, carrying what a run's headers carry.
58
+ * why: a browser's `WebSocket` sends no headers.
59
+ */
60
+ export function liveSocketAddress(endpoint, actingAs) {
61
+ const address = new URL(endpoint.replace(/^http/, 'ws'));
62
+ address.searchParams.set(ASK_WRITES_PARAM, getPref('askWrites'));
63
+ if (actingAs)
64
+ address.searchParams.set(ACTING_AS_PARAM, actingAsHeader(actingAs));
65
+ return address.href;
66
+ }
49
67
  export function tracedTransport(make, endpoint, traces, actingAs) {
50
68
  return {
51
69
  ...make({ endpoint, fetch: tracedFetch(traces), headers: actingAsHeaders(actingAs) }),
@@ -2,16 +2,20 @@
2
2
  * What the studio's page sends an agent: a value for each of its slots and its context
3
3
  * package. Kept in this tab beside the conversation, never in the profile.
4
4
  */
5
+ import type { StatedTurn } from '@theoremjs/web/client';
5
6
  import { type SlotDraft, type StudioRunPayload } from '../../mod.ts';
6
- /** What the builder set: the value picked for each slot, and the context as typed. */
7
+ /** What the builder set: the value picked for each slot and condition, and the context as typed. */
7
8
  export interface PageValues {
8
9
  slots: Record<string, string>;
10
+ conditions: Record<string, string>;
9
11
  contextJson: string;
10
12
  }
11
13
  /** What the agent takes from a page. */
12
14
  export interface PageInputs {
13
15
  /** Allowed values per slot name (descriptions stay on the profile / chat UI). */
14
16
  slots: Record<string, readonly string[]>;
17
+ /** Allowed values per condition name: which prompt lines the turn gets. */
18
+ conditions: Record<string, readonly string[]>;
15
19
  takesContext: boolean;
16
20
  /** The tools the page answers. Only a call asks the page. */
17
21
  pageTools: string[];
@@ -31,6 +35,7 @@ export declare function pageInputsOf(payload: StudioRunPayload): PageInputs | nu
31
35
  /** What goes with a turn or a call. Context that is not JSON is not sent, and says why. */
32
36
  export declare function sentPageValues(inputs: PageInputs | null, values: PageValues): {
33
37
  slots?: Record<string, string>;
38
+ stated?: StatedTurn;
34
39
  context?: unknown;
35
40
  contextError?: string;
36
41
  };