@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/save.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What the builder changed in the studio, as Save needs it: each profile and
+ * tool as it compiled when the project opened and as it compiles now. Both
+ * sides go through the studio's own compiler, so a default the project never
+ * wrote is the same on both and is not a change. A provider is not compiled:
+ * it is what it opened as and what it holds now.
+ *
+ * @module
+ */
+import type { StudioProvider } from '../providers.ts';
+import type { StudioWorkspace } from '../workspace.ts';
+import type { NewSubjects } from './save-new.ts';
+import type { SaveSubject } from './save-plan.ts';
+import type { Removed } from './save-remove.ts';
+import type { SaveChange } from './save-wire.ts';
+/** What the project registers: the ids of its profiles and providers, and the names of its tools. */
+export interface ProjectNames {
+    profiles: readonly string[];
+    tools: readonly string[];
+    providers: readonly string[];
+}
+export type SaveSubjects = {
+    ok: true;
+    subjects: SaveSubject[];
+    added: NewSubjects;
+    removed: Removed;
+    changes: SaveChange[];
+} | {
+    ok: false;
+    issues: string[];
+};
+/**
+ * What Save writes of a provider: its definition, what it connects with, and its key slots, as the
+ * fields its definition holds them in. Its id is what code and models name it by, so it stays.
+ * Every definition holds a connection, so one the page leaves out is written as an empty one.
+ */
+export declare function providerSettings(provider: StudioProvider): Omit<StudioProvider, 'id'>;
+/** The names of the project's profiles and tools, from the workspace it opened as. */
+export declare function projectNames(opened: StudioWorkspace): ProjectNames;
+/**
+ * The profiles, tools, and providers that changed, each before and after, the ones the studio added,
+ * and the ones it removed. `changes` holds what Save cannot write at all: a tool the studio added that no
+ * agent allows, and an edit to a tool no agent allows.
+ */
+export declare function saveSubjects(workspace: StudioWorkspace, names: ProjectNames): SaveSubjects;
+/** A load of the project as the studio shows it once these are removed: what is left of it. */
+export declare function withoutRemoved(loaded: StudioWorkspace, removed: Removed): StudioWorkspace;
+/**
+ * What differs between the project as it loads now and the workspace the builder tested: the ids
+ * and names that are not the same on both sides. Empty when the file holds what was tested.
+ */
+export declare function projectDiffers(loaded: StudioWorkspace, tested: StudioWorkspace): string[];

package/server/save.js

@@ -0,0 +1,209 @@
+/**
+ * What the builder changed in the studio, as Save needs it: each profile and
+ * tool as it compiled when the project opened and as it compiles now. Both
+ * sides go through the studio's own compiler, so a default the project never
+ * wrote is the same on both and is not a change. A provider is not compiled:
+ * it is what it opened as and what it holds now.
+ *
+ * @module
+ */
+import { jsonSchemaFromZod } from '@theoremjs/agents/kernel';
+import { z } from 'zod';
+import { canonical } from "../canonical.js";
+import { compileWorkspace } from "../compile-workspace.js";
+import { unheldConnection, unheldProblem } from "../held-credentials.js";
+import { ON_OWN_KEYS } from "../lent-keys.js";
+import { withoutStudioFills } from "../policy.js";
+/**
+ * What Save writes of a provider: its definition, what it connects with, and its key slots, as the
+ * fields its definition holds them in. Its id is what code and models name it by, so it stays.
+ * Every definition holds a connection, so one the page leaves out is written as an empty one.
+ */
+export function providerSettings(provider) {
+    const { id: _id, connection = {}, ...settings } = provider;
+    return { ...settings, connection };
+}
+function compiled(workspace) {
+    // As the project's own: which models the studio's keys may call is a rule for a run, not for a file.
+    const result = compileWorkspace(workspace, ON_OWN_KEYS);
+    if (!result.ok)
+        return result.issues.map((issue) => issue.message);
+    const tools = new Map();
+    for (const agent of result.agents)
+        for (const tool of agent.customTools)
+            tools.set(tool.name, tool);
+    // A file holds the profile without the studio's own fill-ins, so Save never writes them.
+    const profiles = new Map(result.agents.map((agent) => [agent.agentId, withoutStudioFills(agent.profile)]));
+    const asked = new Map(result.agents.map((agent) => [agent.agentId, agent.questions]));
+    const pictured = new Map(result.agents.map((agent) => [agent.agentId, agent.images]));
+    const providers = new Map(workspace.providers.map((provider) => [provider.id, providerSettings(provider)]));
+    return { agents: result.agents, profiles, asked, pictured, tools, providers };
+}
+/** The names of the project's profiles and tools, from the workspace it opened as. */
+export function projectNames(opened) {
+    return {
+        profiles: opened.agents.map((agent) => agent.identity.agentId),
+        tools: opened.toolSpecs.map((tool) => tool.toolName),
+        providers: opened.providers.map((provider) => provider.id),
+    };
+}
+/** The workspace as the project opened it: each agent, tool, and provider the project has, at its start. */
+function atStart(workspace, names) {
+    const { starts } = workspace;
+    const agents = Object.values(starts.agents).filter((agent) => names.profiles.includes(agent.identity.agentId));
+    const toolSpecs = Object.values(starts.tools).filter((tool) => names.tools.includes(tool.toolName));
+    const providers = Object.values(starts.providers).filter((provider) => names.providers.includes(provider.id));
+    return { ...workspace, agents, toolSpecs, providers };
+}
+/**
+ * The profiles, tools, and providers that changed, each before and after, the ones the studio added,
+ * and the ones it removed. `changes` holds what Save cannot write at all: a tool the studio added that no
+ * agent allows, and an edit to a tool no agent allows.
+ */
+export function saveSubjects(workspace, names) {
+    const before = compiled(atStart(workspace, names));
+    if (Array.isArray(before)) {
+        return { ok: false, issues: ['The studio cannot read the project as it opened.', ...before] };
+    }
+    const after = compiled(workspace);
+    if (Array.isArray(after))
+        return { ok: false, issues: after };
+    const subjects = [];
+    const changes = [];
+    const added = {
+        profiles: [],
+        tools: [],
+        providers: [],
+    };
+    const seen = { profile: new Set(), tool: new Set() };
+    const add = (kind, started, now, known, edited) => {
+        if (started === undefined || !known.includes(started)) {
+            const tool = kind === 'tool' ? after.tools.get(now) : undefined;
+            if (kind === 'profile')
+                added.profiles.push(now);
+            else if (tool)
+                added.tools.push(tool);
+            // A tool no agent allows is not compiled, so no run tested it and there is nothing to write.
+            else
+                changes.push({ kind, of: now, setting: '', status: 'unused' });
+            return;
+        }
+        seen[kind].add(started);
+        const [was, is] = kind === 'profile'
+            ? [before.profiles.get(started), after.profiles.get(now)]
+            : [before.tools.get(started), after.tools.get(now)];
+        // A tool no profile allows on one side is not compiled there, so an edit to it has nothing to compare.
+        if (was === undefined || is === undefined) {
+            if (edited)
+                changes.push({ kind, of: started, setting: '', status: 'unfound' });
+            return;
+        }
+        subjects.push({ kind, of: started, before: was, after: is });
+    };
+    for (const agent of workspace.agents) {
+        const start = workspace.starts.agents[agent.key];
+        add('profile', start?.identity.agentId, agent.identity.agentId.trim(), names.profiles, true);
+    }
+    for (const tool of workspace.toolSpecs) {
+        const start = workspace.starts.tools[tool.key];
+        add('tool', start?.toolName, tool.toolName, names.tools, canonical(start) !== canonical(tool));
+    }
+    for (const provider of workspace.providers) {
+        // One the project does not have was added here: Save writes its definition.
+        if (!names.providers.includes(provider.id)) {
+            added.providers.push(provider);
+            continue;
+        }
+        const start = before.providers.get(provider.id);
+        if (!start) {
+            changes.push({ kind: 'provider', of: provider.id, setting: '', status: 'unfound' });
+            continue;
+        }
+        const after = providerSettings(provider);
+        if (canonical(start) === canonical(after))
+            continue;
+        subjects.push({ kind: 'provider', of: provider.id, before: start, after });
+    }
+    // A mask the page sends that it was not given has no value to run or to save with.
+    const unheld = [
+        ...workspace.providers.map((provider) => unheldConnection(provider.id, provider.connection)),
+        ...subjects
+            .filter((subject) => subject.kind === 'tool')
+            .map((subject) => unheldProblem(subject.of, subject.after, subject.before)),
+        ...added.tools.map((tool) => unheldProblem(tool.name, tool)),
+    ].filter((problem) => problem !== undefined);
+    if (unheld.length)
+        return { ok: false, issues: unheld };
+    const removed = {
+        profiles: names.profiles.filter((id) => !seen.profile.has(id)),
+        tools: names.tools.filter((name) => !seen.tool.has(name)),
+        providers: names.providers.filter((id) => !workspace.providers.some((provider) => provider.id === id)),
+    };
+    return { ok: true, subjects, added: { agents: after.agents, ...added }, removed, changes };
+}
+/** A tool with its schemas as the kernel reads them from the file Save writes: zod's reading of the same JSON. */
+function asKernelReads(tool) {
+    if (tool.type === 'agent')
+        return tool;
+    try {
+        return {
+            ...tool,
+            inputSchema: jsonSchemaFromZod(z.fromJSONSchema(tool.inputSchema), 'input'),
+            outputSchema: jsonSchemaFromZod(z.fromJSONSchema(tool.outputSchema), 'output'),
+        };
+    }
+    catch {
+        // A schema zod cannot read does not load either: the tool is left to differ.
+        return tool;
+    }
+}
+/** A load of the project as the studio shows it once these are removed: what is left of it. */
+export function withoutRemoved(loaded, removed) {
+    return {
+        ...loaded,
+        agents: loaded.agents.filter((agent) => !removed.profiles.includes(agent.identity.agentId)),
+        toolSpecs: loaded.toolSpecs.filter((tool) => !removed.tools.includes(tool.toolName)),
+        providers: loaded.providers.filter((provider) => !removed.providers.includes(provider.id)),
+    };
+}
+/**
+ * What differs between the project as it loads now and the workspace the builder tested: the ids
+ * and names that are not the same on both sides. Empty when the file holds what was tested.
+ */
+export function projectDiffers(loaded, tested) {
+    const now = compiled(loaded);
+    const wanted = compiled(tested);
+    if (Array.isArray(now))
+        return now;
+    if (Array.isArray(wanted))
+        return wanted;
+    const differs = [];
+    const same = (a, b) => canonical(a) === canonical(b);
+    for (const id of new Set([...now.profiles.keys(), ...wanted.profiles.keys()])) {
+        // A decision is its profile, what it is asked, and the pictures it sends: the files must hold all three as tested.
+        const held = same(now.profiles.get(id), wanted.profiles.get(id)) &&
+            same(now.asked.get(id), wanted.asked.get(id)) &&
+            same(now.pictured.get(id), wanted.pictured.get(id));
+        if (!held)
+            differs.push(id);
+    }
+    // A file holds a tool's schema as the page does, or as the kernel reads the page's: a tool the
+    // studio wrote loads as zod's reading of the JSON the builder tested. A schema Save changed in
+    // its Zod holds both, part by part, so the two are the same once zod has read each.
+    for (const name of new Set([...now.tools.keys(), ...wanted.tools.keys()])) {
+        const [loads, tool] = [now.tools.get(name), wanted.tools.get(name)];
+        if (same(loads, tool) || !tool || !loads) {
+            if (!same(loads, tool))
+                differs.push(name);
+            continue;
+        }
+        const read = asKernelReads(tool);
+        if (!same(loads, read) && !same(asKernelReads(loads), read))
+            differs.push(name);
+    }
+    for (const id of new Set([...now.providers.keys(), ...wanted.providers.keys()])) {
+        if (!same(now.providers.get(id), wanted.providers.get(id)))
+            differs.push(id);
+    }
+    return differs;
+}

package/server/serve.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Starts the studio's local server for one project.
+ *
+ *   deno run -A studio/server/serve.ts <setup-module> [--port 4983] [--page http://localhost:5174]
+ *     [--deno-config <deno.json>] [--editor <command>]
+ *
+ * The setup module is the project's: its default export registers the project's
+ * tools, profiles, and providers; an optional `host` export gives tool handlers
+ * their application context (the test user), and an optional `provider` export
+ * says where the providers find their keys. Only this machine can reach the server.
+ *
+ * The project loads in a process of its own (`project.ts`), and this passes the
+ * page's requests on to it, and starts it again when the page asks for a project
+ * whose files the builder's editor changed. Save is here: it writes the builder's
+ * edits into the project's files, checks them, and starts the project again from
+ * disk. It writes only files the project's setup imports, inside the folder the
+ * command ran in, and it never runs git. Open starts the builder's editor on a line of one of
+ * those files: the editor `--editor` names, else `$VISUAL` or `$EDITOR` when it
+ * opens in a window, else VS Code.
+ *
+ * @module
+ */
+export {};