@theoremjs/studio 0.0.0-stage → 0.3.2

package/surface.js

@@ -0,0 +1,631 @@
+/**
+ * The studio as a surface: the draft's sections as nodes an agent can look at and set, its
+ * key slots as secret nodes it can point at and test, and the page's own actions (a new agent,
+ * a try in the preview, launch, export). The page supplies a host; the runtime does the rest.
+ */
+import { fieldMeta, profileGraphFacet } from '@theoremjs/agents/schema';
+import { defineAction, secretCard, } from '@theoremjs/agents/surface';
+import { z } from 'zod';
+import { compileStudio } from "./compile.js";
+import { createBlankDraft, defaultModelBinding, defaultToolSpec, draftFacets, excludeFacet, includableFacets, includeFacet, newModelBinding, newToolSpec, removeModelBinding, STUDIO_PROFILE_TYPES, setProfileType, updateModelBinding, } from "./draft.js";
+import { createConsoleExampleDraft, createDecisionExampleDraft, createExampleDraft, createLiveExampleDraft, createNarratorExampleDraft, } from "./example.js";
+import { modelBindingViolation } from "./policy.js";
+import { modelRoute } from "./providers.js";
+import { bindingSlots } from "./requirements.js";
+import { studioNodeRef, studioTree } from "./tree.js";
+const SEND_CAP_MS = 60_000;
+const KEY_NODE = 'key:';
+const FACET_KEY = {
+    identity: 'identity',
+    models: 'models',
+    tools: 'tools',
+    inputs: 'inputs',
+    outputs: 'outputs',
+    turnBehaviour: 'turnBehaviour',
+    guardrails: 'guardrails',
+    observability: 'observability',
+    image: 'image',
+    speech: 'speech',
+    live: 'live',
+    decision: 'decision',
+    labels: 'labels',
+};
+/** Draft keys a change touched, as the nodes an agent knows. */
+const SECTION_NODE = {
+    modelBindings: 'models',
+    toolSpecs: 'tools',
+    included: '',
+};
+const BLOCKED_FIELDS = {
+    'identity.profileType': 'act setType on the studio',
+    'modelBinding.key': 'a model keeps its own key',
+    'toolSpec.key': 'a tool keeps its own key',
+    'image.references': 'pinned images are added by the person',
+};
+/** How a tool's settings leave the page. */
+const TOOL_FORMATS = {
+    endpoint: 'url',
+    serverUrl: 'url',
+    authRedirectUri: 'url',
+    headersJson: 'headers',
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const facetOf = (nodeId) => nodeId.split(':', 1)[0] ?? nodeId;
+/** The optional sections a type brings that the old one lacked, switched on. */
+function withNewSections(before, after) {
+    const had = new Set(includableFacets(before));
+    return includableFacets(after)
+        .filter((facet) => !had.has(facet))
+        .reduce(includeFacet, after);
+}
+/** A node's own values, which `set` can change. */
+function nodeValues(draft, nodeId) {
+    const ref = studioNodeRef(draft, nodeId);
+    if (!ref)
+        return undefined;
+    if (ref.facet === 'modelBinding') {
+        return { ...draft.modelBindings.find((binding) => binding.key === ref.key) };
+    }
+    if (ref.facet === 'toolSpec')
+        return { ...draft.toolSpecs.find((tool) => tool.key === ref.key) };
+    return { ...draft[FACET_KEY[ref.facet] ?? 'identity'] };
+}
+/** Where a value may be set: its kind must match the one there; a number field may also be null. */
+function kindProblem(current, blank, value) {
+    if (value === null)
+        return current === null || blank === null ? undefined : 'cannot be empty';
+    if (current === null || current === undefined) {
+        return isRecord(value) ? 'must be a single value' : undefined;
+    }
+    if (Array.isArray(current))
+        return Array.isArray(value) ? undefined : 'must be a list';
+    if (isRecord(current))
+        return 'is a group; set its fields one by one, like "include.usage"';
+    return typeof current === typeof value ? undefined : `must be ${typeof current}`;
+}
+function setAtPath(target, blank, path, value) {
+    const [head = '', ...rest] = path.split('.');
+    if (!Object.hasOwn(target, head))
+        return { why: 'no such setting' };
+    if (rest.length === 0) {
+        const problem = kindProblem(target[head], blank?.[head], value);
+        return problem ? { why: problem } : { next: { ...target, [head]: value } };
+    }
+    const inner = target[head];
+    if (!isRecord(inner))
+        return { why: 'no such setting' };
+    const innerBlank = blank?.[head];
+    const set = setAtPath(inner, isRecord(innerBlank) ? innerBlank : undefined, rest.join('.'), value);
+    return 'why' in set ? set : { next: { ...target, [head]: set.next } };
+}
+function editNode(draft, nodeId, changes) {
+    const ref = studioNodeRef(draft, nodeId);
+    const rejected = [];
+    if (!ref)
+        return { next: draft, rejected };
+    const facet = ref.facet;
+    let current = nodeValues(draft, nodeId) ?? {};
+    const blank = facet === 'modelBinding'
+        ? { ...defaultModelBinding() }
+        : facet === 'toolSpec'
+            ? { ...defaultToolSpec() }
+            : createBlankDraft()[FACET_KEY[facet] ?? 'identity'];
+    for (const [path, value] of Object.entries(changes)) {
+        const blocked = BLOCKED_FIELDS[`${facet}.${path}`];
+        if (blocked) {
+            rejected.push({ field: path, why: blocked });
+            continue;
+        }
+        if (facet === 'labels') {
+            if (!fieldMeta(`labels.${path}`))
+                rejected.push({ field: path, why: 'no such line' });
+            else if (typeof value !== 'string')
+                rejected.push({ field: path, why: 'must be text' });
+            else
+                current = { ...current, [path]: value };
+            continue;
+        }
+        const set = setAtPath(current, blank, path, value);
+        if ('why' in set)
+            rejected.push({ field: path, why: set.why });
+        else
+            current = set.next;
+    }
+    if (rejected.length === Object.keys(changes).length)
+        return { next: draft, rejected };
+    if (ref.facet === 'modelBinding') {
+        const { key: _key, ...rest } = current;
+        return { next: updateModelBinding(draft, ref.key, rest), rejected };
+    }
+    if (ref.facet === 'toolSpec') {
+        return {
+            next: {
+                ...draft,
+                toolSpecs: draft.toolSpecs.map((tool) => tool.key === ref.key ? { ...tool, ...current } : tool),
+            },
+            rejected,
+        };
+    }
+    return { next: { ...draft, [FACET_KEY[ref.facet] ?? 'identity']: current }, rejected };
+}
+function describeReply(blocks) {
+    const reply = [];
+    const media = [];
+    const tools = [];
+    const errors = [];
+    for (const block of blocks) {
+        if (block.kind === 'text')
+            reply.push(block.text);
+        else if (block.kind === 'structured')
+            reply.push(JSON.stringify(block.value));
+        else if (block.kind === 'media')
+            media.push({ mimeType: block.mimeType });
+        else if (block.kind === 'tool')
+            tools.push({ name: block.tool.name, state: block.tool.state?.phase });
+        else if (block.kind === 'error')
+            errors.push(block.message);
+    }
+    return { reply: reply.join('\n'), media, tools, errors };
+}
+/** Each key slot the draft uses, and what uses it. */
+/** `binding` as the run policy reads it: its protocol, its provider's definition, and whether the agent decides. */
+function routed(draft, binding) {
+    return {
+        ...modelRoute(draft.providers, draft.identity.profileType, binding),
+        builtInTools: binding.builtInTools,
+    };
+}
+function keySlots(draft) {
+    const slots = new Map();
+    const use = (slot, by) => {
+        if (!slot)
+            return;
+        slots.set(slot, [...(slots.get(slot) ?? []), by]);
+    };
+    use(draft.models.key, 'every model, by default');
+    use(draft.models.fallbackKey, 'every model, as fallback');
+    for (const binding of draft.modelBindings) {
+        const name = binding.modelId || 'a model';
+        use(binding.keySlot, `model ${name}`);
+        use(binding.fallbackKeySlot, `model ${name}, as fallback`);
+        const { keySlot, fallbackKeySlot, given } = bindingSlots(draft, binding);
+        if (given.keySlot)
+            use(keySlot, `model ${name}, from its provider`);
+        if (given.fallbackKeySlot)
+            use(fallbackKeySlot, `model ${name}, from its provider as fallback`);
+    }
+    for (const tool of draft.toolSpecs)
+        use(tool.authSlot, `tool ${tool.toolName || 'unnamed'}`);
+    return slots;
+}
+const typeInput = z.enum(STUDIO_PROFILE_TYPES);
+/** The worked examples one draft holds. The code architect is two agents, so the page loads it. */
+const EXAMPLE_DRAFTS = {
+    travel: createExampleDraft,
+    live: createLiveExampleDraft,
+    narrator: createNarratorExampleDraft,
+    console: createConsoleExampleDraft,
+    decision: createDecisionExampleDraft,
+};
+const exampleInput = z.enum(Object.keys(EXAMPLE_DRAFTS));
+/** The studio's surface, over a host the page (or a test) provides. */
+export function studioSurface(host) {
+    const draft = () => host.getDraft();
+    /** The lent keys the page runs on, if any. */
+    const lent = () => {
+        const on = host.getRunsOn();
+        return on.mode === 'demo' ? on.keys : undefined;
+    };
+    const revision = () => host.getRevision();
+    const compileIssues = () => {
+        const compiled = compileStudio(draft(), host.getRunsOn());
+        return compiled.ok ? [] : compiled.issues;
+    };
+    const keyIssues = () => [...keySlots(draft())].flatMap(([slot]) => {
+        const card = secretCard(host.key(slot));
+        if (!card.set) {
+            return [{ node: `${KEY_NODE}${slot}`, field: 'value', message: `No key in ${slot}` }];
+        }
+        return card.problems.length
+            ? [
+                {
+                    node: `${KEY_NODE}${slot}`,
+                    field: 'value',
+                    message: `The key has ${card.problems.join(', ')}`,
+                },
+            ]
+            : [];
+    });
+    const issues = () => [
+        ...compileIssues().map(({ nodeId, field, message }) => ({
+            node: nodeId,
+            ...(field ? { field } : {}),
+            message,
+        })),
+        ...keyIssues(),
+    ];
+    /**
+     * Selects a node so the person sees what the agent changed. Returns why the change is not made
+     * yet, when the person has to agree to it first.
+     */
+    const apply = (next, nodeId) => {
+        const waits = next !== draft() ? host.update(next) : undefined;
+        if (nodeId && studioNodeRef(draft(), nodeId))
+            host.select(nodeId);
+        return waits;
+    };
+    const refuse = (field, why) => ({
+        rejected: [{ field, why }],
+    });
+    const blocked = () => {
+        const found = compileIssues();
+        return found.length
+            ? {
+                result: {
+                    ok: false,
+                    why: `${String(found.length)} issues to fix first; look at the studio`,
+                },
+            }
+            : undefined;
+    };
+    const rootActions = {
+        newAgent: defineAction({
+            description: 'Start a new agent, replacing the draft (the person can undo). Ask first if they changed the current one.',
+            effect: 'write',
+            intent: true,
+            input: z.object({
+                type: typeInput.describe('The agent type'),
+                example: exampleInput.optional().describe('Start from a worked example'),
+            }),
+            run: async ({ type, example }) => {
+                const blank = createBlankDraft();
+                const next = example
+                    ? await EXAMPLE_DRAFTS[example]()
+                    : withNewSections(blank, setProfileType(blank, type, lent()));
+                host.replaceDraft(next, 'th30 started a new agent.');
+                return { node: 'identity' };
+            },
+        }),
+        setType: defineAction({
+            description: "Change the agent's type; sections the new type adds are turned on.",
+            effect: 'write',
+            input: z.object({ type: typeInput }),
+            run: ({ type }) => {
+                const before = draft();
+                apply(withNewSections(before, setProfileType(before, type, lent())), 'identity');
+                return { node: 'identity' };
+            },
+        }),
+        include: defineAction({
+            description: 'Turn on an optional section.',
+            effect: 'write',
+            input: z.object({ section: z.string() }),
+            run: ({ section }) => {
+                const can = includableFacets(draft());
+                if (!profileGraphFacet(section) || !can.includes(section)) {
+                    return refuse('section', `can add: ${can.join(', ') || 'nothing for this type'}`);
+                }
+                apply(includeFacet(draft(), section), section);
+                return { node: section };
+            },
+        }),
+        exclude: defineAction({
+            description: 'Turn off an optional section.',
+            effect: 'write',
+            input: z.object({ section: z.string() }),
+            run: ({ section }) => {
+                const has = draft().included;
+                if (!has.includes(section))
+                    return refuse('section', `can remove: ${has.join(', ') || 'nothing'}`);
+                apply(excludeFacet(draft(), section));
+                return {};
+            },
+        }),
+        addModel: defineAction({
+            description: 'Add a model; the first becomes the default.',
+            effect: 'write',
+            input: z.object({
+                modelId: z.string().optional().describe('Your name for it'),
+                provider: z.string().optional(),
+                apiId: z.string().optional().describe("The provider's model id"),
+            }),
+            run: (input) => {
+                const current = draft();
+                if (!current.identity.profileType)
+                    return refuse('type', 'act setType first');
+                const binding = {
+                    ...newModelBinding(current, lent()?.start),
+                    ...Object.fromEntries(Object.entries(input).filter(([, value]) => value)),
+                };
+                const node = `modelBinding:${binding.key}`;
+                apply({
+                    ...current,
+                    models: {
+                        ...current.models,
+                        defaultModel: current.models.defaultModel || binding.modelId,
+                    },
+                    modelBindings: [...current.modelBindings, binding],
+                }, node);
+                const violation = modelBindingViolation(routed(draft(), binding), host.getRunsOn());
+                return {
+                    node,
+                    rejected: violation ? [{ field: violation.field, why: violation.message }] : [],
+                };
+            },
+        }),
+        addTool: defineAction({
+            description: 'Add a custom tool.',
+            effect: 'write',
+            input: z.object({ toolName: z.string().optional(), description: z.string().optional() }),
+            run: ({ toolName, description }) => {
+                const current = draft();
+                if (!current.identity.profileType)
+                    return refuse('type', 'act setType first');
+                if (!draftFacets(current).includes('tools')) {
+                    return refuse('tools', 'this agent type takes no tools');
+                }
+                const spec = {
+                    ...newToolSpec(current),
+                    ...(toolName ? { toolName } : {}),
+                    ...(description ? { description } : {}),
+                };
+                const node = `toolSpec:${spec.key}`;
+                apply({ ...current, toolSpecs: [...current.toolSpecs, spec] }, node);
+                return { node };
+            },
+        }),
+        try: defineAction({
+            description: "Send a message to the agent in the preview and read its reply. It runs on the person's keys.",
+            effect: 'run',
+            input: z.object({ message: z.string().min(1) }),
+            run: async ({ message }) => {
+                const stop = blocked();
+                if (stop)
+                    return stop;
+                let timer;
+                const timeout = new Promise((resolve) => {
+                    timer = setTimeout(() => resolve('timeout'), SEND_CAP_MS);
+                });
+                const result = await Promise.race([host.send(message), timeout]);
+                clearTimeout(timer);
+                if (result === 'timeout') {
+                    return {
+                        result: { sent: true, note: 'Still running; the reply will show in the preview.' },
+                    };
+                }
+                if (!result) {
+                    return {
+                        result: {
+                            sent: false,
+                            why: 'The preview cannot take a message: it is busy, or a key is missing. Look at the key nodes.',
+                        },
+                    };
+                }
+                return { result: { sent: true, ...describeReply(result.blocks) } };
+            },
+        }),
+        newConversation: defineAction({
+            description: 'Clear the preview conversation.',
+            effect: 'run',
+            run: () => {
+                host.newConversation();
+                return { result: { cleared: true } };
+            },
+        }),
+        launch: defineAction({
+            description: 'Open the agent on its own page in a new tab.',
+            effect: 'run',
+            run: () => {
+                const stop = blocked();
+                if (stop)
+                    return stop;
+                host.launch();
+                return { result: { launched: true } };
+            },
+        }),
+        export: defineAction({
+            description: 'Download every agent as a .zip of source files, copy the files, or copy them with a brief for an LLM.',
+            effect: 'run',
+            input: z.object({ format: z.enum(['zip', 'copy', 'llm']) }),
+            run: async ({ format }) => {
+                const stop = blocked();
+                if (stop)
+                    return stop;
+                return { result: { done: await host.exportAgent(format), format } };
+            },
+        }),
+    };
+    /** A tool that sends a credential gets the one typed into its test, as a secret. */
+    const credentialField = (nodeId) => {
+        const ref = studioNodeRef(draft(), nodeId);
+        if (ref?.facet !== 'toolSpec' || !host.toolCredential)
+            return {};
+        const tool = draft().toolSpecs.find((candidate) => candidate.key === ref.key);
+        if (!tool || (tool.authType ?? 'none') === 'none')
+            return {};
+        return {
+            credential: {
+                value: host.toolCredential(ref.key),
+                format: 'secret',
+                doc: "The credential the person typed into this tool's test. Used for tests only, never saved.",
+                usedBy: [`tool ${tool.toolName || 'unnamed'}, when tested`],
+            },
+        };
+    };
+    const sectionFields = (nodeId) => {
+        const values = nodeValues(draft(), nodeId) ?? {};
+        const facet = facetOf(nodeId);
+        const fields = Object.fromEntries(Object.entries(values).map(([name, value]) => {
+            const meta = fieldMeta(facet === 'labels' ? `labels.${name}` : `${facet}.${name}`);
+            const why = BLOCKED_FIELDS[`${facet}.${name}`];
+            const format = facet === 'toolSpec' ? TOOL_FORMATS[name] : undefined;
+            return [
+                name,
+                {
+                    value,
+                    ...(meta ? { type: meta.type, doc: meta.doc } : {}),
+                    ...(meta?.options ? { options: meta.options } : {}),
+                    ...(format ? { format } : {}),
+                    ...(why ? { readOnly: why } : {}),
+                },
+            ];
+        }));
+        return { ...fields, ...credentialField(nodeId) };
+    };
+    const sectionNode = (tree, parent) => {
+        const id = tree.id;
+        const facet = facetOf(id);
+        const own = {};
+        if (facet === 'modelBinding') {
+            own.remove = defineAction({
+                description: 'Remove this model.',
+                effect: 'write',
+                run: () => {
+                    const ref = studioNodeRef(draft(), id);
+                    if (ref?.facet !== 'modelBinding')
+                        return refuse('at', 'gone already');
+                    apply(removeModelBinding(draft(), ref.key), 'models');
+                    return { node: 'models' };
+                },
+            });
+        }
+        if (facet === 'toolSpec') {
+            const key = id.slice('toolSpec:'.length);
+            own.remove = defineAction({
+                description: 'Remove this tool.',
+                effect: 'write',
+                run: () => {
+                    const waits = apply({
+                        ...draft(),
+                        toolSpecs: draft().toolSpecs.filter((tool) => tool.key !== key),
+                    });
+                    return waits ? refuse('at', waits) : { node: 'tools' };
+                },
+            });
+            const testTool = host.testTool;
+            if (testTool) {
+                own.test = defineAction({
+                    description: 'Call this tool once for real, with sample input (or yours), and see what came back: status, errors, the reply.',
+                    effect: 'run',
+                    input: z.object({ input: z.record(z.string(), z.unknown()).optional() }),
+                    run: async ({ input }) => ({ result: await testTool(key, input) }),
+                });
+            }
+        }
+        return {
+            id,
+            title: tree.label,
+            parent,
+            fields: () => sectionFields(id),
+            set: (changes) => {
+                const before = draft();
+                if (!studioNodeRef(before, id))
+                    return { rejected: [{ field: 'at', why: 'gone' }] };
+                const { next, rejected } = editNode(before, id, changes);
+                const waits = apply(next, id);
+                if (waits) {
+                    const refused = new Set(rejected.map(({ field }) => field));
+                    const held = Object.keys(changes).filter((field) => !refused.has(field));
+                    return { rejected: [...rejected, ...held.map((field) => ({ field, why: waits }))] };
+                }
+                if (facet === 'modelBinding') {
+                    const binding = draft().modelBindings.find((candidate) => id === `modelBinding:${candidate.key}`);
+                    const violation = binding
+                        ? modelBindingViolation(routed(draft(), binding), host.getRunsOn())
+                        : null;
+                    if (violation)
+                        rejected.push({ field: violation.field, why: violation.message });
+                }
+                return { rejected };
+            },
+            point: (field) => host.select(id, field),
+            ...(Object.keys(own).length ? { actions: own } : {}),
+        };
+    };
+    const keyNode = (slot, usedBy) => {
+        const testKey = host.testKey;
+        return {
+            id: `${KEY_NODE}${slot}`,
+            title: `Key ${slot}`,
+            parent: 'models',
+            summary: `Used by ${usedBy.join('; ')}`,
+            fields: () => ({
+                value: {
+                    value: host.key(slot),
+                    format: 'secret',
+                    doc: 'An API key the person pastes into the Keys panel. Kept only in this tab.',
+                    usedBy,
+                },
+            }),
+            point: () => host.openKeys(slot),
+            ...(testKey
+                ? {
+                    actions: {
+                        test: defineAction({
+                            description: "Ask the key's provider whether it accepts the key.",
+                            effect: 'run',
+                            run: async () => ({ result: await testKey(slot) }),
+                        }),
+                    },
+                }
+                : {}),
+        };
+    };
+    const nodes = () => {
+        const current = draft();
+        const tree = studioTree(current);
+        const found = [
+            {
+                id: '',
+                title: 'Studio',
+                summary: 'The agent the person is building, its sections, keys, and preview.',
+                fields: () => ({
+                    type: {
+                        value: draft().identity.profileType || null,
+                        options: STUDIO_PROFILE_TYPES,
+                        readOnly: 'act setType',
+                    },
+                    canAdd: { value: includableFacets(draft()), readOnly: 'act include' },
+                    included: { value: draft().included, readOnly: 'act exclude' },
+                }),
+                actions: rootActions,
+            },
+            sectionNode(tree, ''),
+        ];
+        const walk = (node, parent) => {
+            found.push(sectionNode(node, parent));
+            for (const child of node.children)
+                walk(child, node.id);
+        };
+        for (const child of tree.children)
+            walk(child, '');
+        for (const [slot, usedBy] of keySlots(current))
+            found.push(keyNode(slot, usedBy));
+        return found;
+    };
+    return {
+        id: 'studio',
+        title: 'Studio',
+        revision,
+        summary: () => {
+            const current = draft();
+            const count = issues().length;
+            return `${current.identity.profileType || 'no type'} agent ${current.identity.handle || current.identity.agentId || 'unnamed'}; ${String(count)} ${count === 1 ? 'issue' : 'issues'}`;
+        },
+        nodes,
+        issues,
+        changesSince: (since) => host.changesSince(since).map((change) => ({
+            revision: change.revision,
+            by: change.by,
+            nodes: [...new Set(change.sections.map((section) => SECTION_NODE[section] ?? section))],
+        })),
+        subscribe: (listener) => host.subscribe(listener),
+        secrets: () => ({
+            ...Object.fromEntries([...keySlots(draft()).keys()].map((slot) => [`key ${slot}`, host.key(slot)])),
+            ...Object.fromEntries(draft().toolSpecs.map((tool) => [
+                `credential ${tool.toolName || tool.key}`,
+                host.toolCredential?.(tool.key) ?? '',
+            ])),
+        }),
+    };
+}

package/system-markup.d.ts

@@ -0,0 +1,20 @@
+import type { SystemPrompt } from '@theoremjs/agents/kernel';
+/**
+ * The studio's way to write a system prompt with private sections: the
+ * whole prompt as text, each private section wrapped as `{private: …}`.
+ */
+type SystemMarkup = {
+    ok: true;
+    prompt: SystemPrompt | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * 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.
+ */
+declare function parseSystemMarkup(text: string): SystemMarkup;
+export type { SystemMarkup };
+export { parseSystemMarkup };