@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/edited-session.js

@@ -0,0 +1,83 @@
+/**
+ * The second load of an open project: the files with the builder's unsaved edits laid over them,
+ * so one message can be answered by both. It starts when the page asks for it, is replaced when
+ * the edits change, and ends when the files do. It reaches the project's process only through the
+ * host it is given, so the rules can be run without one.
+ *
+ * @module
+ */
+import { projectDiffers, projectNames, saveSubjects, withoutRemoved } from "./save.js";
+import { message, refusal, stampOf } from "./save-session.js";
+/**
+ * The load with each added tool's sample reply as the page holds it. A tool added here has no
+ * file to read its sample reply from, and the load answers with it all the same.
+ */
+function withSampleReplies(loaded, tested, added) {
+    const fresh = new Set(added.map((tool) => tool.name));
+    const held = new Map(tested.toolSpecs.map((tool) => [tool.toolName, tool.stubOutputJson]));
+    return {
+        ...loaded,
+        toolSpecs: loaded.toolSpecs.map((tool) => {
+            const reply = fresh.has(tool.toolName) ? held.get(tool.toolName) : undefined;
+            return reply === undefined ? tool : { ...tool, stubOutputJson: reply };
+        }),
+    };
+}
+export function createEditedSession(host) {
+    let held;
+    const close = async () => {
+        const old = held;
+        held = undefined;
+        if (old)
+            await host.stop(old.loaded);
+    };
+    const start = async (workspace, names) => {
+        let subjects;
+        try {
+            subjects = saveSubjects(workspace, names);
+        }
+        catch (error) {
+            return refusal('issues', [message(error)]);
+        }
+        if (!subjects.ok)
+            return refusal('issues', subjects.issues);
+        const edits = { subjects: subjects.subjects, added: subjects.added };
+        const stamp = await stampOf(edits);
+        if (held?.stamp === stamp)
+            return { ok: true, stamp };
+        await close();
+        let loaded;
+        try {
+            loaded = await host.load(edits);
+        }
+        catch (error) {
+            return refusal('load', [message(error)]);
+        }
+        // The same proof Save makes of the files it wrote: this load is what the builder is testing.
+        // What the builder removed is still in this load, where nothing the page shows can reach it.
+        const opened = withSampleReplies(host.opened(loaded), workspace, subjects.added.tools);
+        const differs = projectDiffers(withoutRemoved(opened, subjects.removed), workspace);
+        if (differs.length) {
+            await host.stop(loaded);
+            return refusal('differs', differs);
+        }
+        held = { loaded, stamp };
+        return { ok: true, stamp };
+    };
+    const open = async (workspace, saved) => {
+        const names = projectNames(host.opened(saved));
+        return { ...(await start(workspace, names)), saved: [...names.profiles] };
+    };
+    /** One at a time: a second request waits for the first. */
+    let turn = Promise.resolve();
+    const inTurn = (work) => {
+        const next = turn.then(work, work);
+        turn = next.catch(() => { });
+        return next;
+    };
+    return {
+        open: (workspace, saved) => inTurn(() => open(workspace, saved)),
+        running: () => held?.loaded,
+        close: () => inTurn(close),
+    };
+}

package/server/edits.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The builder's unsaved edits, laid over a load of the project: each changed setting set on the
+ * profile or tool the project's own code registered, and each new agent and tool registered
+ * beside them. Everything the builder did not change stays the project's, handlers and all, so a
+ * run of this load differs from a run of the files only by the edits.
+ *
+ * @module
+ */
+import type { KernelScope } from '@theoremjs/agents';
+import type { ProjectImages, ProjectQuestions } from './handler.ts';
+import type { NewSubjects } from './save-new.ts';
+import type { SaveSubject } from './save-plan.ts';
+/** What the builder changed and added, as Save reads a workspace. */
+export interface ProjectEdits {
+    subjects: readonly SaveSubject[];
+    added: NewSubjects;
+}
+/**
+ * What each decision is asked in the edited load: the questions the setup names, and for a
+ * decision the setup does not name (one the builder added, renamed, or made a decision) the ones
+ * on the page.
+ */
+export declare function editedQuestions(edits: ProjectEdits, named?: ProjectQuestions): ProjectQuestions;
+/** The pictures each decision sends in the edited load, as `editedQuestions` reads its questions. */
+export declare function editedImages(edits: ProjectEdits, named?: ProjectImages): ProjectImages;
+/** One setting that differs: where it is, and its value now. No value when it was taken away. */
+export interface Change {
+    path: readonly string[];
+    value?: unknown;
+}
+/** The settings that differ between two compiled values. A list that differs is one setting. */
+export declare function changedSettings(before: unknown, after: unknown, path?: readonly string[]): Change[];
+/**
+ * Registers the edits over the project `scope` holds. A provider goes before the agents whose
+ * models name it, tools an agent runs before it, and an agent before the tool that calls it: the
+ * order the kernel checks them in.
+ */
+export declare function registerEdits(scope: KernelScope, edits: ProjectEdits): Promise<void>;

package/server/edits.js

@@ -0,0 +1,195 @@
+/**
+ * The builder's unsaved edits, laid over a load of the project: each changed setting set on the
+ * profile or tool the project's own code registered, and each new agent and tool registered
+ * beside them. Everything the builder did not change stays the project's, handlers and all, so a
+ * run of this load differs from a run of the files only by the edits.
+ *
+ * @module
+ */
+import { canonical } from "../canonical.js";
+import { heldSetting, unheldProblem } from "../held-credentials.js";
+import { registerStudioProvider } from "../providers.js";
+import { defineDraft, withCompiledPatterns } from "../runtime-scope.js";
+import { zodFromJsonSchema } from "../tool-schema.js";
+import { registerCustomTool } from "../tools.js";
+/**
+ * What each decision is asked in the edited load: the questions the setup names, and for a
+ * decision the setup does not name (one the builder added, renamed, or made a decision) the ones
+ * on the page.
+ */
+export function editedQuestions(edits, named = {}) {
+    const asked = { ...named };
+    for (const agent of edits.added.agents) {
+        if (agent.questions && !asked[agent.agentId])
+            asked[agent.agentId] = agent.questions;
+    }
+    return asked;
+}
+/** The pictures each decision sends in the edited load, as `editedQuestions` reads its questions. */
+export function editedImages(edits, named = {}) {
+    const sent = { ...named };
+    for (const agent of edits.added.agents) {
+        if (agent.images && !sent[agent.agentId])
+            sent[agent.agentId] = agent.images;
+    }
+    return sent;
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The settings that differ between two compiled values. A list that differs is one setting. */
+export function changedSettings(before, after, path = []) {
+    if (canonical(before) === canonical(after))
+        return [];
+    if (!isRecord(before) || !isRecord(after))
+        return after === undefined ? [{ path }] : [{ path, value: after }];
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])].flatMap((key) => changedSettings(before[key], after[key], [...path, key]));
+}
+/** `held` with one setting changed. What the path does not lead through is the same object as before. */
+function withSetting(held, [key, ...rest], change) {
+    if (key === undefined)
+        return change.value;
+    const { [key]: inner, ...others } = isRecord(held) ? held : {};
+    if (rest.length === 0 && !('value' in change))
+        return others;
+    return { ...others, [key]: withSetting(inner, rest, change) };
+}
+const withSettings = (held, changes) => changes.reduce((current, change) => withSetting(current, change.path, change), held);
+/** A settings group the kernel reads as a whole: one changed setting inside it replaces the group. */
+const WHOLE = [['guardrails', 'detect']];
+const leads = (group, path) => group.every((key, at) => path[at] === key);
+const at = (held, path) => path.reduce((inner, key) => (isRecord(inner) ? inner[key] : undefined), held);
+/** The profile's changes, with every change inside a whole group made one change of the group. */
+function profileChanges(before, after) {
+    const found = changedSettings(before, after);
+    const groups = WHOLE.filter((group) => found.some((change) => leads(group, change.path)));
+    return [
+        ...found.filter((change) => !groups.some((group) => leads(group, change.path))),
+        ...groups.map((path) => {
+            const value = at(after, path);
+            return value === undefined ? { path } : { path, value };
+        }),
+    ];
+}
+/** The settings of a tool that only the studio holds: the kernel's registration has no place for them. */
+const STUDIO_ONLY = new Set(['stubResponse']);
+/** A tool's schema, and the field the kernel holds it in. */
+const SCHEMAS = {
+    inputSchema: 'input',
+    outputSchema: 'output',
+};
+/** `tool`, refused when it shows a credential nothing holds a value for: a call must not carry a mask. */
+function held(tool) {
+    const problem = unheldProblem(tool.name, tool);
+    if (problem)
+        throw new Error(problem);
+    return tool;
+}
+/** The project's tool with the builder's changes: its handler and everything unchanged stay its own. */
+function editedTool(registered, before, after) {
+    const edited = { ...registered };
+    for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+        const [was, is] = [before[key], after[key]];
+        if (STUDIO_ONLY.has(key) || canonical(was) === canonical(is))
+            continue;
+        const schema = SCHEMAS[key];
+        if (schema)
+            Object.assign(edited, { [schema]: zodFromJsonSchema(is) });
+        else if (is === undefined)
+            Reflect.deleteProperty(edited, key);
+        // A credential the page holds masked is the project's own: the edit beside it keeps it.
+        else
+            Object.assign(edited, { [key]: heldSetting(key, is, registered[key]) });
+    }
+    return held(edited);
+}
+function registerNew(scope, tool) {
+    registerCustomTool(scope.tools, held(tool));
+}
+function registerTool(scope, tool, subject) {
+    const registered = subject ? scope.tools.get(subject.of) : undefined;
+    const before = subject?.before;
+    // A tool that became another kind keeps nothing of the old one.
+    if (!registered || before?.type !== tool.type)
+        registerNew(scope, tool);
+    else
+        scope.tools.register(editedTool(registered, before, tool));
+}
+async function registerAgent(scope, agent, subject) {
+    if (agent.structured && agent.profile.type !== 'live')
+        scope.schemas.register(agent.structured.id, agent.structured.spec);
+    const held = subject ? scope.profiles.find(subject.of) : undefined;
+    // An agent that became another type keeps nothing of the old one: the kernel filled the old
+    // type's own settings in, and the new type refuses them.
+    const registered = held?.type === agent.profile.type ? held : undefined;
+    const definition = registered
+        ? withSettings(registered, profileChanges(subject?.before, subject?.after))
+        : agent.profile;
+    scope.profiles.register(defineDraft(await withCompiledPatterns(definition)));
+}
+/**
+ * A provider with the builder's edits over the one the project registered. What the page was not
+ * shown stays as registered: anything it connects with that is not text. Moved to another kernel
+ * definition, it is that definition with what the page holds.
+ */
+function registerProvider(scope, subject) {
+    const registered = scope.providers.get(subject.of);
+    const [before, after] = [subject.before, subject.after];
+    if (!registered || after.definition !== before.definition) {
+        // On another definition, nothing the project connected with before carries over.
+        registerStudioProvider(scope.providers, { ...after, id: subject.of }, undefined, 'replace');
+        return;
+    }
+    const [shown, edited] = [
+        isRecord(before.connection) ? before.connection : {},
+        isRecord(after.connection) ? after.connection : {},
+    ];
+    const connection = { ...(isRecord(registered.connection) ? registered.connection : {}) };
+    for (const key of new Set([...Object.keys(shown), ...Object.keys(edited)])) {
+        if (key in edited)
+            connection[key] = edited[key];
+        else
+            delete connection[key];
+    }
+    scope.providers.replace(registered.definition, {
+        id: subject.of,
+        connection,
+        ...(typeof after.keySlot === 'string' ? { keySlot: after.keySlot } : {}),
+        ...(typeof after.fallbackKeySlot === 'string'
+            ? { fallbackKeySlot: after.fallbackKeySlot }
+            : {}),
+    });
+}
+/**
+ * Registers the edits over the project `scope` holds. A provider goes before the agents whose
+ * models name it, tools an agent runs before it, and an agent before the tool that calls it: the
+ * order the kernel checks them in.
+ */
+export async function registerEdits(scope, edits) {
+    for (const provider of edits.added.providers)
+        registerStudioProvider(scope.providers, provider);
+    for (const held of edits.subjects)
+        if (held.kind === 'provider')
+            registerProvider(scope, held);
+    const subject = (kind, named, name) => edits.subjects.find((held) => held.kind === kind && named(held.after) === name);
+    const fresh = new Set(edits.added.tools.map((tool) => tool.name));
+    const done = new Set();
+    const tool = (held) => {
+        if (done.has(held.name))
+            return;
+        done.add(held.name);
+        const changed = subject('tool', (after) => after.name, held.name);
+        if (changed || fresh.has(held.name))
+            registerTool(scope, held, changed);
+    };
+    const agents = edits.added.agents;
+    for (const agent of agents)
+        for (const held of agent.customTools)
+            if (held.type !== 'agent')
+                tool(held);
+    for (const agent of agents) {
+        for (const held of agent.customTools)
+            tool(held);
+        const changed = subject('profile', (after) => after.id, agent.agentId);
+        if (changed || edits.added.profiles.includes(agent.agentId))
+            await registerAgent(scope, agent, changed);
+    }
+}

package/server/handler.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The studio's local server: a project's registered profiles and tools, as the
+ * studio's workspace, and each profile served to run.
+ *
+ * The page is the studio. It reads its workspace from `GET <base>` and runs
+ * the open profile at `<base>/profiles/<id>`, so a run is the project's own
+ * code, not the page's draft.
+ *
+ * It reads and runs. Writing an edit back to the project is the server's
+ * (`serve.ts`), which starts this in a process of its own and starts it again
+ * after a Save, so a run is always the code on disk.
+ *
+ * @module
+ */
+import { type DecisionAsset, type DecisionQuestion, type Profile, type ProviderHostOptions } from '@theoremjs/agents';
+import { type StudioAsks } from '../asks.ts';
+import { type StudioActingAs, type StudioPeople, type StudioPeopleOffer } from '../people.ts';
+import { type StudioUpgrade } from './live.ts';
+export { STUDIO_BASE } from './draft-handler.ts';
+import { type StudioWorkspace } from '../workspace.ts';
+import type { ProjectOrigins, ProviderPlace, SharedSetting, Unregistered } from './save-wire.ts';
+/** A profile the page could not show or run, and why. */
+export type StudioProblem = {
+    profile: string;
+    message: string;
+};
+/** A model that cannot run as the project's files set it, and why. Its agent still opens and runs. */
+export type StudioModelProblem = {
+    profile: string;
+    model: string;
+    message: string;
+};
+/** A profile or provider the studio shows differently from the project, and each setting it differs in, by path. */
+export type StudioDifference = {
+    kind: 'profile' | 'provider';
+    of: string;
+    settings: string[];
+};
+/** What the page opens. */
+export type StudioDescription = {
+    project: string;
+    /** The project as the studio holds one: an agent per profile, and the tools they share. */
+    workspace: StudioWorkspace;
+    problems: StudioProblem[];
+    /** The models that cannot run as the files set them. None when every one can. */
+    modelProblems?: StudioModelProblem[];
+    /** Where what the studio shows is not what the project registered. None when they agree. */
+    differences?: StudioDifference[];
+    /** Why the project does not compile as the studio opened it, when it does not. */
+    unheld?: string[];
+    /** The settings several profiles share. The studio command reads them from the project's files. */
+    shared?: SharedSetting[];
+    /** The settings the project's files set in code, which the studio shows and does not change. */
+    origins?: ProjectOrigins;
+    /** The profiles and tools the files define that the project did not register. */
+    unregistered?: Unregistered[];
+    /** Where the files define each provider the project registered. */
+    providerPlaces?: ProviderPlace[];
+    /** The tools that write: the ones the studio makes ask before each run, and the ones it cannot. */
+    asks: StudioAsks;
+    /** What the project printed when its files stopped loading. The page then shows the last load that did. */
+    unloaded?: string;
+    /** The editor the studio command opens files in when the page names none, by its command. */
+    editor?: string;
+    /** The setup file the studio command was started on, from the folder it ran in. */
+    setup?: string;
+    /** The places and people the setup file offers a run to act as. None: every run acts as no one. */
+    people?: StudioPeopleOffer;
+    /** Why the people the setup file exports cannot be offered, when they cannot. */
+    peopleProblem?: string;
+};
+export type StudioHandlerOptions = {
+    /** The project's name, shown at the top of the page. */
+    project: string;
+    /** The origins whose page may call the server. Any other origin is refused. */
+    pageOrigins: readonly string[];
+    /** The `host:port` the server listens on. A request that names another host is refused. */
+    listenHost: string;
+    /**
+     * Opaque application context for tool handlers (`ctx.host`): a database client, and the person
+     * the builder picked, in the place they picked. `undefined` is no one. A promise is awaited
+     * before the run starts.
+     */
+    host?: (request: Request, actingAs: StudioActingAs | undefined) => unknown;
+    /** The places and people a run may act as. Without them every run acts as no one. */
+    people?: StudioPeople;
+    /** How the project's registered providers find their keys. Default: as the project registered them. */
+    provider?: ProviderHostOptions;
+    /** What each decision profile asks, by the profile's id: the questions the application passes when it decides. */
+    questions?: ProjectQuestions;
+    /** The pictures each decision profile sends, by the profile's id: the images the application passes when it decides. */
+    images?: ProjectImages;
+    /** How the server takes a socket, which a voice call needs. Without it a live profile is not run. */
+    upgrade?: StudioUpgrade;
+    /**
+     * The key the chats' conversations are sealed with. `serve.ts` makes one per
+     * studio run and hands it to every load, so a chat outlives a Save or an edit.
+     */
+    conversationKey: string;
+};
+/** A project's decision questions: for each decision profile's id, its questions by their ids. */
+export type ProjectQuestions = Record<string, Record<string, DecisionQuestion>>;
+/** A project's decision pictures: for each decision profile's id, its images by reference. */
+export type ProjectImages = Record<string, Record<string, DecisionAsset>>;
+/**
+ * A profile as the studio can print it. What a file writes as code (a validator, a trigger, a
+ * trace sink of its own) cannot be shown as a setting, so it is left to the file: the editor
+ * says where it is set, Save does not touch it, and a run is still the profile as registered.
+ */
+export declare function printableProfile<P extends Profile>(profile: P): P;
+export declare function json(status: number, body: unknown, headers: HeadersInit): Response;
+/**
+ * Whether a request comes from somewhere other than the studio's own page.
+ * A page on another site can reach 127.0.0.1 through the builder's browser: the
+ * origin check stops its requests, and the host check stops a name it pointed at
+ * this machine. A browser's request that names no page at all (an image or a script tag, an
+ * address typed in) is refused too: the studio's page always names itself.
+ */
+export declare function isForeign(request: Request, options: Pick<StudioHandlerOptions, 'listenHost' | 'pageOrigins'>): boolean;
+/** The page's own origin, echoed: a request from any other was refused before this. */
+export declare function corsHeaders(request: Request, pageOrigins: readonly string[]): Record<string, string>;
+/** Why a decision profile is not run: the setup file does not name its questions. */
+export declare function noQuestions(profileId: string): string;
+/**
+ * Why a decision profile's questions cannot be asked, or nothing. A setup file is not always
+ * type-checked, so the studio reads what it exports before it trusts it.
+ */
+export declare function questionsFault(profileId: string, questions: unknown): string | undefined;
+/**
+ * Serves the studio for the tools and profiles registered when it is called.
+ * Register the project first.
+ */
+export declare function createStudioHandler(options: StudioHandlerOptions): (request: Request) => Promise<Response>;