@theoremjs/studio 0.0.0-stage → 0.3.2

package/browser.js

@@ -0,0 +1,4 @@
+export { KNOWN_GEMINI_EMBEDDING_MODELS, KNOWN_OPENROUTER_EMBEDDING_MODELS, keyKind, listLocalStudioModels, listProviderModels, localStudioConfig, STUDIO_KEY_SLOT_CAP, studioKeySlots, studioVault, } from "./browser-connection.js";
+export { browserStudioLiveConnection } from "./browser-live.js";
+export { createBrowserStudioDecisionTransport, createBrowserStudioEmbeddingTransport, createBrowserStudioHostTransport, createBrowserStudioTransport, } from "./browser-transport.js";
+export { attachStudioLiveSession } from "./live-session-bridge.js";

package/canonical.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Values compared as text, whatever order their settings are held in. A file's reading, a merge
+ * and the page each build the same agent or tool with its settings in a different order, and
+ * that is not a difference. On its own so the page and the project's load, which read no source,
+ * do not load the TypeScript the Save plan reads source with.
+ *
+ * @module
+ */
+/** `value` with every object's keys in order and nothing undefined, as text: equal values give equal text. */
+export declare function canonical(value: unknown): string;

package/canonical.js

@@ -0,0 +1,25 @@
+/**
+ * Values compared as text, whatever order their settings are held in. A file's reading, a merge
+ * and the page each build the same agent or tool with its settings in a different order, and
+ * that is not a difference. On its own so the page and the project's load, which read no source,
+ * do not load the TypeScript the Save plan reads source with.
+ *
+ * @module
+ */
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** `value` with every object's keys in order and nothing undefined, as text: equal values give equal text. */
+export function canonical(value) {
+    const ordered = (item) => {
+        if (Array.isArray(item))
+            return item.map(ordered);
+        if (!isRecord(item))
+            return item;
+        const keys = Object.keys(item)
+            .filter((key) => item[key] !== undefined)
+            .sort();
+        return Object.fromEntries(keys.map((key) => [key, ordered(item[key])]));
+    };
+    return JSON.stringify(ordered(value)) ?? 'undefined';
+}

package/compile-workspace.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Compiles every agent of a workspace and orders them so each is registered
+ * after the agents it names: the ones its agent tools run and the one that
+ * summarises for it. Issues land on the node of the agent or tool at fault.
+ */
+import { type CompiledStudio, type StudioIssue } from './compile.ts';
+import type { StudioRunsOn } from './lent-keys.ts';
+import type { StudioDependency } from './runtime-scope.ts';
+import { type StudioWorkspace } from './workspace.ts';
+export interface CompiledWorkspace {
+    /** Each agent after the agents it names: the order a scope registers them in. */
+    agents: CompiledStudio[];
+}
+export type WorkspaceCompileResult = ({
+    ok: true;
+} & CompiledWorkspace) | {
+    ok: false;
+    issues: StudioIssue[];
+};
+/** Every issue across the workspace is reported, each once. */
+export declare function compileWorkspace(workspace: StudioWorkspace, on: StudioRunsOn): WorkspaceCompileResult;
+/**
+ * The agent `agentId`, with the agents it needs as its dependencies, each after
+ * the ones it names: what a run registers. `undefined` when no compiled agent has that id.
+ */
+export declare function workspaceRunAgent(compiled: CompiledWorkspace, agentId: string): (CompiledStudio & {
+    dependencies: StudioDependency[];
+}) | undefined;

package/compile-workspace.js

@@ -0,0 +1,295 @@
+/**
+ * Compiles every agent of a workspace and orders them so each is registered
+ * after the agents it names: the ones its agent tools run and the one that
+ * summarises for it. Issues land on the node of the agent or tool at fault.
+ */
+import { createKernelRegistry, defineProfile, TheoremError, z } from '@theoremjs/agents';
+import { agentToolInputSchema, compileStudio, uncompiled, } from "./compile.js";
+import { kernelDefinition, providerProblems, registerStudioProvider } from "./providers.js";
+import { registerDefined } from "./tools.js";
+import { modelBindingNodeId, providerNodeId, toolSpecNodeId } from "./tree.js";
+import { agentDraft, agentNodeId, scopedNodeId, } from "./workspace.js";
+/** The agents an agent tool can run, and the one type that can summarise. */
+const CALLABLE_TYPES = new Set(['text', 'image', 'speech']);
+function references(workspace) {
+    const tools = new Map(workspace.toolSpecs.map((tool) => [tool.key, tool]));
+    return workspace.agents.flatMap((agent) => [
+        ...agent.tools.allow.flatMap((key) => {
+            const tool = tools.get(key);
+            return tool?.toolType === 'agent' && tool.agentKey
+                ? [{ from: agent, to: tool.agentKey, nodeId: toolSpecNodeId(key), field: 'agentKey' }]
+                : [];
+        }),
+        ...agent.modelBindings.flatMap((binding) => binding.compactTiming && binding.compactWith
+            ? [
+                {
+                    from: agent,
+                    to: binding.compactWith,
+                    nodeId: agentNodeId(agent.key, modelBindingNodeId(binding.key)),
+                    field: 'compactWith',
+                },
+            ]
+            : []),
+    ]);
+}
+/** Each agent's key, to the keys of the agents it names. */
+function namedBy(workspace, refs) {
+    const named = new Map(workspace.agents.map((agent) => [agent.key, new Set()]));
+    for (const ref of refs)
+        if (named.has(ref.to))
+            named.get(ref.from.key)?.add(ref.to);
+    return named;
+}
+/** The agents from `start` to `end`, each naming the next; undefined when `start` never reaches `end`. */
+function chain(named, start, end) {
+    // Each agent reached, to the one it was reached from.
+    const via = new Map([[start, undefined]]);
+    const queue = [start];
+    for (let key = queue.shift(); key !== undefined; key = queue.shift()) {
+        if (key === end) {
+            const path = [];
+            for (let at = key; at !== undefined; at = via.get(at))
+                path.unshift(at);
+            return path;
+        }
+        for (const next of named.get(key) ?? []) {
+            if (!via.has(next)) {
+                via.set(next, key);
+                queue.push(next);
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Where a reference closes a circle, what it is and how to break it. Each agent
+ * must be set up after the agents it names, so a circle has no first one.
+ */
+function circleMessage(ref, path, idOf) {
+    const from = `'${idOf(ref.from.key) ?? ''}'`;
+    const to = `'${idOf(ref.to) ?? ''}'`;
+    if (ref.from.key === ref.to) {
+        return ref.field === 'agentKey'
+            ? `${from} has this tool on, and the tool runs ${from} itself. Choose another agent for it to run, or turn it off for ${from}.`
+            : `${from} can't summarise its own conversation. Choose another text agent.`;
+    }
+    const circle = [ref.from.key, ...path].map((key) => idOf(key) ?? '').join(' → ');
+    return ref.field === 'agentKey'
+        ? `${from} has this tool on, and it runs ${to}, which leads back to ${from} (${circle}). Agents can't run each other in a circle: turn this tool off for ${from}, or remove the way back.`
+        : `${to} summarises for ${from}, and ${to} leads back to ${from} (${circle}). Agents can't run each other in a circle: choose another agent to summarise, or remove the way back.`;
+}
+/** Agents in workspace order, each after the agents it names; the rest are in a loop. */
+function registrationOrder(workspace, named) {
+    const done = new Set();
+    const ordered = [];
+    let progressed = true;
+    while (progressed) {
+        progressed = false;
+        for (const agent of workspace.agents) {
+            if (done.has(agent.key))
+                continue;
+            if ([...(named.get(agent.key) ?? [])].every((key) => done.has(key))) {
+                done.add(agent.key);
+                ordered.push(agent);
+                progressed = true;
+            }
+        }
+    }
+    return { ordered, looped: workspace.agents.filter((agent) => !done.has(agent.key)) };
+}
+/** An id two agents share, or a tool name two tools share, is an issue on each after the first. */
+function reportDuplicates(workspace, report) {
+    const ids = new Set();
+    for (const agent of workspace.agents) {
+        const id = agent.identity.agentId.trim();
+        if (id && ids.has(id)) {
+            report({
+                nodeId: agentNodeId(agent.key),
+                message: `Another agent has the id '${id}'.`,
+                field: 'agentId',
+            });
+        }
+        ids.add(id);
+    }
+    const names = new Set();
+    for (const tool of workspace.toolSpecs) {
+        const name = tool.toolName.trim();
+        if (name && names.has(name)) {
+            report({
+                nodeId: toolSpecNodeId(tool.key),
+                message: `Tool name '${name}' is used twice.`,
+                field: 'toolName',
+            });
+        }
+        names.add(name);
+    }
+    const providers = new Set();
+    for (const provider of workspace.providers) {
+        if (provider.id && providers.has(provider.id)) {
+            report({
+                nodeId: providerNodeId(provider.id),
+                message: `Another provider has the id '${provider.id}'.`,
+                field: 'id',
+            });
+        }
+        providers.add(provider.id);
+    }
+}
+/** Why the agent a reference names can't do its job; undefined when it can, or isn't set up. */
+function wrongTypeMessage(ref, target) {
+    const type = target?.identity.profileType;
+    if (!target || !type)
+        return undefined;
+    const id = target.identity.agentId.trim();
+    if (ref.field === 'agentKey' && !CALLABLE_TYPES.has(type)) {
+        return `'${id}' is a ${type} agent. An agent tool runs a text, image, or speech agent.`;
+    }
+    if (ref.field === 'compactWith' && type !== 'text') {
+        return `'${id}' is a ${type} agent. Only a text agent summarises.`;
+    }
+    return undefined;
+}
+/** Each agent's own compile, in registration order; an agent's issues land under its node. */
+function compileAgents(workspace, agents, on, agentIdOf, report) {
+    const agentInputOf = (key) => {
+        const called = agentDraft(workspace, key);
+        return called && agentToolInputSchema(called);
+    };
+    const compiled = [];
+    for (const agent of agents) {
+        const draft = agentDraft(workspace, agent.key);
+        const result = draft && compileStudio(draft, on, agentIdOf, agentInputOf);
+        if (!result)
+            continue;
+        if (result.ok) {
+            const { ok: _ok, ...rest } = result;
+            compiled.push({ key: agent.key, agent: rest });
+            continue;
+        }
+        for (const issue of result.issues) {
+            report({ ...issue, nodeId: scopedNodeId(agent.key, issue.nodeId) });
+        }
+    }
+    return compiled;
+}
+/**
+ * The kernel's own rules across the workspace, such as an agent tool's agent that can stop on a
+ * gate: the first provider or agent the kernel's registry refuses, as an issue on it. The registry holds the
+ * workspace's providers as they are now, so an agent is checked against what it would run on.
+ */
+function kernelIssue(workspace, compiled) {
+    const registry = createKernelRegistry();
+    // why: a project's own definition is the project's; the server checks its agents when it opens.
+    const own = new Set();
+    for (const provider of workspace.providers) {
+        if (!kernelDefinition(provider.definition)) {
+            own.add(provider.id);
+            continue;
+        }
+        try {
+            registerStudioProvider(registry.providers, provider);
+        }
+        catch (err) {
+            const message = err instanceof z.ZodError
+                ? err.issues[0]?.message
+                : err instanceof TheoremError
+                    ? err.message
+                    : undefined;
+            if (message === undefined)
+                throw err;
+            return { nodeId: providerNodeId(provider.id), message };
+        }
+    }
+    for (const { key, agent } of compiled) {
+        const { profile } = agent;
+        if (profile.type !== 'host' &&
+            Object.values(profile.models).some((binding) => own.has(binding.provider)))
+            continue;
+        try {
+            registerDefined(registry, defineProfile(uncompiled(agent.profile)), agent.customTools, agent.structured);
+        }
+        catch (err) {
+            if (!(err instanceof TheoremError))
+                throw err;
+            return { nodeId: agentNodeId(key), message: err.message };
+        }
+    }
+    return undefined;
+}
+/** Every issue across the workspace is reported, each once. */
+export function compileWorkspace(workspace, on) {
+    const issues = new Map();
+    const report = (issue) => {
+        issues.set(JSON.stringify([issue.nodeId, issue.field, issue.index, issue.message]), issue);
+    };
+    const byKey = new Map(workspace.agents.map((agent) => [agent.key, agent]));
+    const agentIdOf = (key) => byKey.get(key)?.identity.agentId.trim();
+    reportDuplicates(workspace, report);
+    for (const provider of workspace.providers) {
+        for (const problem of providerProblems(provider)) {
+            report({ nodeId: providerNodeId(provider.id), ...problem });
+        }
+    }
+    const refs = references(workspace);
+    for (const ref of refs) {
+        const message = wrongTypeMessage(ref, byKey.get(ref.to));
+        if (message)
+            report({ nodeId: ref.nodeId, message, field: ref.field });
+    }
+    const named = namedBy(workspace, refs);
+    const { ordered, looped } = registrationOrder(workspace, named);
+    // Each reference that closes a circle is an issue on the field that holds it.
+    for (const ref of refs) {
+        const path = chain(named, ref.to, ref.from.key);
+        if (path)
+            report({
+                nodeId: ref.nodeId,
+                field: ref.field,
+                message: circleMessage(ref, path, agentIdOf),
+            });
+    }
+    const compiled = compileAgents(workspace, [...ordered, ...looped], on, agentIdOf, report);
+    if (issues.size)
+        return { ok: false, issues: [...issues.values()] };
+    const refused = kernelIssue(workspace, compiled);
+    if (refused)
+        return { ok: false, issues: [refused] };
+    return { ok: true, agents: compiled.map(({ agent }) => agent) };
+}
+/**
+ * The agent `agentId`, with the agents it needs as its dependencies, each after
+ * the ones it names: what a run registers. `undefined` when no compiled agent has that id.
+ */
+export function workspaceRunAgent(compiled, agentId) {
+    const byId = new Map(compiled.agents.map((agent) => [agent.agentId, agent]));
+    const chatted = byId.get(agentId);
+    if (!chatted)
+        return undefined;
+    const needed = new Set();
+    const visit = (id) => {
+        const agent = byId.get(id);
+        if (!agent || needed.has(id))
+            return;
+        needed.add(id);
+        for (const named of namedAgents(agent))
+            visit(named);
+    };
+    for (const named of namedAgents(chatted))
+        visit(named);
+    needed.delete(agentId);
+    const dependencies = compiled.agents
+        .filter((agent) => needed.has(agent.agentId))
+        .map(({ profile, customTools, structured }) => ({
+        profile,
+        customTools,
+        ...(structured ? { structured } : {}),
+    }));
+    return { ...chatted, dependencies };
+}
+/** The agent ids a compiled agent names: its agent tools' and its compaction's. */
+function namedAgents(agent) {
+    const tools = agent.customTools.flatMap((tool) => (tool.type === 'agent' ? [tool.profile] : []));
+    const models = 'models' in agent.profile ? Object.values(agent.profile.models) : [];
+    const compactors = models.flatMap((binding) => binding.compaction?.profile ? [binding.compaction.profile] : []);
+    return [...tools, ...compactors];
+}

package/compile.d.ts

@@ -0,0 +1,65 @@
+import { type DecisionAsset, type DecisionQuestion, type ImageProfileDefinition, type LiveProfileDefinition, type ProfileGuardrailsSpec, type SpeechProfileDefinition, type TextProfileDefinition } from '@theoremjs/agents';
+import { type DecisionProfileDefinition, type EmbeddingProfileDefinition, type HostProfileDefinition, type ProfileDefinition } from '@theoremjs/agents/kernel';
+import type { GuardrailsDraft, StudioDraft } from './draft.ts';
+import type { StudioRunsOn } from './lent-keys.ts';
+import { type StudioProvider } from './providers.ts';
+import type { StructuredRegistration, ToolRegistration } from './registrations.ts';
+export type StudioProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition | DecisionProfileDefinition | EmbeddingProfileDefinition | HostProfileDefinition;
+/** A profile that runs a model turn: every studio type but decision and host. */
+export type StudioTurnProfileDefinition = Exclude<StudioProfileDefinition, DecisionProfileDefinition | HostProfileDefinition>;
+/**
+ * `field` is the draft key at fault on that node (e.g. `handle`, `defaultEffort`) and `index`
+ * the list entry; issues about the node as a whole have neither.
+ */
+export interface StudioIssue {
+    nodeId: string;
+    message: string;
+    field?: string;
+    index?: number;
+}
+export interface CompiledStudio {
+    agentId: string;
+    profile: StudioProfileDefinition;
+    customTools: ToolRegistration[];
+    structured?: StructuredRegistration;
+    /** A decision'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 can name, each with its adapter. */
+    providers: readonly StudioProvider[];
+}
+export type StudioCompileResult = ({
+    ok: true;
+} & CompiledStudio) | {
+    ok: false;
+    issues: StudioIssue[];
+};
+/**
+ * The agent id another agent of the workspace has, by its draft key; `undefined` when
+ * none has that key. A single draft names no other agent.
+ */
+export type AgentIdOf = (key: string) => string | undefined;
+/**
+ * What a tool that runs another agent of the workspace takes, by that agent's draft key;
+ * `undefined` when none has that key or an agent tool can't run it.
+ */
+export type AgentToolInputOf = (key: string) => Record<string, unknown> | undefined;
+/** What a tool that runs this draft's agent takes, as the kernel derives it from the agent's inputs. */
+export declare function agentToolInputSchema(draft: StudioDraft): Record<string, unknown> | undefined;
+/** Why these headers can't be saved, when one of them looks like a credential. */
+export declare function credentialHeaderProblem(headers: Record<string, string> | undefined): string | undefined;
+/**
+ * Why a tool's URL can't be saved, when a query parameter in it looks like a credential. A masked
+ * one is the project's own; a new one goes under Auth, which can send an API key in the URL.
+ */
+export declare function credentialUrlProblem(url: string | undefined): string | undefined;
+/** The network guardrail `guardrails` compiles to, which a draft's runs keep to: what a connection test sends. */
+export declare function draftNetwork(guardrails: GuardrailsDraft): ProfileGuardrailsSpec['network'];
+/** `profile` as it can be defined here, before the run's server compiles its patterns. */
+export declare function uncompiled<P extends ProfileDefinition>(profile: P): P;
+/**
+ * Every issue is reported, not just the first. `agentIdOf` and `agentInputOf` resolve the
+ * agents a workspace draft names.
+ */
+export declare function compileStudio(draft: StudioDraft, on: StudioRunsOn, agentIdOf?: AgentIdOf, agentInputOf?: AgentToolInputOf): StudioCompileResult;