@theoremjs/studio 0.0.0-stage → 0.3.2

package/runtime-scope.js

@@ -0,0 +1,308 @@
+/**
+ * Studio drafts, each run on a kernel scope of its own. Two visitors can
+ * name the same profile, tool, or schema without either one seeing the other's.
+ */
+import { createKernelScope, defineProfile, defineProtocol, defineProvider, TheoremError, } from '@theoremjs/agents';
+import { listsPatterns, TAINT_GATES, } from '@theoremjs/agents/guardrails';
+import { z } from 'zod';
+import { STUDIO_KEY_SLOT_CAP, studioKeySlots } from "./browser-connection.js";
+import { lentCompression, runtimeNetwork } from "./lent-keys.js";
+import { modelBindingViolation } from "./policy.js";
+import { localProviderAddress, registerStudioProvider, STUDIO_PROVIDERS } from "./providers.js";
+import { registerDefined } from "./tools.js";
+/** The protocol event a scripted model's event stands for. */
+function protocolEvent(event) {
+    if (event.type === 'tool')
+        return { type: 'tool_call', call: event.tool };
+    if (event.type === 'done') {
+        return {
+            type: 'done',
+            stop: event.stop,
+            ...(event.interrupted ? { interrupted: true } : {}),
+        };
+    }
+    return event;
+}
+/** A provider whose one protocol answers every call with `model`, sending nothing. */
+function scriptedProvider(id, protocolId, model) {
+    const protocol = defineProtocol({
+        id: protocolId,
+        name: 'Scripted',
+        description: 'Answers with the events a scripted model gives.',
+        endpoints: { text: '/', image: '/', speech: '/' },
+        options: z.record(z.string(), z.json()),
+        create: (context) => ({
+            async *complete(request) {
+                let done = false;
+                // why: a scripted model writes whatever built-ins the binding names.
+                for await (const event of model.complete({
+                    ...request,
+                    builtInTools: context.builtInTools,
+                })) {
+                    if (event.type === 'done')
+                        done = true;
+                    yield protocolEvent(event);
+                }
+                if (!done)
+                    yield { type: 'done', stop: { kind: 'completed' } };
+            },
+        }),
+    });
+    return defineProvider({
+        id,
+        name: 'Scripted',
+        description: 'Answers with a scripted model.',
+        serves: () => [{ protocol, baseUrl: 'https://scripted.invalid' }],
+    });
+}
+/**
+ * The host options a profile's turn runs with. A runtime with a scripted model registers it as a
+ * provider of its own and binds the profile's model to it.
+ */
+export function runtimeProvider(runtime, scope, profile, model) {
+    const scripted = runtime.provider?.(profile, model);
+    if (scripted && profile.type !== 'host') {
+        const selected = model ?? ('defaultModel' in profile ? profile.defaultModel : Object.keys(profile.models)[0]);
+        const binding = profile.models[selected];
+        const id = `scripted-${profile.id.toLowerCase().replace(/[^a-z0-9-]/g, '-')}`;
+        // why: a protocol id is letters and digits only; a provider id may hold hyphens.
+        const protocol = id.replaceAll('-', '');
+        scope.providers.replace(scriptedProvider(id, protocol, scripted));
+        scope.profiles.register({
+            ...profile,
+            models: {
+                ...profile.models,
+                [selected]: {
+                    ...binding,
+                    protocol,
+                    provider: id,
+                    options: {},
+                    keySlot: undefined,
+                    fallbackKeySlot: undefined,
+                },
+            },
+        });
+    }
+    const options = runtime.providers ?? {};
+    const host = runtime.hostOptions?.(profile, model) ?? {};
+    return {
+        ...host,
+        vault: host.vault ?? options.vault,
+        fetch: host.fetch ?? options.fetch ?? options.local?.fetch,
+        wait: host.wait ?? options.wait,
+    };
+}
+/** The studio's providers, the local one at the runtime's address, then the project's own. */
+function registerRuntimeProviders(scope, runtime) {
+    const local = runtime?.providers?.local?.baseUrl;
+    for (const provider of STUDIO_PROVIDERS) {
+        registerStudioProvider(scope.providers, provider.definition === 'local' && local
+            ? { ...provider, connection: { baseUrl: localProviderAddress(local) } }
+            : provider);
+    }
+    for (const definition of runtime?.providerDefinitions ?? [])
+        scope.providers.register(definition);
+}
+/**
+ * Each called agent runs on a provider of its own, so it reads its own key
+ * slots and may use another provider than its caller. The runtime may refuse
+ * the call first.
+ */
+export function agentCallHook(scope, runtime) {
+    return async (call) => {
+        const refused = await runtime.onAgentCall?.(call);
+        if (refused)
+            return refused;
+        return { provider: runtimeProvider(runtime, scope, scope.profiles.get(call.profile)) };
+    };
+}
+/** The stricter of two gates. */
+function stricterGate(a, b) {
+    return TAINT_GATES.indexOf(a ?? 'off') > TAINT_GATES.indexOf(b) ? a : b;
+}
+/** `guardrails` held to what lent keys refuse after a remote read. */
+function withHeldTaint(guardrails, runtime) {
+    if (runtime.mode !== 'demo' || runtime.keys.holds.afterRemoteRead === 'off')
+        return guardrails;
+    const afterRemoteRead = stricterGate(guardrails.taint?.afterRemoteRead, runtime.keys.holds.afterRemoteRead);
+    if (afterRemoteRead === guardrails.taint?.afterRemoteRead)
+        return guardrails;
+    return { ...guardrails, taint: { ...guardrails.taint, afterRemoteRead } };
+}
+function runtimeGuardrails(guardrails, runtime) {
+    switch (runtimeNetwork(runtime)) {
+        case 'public':
+            return { ...guardrails, network: undefined };
+        case 'none':
+            return { ...guardrails, network: { allowedSchemes: [] } };
+        case 'asWritten':
+            return guardrails;
+    }
+}
+function runtimeProfileDefinition(def, runtime) {
+    // A speech, decision, or embedding profile calls no tools: no network or taint hold governs it.
+    if (def.type === 'speech' || def.type === 'decision' || def.type === 'embedding')
+        return def;
+    // A host runs one tool per call, so a turn never reads before it acts; the kernel refuses taint there.
+    if (def.type === 'host') {
+        return {
+            ...def,
+            guardrails: runtimeGuardrails(def.guardrails ?? {}, runtime),
+        };
+    }
+    return {
+        ...withLentCompression(def, runtime),
+        guardrails: withHeldTaint(runtimeGuardrails(def.guardrails ?? {}, runtime), runtime),
+    };
+}
+/** A Live profile on lent keys runs with the compression sizes the editor shows for them. */
+function withLentCompression(def, runtime) {
+    if (def.type !== 'live' || runtime.mode !== 'demo')
+        return def;
+    const compression = def.live?.contextCompression;
+    if (!compression)
+        return def;
+    const sizes = lentCompression(runtime.keys, {
+        triggerTokens: compression.triggerTokens,
+        targetTokens: compression.slidingWindow.targetTokens,
+    });
+    return {
+        ...def,
+        live: {
+            ...def.live,
+            contextCompression: {
+                ...compression,
+                triggerTokens: sizes.triggerTokens,
+                slidingWindow: { ...compression.slidingWindow, targetTokens: sizes.targetTokens },
+            },
+        },
+    };
+}
+/**
+ * `def` with the table compiled for each detector's patterns, here where the draft runs: a table
+ * a browser sent is never trusted, since compiling is what refuses a pattern that could hang on
+ * hostile text. The compiler loads only for a draft that has patterns.
+ */
+export async function withCompiledPatterns(def) {
+    if (!hasPatterns(def))
+        return def;
+    const { compileDetect } = await import('@theoremjs/agents/guardrails/compile');
+    return withPatterns(def, compileDetect);
+}
+/** Whether `def` has a detector that lists patterns to compile. */
+function hasPatterns(def) {
+    const detect = def.guardrails && 'detect' in def.guardrails ? def.guardrails.detect : undefined;
+    return typeof detect === 'object' && listsPatterns(detect);
+}
+/** `def` with its patterns compiled by `compile`, for a caller that already holds the compiler. */
+export function withPatterns(def, compile) {
+    if (!hasPatterns(def))
+        return def;
+    const guardrails = def.guardrails;
+    return { ...def, guardrails: { ...guardrails, detect: compile(guardrails.detect) } };
+}
+/**
+ * Refuses a tool schema a browser sent whose `pattern` could hang on text a model writes: zod
+ * runs it on every call, here on the run's server. It is the check the kernel makes of a
+ * detector's patterns, and loads only for a draft whose schemas have patterns.
+ */
+async function refuseSlowSchemaPatterns(tools) {
+    const found = tools.flatMap((tool) => ['input', 'output'].flatMap((side) => schemaPatterns(tool[`${side}Schema`]).map((source) => ({ tool: tool.name, side, source }))));
+    if (!found.length)
+        return;
+    const { slowPatternProblem } = await import('@theoremjs/agents/guardrails/compile');
+    for (const { tool, side, source } of found) {
+        const slow = slowPatternProblem(source);
+        if (slow) {
+            // labels-exempt: builder diagnostic
+            throw new TheoremError('request', `${tool}: the pattern /${source}/ in its ${side} schema ${slow}`);
+        }
+    }
+}
+/** Every regular expression a JSON Schema holds: each `pattern`, and each `patternProperties` key. */
+function schemaPatterns(value) {
+    if (Array.isArray(value))
+        return value.flatMap(schemaPatterns);
+    if (!value || typeof value !== 'object')
+        return [];
+    return Object.entries(value).flatMap(([key, inner]) => [
+        ...(key === 'pattern' && typeof inner === 'string' ? [inner] : []),
+        ...(key === 'patternProperties' && inner && typeof inner === 'object'
+            ? Object.keys(inner)
+            : []),
+        ...schemaPatterns(inner),
+    ]);
+}
+/**
+ * `work` on a draft a request carries: the sender wrote the draft, so a draft the kernel refuses is
+ * a bad request (`request`), not the host's configuration (`config`).
+ */
+function asDraft(work) {
+    try {
+        return work();
+    }
+    catch (err) {
+        if (err instanceof TheoremError && err.kind === 'config') {
+            throw new TheoremError('request', err.message, { cause: err });
+        }
+        throw err;
+    }
+}
+/** `defineProfile` for a draft a request carries. */
+export const defineDraft = ((definition) => asDraft(() => defineProfile(definition)));
+/** Registers the draft's tools, schema, and profile into `scope`, as the runtime runs it. */
+async function registerDraft(scope, profile, customTools, structured, runtime) {
+    if (studioKeySlots(profile).length > STUDIO_KEY_SLOT_CAP) {
+        throw new TheoremError('request', 'The studio supports up to 32 key slots.'); // labels-exempt: builder diagnostic
+    }
+    await refuseSlowSchemaPatterns(customTools);
+    const defined = defineDraft(runtimeProfileDefinition(await withCompiledPatterns(profile), runtime));
+    if (defined.type !== 'host') {
+        for (const binding of Object.values(defined.models)) {
+            const violation = modelBindingViolation({
+                profileType: defined.type,
+                protocol: binding.protocol,
+                provider: binding.provider,
+                definition: scope.providers.require(binding.provider, binding.apiId).definition.id,
+                apiId: binding.apiId,
+                decision: defined.type === 'decision',
+                builtInTools: 'builtInTools' in binding ? (binding.builtInTools ?? []) : [],
+            }, runtime);
+            if (violation)
+                throw new TheoremError('request', violation.message); // labels-exempt: builder connection diagnostic
+        }
+    }
+    // why: Registering checks each binding's options and the tools and schemas it names, all the sender's.
+    return asDraft(() => registerDefined(scope, defined, customTools, structured, runtime.toolHandlers));
+}
+/**
+ * A new scope holding one request's draft, and the profile to run on it. Never cache or share it:
+ * the scope also holds MCP sessions, and a shared one would hand a keyless server's session to
+ * every visitor and keep it past the request. `dependencies` are registered first, in order.
+ */
+export async function studioScope(profile, customTools, structured, runtime, dependencies = []) {
+    const scope = createKernelScope();
+    registerRuntimeProviders(scope, runtime);
+    for (const dependency of dependencies) {
+        await registerDraft(scope, dependency.profile, dependency.customTools, dependency.structured, runtime);
+    }
+    return {
+        scope,
+        profile: await registerDraft(scope, profile, customTools, structured, runtime),
+    };
+}
+/**
+ * A new scope holding drafts as written, the last one returned: no runtime
+ * rewrites their guardrails or checks their model bindings. For a run that
+ * calls no model and reaches no host. Never cache or share it.
+ */
+export async function writtenScope(drafts) {
+    const scope = createKernelScope();
+    registerRuntimeProviders(scope);
+    let profile;
+    for (const draft of drafts) {
+        await refuseSlowSchemaPatterns(draft.customTools);
+        profile = registerDefined(scope, defineDraft(await withCompiledPatterns(draft.profile)), draft.customTools, draft.structured);
+    }
+    return { scope, profile };
+}

package/runtime.d.ts

@@ -0,0 +1,84 @@
+import { type DecisionAsset, type ProfileDefinition, type TraceRecord, type TurnEvent } from '@theoremjs/agents';
+import { type TranscriptBlock } from '@theoremjs/agents/interface';
+import { type EmbeddingRequest, type EmbeddingResult, type RunDecisionOptions } from '@theoremjs/agents/kernel';
+import { type ConversationView, type DecisionTransport, type TheoremConversationRequest, type TheoremHostCallRequest, type TheoremInvokeRequest, type TheoremRewindRequest, type TheoremRewound, type TheoremTurnRequest } from '@theoremjs/react/client';
+import { type ReplyLine, type SteerInbox, type TheoremConversationStore } from '@theoremjs/react/server';
+import type { StructuredRegistration, ToolRegistration } from './registrations.ts';
+import type { StudioRunPayload } from './run-payload.ts';
+import { type StudioDependency, type StudioRuntime } from './runtime-scope.ts';
+import { type StudioTraceLine } from './traces.ts';
+import type { StudioSteerLine } from './transport.ts';
+export declare const studioTraces: import("./traces.ts").StudioTraceRouter;
+/** A compiled draft as a run takes it. */
+export type StudioDraftRun = {
+    profile: ProfileDefinition;
+    customTools: ToolRegistration[];
+    structured?: StructuredRegistration;
+    runtime: StudioRuntime;
+    /** The agents this one names, registered before it. */
+    dependencies?: StudioDependency[];
+};
+export { newConversationKey } from './conversation-key.ts';
+/** Where a chat's conversation is kept: the store, and the session its refs open in. */
+export type StudioConversations = {
+    sessionId: string;
+    store: TheoremConversationStore;
+};
+/**
+ * One message, run against the conversation the host keeps: the paused calls it
+ * walks away from settle first, then the reply runs.
+ */
+export declare function streamStudioTurn(args: StudioDraftRun & {
+    request: TheoremTurnRequest;
+    conversations: StudioConversations;
+    signal: AbortSignal;
+    /** Where the turn's mid-turn steers queue. */
+    steer: SteerInbox;
+}): AsyncGenerator<ReplyLine | StudioTraceLine | StudioSteerLine>;
+/**
+ * The user's answer to a paused call. In a kept conversation the reply goes on
+ * in the same stream once no call waits; otherwise the stream is the call's.
+ */
+export declare function streamStudioInvoke(args: StudioDraftRun & {
+    answer: TheoremInvokeRequest;
+    conversations: StudioConversations;
+    signal: AbortSignal;
+}): AsyncGenerator<ReplyLine | StudioTraceLine>;
+/** A conversation that opens on blocks the page wrote, read first by the draft's guardrails: its ref and view. */
+export declare function startStudioConversation(draft: StudioDraftRun, conversations: StudioConversations, blocks: readonly TranscriptBlock[]): Promise<{
+    conversation: string;
+    view: ConversationView;
+}>;
+/** The conversation under a ref, as the page draws it. */
+export declare function studioConversation(draft: StudioDraftRun, conversations: StudioConversations, request: TheoremConversationRequest): Promise<ConversationView>;
+/** The conversation cut after one block; a reply that waits on gates is walked away from first. */
+export declare function rewindStudio(draft: StudioDraftRun, conversations: StudioConversations, request: TheoremRewindRequest, signal: AbortSignal): Promise<TheoremRewound>;
+/** The user's answer to a host draft's paused call: the studio keeps no session, so the browser replays it. */
+export declare function streamStudioHostInvoke(args: StudioDraftRun & {
+    answer: TheoremInvokeRequest;
+    signal: AbortSignal;
+}): AsyncGenerator<TurnEvent | StudioTraceLine>;
+/** One call of a host draft's tool, streamed. */
+export declare function streamStudioCall(args: {
+    profile: ProfileDefinition;
+    customTools: ToolRegistration[];
+    call: TheoremHostCallRequest;
+    /** Tools the user allowed for the page; the studio keeps no session. */
+    sessionPermissions?: string[];
+    signal?: AbortSignal;
+    runtime: StudioRuntime;
+    dependencies?: StudioDependency[];
+}): AsyncGenerator<TurnEvent | StudioTraceLine>;
+export { type StudioDependency, type StudioRuntime, studioScope } from './runtime-scope.ts';
+/** Both hosts run decisions through the kernel; the browser supplies its provider vault. */
+export declare function runStudioDecision(payload: StudioRunPayload, state: Parameters<DecisionTransport['decide']>[0], options: RunDecisionOptions, signal?: AbortSignal, assets?: Record<string, DecisionAsset>): Promise<{
+    result: import("@theoremjs/agents").DecisionResult;
+    traces: TraceRecord[];
+}>;
+/** Runs one embedding preview and returns its normalized result with the records it wrote. */
+export declare function runStudioEmbedding(payload: StudioRunPayload, request: Omit<EmbeddingRequest, 'profile'>, runtime: StudioRuntime): Promise<{
+    result: EmbeddingResult;
+    traces: TraceRecord[];
+}>;
+export { failedDecisionTraces, withFailedTraces } from '@theoremjs/react/client';
+export { studioKeySlots } from './browser-connection.ts';