@theoremjs/studio 0.0.0-stage → 0.3.2

package/system-markup.js

@@ -0,0 +1,51 @@
+const OPEN = /\{\s*private\s*:/g;
+function lineAt(text, index) {
+    return text.slice(0, index).split('\n').length;
+}
+/**
+ * A section closes at the `}` that balances its `{`, so braces inside it pair
+ * up as written. Its text is trimmed; the text around it is kept as written,
+ * apart from the ends of the whole prompt.
+ */
+function parseSystemMarkup(text) {
+    const parts = [];
+    let at = 0;
+    for (const open of text.matchAll(OPEN)) {
+        if (open.index < at)
+            continue;
+        let depth = 1;
+        let close = open.index + open[0].length;
+        for (; close < text.length && depth > 0; close++) {
+            if (text[close] === '{')
+                depth++;
+            else if (text[close] === '}')
+                depth--;
+        }
+        if (depth > 0) {
+            return {
+                ok: false,
+                message: `The {private: section on line ${String(lineAt(text, open.index))} has no closing }.`,
+            };
+        }
+        const secret = text.slice(open.index + open[0].length, close - 1).trim();
+        if (!secret) {
+            return {
+                ok: false,
+                message: `The {private: section on line ${String(lineAt(text, open.index))} is empty.`,
+            };
+        }
+        parts.push(text.slice(at, open.index), { private: secret });
+        at = close;
+    }
+    parts.push(text.slice(at));
+    if (parts.length === 1)
+        return { ok: true, prompt: text.trim() || undefined };
+    const first = parts[0];
+    const last = parts.at(-1);
+    if (typeof first === 'string')
+        parts[0] = first.trimStart();
+    if (typeof last === 'string')
+        parts[parts.length - 1] = last.trimEnd();
+    return { ok: true, prompt: parts.filter((part) => part !== '') };
+}
+export { parseSystemMarkup };

package/tool-schema.d.ts

@@ -0,0 +1,23 @@
+import { type JsonSchema } from '@theoremjs/react/client';
+import { type ZodType } from 'zod';
+export declare const DEFAULT_TOOL_INPUT_SCHEMA = "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"query\": { \"type\": \"string\" }\n  },\n  \"required\": [\"query\"]\n}";
+export declare const DEFAULT_TOOL_OUTPUT_SCHEMA = "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"result\": { \"type\": \"string\" }\n  },\n  \"required\": [\"result\"]\n}";
+export type { JsonSchema };
+/**
+ * A tool's zod schema, read from its JSON Schema exactly as a file Save writes reads it, so a
+ * studio run checks a tool's input and output by the same contract the saved code does.
+ */
+export declare function zodFromJsonSchema(schema: JsonSchema): ZodType;
+/** Required fields, and optional ones with an example; the package's form fills a tool's request the same way. */
+export declare function sampleFromJsonSchema(schema: JsonSchema): Record<string, unknown>;
+export declare function quoteSource(text: string): string;
+/** Bare when the key is an identifier. */
+export declare function keySource(key: string, quote?: (text: string) => string): string;
+/** `label` names the schema in the error. */
+export declare function parseJsonSchema(raw: string, label: string): {
+    ok: true;
+    schema: JsonSchema;
+} | {
+    ok: false;
+    error: string;
+};

package/tool-schema.js

@@ -0,0 +1,69 @@
+import { sampleFromSchema } from '@theoremjs/react/client';
+import { z } from 'zod';
+export const DEFAULT_TOOL_INPUT_SCHEMA = `{
+  "type": "object",
+  "properties": {
+    "query": { "type": "string" }
+  },
+  "required": ["query"]
+}`;
+export const DEFAULT_TOOL_OUTPUT_SCHEMA = `{
+  "type": "object",
+  "properties": {
+    "result": { "type": "string" }
+  },
+  "required": ["result"]
+}`;
+/**
+ * A tool's zod schema, read from its JSON Schema exactly as a file Save writes reads it, so a
+ * studio run checks a tool's input and output by the same contract the saved code does.
+ */
+export function zodFromJsonSchema(schema) {
+    return z.fromJSONSchema(schema);
+}
+/** Required fields, and optional ones with an example; the package's form fills a tool's request the same way. */
+export function sampleFromJsonSchema(schema) {
+    return sampleFromSchema(schema);
+}
+/** Characters escaped even inside a string literal, so pasted source can't close a `<script>` or break a line. */
+const UNSAFE_SOURCE_CHARS = {
+    '<': '\\u003C',
+    '>': '\\u003E',
+    '\u2028': '\\u2028',
+    '\u2029': '\\u2029',
+};
+export function quoteSource(text) {
+    const body = JSON.stringify(text)
+        .slice(1, -1)
+        .replaceAll('\\"', '"')
+        .replaceAll("'", "\\'")
+        .replace(/[<>\u2028\u2029]/g, (char) => UNSAFE_SOURCE_CHARS[char] ?? char);
+    return `'${body}'`;
+}
+/** Bare when the key is an identifier. */
+export function keySource(key, quote = quoteSource) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : quote(key);
+}
+/** `label` names the schema in the error. */
+export function parseJsonSchema(raw, label) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return { ok: false, error: `${label} JSON Schema is required.` };
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { ok: false, error: `${label} JSON Schema must be an object.` };
+        }
+        // Read here as the saved file reads it, so a schema zod can't read is this field's issue.
+        try {
+            zodFromJsonSchema(parsed);
+        }
+        catch (err) {
+            return { ok: false, error: `${label} JSON Schema can't be read: ${err.message}.` };
+        }
+        return { ok: true, schema: parsed };
+    }
+    catch {
+        return { ok: false, error: `${label} JSON Schema is not valid JSON.` };
+    }
+}

package/tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Function tools answer with the builder's sample reply, else the handler the host gives for their
+ * name, else a stub shaped by their output schema.
+ */
+import type { KernelRegistry, Profile } from '@theoremjs/agents';
+import type { ToolRegistry } from '@theoremjs/agents/kernel';
+import type { StructuredRegistration, ToolRegistration } from './registrations.ts';
+/** Answers a function tool's call, for a host that runs its own tools in the studio. */
+export type StudioToolHandler = (input: Record<string, unknown>) => Record<string, unknown>;
+/** The host's handlers, by tool name. */
+export type StudioToolHandlers = Readonly<Record<string, StudioToolHandler>>;
+/** Registers one studio tool, its schemas read as the file Save writes reads them. */
+export declare function registerCustomTool(tools: ToolRegistry, tool: ToolRegistration, handlers?: StudioToolHandlers): void;
+export declare function registerStudioTools(tools: ToolRegistry, customTools: readonly ToolRegistration[], handlers?: StudioToolHandlers): void;
+/** Registers a draft's tools and schema, then its profile, into `registry`. */
+export declare function registerDefined(registry: KernelRegistry, profile: Profile, customTools: readonly ToolRegistration[], structured: StructuredRegistration | undefined, handlers?: StudioToolHandlers): Profile;

package/tools.js

@@ -0,0 +1,91 @@
+/**
+ * Function tools answer with the builder's sample reply, else the handler the host gives for their
+ * name, else a stub shaped by their output schema.
+ */
+import { GOOGLE_BUILTIN_TOOLS } from '@theoremjs/agents/presets/google';
+import { stubOutputFromSchema } from "./stub.js";
+import { zodFromJsonSchema } from "./tool-schema.js";
+/** Registers one studio tool, its schemas read as the file Save writes reads them. */
+export function registerCustomTool(tools, tool, handlers = {}) {
+    const base = {
+        name: tool.name,
+        description: tool.description,
+        category: tool.category,
+        access: tool.access,
+        paths: tool.paths,
+        loadTier: tool.loadTier,
+        permission: tool.permission,
+        ...(tool.labels ? { labels: tool.labels } : {}),
+    };
+    if (tool.type === 'agent') {
+        tools.register({
+            ...base,
+            type: 'agent',
+            profile: tool.profile,
+            ...(tool.maxCallsPerTurn !== undefined ? { maxCallsPerTurn: tool.maxCallsPerTurn } : {}),
+        });
+        return;
+    }
+    const shared = {
+        ...base,
+        input: zodFromJsonSchema(tool.inputSchema),
+        output: zodFromJsonSchema(tool.outputSchema),
+    };
+    if (tool.type === 'http') {
+        tools.register({
+            ...shared,
+            type: 'http',
+            endpoint: tool.endpoint,
+            method: tool.method,
+            headers: tool.headers,
+            mapping: tool.mapping,
+            auth: tool.auth,
+        });
+        return;
+    }
+    if (tool.type === 'mcp') {
+        tools.register({
+            ...shared,
+            type: 'mcp',
+            serverUrl: tool.serverUrl,
+            mcpToolName: tool.mcpToolName,
+            headers: tool.headers,
+            auth: tool.auth,
+        });
+        return;
+    }
+    if (tool.answeredBy === 'page') {
+        tools.register({ ...shared, type: 'function', answeredBy: 'page' });
+        return;
+    }
+    const handler = tool.stubResponse || !Object.hasOwn(handlers, tool.name) ? undefined : handlers[tool.name];
+    const stub = tool.stubResponse ?? stubOutputFromSchema(tool.outputSchema);
+    tools.register({
+        ...shared,
+        type: 'function',
+        handler: handler
+            ? (input) => {
+                try {
+                    return Promise.resolve(handler(input));
+                }
+                catch (err) {
+                    return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            : () => Promise.resolve(stub),
+    });
+}
+export function registerStudioTools(tools, customTools, handlers) {
+    tools.registerMany(GOOGLE_BUILTIN_TOOLS);
+    for (const tool of customTools)
+        registerCustomTool(tools, tool, handlers);
+}
+/** Registers a draft's tools and schema, then its profile, into `registry`. */
+export function registerDefined(registry, profile, customTools, structured, handlers) {
+    registerStudioTools(registry.tools, customTools, handlers);
+    if (structured && profile.type !== 'live') {
+        registry.schemas.register(structured.id, structured.spec);
+    }
+    registry.profiles.register(profile);
+    return profile;
+}

package/traces.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The kernel copies request metadata into every record, so one router `sink` hands each record
+ * to the run that wrote it. Recording, sampling, and scrubbing stay the profile's observability
+ * policy: a record the policy does not write never reaches the router.
+ */
+import type { TraceRecord, TraceSink } from '@theoremjs/agents/observability';
+export declare const STUDIO_RUN_METADATA_KEY = "studioRun";
+/** A trace record on the studio's run stream (NDJSON line or Live socket message). */
+export type StudioTraceLine = {
+    type: 'trace';
+    record: TraceRecord;
+};
+/** One run's route: pass `metadata` on its request, `close` when the run ends. */
+export interface StudioTraceRoute {
+    metadata: Record<string, string>;
+    close(): void;
+}
+export interface StudioTraceRouter {
+    /** Register for `STUDIO_TRACE_DESTINATION`. */
+    sink: TraceSink;
+    /** Open a route; `onRecord` receives each record the run writes while it is open. */
+    route(onRecord: (record: TraceRecord) => void): StudioTraceRoute;
+}
+export declare function createStudioTraceRouter(): StudioTraceRouter;

package/traces.js

@@ -0,0 +1,29 @@
+/**
+ * The kernel copies request metadata into every record, so one router `sink` hands each record
+ * to the run that wrote it. Recording, sampling, and scrubbing stay the profile's observability
+ * policy: a record the policy does not write never reaches the router.
+ */
+export const STUDIO_RUN_METADATA_KEY = 'studioRun';
+export function createStudioTraceRouter() {
+    const routes = new Map();
+    return {
+        sink: {
+            write: (record) => {
+                const run = record.metadata?.[STUDIO_RUN_METADATA_KEY];
+                if (typeof run === 'string')
+                    routes.get(run)?.(record);
+                return Promise.resolve();
+            },
+        },
+        route(onRecord) {
+            const run = globalThis.crypto.randomUUID();
+            routes.set(run, onRecord);
+            return {
+                metadata: { [STUDIO_RUN_METADATA_KEY]: run },
+                close: () => {
+                    routes.delete(run);
+                },
+            };
+        },
+    };
+}

package/transport.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Every request carries the compiled payload and the client-held `replay` state (permissions,
+ * paused call). That is safe only because the studio user owns the whole profile and its
+ * tools; product hosts keep the profile on the server (`createHttpTransport` with
+ * `createTheoremHandler`).
+ */
+import { type TurnEvent } from '@theoremjs/agents';
+import { type ProfileInterface } from '@theoremjs/agents/interface';
+import { type ChatLineSink, type ConversationLine, type DecisionTransport, type EmbeddingTransport, type HostTransport, type HttpOptions, type MalformedEvent, type TheoremTransport, type TraceFeed, type TurnEventSink, type UnsupportedEvent } from '@theoremjs/react/client';
+import { z } from 'zod';
+import { type StudioRunPayload } from './run-payload.ts';
+import type { StudioTraceLine } from './traces.ts';
+export declare function studioInterface(payload: StudioRunPayload): ProfileInterface;
+/** False for a run kept by a package whose settings this one no longer takes. */
+export declare function studioRunDefines(payload: StudioRunPayload): boolean;
+/** Clears every kept run this package no longer defines. */
+export declare function clearStaleStudioRuns(store?: Storage | null): void;
+/** The server picks the id, so a steer reaches only a run this browser started. */
+export type StudioSteerLine = {
+    type: 'steer_inbox';
+    inbox: string;
+};
+type StudioLine = TurnEvent | ConversationLine | StudioTraceLine | StudioSteerLine;
+/** A trace record's line on a run's stream, as the page reads it. */
+export declare const studioTraceLine: z.ZodObject<{
+    type: z.ZodLiteral<"trace">;
+    record: z.ZodType<import("@theoremjs/agents").TraceRecord, unknown, z.core.$ZodTypeInternals<import("@theoremjs/agents").TraceRecord, unknown>>;
+}, z.core.$strip>;
+/** A chat's lines go to the sink; a host draft's call streams turn events alone. */
+export declare function routeStudioLines(onLine: ChatLineSink, traces: TraceFeed, onSteerInbox: (inbox: string) => void): (line: StudioLine | UnsupportedEvent | MalformedEvent) => void;
+/**
+ * A host draft's call as the chat router reads it. Its wire leaves conversation
+ * lines out, so one reaching the call is a fault in the studio, not a line to drop.
+ */
+export declare function hostCallLines(onEvent: TurnEventSink): ChatLineSink;
+/**
+ * How a studio transport reaches the server. `traces` is the feed its trace records land in:
+ * pass one feed to every transport of a conversation so a recompiled draft keeps the earlier
+ * turns' traces beside the transcript that kept them.
+ */
+export type StudioTransportOptions = HttpOptions & {
+    traces?: TraceFeed;
+};
+export declare function createStudioEmbeddingTransport(payload: StudioRunPayload, options?: StudioTransportOptions): EmbeddingTransport;
+export declare function createStudioTransport(payload: StudioRunPayload, options?: StudioTransportOptions): TheoremTransport;
+/**
+ * A decision draft's transport: the page describes the profile itself, and every decision posts
+ * the draft's profile and questions beside the state, since the studio user authors both.
+ */
+export declare function createStudioDecisionTransport(payload: StudioRunPayload, options?: StudioTransportOptions): DecisionTransport;
+/**
+ * A host draft's transport: the page describes the tools from the draft's own schemas, and every
+ * call posts the draft's profile and tools beside it. The server retains operation authority;
+ * permission answers remain explicit request data.
+ */
+export declare function createStudioHostTransport(payload: StudioRunPayload, options?: StudioTransportOptions): HostTransport;
+export {};

package/transport.js

@@ -0,0 +1,187 @@
+/**
+ * Every request carries the compiled payload and the client-held `replay` state (permissions,
+ * paused call). That is safe only because the studio user owns the whole profile and its
+ * tools; product hosts keep the profile on the server (`createHttpTransport` with
+ * `createTheoremHandler`).
+ */
+import { defineProfile, TheoremError, TURN_EVENT_SCHEMAS, traceRecordSchema, } from '@theoremjs/agents';
+import { interfaceFromProfile } from '@theoremjs/agents/interface';
+import { createToolRegistry } from '@theoremjs/agents/kernel';
+import { CHAT_LINES, createTraceFeed, decisionAssets, decisionInterface, embeddingInterface, fetchConversation, fetchRewound, hostInterface, postDecision, postEmbedding, postJson, postNdjson, } from '@theoremjs/react/client';
+import { z } from 'zod';
+import { uncompiled } from "./compile.js";
+import { clearStudioRunPayload, keptStudioRunIds, loadStudioRunPayload, } from "./run-payload.js";
+import { registerStudioTools } from "./tools.js";
+/**
+ * The agents the payload's agent names come first, so its agent tools find them. The patterns
+ * are left out, as `compileStudio` checks them: only the run's server compiles them.
+ */
+function defineStudioRun(payload) {
+    const profiles = new Map();
+    const tools = createToolRegistry((id) => profiles.get(id));
+    for (const dependency of payload.dependencies ?? []) {
+        registerStudioTools(tools, dependency.customTools);
+        const profile = defineProfile(uncompiled(dependency.profile));
+        profiles.set(profile.id, profile);
+    }
+    registerStudioTools(tools, payload.customTools);
+    return { profile: defineProfile(uncompiled(payload.profile)), tools };
+}
+export function studioInterface(payload) {
+    const { profile, tools } = defineStudioRun(payload);
+    return interfaceFromProfile(profile, tools);
+}
+/** False for a run kept by a package whose settings this one no longer takes. */
+export function studioRunDefines(payload) {
+    try {
+        defineStudioRun(payload);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof TheoremError)
+            return false;
+        throw err;
+    }
+}
+/** Clears every kept run this package no longer defines. */
+export function clearStaleStudioRuns(store) {
+    for (const id of keptStudioRunIds(store)) {
+        const payload = loadStudioRunPayload(id, store);
+        if (!payload || !studioRunDefines(payload))
+            clearStudioRunPayload(id, store);
+    }
+}
+/** A trace record's line on a run's stream, as the page reads it. */
+export const studioTraceLine = z.object({ type: z.literal('trace'), record: traceRecordSchema });
+true;
+const studioSteerLine = z.object({ type: z.literal('steer_inbox'), inbox: z.string().min(1) });
+true;
+const studioLines = {
+    ...CHAT_LINES,
+    trace: studioTraceLine,
+    steer_inbox: studioSteerLine,
+};
+/** A host draft's call keeps no conversation and takes no steers: its stream is turn events and traces. */
+const hostLines = {
+    ...TURN_EVENT_SCHEMAS,
+    trace: studioTraceLine,
+};
+/** A chat's lines go to the sink; a host draft's call streams turn events alone. */
+export function routeStudioLines(onLine, traces, onSteerInbox) {
+    return (line) => {
+        if (line.type === 'trace')
+            traces.push(line.record);
+        else if (line.type === 'steer_inbox')
+            onSteerInbox(line.inbox);
+        else
+            onLine(line);
+    };
+}
+function ignoreSteerInbox() { }
+/**
+ * A host draft's call as the chat router reads it. Its wire leaves conversation
+ * lines out, so one reaching the call is a fault in the studio, not a line to drop.
+ */
+export function hostCallLines(onEvent) {
+    return (line) => {
+        if (line.type === 'conversation') {
+            // labels-exempt: internal diagnostic; the user reads error.internal
+            throw new TheoremError('internal', 'a host call streamed a conversation line');
+        }
+        onEvent(line);
+    };
+}
+export function createStudioEmbeddingTransport(payload, options = {}) {
+    const traces = options.traces ?? createTraceFeed();
+    return {
+        describe: () => Promise.resolve(embeddingInterface(defineProfile(payload.profile))),
+        embed: (input, embed, signal) => postEmbedding('/api/studio/embedding/embed', { profile: payload.profile, input, ...embed }, signal, options),
+        traces,
+    };
+}
+export function createStudioTransport(payload, options = {}) {
+    const compiled = {
+        profile: payload.profile,
+        customTools: payload.customTools,
+        structured: payload.structured,
+        dependencies: payload.dependencies,
+    };
+    const traces = options.traces ?? createTraceFeed();
+    /** The server's steer inbox for each turn, by the client's turn id. */
+    const inboxes = new Map();
+    return {
+        pageResult: (body, signal) => postJson('/api/studio/page-result', body, { ...options, signal }),
+        describe: () => Promise.resolve(studioInterface(payload)),
+        turn: async (request, onEvent, signal) => {
+            try {
+                await postNdjson('/api/studio/turn', { ...compiled, ...request }, studioLines, routeStudioLines(onEvent, traces, (inbox) => {
+                    if (request.turnId)
+                        inboxes.set(request.turnId, inbox);
+                }), { ...options, signal });
+            }
+            finally {
+                if (request.turnId)
+                    inboxes.delete(request.turnId);
+            }
+        },
+        invoke: (request, onEvent, signal) => postNdjson('/api/studio/invoke', 
+        // `replay` carries the paused call.
+        { ...compiled, ...request }, studioLines, routeStudioLines(onEvent, traces, ignoreSteerInbox), { ...options, signal }),
+        conversation: (request, signal) => fetchConversation('/api/studio/conversation', { ...compiled, ...request }, { ...options, signal }),
+        rewind: (request, signal) => fetchRewound('/api/studio/rewind', { ...compiled, ...request }, { ...options, signal }),
+        async steer({ turnId, id, inject }) {
+            const inbox = inboxes.get(turnId);
+            if (!inbox) {
+                // labels-exempt: internal diagnostic; the user reads session.turn_ended
+                throw new TheoremError('request', 'steer: the turn has not opened its inbox', {
+                    copy: { key: 'session.turn_ended' },
+                });
+            }
+            // The server's inbox is the turn it steers, so the body is a `TheoremSteerRequest`.
+            await postJson('/api/studio/turn/steer', { turnId: inbox, id, inject }, options);
+        },
+        traces,
+    };
+}
+/**
+ * A decision draft's transport: the page describes the profile itself, and every decision posts
+ * the draft's profile and questions beside the state, since the studio user authors both.
+ */
+export function createStudioDecisionTransport(payload, options = {}) {
+    const questions = payload.questions ?? {};
+    const traces = options.traces ?? createTraceFeed();
+    return {
+        describe: () => Promise.resolve(decisionInterface(defineProfile(payload.profile), questions, payload.images)),
+        decide: (state, signal, page) => {
+            const assets = decisionAssets(payload.images, page);
+            return postDecision('/api/studio/decide', { profile: payload.profile, questions, state, ...(assets ? { assets } : {}) }, signal, options);
+        },
+        traces,
+    };
+}
+/**
+ * A host draft's transport: the page describes the tools from the draft's own schemas, and every
+ * call posts the draft's profile and tools beside it. The server retains operation authority;
+ * permission answers remain explicit request data.
+ */
+export function createStudioHostTransport(payload, options = {}) {
+    const compiled = {
+        profile: payload.profile,
+        customTools: payload.customTools,
+        dependencies: payload.dependencies,
+    };
+    const traces = options.traces ?? createTraceFeed();
+    let sessionPermissions = [];
+    return {
+        pageResult: (body, signal) => postJson('/api/studio/page-result', body, { ...options, signal }),
+        describe: () => Promise.resolve(hostInterface(defineProfile(payload.profile), (name) => payload.customTools.find((tool) => tool.name === name))),
+        call: (request, onEvent, signal) => postNdjson('/api/studio/call', { ...compiled, ...request, sessionPermissions }, hostLines, routeStudioLines(hostCallLines(onEvent), traces, ignoreSteerInbox), { ...options, signal }),
+        invoke: (request, onEvent, signal) => {
+            sessionPermissions = request.replay?.sessionPermissions ?? sessionPermissions;
+            return postNdjson('/api/studio/invoke', 
+            // `replay` carries the paused call.
+            { ...compiled, ...request }, hostLines, routeStudioLines(hostCallLines(onEvent), traces, ignoreSteerInbox), { ...options, signal });
+        },
+        traces,
+    };
+}

package/tree.d.ts

@@ -0,0 +1,32 @@
+/** Node ids are what compile issues point at, so a tree, a graph, or a form can place an issue. */
+import { type ProfileGraphFacetId } from '@theoremjs/agents/schema';
+import { type StudioDraft } from './draft.ts';
+export declare function modelBindingNodeId(key: string): string;
+export declare function toolSpecNodeId(key: string): string;
+/** The inverse of `toolSpecNodeId`; `undefined` for any other id. */
+export declare function toolSpecKeyOf(id: string): string | undefined;
+/** The node a provider's own settings open at. */
+export declare function providerNodeId(id: string): string;
+/** The inverse of `providerNodeId`; `undefined` for any other id. */
+export declare function providerIdOf(id: string): string | undefined;
+export type StudioNodeRef = {
+    facet: 'modelBinding';
+    key: string;
+} | {
+    facet: 'toolSpec';
+    key: string;
+} | {
+    facet: Exclude<ProfileGraphFacetId, 'modelBinding' | 'toolSpec'>;
+};
+export interface StudioTreeNode {
+    id: string;
+    ref: StudioNodeRef;
+    label: string;
+    children: StudioTreeNode[];
+}
+/** `undefined` when the id names nothing. */
+export declare function studioNodeRef(draft: StudioDraft, id: string): StudioNodeRef | undefined;
+/** One leaf per tool, as the Tools facet lists them. */
+export declare function toolSpecNodes(toolSpecs: StudioDraft['toolSpecs']): StudioTreeNode[];
+/** The root is labelled with the profile id; its children are the compiled facets in `PROFILE_GRAPH` order. */
+export declare function studioTree(draft: StudioDraft): StudioTreeNode;

package/tree.js

@@ -0,0 +1,83 @@
+/** Node ids are what compile issues point at, so a tree, a graph, or a form can place an issue. */
+import { PROFILE_GRAPH } from '@theoremjs/agents/schema';
+import { draftFacets } from "./draft.js";
+export function modelBindingNodeId(key) {
+    return `modelBinding:${key}`;
+}
+const TOOL_SPEC_PREFIX = 'toolSpec:';
+export function toolSpecNodeId(key) {
+    return `${TOOL_SPEC_PREFIX}${key}`;
+}
+/** The inverse of `toolSpecNodeId`; `undefined` for any other id. */
+export function toolSpecKeyOf(id) {
+    return id.startsWith(TOOL_SPEC_PREFIX) ? id.slice(TOOL_SPEC_PREFIX.length) : undefined;
+}
+const PROVIDER_PREFIX = 'provider:';
+/** The node a provider's own settings open at. */
+export function providerNodeId(id) {
+    return `${PROVIDER_PREFIX}${id}`;
+}
+/** The inverse of `providerNodeId`; `undefined` for any other id. */
+export function providerIdOf(id) {
+    return id.startsWith(PROVIDER_PREFIX) ? id.slice(PROVIDER_PREFIX.length) : undefined;
+}
+const FACET_LABEL = new Map(PROFILE_GRAPH.map((facet) => [facet.id, facet.label]));
+function facetLabel(id) {
+    return FACET_LABEL.get(id) ?? id;
+}
+/** `undefined` when the id names nothing. */
+export function studioNodeRef(draft, id) {
+    const [facet, key] = id.split(':', 2);
+    if (facet === 'modelBinding' && key !== undefined) {
+        return draft.modelBindings.some((binding) => binding.key === key) ? { facet, key } : undefined;
+    }
+    const tool = toolSpecKeyOf(id);
+    if (tool !== undefined) {
+        return draft.toolSpecs.some((spec) => spec.key === tool)
+            ? { facet: 'toolSpec', key: tool }
+            : undefined;
+    }
+    const facets = draftFacets(draft);
+    if (key !== undefined || !facets.includes(id))
+        return undefined;
+    return { facet: id };
+}
+function branchNodes(draft, facet) {
+    if (facet === 'models') {
+        return draft.modelBindings.map((binding) => ({
+            id: modelBindingNodeId(binding.key),
+            ref: { facet: 'modelBinding', key: binding.key },
+            label: binding.modelId.trim() || facetLabel('modelBinding'),
+            children: [],
+        }));
+    }
+    if (facet === 'tools')
+        return toolSpecNodes(draft.toolSpecs);
+    return [];
+}
+/** One leaf per tool, as the Tools facet lists them. */
+export function toolSpecNodes(toolSpecs) {
+    return toolSpecs.map((tool) => ({
+        id: toolSpecNodeId(tool.key),
+        ref: { facet: 'toolSpec', key: tool.key },
+        label: tool.toolName.trim() || facetLabel('toolSpec'),
+        children: [],
+    }));
+}
+/** The root is labelled with the profile id; its children are the compiled facets in `PROFILE_GRAPH` order. */
+export function studioTree(draft) {
+    const children = draftFacets(draft)
+        .filter((facet) => facet !== 'identity')
+        .map((facet) => ({
+        id: facet,
+        ref: { facet: facet },
+        label: facetLabel(facet),
+        children: branchNodes(draft, facet),
+    }));
+    return {
+        id: 'identity',
+        ref: { facet: 'identity' },
+        label: draft.identity.agentId.trim() || facetLabel('identity'),
+        children,
+    };
+}