@theoremjs/studio 0.0.0-stage → 0.3.2

package/ui/lib/studio-project.js

@@ -0,0 +1,177 @@
+/**
+ * A project open in the studio. A local server (`studio/server/serve.ts` in the package) hands
+ * the page the project's registered profiles and tools as a workspace, and runs each profile's
+ * own code.
+ */
+import { createContext, useContext } from 'react';
+import { filesPrint, providersAtStart, } from "../../mod.js";
+import { READ_STEPS } from "../../read-steps.js";
+import { projectEndpoint } from "./project-address.js";
+import { getPref } from "./studio-prefs.js";
+/**
+ * What the project's files hold that exported code names and does not write again. A provider the
+ * builder changed is left out, so the code writes it as the studio holds it.
+ */
+export function projectCode(project, workspace) {
+    if (!project)
+        return undefined;
+    const kept = new Set(providersAtStart(workspace));
+    return {
+        providers: project.providerPlaces.filter((place) => kept.has(place.id)),
+        origins: project.origins.profiles,
+    };
+}
+export const NO_ASKS = { asked: [], inside: [] };
+const NO_ORIGINS = { profiles: {}, tools: {}, providers: {} };
+/** Set while the page has a project open; `null` on the website's own page. */
+export const ProjectContext = createContext(null);
+export function useProject() {
+    return useContext(ProjectContext);
+}
+/** The session for a project already open: the run page names it in its address. */
+export function projectSession(name) {
+    return {
+        endpoint: projectEndpoint(),
+        name,
+        profiles: [],
+        providers: [],
+        problems: [],
+        modelProblems: [],
+        differences: [],
+        unheld: [],
+        shared: [],
+        unregistered: [],
+        origins: NO_ORIGINS,
+        providerPlaces: [],
+        asks: NO_ASKS,
+        print: '',
+        people: undefined,
+        peopleProblem: undefined,
+    };
+}
+/** Where the local server runs the profile with this id. */
+export function projectProfileEndpoint(project, profileId) {
+    return `${project.endpoint}/profiles/${encodeURIComponent(profileId)}`;
+}
+async function post(project, path, body) {
+    const response = await fetch(`${project.endpoint}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok)
+        throw new Error(`The studio server answered ${String(response.status)}.`);
+    return response.json();
+}
+/** What Save would write for this workspace: each change, and the lines of each file. Writes nothing. */
+export function reviewSave(project, workspace) {
+    return post(project, '/save', { workspace });
+}
+/** Writes the changes of a review the builder read. The server checks the project and reloads it. */
+export function writeSave(project, workspace, stamp) {
+    return post(project, '/save', { workspace, stamp });
+}
+/** Puts the files of the last Save back. */
+export function undoSave(project) {
+    return post(project, '/save/undo', {});
+}
+/**
+ * Starts the load that runs this workspace's edits over the project's files, when it is not the
+ * one running. Writes nothing.
+ */
+export function openEdited(project, workspace) {
+    return post(project, '/edited', { workspace });
+}
+/** Where the local server runs the profile with this id as the builder's edits make it. */
+export function editedProfileEndpoint(project, profileId) {
+    return `${project.endpoint}/edited/profiles/${encodeURIComponent(profileId)}`;
+}
+/** Shows a line of one of the project's files in the editor the builder chose, or the studio command's. */
+export function openInEditor(project, place) {
+    const editor = getPref('editor');
+    return post(project, '/open', editor ? { ...place, editor } : place);
+}
+async function describe() {
+    const response = await fetch(projectEndpoint());
+    if (!response.ok)
+        throw new Error(`The studio server answered ${String(response.status)}.`);
+    return response.json();
+}
+/**
+ * The project as the server describes it, after each step of its read of the files: `said` hears
+ * each as it happens. The server sends a line of JSON for each, then one holding the project.
+ */
+async function describeSaying(said) {
+    const response = await fetch(`${projectEndpoint()}?${READ_STEPS}`);
+    if (!response.ok || !response.body) {
+        throw new Error(`The studio server answered ${String(response.status)}.`);
+    }
+    const lines = response.body.pipeThrough(new TextDecoderStream()).getReader();
+    let kept = '';
+    let opened;
+    const take = (line) => {
+        if (!line)
+            return;
+        const read = JSON.parse(line);
+        if ('opened' in read)
+            opened = read.opened;
+        else
+            said(read);
+    };
+    for (let next = await lines.read(); !next.done; next = await lines.read()) {
+        const whole = (kept + next.value).split('\n');
+        kept = whole.pop() ?? '';
+        whole.forEach(take);
+    }
+    take(kept);
+    if (!opened)
+        throw new Error('The studio server stopped before it sent the project.');
+    return opened;
+}
+/** What the files say, of a project as the server describes it. */
+function filesOf(opened) {
+    return {
+        profiles: opened.workspace.agents.map((agent) => agent.identity.agentId),
+        providers: opened.workspace.providers.map((provider) => provider.id),
+        problems: opened.problems,
+        modelProblems: opened.modelProblems ?? [],
+        differences: opened.differences ?? [],
+        unheld: opened.unheld ?? [],
+        origins: opened.origins ?? NO_ORIGINS,
+        providerPlaces: opened.providerPlaces ?? [],
+        asks: opened.asks ?? NO_ASKS,
+        print: filesPrint(opened.workspace),
+        // Set even when absent, so a setup file that stops offering people stops being offered.
+        people: opened.people,
+        peopleProblem: opened.peopleProblem,
+        ...(opened.unloaded === undefined ? {} : { unloaded: opened.unloaded }),
+    };
+}
+/**
+ * What the project's files say now that the page does not hold as edits: the profiles they hold
+ * and the ones the studio cannot run, the settings they set in code, whose lines a Save moves,
+ * and the tools the studio makes ask. With them, the workspace the files open as.
+ */
+export async function readFiles() {
+    const opened = await describe();
+    return { files: filesOf(opened), workspace: opened.workspace };
+}
+/**
+ * The project the local server has open. `said` hears each step of the server's read of the
+ * files. Throws when no server answers.
+ */
+export async function openProject(said) {
+    const opened = await (said ? describeSaying(said) : describe());
+    return {
+        project: {
+            endpoint: projectEndpoint(),
+            name: opened.project,
+            shared: opened.shared ?? [],
+            unregistered: opened.unregistered ?? [],
+            ...(opened.editor === undefined ? {} : { editor: opened.editor }),
+            ...(opened.setup === undefined ? {} : { setup: opened.setup }),
+            ...filesOf(opened),
+        },
+        workspace: opened.workspace,
+    };
+}

package/ui/lib/studio-restore.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Reading the studio's workspace back from this tab's sessionStorage. A kept workspace that no
+ * longer fits the current shape is set aside, and a draft kept by the one-agent studio opens as
+ * a workspace holding it.
+ */
+import { type StudioWorkspace } from '../../mod.ts';
+import { type RestoredStudio } from './studio-session.ts';
+/**
+ * The workspace this tab last kept. `discarded` when one was there but could not be read back (an
+ * older shape after a deploy, or a broken write); it is removed so the next load starts clean.
+ */
+export declare function restoreStudio(): {
+    kind: 'restored';
+    value: RestoredStudio;
+} | {
+    kind: 'none' | 'discarded';
+};
+/**
+ * Keeps edits the project's files changed under, masked as the tab keeps a workspace, until the
+ * builder brings them back or lets them go. A reload offers them again.
+ */
+export declare function setAside(key: string, edits: StudioWorkspace): void;
+/** Forgets a project's set-aside edits: the builder brought them back or let them go. */
+export declare function dropAside(key: string): void;
+/** The edits set aside for a project and not yet answered for, over the files as `opened`. */
+export declare function editsAside(key: string, opened: StudioWorkspace): StudioWorkspace | undefined;
+/**
+ * Keeps the files as the studio read them, beside the edits that stand on that reading. It says
+ * which profiles the builder removed, so a merge after a reload leaves them removed.
+ */
+export declare function keepReading(key: string, print: string, read: StudioWorkspace): void;
+/** The files as the studio read them when they printed as `print`, if this tab kept that reading. */
+export declare function keptReading(key: string, print: string | undefined): StudioWorkspace | undefined;
+/**
+ * The edits this tab kept for a project. `restored` with the reading of the files they stand on:
+ * when the files changed since, the studio merges the change into them as it does one the
+ * builder's editor writes while the page is open. `moved` when the edits stand on no reading, so
+ * nothing says what the files changed: the files open, and the edits are set aside and handed back
+ * to be offered. Kept edits that cannot be read back are removed.
+ */
+export declare function restoreProject(key: string, opened: StudioWorkspace, files: string): {
+    kind: 'restored';
+    value: RestoredStudio;
+} | {
+    kind: 'moved';
+    workspace: StudioWorkspace;
+} | {
+    kind: 'none' | 'discarded';
+};

package/ui/lib/studio-restore.js

@@ -0,0 +1,251 @@
+/**
+ * Reading the studio's workspace back from this tab's sessionStorage. A kept workspace that no
+ * longer fits the current shape is set aside, and a draft kept by the one-agent studio opens as
+ * a workspace holding it.
+ */
+import { agentDraft, createBlankDraft, editedSince, STUDIO_WORKSPACE_VERSION, workspaceFromDraft, } from "../../mod.js";
+import { CHAT_PREFIX, isRecord, session, WORKSPACE_KEY, } from "./studio-session.js";
+import { keptTool, keptWorkspace } from "./studio-store.js";
+const V1_DRAFT_KEY = 'theorem.studio.v1';
+const V1_CHAT_KEY = 'theorem.studio.v1.chat';
+/**
+ * True when `value` has every section `shape` has, all the way down, and lists, text and
+ * switches where it has them. A draft kept before the draft changed shape fails it, so it is
+ * set aside rather than compiled.
+ */
+function hasShapeOf(value, shape) {
+    if (Array.isArray(shape))
+        return Array.isArray(value);
+    if (typeof shape === 'string' || typeof shape === 'boolean')
+        return typeof value === typeof shape;
+    if (!isRecord(shape))
+        return true;
+    if (!isRecord(value))
+        return false;
+    return Object.entries(shape).every(([key, part]) => hasShapeOf(value[key], part));
+}
+function isWorkspace(value) {
+    if (!isRecord(value) || value.v !== STUDIO_WORKSPACE_VERSION)
+        return false;
+    const { agents, toolSpecs, selected, chatWith } = value;
+    if (!Array.isArray(agents) || agents.length === 0 || !Array.isArray(toolSpecs))
+        return false;
+    if (!Array.isArray(value.providers))
+        return false;
+    if (typeof selected !== 'string' || typeof chatWith !== 'string')
+        return false;
+    const { starts } = value;
+    if (!isRecord(starts) || !isRecord(starts.agents) || !isRecord(starts.tools))
+        return false;
+    if (!isRecord(starts.providers))
+        return false;
+    const blank = createBlankDraft();
+    const workspace = value;
+    return agents.every((agent) => isRecord(agent) &&
+        typeof agent.key === 'string' &&
+        isRecord(agent.tools) &&
+        Array.isArray(agent.tools.allow) &&
+        hasShapeOf(agentDraft(workspace, agent.key), blank));
+}
+function isStoredWorkspace(value) {
+    return (isRecord(value) &&
+        value.v === STUDIO_WORKSPACE_VERSION &&
+        isWorkspace(value.workspace) &&
+        typeof value.revision === 'number');
+}
+/** A one-agent draft kept before workspaces, as the studio kept it. */
+function isV1Draft(value) {
+    return (isRecord(value) &&
+        value.v === 1 &&
+        hasShapeOf(value.draft, createBlankDraft()) &&
+        typeof value.revision === 'number' &&
+        typeof value.selectedId === 'string');
+}
+function parsed(store, key) {
+    const raw = store.getItem(key);
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A one-agent draft from before workspaces, as a workspace holding it. Its conversation was kept
+ * whole, before conversations were sealed, so nothing can resume it. Either way the old keys go.
+ */
+function migrateV1(store) {
+    const kept = parsed(store, V1_DRAFT_KEY);
+    if (kept === undefined)
+        return undefined;
+    store.removeItem(V1_DRAFT_KEY);
+    store.removeItem(V1_CHAT_KEY);
+    if (!isV1Draft(kept))
+        return 'discarded';
+    const workspace = workspaceFromDraft(kept.draft, kept.selectedId);
+    return { workspace, revision: kept.revision };
+}
+function forgetAll(store) {
+    store.removeItem(WORKSPACE_KEY);
+    for (const key of Object.keys(store)) {
+        if (key.startsWith(CHAT_PREFIX))
+            store.removeItem(key);
+    }
+}
+/**
+ * The workspace this tab last kept. `discarded` when one was there but could not be read back (an
+ * older shape after a deploy, or a broken write); it is removed so the next load starts clean.
+ */
+export function restoreStudio() {
+    const store = session();
+    if (!store)
+        return { kind: 'none' };
+    const kept = parsed(store, WORKSPACE_KEY);
+    if (kept === undefined) {
+        const migrated = migrateV1(store);
+        if (migrated === 'discarded')
+            return { kind: 'discarded' };
+        return migrated ? { kind: 'restored', value: migrated } : { kind: 'none' };
+    }
+    if (isStoredWorkspace(kept)) {
+        const { workspace, revision } = kept;
+        return { kind: 'restored', value: { workspace, revision } };
+    }
+    forgetAll(store);
+    return { kind: 'discarded' };
+}
+const MASKED = ['endpoint', 'serverUrl', 'headersJson'];
+/**
+ * A kept workspace with what keeping it masked put back from the files: a tool's URLs and headers,
+ * in its start and wherever the builder had not changed them. One they did change stays masked.
+ */
+function withFilesCredentials(kept, files) {
+    const held = new Map(files.toolSpecs.map((tool) => [tool.toolName, tool]));
+    const starts = { ...kept.starts.tools };
+    const tools = new Map(kept.toolSpecs.map((tool) => [tool.key, tool]));
+    for (const [key, start] of Object.entries(kept.starts.tools)) {
+        const file = held.get(start.toolName);
+        if (!file)
+            continue;
+        const masked = keptTool(file);
+        const now = tools.get(key);
+        const back = { ...start };
+        const next = now && { ...now };
+        for (const field of MASKED) {
+            if (file[field] === undefined || start[field] !== masked[field])
+                continue;
+            back[field] = file[field];
+            if (next && now[field] === start[field])
+                next[field] = file[field];
+        }
+        starts[key] = back;
+        if (next)
+            tools.set(key, next);
+    }
+    return {
+        ...kept,
+        toolSpecs: kept.toolSpecs.map((tool) => tools.get(tool.key) ?? tool),
+        starts: { ...kept.starts, tools: starts },
+    };
+}
+/** Where a project's set-aside edits wait for the builder's answer. */
+const asideKey = (key) => `${key}.aside`;
+/**
+ * Keeps edits the project's files changed under, masked as the tab keeps a workspace, until the
+ * builder brings them back or lets them go. A reload offers them again.
+ */
+export function setAside(key, edits) {
+    const record = {
+        v: STUDIO_WORKSPACE_VERSION,
+        workspace: keptWorkspace(edits),
+        revision: 0,
+    };
+    try {
+        session()?.setItem(asideKey(key), JSON.stringify(record));
+    }
+    catch {
+        // Quota or a blocked store: the offer on the page still holds the edits.
+    }
+}
+/** Forgets a project's set-aside edits: the builder brought them back or let them go. */
+export function dropAside(key) {
+    session()?.removeItem(asideKey(key));
+}
+/** The edits set aside for a project and not yet answered for, over the files as `opened`. */
+export function editsAside(key, opened) {
+    const store = session();
+    const kept = store ? parsed(store, asideKey(key)) : undefined;
+    if (kept === undefined)
+        return undefined;
+    if (isStoredWorkspace(kept))
+        return withFilesCredentials(kept.workspace, opened);
+    dropAside(key);
+    return undefined;
+}
+/** Where the files a project's kept edits stand on wait, as the studio read them. */
+const readingKey = (key) => `${key}.read`;
+/**
+ * Keeps the files as the studio read them, beside the edits that stand on that reading. It says
+ * which profiles the builder removed, so a merge after a reload leaves them removed.
+ */
+export function keepReading(key, print, read) {
+    const record = {
+        v: STUDIO_WORKSPACE_VERSION,
+        workspace: keptWorkspace(read),
+        revision: 0,
+        files: print,
+    };
+    try {
+        session()?.setItem(readingKey(key), JSON.stringify(record));
+    }
+    catch {
+        // Quota or a blocked store: a profile removed here comes back after a reload.
+    }
+}
+/** The files as the studio read them when they printed as `print`, if this tab kept that reading. */
+export function keptReading(key, print) {
+    const store = session();
+    const kept = store ? parsed(store, readingKey(key)) : undefined;
+    return isStoredWorkspace(kept) && kept.files === print ? kept.workspace : undefined;
+}
+/**
+ * The edits this tab kept for a project. `restored` with the reading of the files they stand on:
+ * when the files changed since, the studio merges the change into them as it does one the
+ * builder's editor writes while the page is open. `moved` when the edits stand on no reading, so
+ * nothing says what the files changed: the files open, and the edits are set aside and handed back
+ * to be offered. Kept edits that cannot be read back are removed.
+ */
+export function restoreProject(key, opened, files) {
+    const store = session();
+    if (!store)
+        return { kind: 'none' };
+    const kept = parsed(store, key);
+    if (kept === undefined)
+        return { kind: 'none' };
+    if (!isStoredWorkspace(kept)) {
+        store.removeItem(key);
+        return { kind: 'discarded' };
+    }
+    const workspace = withFilesCredentials(kept.workspace, opened);
+    if (kept.files === files) {
+        return {
+            kind: 'restored',
+            value: { workspace, revision: kept.revision, project: { key, files } },
+        };
+    }
+    // With nothing edited the files open as they are.
+    const isEdited = kept.files === undefined || editedSince(kept.workspace, kept.files);
+    if (isEdited && kept.files !== undefined) {
+        return {
+            kind: 'restored',
+            value: { workspace, revision: kept.revision, project: { key, files: kept.files } },
+        };
+    }
+    store.removeItem(key);
+    if (!isEdited)
+        return { kind: 'none' };
+    setAside(key, kept.workspace);
+    return { kind: 'moved', workspace };
+}

package/ui/lib/studio-run-open.d.ts

@@ -0,0 +1,15 @@
+import { type StudioRunPayload } from '../../mod.ts';
+import { type ProjectSession } from './studio-project.ts';
+/** What a run tab opens on: the compiled agent, and the project it belongs to if it has one. */
+export type StudioRunOpened = {
+    payload: StudioRunPayload;
+    project: ProjectSession | null;
+};
+/**
+ * What the run tab at `url` opens on, or `null` when its agent is gone. The compiled agent is kept
+ * in this browser's storage under the id in the address, so this runs in the browser. `project`
+ * says whether this host can have a project open; without it, the address's project is ignored.
+ */
+export declare function openStudioRun(url: string, options: {
+    project: boolean;
+}): StudioRunOpened | null;

package/ui/lib/studio-run-open.js

@@ -0,0 +1,16 @@
+import { clearStaleStudioRuns, loadStudioRunPayload, readStudioRunIdFromUrl, } from "../../mod.js";
+import { projectSession } from "./studio-project.js";
+/**
+ * What the run tab at `url` opens on, or `null` when its agent is gone. The compiled agent is kept
+ * in this browser's storage under the id in the address, so this runs in the browser. `project`
+ * says whether this host can have a project open; without it, the address's project is ignored.
+ */
+export function openStudioRun(url, options) {
+    clearStaleStudioRuns();
+    const runId = readStudioRunIdFromUrl(url);
+    const payload = runId ? loadStudioRunPayload(runId) : null;
+    if (!payload)
+        return null;
+    const name = options.project ? new URL(url).searchParams.get('project') : null;
+    return { payload, project: name ? projectSession(name) : null };
+}

package/ui/lib/studio-session.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Where the studio keeps itself: this tab's sessionStorage, under the keys and in the record
+ * shape the workspace store, its restore, and the kept conversations share.
+ */
+import type { STUDIO_WORKSPACE_VERSION, StudioWorkspace } from '../../mod.ts';
+export declare const WORKSPACE_KEY = "theorem.studio.v2";
+/** A project's workspace is kept under its own name, apart from the website's and other projects'. */
+export declare const projectKey: (name: string) => string;
+/** One conversation per agent, under this and the agent's key. */
+export declare const CHAT_PREFIX = "theorem.studio.v2.chat:";
+/** A kept workspace, read back with its revision. */
+export interface RestoredStudio {
+    workspace: StudioWorkspace;
+    revision: number;
+    /**
+     * A project's workspace: the key it is kept under, and the print of the files its starts stand
+     * on. A reload brings the edits back while the files still print the same.
+     */
+    project?: {
+        key: string;
+        files: string;
+    };
+}
+/** What sessionStorage holds. */
+export interface StoredWorkspace {
+    v: typeof STUDIO_WORKSPACE_VERSION;
+    workspace: StudioWorkspace;
+    revision: number;
+    /** For a project's workspace: the print of the files its starts stand on. */
+    files?: string;
+}
+/** This tab's sessionStorage, or null where there is none or it is blocked. */
+export declare function session(): Storage | null;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/ui/lib/studio-session.js

@@ -0,0 +1,17 @@
+export const WORKSPACE_KEY = 'theorem.studio.v2';
+/** A project's workspace is kept under its own name, apart from the website's and other projects'. */
+export const projectKey = (name) => `${WORKSPACE_KEY}.project:${name}`;
+/** One conversation per agent, under this and the agent's key. */
+export const CHAT_PREFIX = 'theorem.studio.v2.chat:';
+/** This tab's sessionStorage, or null where there is none or it is blocked. */
+export function session() {
+    try {
+        return typeof sessionStorage === 'undefined' ? null : sessionStorage;
+    }
+    catch {
+        return null;
+    }
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/ui/lib/studio-settings.d.ts

@@ -0,0 +1,15 @@
+export declare const SETTINGS_SECTIONS: readonly ["files", "confirmations", "keys", "people", "project", "about"];
+export type SettingsSection = (typeof SETTINGS_SECTIONS)[number];
+export interface SettingsDoor {
+    /** True once a screen that shows Settings is on the page: the door opens nothing before then. */
+    ready: boolean;
+    open: boolean;
+    section: SettingsSection;
+}
+/** Opens Settings, on `section` when one is named and where it was left otherwise. */
+export declare function openSettings(section?: SettingsSection): void;
+export declare function closeSettings(): void;
+export declare function showSettingsSection(section: SettingsSection): void;
+/** Says a screen that shows Settings is on the page; the answer says it left. */
+export declare function settingsScreen(): () => void;
+export declare function useSettingsDoor(): SettingsDoor;

package/ui/lib/studio-settings.js

@@ -0,0 +1,48 @@
+/**
+ * Whether Settings is open, and on which section. The door to it sits in the shell's rail, away
+ * from the screen that shows it, so both read the one place here.
+ */
+import { useSyncExternalStore } from 'react';
+export const SETTINGS_SECTIONS = [
+    'files',
+    'confirmations',
+    'keys',
+    'people',
+    'project',
+    'about',
+];
+let door = { ready: false, open: false, section: 'files' };
+const listeners = new Set();
+function move(next) {
+    door = { ...door, ...next };
+    for (const listener of listeners)
+        listener();
+}
+/** Opens Settings, on `section` when one is named and where it was left otherwise. */
+export function openSettings(section) {
+    if (door.ready)
+        move({ open: true, ...(section ? { section } : {}) });
+}
+export function closeSettings() {
+    move({ open: false });
+}
+export function showSettingsSection(section) {
+    move({ section });
+}
+/** Says a screen that shows Settings is on the page; the answer says it left. */
+export function settingsScreen() {
+    move({ ready: true });
+    return () => {
+        move({ ready: false, open: false });
+    };
+}
+const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+};
+const read = () => door;
+export function useSettingsDoor() {
+    return useSyncExternalStore(subscribe, read, read);
+}