@theoremjs/studio 0.0.0-stage → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ORCHID AI LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,296 @@
-# Temporary Holding Version
+# @theoremjs/studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@theoremjs/studio?logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/@theoremjs/studio)
+[![CI](https://github.com/masudl-hub/theoremai/actions/workflows/ci.yml/badge.svg)](https://github.com/masudl-hub/theoremai/actions/workflows/ci.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/masudl-hub/theoremai/blob/main/LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/masudl-hub/theoremai)
+
+Edit, run, and test Theorem agents in a studio: on your own project with one command, or as a screen in your own app.
+
+## The idea
+
+The **studio** is a screen for one agent **profile** (see [`@theoremjs/agents`](https://www.npmjs.com/package/@theoremjs/agents)) at a time. You edit the profile as a form or as code, run it in a chat beside the editor, and probe its guardrails.
+
+The screen keeps the profile it edits in the browser, as a **draft**. It sends the draft with every request to a server under `/api/studio`. You choose which server answers:
+
+```text
+                    ┌──────────────────────────────┐
+                    │ BROWSER                      │
+                    │ <StudioScreen />             │
+                    │ edits the draft · runs it    │
+                    └──────────────┬───────────────┘
+                                   │ POST /api/studio/*
+                                   │ (the draft rides along)
+                 ┌─────────────────┴──────────────────┐
+                 ▼                                    ▼
+┌────────────────────────────────┐  ┌────────────────────────────────┐
+│ THE COMMAND                    │  │ YOUR APP                       │
+│ npx theorem-studio             │  │ createStudioDraftHandler()     │
+│                                │  │                                │
+│ your project, on this machine  │  │ any visitor, on your server    │
+│ saves edits to your files      │  │ saves nothing                  │
+└────────────────────────────────┘  └────────────────────────────────┘
+```
+
+- **The command** opens your project's agents. It runs them with your project's tools and keys, and writes your edits back to your files.
+- **The screen in your app** shows the same studio to your users. Your server answers with one handler. It runs drafts only on keys you choose to lend.
+
+## Install
+
+```bash
+npm install -D @theoremjs/studio @theoremjs/agents @theoremjs/react
+```
+
+The command needs [Deno](https://deno.com). The installed `@theoremjs/studio`, `@theoremjs/agents`, and `@theoremjs/react` versions must match exactly.
+
+To show the screen in your app, also install the peers at the versions this package lists in `peerDependencies`:
+
+```bash
+npm install react react-dom zod @astryxdesign/core@0.7.0 @astryxdesign/theme-neutral@0.7.0 @stylexjs/stylex@0.19.0
+```
+
+## Open your project
+
+```bash
+npx theorem-studio
+```
+
+The command starts two servers that only this machine reaches: your project's server, under Deno, and the studio's page. It opens the project's **setup file**: `studio.setup.ts` or `<name>.studio.setup.ts`. When the project has several, it asks which one.
+
+Add `"studio": "theorem-studio"` to your scripts to run it as `npm run studio`.
+
+```text
+theorem-studio [setup] [--editor <command>] [--deno-config <file>] [--no-watch]
+```
+
+| Option | What it does |
+| --- | --- |
+| `setup` | The setup file to open, by its file or its name. |
+| `--editor <command>` | The editor the studio opens a line of your files in. Default: `$VISUAL` or `$EDITOR` when it opens a window, else `code`. |
+| `--deno-config <file>` | The Deno config your project loads with. Default: the `deno.json` or `deno.jsonc` in the folder you ran the command in, else the studio's. |
+| `--no-watch` | Do not watch the files the setup reads. The studio reads them again when you come back to it. |
+
+### What a setup file exports
+
+Every export is optional. The studio reads only these:
+
+| Export | What the studio does with it |
+|---|---|
+| `default()` | Calls it once as it loads the project, before anything runs: register the project's profiles and tools here. It may be `async`. |
+| `provider` | The keys, network, and limits every model call runs on (`ProviderHostOptions` from `@theoremjs/agents/kernel`). Without it, a run's model call fails for want of a key. |
+| `people`, `host` | Who a run's tools act for (below). |
+| `questions` | What each decision profile asks, by the profile's id: `{ [profileId]: { [questionId]: DecisionQuestion } }`. |
+| `images` | The pictures each decision profile sends with every decision, by the profile's id: `{ [profileId]: { [reference]: DecisionAsset } }`, where a reference is the name its questions write, such as `'<ghs02>'`. |
+
+### Keys a run uses
+
+A profile's model names a key slot. `provider.vault` holds a key for each slot, so a studio run signs with the key the same profile uses in your app. Load the keys however your start script does, and read them when the setup file loads; the studio never writes them down:
+
+```ts
+export const provider = {
+  vault: { openai: Deno.env.get('OPENAI_API_KEY') ?? '' },
+};
+```
+
+For a key that comes from a secret store, a slot can hold a function instead. The studio calls it with the provider and slot when a call needs the key. A slot left out or empty fails that run with the slot's name, not a guess at another key.
+
+### Who a run acts as
+
+A setup file can export `people` and `host` to let the builder pick who the project's tools act for:
+
+```ts
+import type { StudioActingAs, StudioPeople } from '@theoremjs/studio/people';
+
+export const people: StudioPeople = {
+  places: [{ id: 'stage', label: 'Stage' }],
+  existing: (place) => [{ id: 'user-1', label: 'Test keeper' }], // optional
+  fresh: (place) => makeTestUser(place), // optional; removing it later is yours
+  start: undefined, // optional pick the studio opens on; without it, no one
+};
+export function host(request: Request, actingAs: StudioActingAs | undefined): unknown {
+  return actingAs ? buildContextFor(actingAs.person.id) : undefined;
+}
+```
+
+The builder picks a place and a person in Settings, under People. Each run carries the pick, and `host` builds the tools' context from it. `host` may be `async`; the run waits for it. Each person keeps their own chat and session. Without `people`, every run acts as no one.
+
+## Show the studio in your app
+
+Use this when your users should edit and run agents on your site: a playground, or an internal tool. You need a Vite build, the screen, and one server route.
+
+### 1. Add the Vite plugin
+
+`studioVite` resolves the screen's packages to your install, so your page has one copy of React and Astryx. It also serves the code editor's icons and the type declarations it checks a profile's code against.
+
+```ts
+// vite.config.ts
+import { studioVite } from '@theoremjs/studio/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [react(), studioVite({ hostRoot: import.meta.dirname })],
+});
+```
+
+`hostRoot` is the folder of the app that shows the screen.
+
+### 2. Show the screen
+
+```tsx
+import { LayerProvider } from '@astryxdesign/core/Layer';
+import { Theme } from '@astryxdesign/core/theme';
+import { theoremStudioTheme } from '@theoremjs/studio/ui/built/theorem-studio.ts';
+import { openStudio } from '@theoremjs/studio/ui/lib/studio-open.ts';
+import { StudioScreen } from '@theoremjs/studio/ui/studio-screen.tsx';
+import '@theoremjs/studio/ui/figtree.css';
+import '@astryxdesign/core/reset.css';
+import '@astryxdesign/core/astryx.css';
+import '@theoremjs/studio/ui/built/theme.css';
+import '@theoremjs/studio/ui/motion.css';
+
+export function Studio() {
+  return (
+    <Theme theme={theoremStudioTheme} mode="dark">
+      <LayerProvider>
+        <StudioScreen opened={openStudio()} host={{ kernelVersion: '0.3.1' }} />
+      </LayerProvider>
+    </Theme>
+  );
+}
+```
+
+Render it in the browser only. `openStudio()` reads the tab's kept workspace, so it does not run on a server.
+
+`host` tells the screen about your page:
+
+| Field | What it does |
+| --- | --- |
+| `kernelVersion` | The `@theoremjs/agents` version, shown under the studio's title. Required. |
+| `lentKeys` | Keys your page lends to whoever opens the studio. See [Lend your keys](#lend-your-keys). |
+| `toolHandlers` | Handlers for your page's own function tools, by name. A tool with none answers with its sample reply or a stub. |
+| `hasSettings` | True when your page has a door to Settings. Keys then show in Settings, not in the editor's header. |
+| `mountSurface` | Mounts the screen's surface while the screen is open, and returns the unmount. |
+| `onReport` | Called as what is on screen changes, and with `null` when the screen closes. |
+
+### 3. Answer at `/api/studio`
+
+The screen sends every request under `/api/studio`. Mount one handler there:
+
+```ts
+import { createStudioDraftHandler, STUDIO_BASE } from '@theoremjs/studio/server';
+
+const studio = createStudioDraftHandler();
+
+export default {
+  fetch(request: Request): Promise<Response> | Response {
+    if (new URL(request.url).pathname.startsWith(`${STUDIO_BASE}/`)) return studio(request);
+    return new Response('Not found', { status: 404 });
+  },
+};
+```
+
+The handler takes a Web `Request` and returns a `Response`. It serves no project: each request carries its draft.
+
+Without lent keys, the handler answers three requests:
+
+- the guardrail probe, on a scripted model, so no model is called;
+- the key test, for a key the builder types;
+- the tool connection test, which reaches public hosts only.
+
+Drafts then run in the browser, on the builder's own keys.
+
+To call `onProbePassed` after the reply on a Worker, pass `ctx.waitUntil` as the second argument: `studio(request, (work) => ctx.waitUntil(work))`.
+
+## Lend your keys
+
+Use this when visitors without a key should still run drafts: a public playground on your free-tier keys. The drafts then run on your server, so you decide what they may use.
+
+You describe the keys once, as a `LentKeys`. It says which models the keys run and which built-in tools each model may use. It also says how large a decision may be, including how many images it may carry (`decision.images`) and how heavy each may be (`decision.imageBytes`). A decision's own pictures and the ones dropped into its state count together, and what runs on the keys keep to. Give the same `LentKeys` to the screen and to the handler:
+
+```ts
+import type { LentKeys } from '@theoremjs/studio';
+import { createStudioDraftHandler } from '@theoremjs/studio/server';
+
+declare const keys: LentKeys;
+declare const env: { GEMINI_KEY: string };
+
+const studio = createStudioDraftHandler({
+  lent: {
+    mode: 'demo',
+    keys,
+    // Fill each key slot the draft's models name.
+    hostOptions: (profile) => ({
+      vault: Object.fromEntries(
+        'models' in profile
+          ? Object.values(profile.models).flatMap((model) => (model.keySlot ? [[model.keySlot, env.GEMINI_KEY]] : []))
+          : [],
+      ),
+    }),
+  },
+  spend: (kind, request) => {
+    // Count `kind` for whoever sent `request`. Throw a TheoremError to refuse it.
+  },
+});
+```
+
+```tsx
+<StudioScreen opened={openStudio()} host={{ kernelVersion: '0.3.1', lentKeys: keys }} />
+```
+
+`hostOptions` gets each draft's profile. The draft names its own key slots, so fill the slots its models name. A decision or embedding whose vault holds no key is refused with `auth`.
+
+With `lent`, the handler also runs chats, calls, decisions, and embeddings. A draft that names a model the keys do not run is refused with the reason `LentKeys.violation` gives.
+
+| Option | What it does |
+| --- | --- |
+| `lent` | `{ mode: 'demo', keys }`, with `hostOptions` filling each profile's key slots, and your tool handlers. Without it, no draft runs on the server. |
+| `spend` | Spends one `decision`, `call`, or `agent` turn for whoever sent the request, before it runs. Throw a `TheoremError` to refuse it; the screen shows its wording. Default: nothing is counted. |
+| `resolveHost` | Resolves the names the connection test calls, so the network guard refuses one that answers a private address. Workers have no DNS lookup: pass `dnsOverHttpsResolver(...)`. Default: `lent.resolveHost`. |
+| `onProbePassed` | Gets each probed text that some guardrail boundary let through, after the reply. |
+| `sessionStore`, `pageToolBroker`, `steer` | Where visitor sessions, page tool results, and a running chat's steers are kept. Default: in memory. A host on several isolates needs stores they all reach. |
+| `conversationKey` | The key chat conversations are sealed with. Default: a new one for this handler's lifetime. A restart, or another isolate, then cannot open a chat, and the chat continues from the page's transcript. Pass one key to every isolate to keep each conversation on the server. |
+| `draftNetwork` | True only when the handler serves the builder alone, on their own machine, as the command's does. A connection test then keeps to the draft's network guardrail. Otherwise it reaches public hosts only. |
+
+Live calls on lent keys open a WebSocket to `/api/live/relay`, not `/api/studio`. This package does not ship that relay. Build it on your server with `attachStudioLiveSession` from `@theoremjs/studio/browser`, and see the relay section of [`@theoremjs/react`](https://www.npmjs.com/package/@theoremjs/react).
+
+## Entry points
+
+| Import | What it holds |
+| --- | --- |
+| `theorem-studio` | The command. |
+| `@theoremjs/studio/server` | `createStudioDraftHandler`, `STUDIO_BASE`, and their types. |
+| `@theoremjs/studio/ui/*` | The screen: `ui/studio-screen.tsx`, `ui/lib/studio-open.ts`, the theme in `ui/built/`, and the stylesheets. |
+| `@theoremjs/studio/vite` | `studioVite`. |
+| `@theoremjs/studio/people` | `StudioPeople` and `StudioActingAs`, for a setup file. |
+| `@theoremjs/studio/browser` | Runs a draft in the browser on the builder's keys, and `attachStudioLiveSession` for a live relay. |
+| `@theoremjs/studio/runtime` | `studioScope` and the run functions the handler is built on, for a server of your own. |
+| `@theoremjs/studio/surface` | `studioSurface`: the draft as nodes an agent can read and set. |
+| `@theoremjs/studio` | The draft and its tools (below). |
+
+## The `@theoremjs/studio` entry
+
+Use these when you build on the studio's draft yourself: compile it, export it as source, or probe its guardrails.
+
+| Export | Purpose |
+| --- | --- |
+| `StudioDraft`, `createBlankDraft()`, `createExampleDraft()` | Editable profile draft; blank, or the travel concierge |
+| `createDecisionExampleDraft()`, `DECISION_EXAMPLE_STATE`, `decisionExampleAssets()` | The decision example: Jev 1.14 asked about a pantry shelf, with box, Number and Choice questions. Its four pictures ship with it, and load only when the example is made, so both functions return a promise. The ginger, the colour chart and the flag are the decision's own, sent with every decision. The chart question sets its box's image to `<apple_ripeness>`. The run tab starts with the shelf in its state. Each is written as its reference, such as `<ginger>`, in the state or in the questions. The shelf and ginger photos are CC0 and the flag is public domain, all from Wikimedia Commons. The colour chart was drawn for the example |
+| `createLiveExampleDraft()`, `createNarratorExampleDraft()`, `createConsoleExampleDraft()`, `createArchitectWorkspace()` | The other examples: the concierge as a live agent, a speech narrator, a host tool console, and a code architect that calls the narrator through an agent tool |
+| `setProfileType()`, `includeFacet()`, `excludeFacet()`, `newModelBinding()`, `newToolSpec()` | Draft edits that keep it consistent with `PROFILE_GRAPH` |
+| `studioTree()`, `studioNodeRef()`, `modelBindingNodeId()`, `toolSpecNodeId()` | The draft as a tree; node ids that issues point at |
+| `compileStudio()` | Draft → profile definition, custom tools, structured schema; or issues keyed by node |
+| `studioSource()` | Compiled draft as a TypeScript module (`registerTool`, `defineProfile`, `registerProfile`) |
+| `LentKeys`, `LentHolds`, `StudioRunsOn`, `ON_OWN_KEYS`, `modelBindingViolation()` | What a studio runs on: a page's lent keys (which models, built-ins, and decision sizes they allow, and what runs on them keep to whatever a profile says), or the builder's own keys or machine, where a profile runs as written |
+| `zodFromJsonSchema()`, `parseJsonSchema()` | Authored JSON Schema → Zod for registration |
+| run-payload helpers, `studioRunDefines()`, `clearStaleStudioRuns()` | Handoff of a compiled draft to the run tab, whether a kept run still defines on this package, and clearing the ones that do not |
+| `createStudioTransport()`, `studioInterface()` | The run tab's transport for a compiled draft; its `traces` feed receives the records each run writes |
+| `runGuardrailProbes()`, `runGuardrailProbe()`, `probeDraft()`, `PROBE_BOUNDARIES`, `PROBE_BOUNDARY_NOTES`, `PROBE_STATUSES` | Test a draft's guardrails: send one text across every boundary, or across one, on a scripted model. Each boundary answers with a status (passed, flagged, redacted, or blocked), whether its turn was tainted by a remote read, the guardrail events, what went on past the boundary, and the turn's trace records. No model or host is called. Each boundary's note says what crosses it, when the kernel reads it and what the kernel does there |
+| `PROBE_BATTERY` | Hard texts to probe with: disguised attacks and harmless texts that look like attacks, each with the boundary it crosses and whether a guardrail should act on it |
+| `createStudioTraceRouter()`, `STUDIO_RUN_METADATA_KEY`, `StudioTraceLine` | Trace delivery: the server registers the router's sink for `STUDIO_TRACE_DESTINATION`; each run opens a route and passes its metadata, and gets back `{ type: 'trace', record }` lines (after a text run's events, or on the Live socket as each record is written) |
+| `demoToolSpecs()`, `demoInputsSpec()` | Every example tool seed, and the inputs facet seed |
+| `DEMO_CONCIERGE_SYSTEM`, `DEMO_ALLOWED_HOSTS` | Demo system prompt and egress allowlist |
+| `DEMO_HTTP_SAMPLE_INPUT`, `demoHttpSampleInput()` | Connection-test payloads for demo HTTP tools |
+| `registerStudioTools()`, `StudioToolHandlers` | Register a draft's tools; a function tool answers with its sample reply, else the handler the host gives for its name, else a stub from its output schema |
+| `stubOutputFromSchema()` | Generic stub object from a JSON Schema |
+| `StudioInputsSpec`, `StudioToolSeed`, `StudioToolSpecSeed` | Serializable seed shapes |

package/agreement.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether a profile the studio opened is the profile the project registered. The studio reads a
+ * profile into its own draft and compiles it back; the two may differ only in the settings the
+ * studio's policy sets for itself, and any other difference is one the studio has to show.
+ *
+ * @module
+ */
+/**
+ * Each setting `studio` holds differently from `project`, by its path. A setting left out is the
+ * value the kernel says leaving it out stands for, and where the kernel names no such value,
+ * left out and written are two things. A section left out is one written with nothing in it: each
+ * setting in it is then read as left out, and a difference is named where it is.
+ */
+export declare function differingSettings(project: unknown, studio: unknown): string[];

package/agreement.js

@@ -0,0 +1,80 @@
+/**
+ * Whether a profile the studio opened is the profile the project registered. The studio reads a
+ * profile into its own draft and compiles it back; the two may differ only in the settings the
+ * studio's policy sets for itself, and any other difference is one the studio has to show.
+ *
+ * @module
+ */
+import { resolveAllow, resolveDetect } from '@theoremjs/agents/guardrails';
+import { unsetValue } from '@theoremjs/agents/kernel';
+import { STUDIO_POLICY_UNSET } from "./policy.js";
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Whether the studio holds `theirs` at `path` only because the project left it out: its policy fills it in. */
+function isPolicyFill(path, ours, theirs) {
+    return (ours === undefined && theirs !== undefined && STUDIO_POLICY_UNSET[path.join('.')] === theirs);
+}
+/** `held` without the table the kernel works out from its patterns. */
+const uncompiled = ({ compiled: _, ...held }) => held;
+/**
+ * What the kernel reads `detect` as: each detector's action at each boundary, whose patterns it
+ * reads with, and what it lets through. Two settings the kernel reads the same are the same here.
+ */
+function detectAsRead(detect) {
+    if (detect === undefined)
+        return undefined;
+    const { sources = {}, host = [], ...read } = resolveDetect(detect);
+    const allow = Object.entries(resolveAllow(detect)).map(([detector, held]) => [
+        detector,
+        {
+            ...held,
+            fromTools: held.fromTools ?? unsetValue(['guardrails', 'detect', detector, 'allow', 'fromTools']),
+        },
+    ]);
+    return {
+        ...read,
+        sources: Object.fromEntries(Object.entries(sources).map(([detector, source]) => [detector, uncompiled(source)])),
+        host: Object.fromEntries(host.map(({ id, ...rule }) => [id, uncompiled(rule)])),
+        allow: Object.fromEntries(allow),
+    };
+}
+/** A profile with its `detect` as the kernel reads it. */
+function asRead(profile) {
+    if (!isRecord(profile) ||
+        !isRecord(profile.guardrails) ||
+        profile.guardrails.detect === undefined)
+        return profile;
+    return {
+        ...profile,
+        guardrails: { ...profile.guardrails, detect: detectAsRead(profile.guardrails.detect) },
+    };
+}
+/**
+ * Each setting `studio` holds differently from `project`, by its path. A setting left out is the
+ * value the kernel says leaving it out stands for, and where the kernel names no such value,
+ * left out and written are two things. A section left out is one written with nothing in it: each
+ * setting in it is then read as left out, and a difference is named where it is.
+ */
+export function differingSettings(project, studio) {
+    const found = [];
+    const walk = (ours, theirs, path) => {
+        if (isPolicyFill(path, ours, theirs))
+            return;
+        let [mine, yours] = [ours ?? unsetValue(path), theirs ?? unsetValue(path)];
+        if (mine === undefined && isRecord(yours))
+            mine = {};
+        if (yours === undefined && isRecord(mine))
+            yours = {};
+        if (JSON.stringify(mine) === JSON.stringify(yours))
+            return;
+        if (!isRecord(mine) || !isRecord(yours)) {
+            found.push(path.join('.'));
+            return;
+        }
+        for (const key of new Set([...Object.keys(mine), ...Object.keys(yours)]))
+            walk(mine[key], yours[key], [...path, key]);
+    };
+    walk(asRead(project), asRead(studio), []);
+    return found;
+}

package/asks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The question the studio puts before a real run of a tool that writes: which tool, how it is
+ * set, what the run sends, and where. A tool that only reads is run unasked.
+ *
+ * @module
+ */
+import type { ToolSpecDraft } from './draft.ts';
+/** What the builder reads before a tool that writes runs. */
+export interface WriteAsk {
+    tool: string;
+    access: Exclude<ToolSpecDraft['access'], 'read-only'>;
+    /** The request the run makes, as `METHOD address`. */
+    sends: string;
+    /** The input the run sends, as the JSON the builder typed. */
+    input: string;
+}
+/**
+ * The question to put before the editor's Test of `tool`, or undefined when the test needs none:
+ * the tool only reads, or the test only lists an MCP server's tools and calls none.
+ */
+export declare function writeAsk(tool: ToolSpecDraft, input: string): WriteAsk | undefined;
+/** What the question says above the input. */
+export declare function writeAskLine(ask: WriteAsk): string;
+/** A registered tool, as far as asking goes. An agent tool names the profile it runs. */
+export interface AskTool {
+    name: string;
+    type: string;
+    access: string;
+    permission: string;
+    profile?: string;
+}
+/** Which of a project's tools the studio makes ask, and which it cannot. */
+export interface StudioAsks {
+    /** The tools that ask before each run here and would not in the application. */
+    asked: string[];
+    /**
+     * The tools that write and run unasked: a called agent runs them, and a question inside a called
+     * agent has no one to answer it. The call to that agent asks instead.
+     */
+    inside: string[];
+}
+/**
+ * The tools the studio makes ask before each run: every one that writes, and every agent tool
+ * whose agent can reach one that writes. A tool a called agent runs is left as it is, because the
+ * kernel refuses a called agent whose tool can stop on a question.
+ */
+export declare function studioAsks(tools: readonly AskTool[], allowed: (profile: string) => readonly string[]): StudioAsks;

package/asks.js

@@ -0,0 +1,54 @@
+/**
+ * The question the studio puts before a real run of a tool that writes: which tool, how it is
+ * set, what the run sends, and where. A tool that only reads is run unasked.
+ *
+ * @module
+ */
+/**
+ * The question to put before the editor's Test of `tool`, or undefined when the test needs none:
+ * the tool only reads, or the test only lists an MCP server's tools and calls none.
+ */
+export function writeAsk(tool, input) {
+    if (tool.access === 'read-only' || tool.toolType !== 'http')
+        return undefined;
+    return {
+        tool: tool.toolName,
+        access: tool.access,
+        sends: `${tool.method ?? 'GET'} ${tool.endpoint ?? ''}`.trim(),
+        input: input.trim() || '{}',
+    };
+}
+/** What the question says above the input. */
+export function writeAskLine(ask) {
+    const set = ask.access === 'destructive' ? 'destructive' : 'read and write';
+    return `It is set as ${set}. Run sends a real request: ${ask.sends}`;
+}
+/**
+ * The tools the studio makes ask before each run: every one that writes, and every agent tool
+ * whose agent can reach one that writes. A tool a called agent runs is left as it is, because the
+ * kernel refuses a called agent whose tool can stop on a question.
+ */
+export function studioAsks(tools, allowed) {
+    const named = new Map(tools.map((tool) => [tool.name, tool]));
+    const runs = (tool) => tool.type === 'agent' && tool.profile ? allowed(tool.profile) : [];
+    const inside = new Set(tools.flatMap(runs));
+    const writes = (tool, seen) => {
+        if (seen.has(tool.name))
+            return false;
+        seen.add(tool.name);
+        if (tool.access !== 'read-only')
+            return true;
+        return runs(tool).some((name) => {
+            const inner = named.get(name);
+            return inner !== undefined && writes(inner, seen);
+        });
+    };
+    // A provider's built-in tool runs on the provider and never stops on a question.
+    const writing = tools.filter((tool) => tool.type !== 'builtin' && writes(tool, new Set()));
+    return {
+        asked: writing
+            .filter((tool) => !inside.has(tool.name) && tool.permission !== 'always_confirm')
+            .map((tool) => tool.name),
+        inside: writing.filter((tool) => inside.has(tool.name)).map((tool) => tool.name),
+    };
+}

package/browser-connection.d.ts

@@ -0,0 +1,49 @@
+import { type KeyVault } from '@theoremjs/agents';
+import type { StudioBrowserRuntime } from './browser-transport.ts';
+/** Browser-only host configuration. Never part of a compiled profile or persisted run payload. */
+export interface StudioBrowserConnection {
+    /** One vault for every provider; each model reads the slot it names. */
+    vault: KeyVault;
+    /** A local model that needs a token names a slot, like any other model. */
+    local: {
+        baseUrl: string;
+    };
+    remoteTools: boolean;
+}
+/** Which service a pasted key belongs to, from its published prefix; `undefined` when unknown. */
+export declare function keyKind(secret: string | undefined): 'gemini' | 'openrouter' | undefined;
+export declare function localStudioConfig(local: StudioBrowserConnection['local']): NonNullable<StudioBrowserRuntime['providers']>['local'];
+export declare const STUDIO_KEY_SLOT_CAP = 32;
+/** The same localhost origin and transport used for inference; never a site proxy. */
+export declare function listLocalStudioModels(local: StudioBrowserConnection['local'], signal?: AbortSignal): Promise<string[]>;
+/** The profile types a model runs for; a provider's list is filtered to the one being edited. */
+export type ListedProfileType = 'text' | 'image' | 'speech' | 'live' | 'embedding';
+/** A model a provider lists, as the studio's picker shows it. */
+export interface ProviderModel {
+    /** What the profile's `apiId` is set to. */
+    id: string;
+    label: string;
+}
+/** The providers whose models the studio can list from the browser. */
+export type ListedProvider = 'gemini' | 'openrouter';
+export declare const KNOWN_GEMINI_EMBEDDING_MODELS: readonly ProviderModel[];
+export declare const KNOWN_OPENROUTER_EMBEDDING_MODELS: readonly ProviderModel[];
+/**
+ * The models a provider offers for a profile type, fetched from the browser with the key in this
+ * tab, never through the site. OpenRouter lists without a key and says what each model returns, so
+ * its list keeps only models of the profile's kind. Gemini needs the key and says only which calls
+ * a model takes, so its list keeps the models that answer a turn (live models for live).
+ */
+export declare function listProviderModels(provider: ListedProvider, profileType: ListedProfileType, key: string | undefined, signal?: AbortSignal): Promise<ProviderModel[]>;
+/** Slot references come from the compiled contract, including each model's overrides. */
+export declare function studioKeySlots(profile: {
+    type?: string;
+    key?: string;
+    fallbackKey?: string;
+    models?: Record<string, {
+        keySlot?: string;
+        fallbackKeySlot?: string;
+    }>;
+}): string[];
+/** Defines even empty referenced slots, so names such as `constructor` never read inherited values. */
+export declare function studioVault(slots: readonly string[], vault: KeyVault): KeyVault;