@theoremjs/studio 0.0.0-stage → 0.3.2

package/read-steps.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What the studio command says while it reads a project, a line at a time, before it answers with
+ * the project. Each file is named from the project's folder.
+ */
+export type ReadStep = 
+/** A file was read. `from` is the file whose import led to it; the setup file has none. */
+{
+    file: string;
+    from?: string;
+}
+/** A profile or a tool was found in a file already read. `type` is the type the file writes for it. */
+ | {
+    found: 'profile' | 'tool';
+    name: string;
+    file: string;
+    type?: string;
+}
+/** The files changed since the last load, so the project is loading again. */
+ | {
+    again: true;
+};
+/** The address that asks for the steps before the project. */
+export declare const READ_STEPS = "steps";

package/read-steps.js

@@ -0,0 +1,2 @@
+/** The address that asks for the steps before the project. */
+export const READ_STEPS = 'steps';

package/reader.d.ts

@@ -0,0 +1,11 @@
+import type { ClientTurnOptions } from '@theoremjs/agents/host';
+import type { StudioRunsOn } from './lent-keys.ts';
+/**
+ * Who reads what the studio runs: the builder, on their own machine and keys. A failure says what
+ * actually happened (no key in a slot, a rejected key, an unreachable server) instead of the
+ * visitor wording. Every handler the studio serves and every run it makes in the page words its
+ * replies with this; a run on lent keys is a visitor's, and words its own with `studioReader`.
+ */
+export declare const STUDIO_READER: ClientTurnOptions;
+/** Who reads a run: a visitor on lent keys, else the builder (`STUDIO_READER`). */
+export declare function studioReader(on: StudioRunsOn): ClientTurnOptions;

package/reader.js

@@ -0,0 +1,11 @@
+/**
+ * Who reads what the studio runs: the builder, on their own machine and keys. A failure says what
+ * actually happened (no key in a slot, a rejected key, an unreachable server) instead of the
+ * visitor wording. Every handler the studio serves and every run it makes in the page words its
+ * replies with this; a run on lent keys is a visitor's, and words its own with `studioReader`.
+ */
+export const STUDIO_READER = { reader: 'builder' };
+/** Who reads a run: a visitor on lent keys, else the builder (`STUDIO_READER`). */
+export function studioReader(on) {
+    return on.mode === 'demo' ? { reader: 'visitor' } : STUDIO_READER;
+}

package/registrations.d.ts

@@ -0,0 +1,83 @@
+import type { StructuredSpec, ToolAuthConfig, ToolLabels } from '@theoremjs/agents/kernel';
+import type { HttpMethod, ToolAccess, ToolLoadTier, ToolPermission } from '@theoremjs/agents/schema';
+/** The kernel's auth config; the host's OAuth endpoints are never set from the studio. */
+export type StudioToolAuth = Omit<ToolAuthConfig, 'preResolved'>;
+export type StudioToolLabels = Pick<ToolLabels, 'activity' | 'activityPast' | 'activityFailed' | 'request'>;
+export type StructuredRegistration = {
+    id: string;
+    spec: StructuredSpec;
+};
+export type FunctionToolRegistration = {
+    type: 'function';
+    name: string;
+    description: string;
+    category: string;
+    access: ToolAccess;
+    permission: ToolPermission;
+    loadTier: ToolLoadTier;
+    paths: string[];
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    labels?: StudioToolLabels;
+    /** Overrides the generic stub. */
+    stubResponse?: Record<string, unknown>;
+    /** The page answers the call: the kernel supplies the handler, and the page sends the output. */
+    answeredBy?: 'page';
+};
+export type HttpToolRegistration = {
+    type: 'http';
+    name: string;
+    description: string;
+    category: string;
+    access: ToolAccess;
+    permission: ToolPermission;
+    loadTier: ToolLoadTier;
+    paths: string[];
+    endpoint: string;
+    method: HttpMethod;
+    headers?: Record<string, string>;
+    mapping?: {
+        pathParams?: string[];
+        queryParams?: string[];
+        bodyParam?: string;
+    };
+    auth?: StudioToolAuth;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    labels?: StudioToolLabels;
+};
+export type McpToolRegistration = {
+    type: 'mcp';
+    name: string;
+    description: string;
+    category: string;
+    access: ToolAccess;
+    permission: ToolPermission;
+    loadTier: ToolLoadTier;
+    paths: string[];
+    serverUrl: string;
+    mcpToolName: string;
+    headers?: Record<string, string>;
+    auth?: StudioToolAuth;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    labels?: StudioToolLabels;
+};
+/** Runs one turn of another registered agent; its schemas are the kernel's fixed ones. */
+export type AgentToolRegistration = {
+    type: 'agent';
+    name: string;
+    description: string;
+    category: string;
+    access: ToolAccess;
+    permission: ToolPermission;
+    loadTier: ToolLoadTier;
+    paths: string[];
+    /** The agent's profile id, registered before this tool. */
+    profile: string;
+    maxCallsPerTurn?: number;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    labels?: StudioToolLabels;
+};
+export type ToolRegistration = FunctionToolRegistration | HttpToolRegistration | McpToolRegistration | AgentToolRegistration;

package/registrations.js

@@ -0,0 +1 @@
+export {};

package/requirements.d.ts

@@ -0,0 +1,22 @@
+/** Shared by the compiler and the editor so both agree; mirrors the kernel's `PROFILE_FIELD_PRESENCE`. */
+import type { InputsDraft, ModelBindingDraft, StudioDraft } from './draft.ts';
+export declare function defaultModelRequired(draft: StudioDraft): boolean;
+/**
+ * Whether a model other than a local one reads no vault slot: not its own, its provider's, or the
+ * profile's. The kernel runs it without a key, so a provider that needs one refuses the run.
+ */
+export declare function keySlotUnset(draft: StudioDraft): boolean;
+/**
+ * The key slots a model of `draft` reads: its own, the profile's, or its provider's. Each says
+ * whether it is the provider's, which the profile does not write.
+ */
+export declare function bindingSlots(draft: StudioDraft, binding: ModelBindingDraft): {
+    keySlot?: string;
+    fallbackKeySlot?: string;
+    given: {
+        keySlot: boolean;
+        fallbackKeySlot: boolean;
+    };
+};
+export declare function defaultEffortRequired(binding: ModelBindingDraft): boolean;
+export declare function inputLimitsRequired(inputs: InputsDraft): boolean;

package/requirements.js

@@ -0,0 +1,38 @@
+/** Shared by the compiler and the editor so both agree; mirrors the kernel's `PROFILE_FIELD_PRESENCE`. */
+import { modelSlots } from "./providers.js";
+export function defaultModelRequired(draft) {
+    return draft.modelBindings.length > 1;
+}
+/**
+ * Whether a model other than a local one reads no vault slot: not its own, its provider's, or the
+ * profile's. The kernel runs it without a key, so a provider that needs one refuses the run.
+ */
+export function keySlotUnset(draft) {
+    return draft.modelBindings.some((binding) => binding.provider !== 'local' && !modelSlots(draft.providers, binding).keySlot);
+}
+/**
+ * The key slots a model of `draft` reads: its own, the profile's, or its provider's. Each says
+ * whether it is the provider's, which the profile does not write.
+ */
+export function bindingSlots(draft, binding) {
+    const written = {
+        provider: binding.provider,
+        keySlot: binding.keySlot || draft.models.key,
+        fallbackKeySlot: binding.fallbackKeySlot || draft.models.fallbackKey,
+    };
+    const read = modelSlots(draft.providers, written);
+    return {
+        ...read,
+        given: {
+            keySlot: Boolean(read.keySlot) && !written.keySlot,
+            fallbackKeySlot: Boolean(read.fallbackKeySlot) && !written.fallbackKeySlot,
+        },
+    };
+}
+export function defaultEffortRequired(binding) {
+    const aliases = binding.efforts.map(({ alias }) => alias.trim()).filter(Boolean);
+    return new Set(aliases).size > 1;
+}
+export function inputLimitsRequired(inputs) {
+    return inputs.attachmentsAccept.length > 0 || inputs.voiceAccept.length > 0;
+}

package/run-payload-core.d.ts

@@ -0,0 +1,28 @@
+/** No package imports; typed wrappers live in `run-payload.ts`. */
+export declare const STUDIO_RUN_PAYLOAD_KEY = "theoremjs.studio.run";
+export declare const STUDIO_RUN_PAYLOAD_KEY_PREFIX = "theoremjs.studio.run.";
+/** Ordered index of saved run ids (newest first). */
+export declare const STUDIO_RUN_INDEX_KEY = "theoremjs.studio.run.index";
+export declare const STUDIO_RUN_PAYLOAD_CAP = 8;
+export type StudioRunIndexEntry = {
+    id: string;
+    savedAt: number;
+};
+export type StudioRunIndex = {
+    entries: StudioRunIndexEntry[];
+};
+export declare function studioRunPayloadKey(runId: string): string;
+export declare function createStudioRunId(): string;
+export declare function readStudioRunIdFromUrl(url?: string | {
+    href: string;
+}): string | null;
+export declare function upsertStudioRunIndex(entries: readonly StudioRunIndexEntry[], runId: string, savedAt: number, cap?: number): {
+    entries: StudioRunIndexEntry[];
+    prunedIds: string[];
+};
+/** Prunes the oldest payloads beyond the cap. */
+export declare function saveStudioRunPayloadRecord(payload: Record<string, unknown>, runId: string, storeOverride?: Storage | null): void;
+export declare function loadStudioRunPayloadRecord(runId: string, storeOverride?: Storage | null): Record<string, unknown> | null;
+/** Every kept run's id, indexed or not. */
+export declare function keptStudioRunIds(storeOverride?: Storage | null): string[];
+export declare function clearStudioRunPayloadRecord(runId: string, storeOverride?: Storage | null): void;

package/run-payload-core.js

@@ -0,0 +1,123 @@
+/** No package imports; typed wrappers live in `run-payload.ts`. */
+export const STUDIO_RUN_PAYLOAD_KEY = 'theoremjs.studio.run';
+export const STUDIO_RUN_PAYLOAD_KEY_PREFIX = `${STUDIO_RUN_PAYLOAD_KEY}.`;
+/** Ordered index of saved run ids (newest first). */
+export const STUDIO_RUN_INDEX_KEY = `${STUDIO_RUN_PAYLOAD_KEY}.index`;
+export const STUDIO_RUN_PAYLOAD_CAP = 8;
+export function studioRunPayloadKey(runId) {
+    return `${STUDIO_RUN_PAYLOAD_KEY_PREFIX}${runId}`;
+}
+export function createStudioRunId() {
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+        return crypto.randomUUID();
+    }
+    return `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function readStudioRunIdFromUrl(url = typeof window !== 'undefined'
+    ? globalThis.location
+    : { href: '' }) {
+    const href = typeof url === 'string' ? url : url.href;
+    if (!href)
+        return null;
+    try {
+        const parsed = new URL(href, 'http://localhost');
+        const run = parsed.searchParams.get('run')?.trim();
+        return run && run.length > 0 ? run : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function upsertStudioRunIndex(entries, runId, savedAt, cap = STUDIO_RUN_PAYLOAD_CAP) {
+    const without = entries.filter((entry) => entry.id !== runId);
+    const next = [{ id: runId, savedAt }, ...without];
+    if (next.length <= cap) {
+        return { entries: next, prunedIds: [] };
+    }
+    const kept = next.slice(0, cap);
+    const prunedIds = next.slice(cap).map((entry) => entry.id);
+    return { entries: kept, prunedIds };
+}
+function resolveStore(store) {
+    if (store !== undefined)
+        return store;
+    if (typeof globalThis === 'undefined' || !('localStorage' in globalThis))
+        return null;
+    try {
+        // Private-mode / blocked storage can throw on access.
+        return globalThis.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+function readIndex(store) {
+    const raw = store.getItem(STUDIO_RUN_INDEX_KEY);
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.entries) ? parsed.entries : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeIndex(store, entries) {
+    store.setItem(STUDIO_RUN_INDEX_KEY, JSON.stringify({ entries }));
+}
+/** Prunes the oldest payloads beyond the cap. */
+export function saveStudioRunPayloadRecord(payload, runId, storeOverride) {
+    const store = resolveStore(storeOverride);
+    if (!store || !runId)
+        return;
+    store.removeItem(STUDIO_RUN_PAYLOAD_KEY);
+    const body = {
+        version: 1,
+        ...payload,
+        runId,
+    };
+    store.setItem(studioRunPayloadKey(runId), JSON.stringify(body));
+    const { entries, prunedIds } = upsertStudioRunIndex(readIndex(store), runId, Date.now(), STUDIO_RUN_PAYLOAD_CAP);
+    for (const id of prunedIds) {
+        store.removeItem(studioRunPayloadKey(id));
+    }
+    writeIndex(store, entries);
+}
+export function loadStudioRunPayloadRecord(runId, storeOverride) {
+    const store = resolveStore(storeOverride);
+    if (!store || !runId)
+        return null;
+    const raw = store.getItem(studioRunPayloadKey(runId));
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every kept run's id, indexed or not. */
+export function keptStudioRunIds(storeOverride) {
+    const store = resolveStore(storeOverride);
+    if (!store)
+        return [];
+    const ids = [];
+    for (let i = 0; i < store.length; i++) {
+        const key = store.key(i);
+        if (key?.startsWith(STUDIO_RUN_PAYLOAD_KEY_PREFIX) && key !== STUDIO_RUN_INDEX_KEY)
+            ids.push(key.slice(STUDIO_RUN_PAYLOAD_KEY_PREFIX.length));
+    }
+    return ids;
+}
+export function clearStudioRunPayloadRecord(runId, storeOverride) {
+    const store = resolveStore(storeOverride);
+    if (!store || !runId)
+        return;
+    store.removeItem(studioRunPayloadKey(runId));
+    writeIndex(store, readIndex(store).filter((entry) => entry.id !== runId));
+}

package/run-payload.d.ts

@@ -0,0 +1,32 @@
+import type { DecisionAsset, DecisionQuestion, ProfileDefinition } from '@theoremjs/agents';
+import type { StudioConnectionMode } from './policy.ts';
+import type { StudioProvider } from './providers.ts';
+import type { StructuredRegistration, ToolRegistration } from './registrations.ts';
+import { createStudioRunId, keptStudioRunIds, readStudioRunIdFromUrl, STUDIO_RUN_INDEX_KEY, STUDIO_RUN_PAYLOAD_CAP, STUDIO_RUN_PAYLOAD_KEY, STUDIO_RUN_PAYLOAD_KEY_PREFIX, type StudioRunIndex, type StudioRunIndexEntry, studioRunPayloadKey, upsertStudioRunIndex } from './run-payload-core.ts';
+import type { StudioDependency } from './runtime-scope.ts';
+export { createStudioRunId, keptStudioRunIds, readStudioRunIdFromUrl, STUDIO_RUN_INDEX_KEY, STUDIO_RUN_PAYLOAD_CAP, STUDIO_RUN_PAYLOAD_KEY, STUDIO_RUN_PAYLOAD_KEY_PREFIX, type StudioRunIndex, type StudioRunIndexEntry, studioRunPayloadKey, upsertStudioRunIndex, };
+export type StudioRunPayload = {
+    /** Payload schema version — bump when handoff shape changes. */
+    version?: 1;
+    /** Execution choice only. Credentials never belong in this persisted payload. */
+    connectionMode?: StudioConnectionMode;
+    /** Non-secret localhost connection setting; no bearer key travels with it. */
+    localBaseUrl?: string;
+    runId?: string;
+    agentId: string;
+    profile: ProfileDefinition;
+    customTools: ToolRegistration[];
+    structured?: StructuredRegistration;
+    /** A decision profile's questions, by id. */
+    questions?: Record<string, DecisionQuestion>;
+    /** The pictures every decision sends, by the reference its questions write. */
+    images?: Record<string, DecisionAsset>;
+    /** The providers its models name, each with its adapter. Left out, they are the studio's own. */
+    providers?: readonly StudioProvider[];
+    /** The agents this one names, each after the agents it names; registered before it. */
+    dependencies?: StudioDependency[];
+};
+/** `localStorage`, not `sessionStorage`: session storage is per-tab, so a `window.open` handoff would lose it. */
+export declare function saveStudioRunPayload(payload: StudioRunPayload, runId: string, storeOverride?: Storage | null): void;
+export declare function loadStudioRunPayload(runId: string, storeOverride?: Storage | null): StudioRunPayload | null;
+export declare function clearStudioRunPayload(runId: string, storeOverride?: Storage | null): void;

package/run-payload.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { clearStudioRunPayloadRecord, createStudioRunId, keptStudioRunIds, loadStudioRunPayloadRecord, readStudioRunIdFromUrl, STUDIO_RUN_INDEX_KEY, STUDIO_RUN_PAYLOAD_CAP, STUDIO_RUN_PAYLOAD_KEY, STUDIO_RUN_PAYLOAD_KEY_PREFIX, saveStudioRunPayloadRecord, studioRunPayloadKey, upsertStudioRunIndex, } from "./run-payload-core.js";
+export { createStudioRunId, keptStudioRunIds, readStudioRunIdFromUrl, STUDIO_RUN_INDEX_KEY, STUDIO_RUN_PAYLOAD_CAP, STUDIO_RUN_PAYLOAD_KEY, STUDIO_RUN_PAYLOAD_KEY_PREFIX, studioRunPayloadKey, upsertStudioRunIndex, };
+const kept = z.looseObject({
+    profile: z.looseObject({ id: z.string() }),
+    customTools: z.array(z.looseObject({ name: z.string() })),
+});
+/** The outline of a run kept in this browser, which an older or other package may have written. */
+const keptRun = kept.extend({
+    agentId: z.string(),
+    dependencies: z.array(kept).optional(),
+});
+/** `localStorage`, not `sessionStorage`: session storage is per-tab, so a `window.open` handoff would lose it. */
+export function saveStudioRunPayload(payload, runId, storeOverride) {
+    saveStudioRunPayloadRecord({ ...payload }, runId, storeOverride);
+}
+export function loadStudioRunPayload(runId, storeOverride) {
+    const raw = loadStudioRunPayloadRecord(runId, storeOverride);
+    // Only the outline is checked here; `defineProfile` checks the profiles when the run opens.
+    if (!raw || !keptRun.safeParse(raw).success)
+        return null;
+    return raw;
+}
+export function clearStudioRunPayload(runId, storeOverride) {
+    clearStudioRunPayloadRecord(runId, storeOverride);
+}

package/runtime-scope.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 { defineProfile, type KernelScope, type Profile, type ProfileDefinition, type Provider, type ResolveHost, type ToolExecutionCoordinator } from '@theoremjs/agents';
+import { type DetectSpec } from '@theoremjs/agents/guardrails';
+import type { AgentCall, AgentCallHook, ProviderHostOptions, TurnModel } from '@theoremjs/agents/kernel';
+export interface StudioProviderOptions extends ProviderHostOptions {
+    local?: {
+        baseUrl: string;
+        fetch?: typeof fetch;
+    };
+}
+import { type StudioRunsOn } from './lent-keys.ts';
+import type { StructuredRegistration, ToolRegistration } from './registrations.ts';
+import { type StudioToolHandlers } from './tools.ts';
+/** What a run holds besides what it runs on. */
+export interface StudioRuntimeBase {
+    /** A project's own provider definitions, registered after the studio's. */
+    providerDefinitions?: readonly Provider[];
+    execution?: ToolExecutionCoordinator;
+    pageExecution?: import('@theoremjs/agents').PageToolExecution;
+    providers?: StudioProviderOptions;
+    hostOptions?: (profile: Profile, model?: string) => ProviderHostOptions;
+    /** Answers every model call with a scripted model, in place of the profile's provider. */
+    provider?: (profile: Profile, model?: string) => TurnModel;
+    resolveHost?: ResolveHost;
+    remoteTools?: boolean;
+    /** Handlers the host runs for function tools, by name. A tool with none answers with its stub. */
+    toolHandlers?: StudioToolHandlers;
+    /** Before each agent tool call runs its agent: return `refuse` to stop it. */
+    onAgentCall?: (call: AgentCall) => {
+        refuse: string;
+    } | undefined | Promise<{
+        refuse: string;
+    } | undefined>;
+}
+/** A run, and what it runs on: a run on lent keys carries the keys it is held to. */
+export type StudioRuntime = StudioRuntimeBase & StudioRunsOn;
+/**
+ * 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 declare function runtimeProvider(runtime: StudioRuntime, scope: KernelScope, profile: Profile, model?: string): ProviderHostOptions;
+/**
+ * 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 declare function agentCallHook(scope: KernelScope, runtime: StudioRuntime): AgentCallHook;
+/**
+ * `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 declare function withCompiledPatterns<D extends ProfileDefinition>(def: D): Promise<D>;
+/** `def` with its patterns compiled by `compile`, for a caller that already holds the compiler. */
+export declare function withPatterns<D extends ProfileDefinition>(def: D, compile: (detect: DetectSpec) => DetectSpec): D;
+/** `defineProfile` for a draft a request carries. */
+export declare const defineDraft: typeof defineProfile;
+/** An agent the run's agent names, registered before it: one its agent tools run, or its summariser. */
+export interface StudioDependency {
+    profile: ProfileDefinition;
+    customTools: readonly ToolRegistration[];
+    structured?: StructuredRegistration;
+}
+/**
+ * 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 declare function studioScope(profile: ProfileDefinition, customTools: readonly ToolRegistration[], structured: StructuredRegistration | undefined, runtime: StudioRuntime, dependencies?: readonly StudioDependency[]): Promise<{
+    scope: KernelScope;
+    profile: Profile;
+}>;
+/**
+ * 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 declare function writtenScope(drafts: readonly StudioDependency[]): Promise<{
+    scope: KernelScope;
+    profile: Profile | undefined;
+}>;