@theoremjs/studio 0.0.0-stage → 0.3.2

package/ui/lib/project-traces.d.ts

@@ -0,0 +1,17 @@
+import type { TraceFeed } from '@theoremjs/react/client';
+import type { StudioRunPayload } from '../../mod.ts';
+import { type StudioActingAs } from '../../people.ts';
+/** Whether the agent records traces, so the page can offer them: the rule every view reads. */
+export declare function recordsTraces(payload: StudioRunPayload | null): boolean;
+/**
+ * A transport to one of a project's profiles whose runs' traces land on `traces`, where the
+ * trace panel reads them: the same panel a draft's run fills in the playground. Each run carries
+ * who it acts as, so the project's tools act for that person.
+ */
+export declare function tracedTransport<T extends object>(make: (options: {
+    endpoint: string;
+    fetch: typeof fetch;
+    headers: Record<string, string>;
+}) => T, endpoint: string, traces: TraceFeed, actingAs: StudioActingAs | undefined): T & {
+    traces: TraceFeed;
+};

package/ui/lib/project-traces.js

@@ -0,0 +1,54 @@
+import { resolveObservabilityPolicy } from '@theoremjs/agents';
+import { actingAsHeaders } from "../../people.js";
+import { eachLine, NDJSON } from "../../stream-lines.js";
+import { studioTraceLine } from "../../transport.js";
+/** Whether the agent records traces, so the page can offer them: the rule every view reads. */
+export function recordsTraces(payload) {
+    return payload !== null && resolveObservabilityPolicy(payload.profile.observability).record;
+}
+/** The trace record a line of a run's stream carries, or nothing when it is one of the run's events. */
+function traceOf(line) {
+    if (!line.includes('"trace"'))
+        return undefined;
+    try {
+        const read = studioTraceLine.safeParse(JSON.parse(line));
+        return read.success ? read.data.record : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Takes the trace lines off a run's stream and puts their records on the feed. */
+function withoutTraces(traces) {
+    return eachLine((line, send) => {
+        const record = traceOf(line);
+        if (record)
+            traces.push(record);
+        else
+            send(line);
+    });
+}
+/** `fetch` for a project's runs: the studio's local server sends each run's trace behind its events. */
+function tracedFetch(traces) {
+    return async (input, init) => {
+        const response = await fetch(input, init);
+        if (!response.body || !response.headers.get('content-type')?.startsWith(NDJSON))
+            return response;
+        return new Response(response.body.pipeThrough(withoutTraces(traces)), {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    };
+}
+/**
+ * A transport to one of a project's profiles whose runs' traces land on `traces`, where the
+ * trace panel reads them: the same panel a draft's run fills in the playground. Each run carries
+ * who it acts as, so the project's tools act for that person.
+ */
+export function tracedTransport(make, endpoint, traces, actingAs) {
+    return {
+        ...make({ endpoint, fetch: tracedFetch(traces), headers: actingAsHeaders(actingAs) }),
+        traces,
+    };
+}

package/ui/lib/read-map.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The map the loader draws while the studio command reads a project: the setup file on the left,
+ * the folders its imports reach as branches, and the agents and tools found in them on the right.
+ * Laid out from the steps the command has said so far, to fit a number of rows.
+ */
+import type { ReadStep } from '../../read-steps.ts';
+export type ReadNodeKind = 'entry' | 'folder' | 'profile' | 'tool' | 'more';
+export interface ReadNode {
+    id: string;
+    kind: ReadNodeKind;
+    label: string;
+    /** The column, the setup file's being 0. */
+    col: number;
+    /** The row, which may fall between two when the node sits beside several. */
+    row: number;
+    parent?: string;
+    /** The step that first reaches the node: it is drawn once that step is. */
+    first: number;
+    /** The steps that read a file of the node's own, in order. Each is a dot on the line into it. */
+    own: number[];
+    /** The type an agent or a tool was written with. */
+    type?: string;
+}
+export interface ReadMap {
+    nodes: ReadNode[];
+    cols: number;
+    rows: number;
+}
+/** The map of `steps`, in at most `rows` rows when the project allows it. */
+export declare function readMap(steps: readonly ReadStep[], rows: number): ReadMap;

package/ui/lib/read-map.js

@@ -0,0 +1,173 @@
+/** How deep folders are told apart before the rows run out. */
+const DEPTH = 3;
+function folder(path, parent) {
+    return { path, parent, folders: new Map(), own: [], found: [], folded: 0 };
+}
+function dirOf(file) {
+    const parts = file.split(/[\\/]/);
+    parts.pop();
+    return parts;
+}
+/** The folders the files are in, no deeper than `depth`, each holding the steps that read its files. */
+function foldersOf(steps, depth) {
+    const root = folder('');
+    const at = (file) => {
+        let here = root;
+        for (const part of dirOf(file).slice(0, depth)) {
+            let next = here.folders.get(part);
+            if (!next) {
+                next = folder(here.path ? `${here.path}/${part}` : part, here);
+                here.folders.set(part, next);
+            }
+            here = next;
+        }
+        return here;
+    };
+    steps.forEach((step, index) => {
+        if ('file' in step && !('found' in step))
+            at(step.file).own.push(index);
+        else if ('found' in step)
+            at(step.file).found.push({
+                kind: step.found,
+                name: step.name,
+                step: index,
+                ...(step.type === undefined ? {} : { type: step.type }),
+            });
+    });
+    return root;
+}
+/** A folder that only holds one other is drawn as that one, named by the whole path. */
+function shortened(here) {
+    for (const [name, child] of here.folders)
+        here.folders.set(name, shortened(child));
+    const [only] = here.folders.values();
+    if (here.parent && here.folders.size === 1 && only && !here.own.length && !here.found.length) {
+        only.parent = here.parent;
+        return only;
+    }
+    for (const child of here.folders.values())
+        child.parent = here;
+    return here;
+}
+function ends(here) {
+    if (!here.folders.size)
+        return [here];
+    return [...here.folders.values()].flatMap(ends);
+}
+function firstOf(here) {
+    const firsts = [...here.own.slice(0, 1), ...here.found.map((found) => found.step)];
+    for (const child of here.folders.values())
+        firsts.push(firstOf(child));
+    return Math.min(...firsts);
+}
+/** Keeps the first folders that fit under the top and folds the rest into the last one kept. */
+function folded(root, rows) {
+    const kept = [...root.folders.entries()];
+    if (kept.length <= rows)
+        return;
+    const [, last] = kept[rows - 1] ?? [];
+    if (!last)
+        return;
+    for (const [name, extra] of kept.slice(rows)) {
+        root.folders.delete(name);
+        last.folded += 1;
+        const take = (from) => {
+            last.own.push(...from.own);
+            last.found.push(...from.found);
+            for (const child of from.folders.values())
+                take(child);
+        };
+        take(extra);
+    }
+    last.own.sort((a, b) => a - b);
+}
+/** The folders as deep as the rows allow. */
+function fitted(steps, rows) {
+    for (let depth = DEPTH; depth > 1; depth -= 1) {
+        const root = shortened(foldersOf(steps, depth));
+        if (ends(root).length <= rows)
+            return root;
+    }
+    const root = shortened(foldersOf(steps, 1));
+    folded(root, rows);
+    return root;
+}
+function depthOf(here) {
+    return Math.max(0, ...[...here.folders.values()].map((child) => 1 + depthOf(child)));
+}
+/** The map of `steps`, in at most `rows` rows when the project allows it. */
+export function readMap(steps, rows) {
+    const room = Math.max(1, rows);
+    const root = fitted(steps, room);
+    const all = [];
+    const collect = (here) => {
+        all.push(here);
+        for (const child of here.folders.values())
+            collect(child);
+    };
+    collect(root);
+    // Each folder that ends a branch takes a row, with or without anything found in it.
+    const holding = all.filter((each) => each.found.length);
+    const bare = ends(root).filter((each) => !each.found.length && each !== root).length;
+    const each = Math.max(1, Math.floor((room - bare) / Math.max(1, holding.length)));
+    const foundCol = depthOf(root) + 1;
+    const nodes = [];
+    let row = 0;
+    const place = (here, col, parent) => {
+        const id = here === root ? 'entry' : `folder:${here.path}`;
+        const from = row;
+        for (const child of here.folders.values())
+            place(child, col + 1, id);
+        const shown = here.found.length > each ? here.found.slice(0, each - 1) : here.found;
+        for (const found of shown) {
+            nodes.push({
+                id: `${found.kind}:${found.name}`,
+                kind: found.kind,
+                label: found.name,
+                col: foundCol,
+                row,
+                parent: id,
+                first: found.step,
+                own: [],
+                ...(found.type === undefined ? {} : { type: found.type }),
+            });
+            row += 1;
+        }
+        const rest = here.found.slice(shown.length);
+        if (rest.length) {
+            const label = `${String(rest.length)} ${shown.length ? 'more' : 'agents and tools'}`;
+            nodes.push({
+                id: `more:${here.path}`,
+                kind: 'more',
+                label,
+                col: foundCol,
+                row,
+                parent: id,
+                first: rest[0]?.step ?? 0,
+                own: [],
+            });
+            row += 1;
+        }
+        if (row === from)
+            row += 1;
+        const span = [from, row - 1];
+        const name = here.path.slice(here.parent && here.parent !== root ? here.parent.path.length + 1 : 0);
+        nodes.push({
+            id,
+            kind: here === root ? 'entry' : 'folder',
+            label: here.folded ? `${name} and ${String(here.folded)} more` : name,
+            col,
+            row: (span[0] + span[1]) / 2,
+            ...(parent === undefined ? {} : { parent }),
+            first: here === root ? 0 : firstOf(here),
+            own: here.own,
+        });
+        return span;
+    };
+    place(root, 0);
+    const entry = steps.find((step) => 'file' in step && !('found' in step));
+    const top = nodes.find((node) => node.id === 'entry');
+    if (top)
+        top.label = entry?.file.split(/[\\/]/).pop() ?? '';
+    return { nodes, cols: foundCol + 1, rows: row };
+}

package/ui/lib/read-progress.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What the studio command has said of its read of the project so far, kept for the loader to draw.
+ * The loader draws on its own clock, so it looks here each frame instead of being told.
+ */
+import type { ReadStep } from '../../read-steps.ts';
+export interface Reading {
+    /** Every step said so far, in order. The same list each time, longer. */
+    steps(): readonly ReadStep[];
+    /** Whether the project has arrived, so no step follows. */
+    done(): boolean;
+    say(step: ReadStep): void;
+    finish(): void;
+}
+export declare function createReading(): Reading;

package/ui/lib/read-progress.js

@@ -0,0 +1,12 @@
+export function createReading() {
+    const steps = [];
+    let done = false;
+    return {
+        steps: () => steps,
+        done: () => done,
+        say: (step) => void steps.push(step),
+        finish: () => {
+            done = true;
+        },
+    };
+}

package/ui/lib/refusal-lines.d.ts

@@ -0,0 +1,3 @@
+import type { SaveRefusal } from '../../server/save-wire.ts';
+/** A refusal's detail as lines the builder reads: what did not load as edited, or what the project said. */
+export declare function refusalLines(refusal: SaveRefusal): string[];

package/ui/lib/refusal-lines.js

@@ -0,0 +1,8 @@
+/** A refusal's detail as lines the builder reads: what did not load as edited, or what the project said. */
+export function refusalLines(refusal) {
+    if (refusal.detail.length === 0)
+        return [];
+    if (refusal.reason === 'differs')
+        return [`Not loading as edited: ${refusal.detail.join(', ')}.`];
+    return refusal.detail.flatMap((each) => each.split('\n')).filter((line) => line.trim() !== '');
+}

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

@@ -0,0 +1,5 @@
+/**
+ * `transport`, calling `note` before each request it sends. `describe` only reads the profile,
+ * so it doesn't count.
+ */
+export declare function noting<T extends object>(transport: T, note: () => void): T;

package/ui/lib/studio-activity.js

@@ -0,0 +1,17 @@
+/**
+ * `transport`, calling `note` before each request it sends. `describe` only reads the profile,
+ * so it doesn't count.
+ */
+export function noting(transport, note) {
+    return new Proxy(transport, {
+        get(target, key) {
+            const value = Reflect.get(target, key);
+            if (typeof value !== 'function' || key === 'describe')
+                return value;
+            return (...args) => {
+                note();
+                return Reflect.apply(value, target, args);
+            };
+        },
+    });
+}

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

@@ -0,0 +1,27 @@
+import type { TraceFeed } from '@theoremjs/react/client';
+import type { StudioBrowserRuntime } from '../../browser.ts';
+import type { StudioRunPayload } from '../../mod.ts';
+/** What the builder preview and the standalone run tab hand a one-call console. */
+export interface StudioConsoleProps {
+    payload: StudioRunPayload;
+    className?: string;
+    runtime?: StudioBrowserRuntime | null;
+    /** The conversation's trace feed, kept across recompiles. */
+    traces?: TraceFeed;
+    /** Called before each call; stable, or the transport is rebuilt each render. */
+    onActivity?: () => void;
+    /** The page's own trace control. */
+    trace?: boolean;
+    /** The page is already the shell. The console sits in it. */
+    flush?: boolean;
+    /** The request on the left and the result on the right. */
+    columns?: boolean;
+}
+/** How a console is laid out, whatever its transport. */
+export type ConsoleViewProps = Pick<StudioConsoleProps, 'payload' | 'className' | 'trace' | 'flush' | 'columns'>;
+/** A console's transport: in the browser's runtime when there is one, else through the studio's server. */
+export declare function useStudioTransport<T extends object>({ payload, runtime, traces, onActivity }: StudioConsoleProps, onServer: (payload: StudioRunPayload, options: {
+    traces?: TraceFeed;
+}) => T, inBrowser: (payload: StudioRunPayload, runtime: StudioBrowserRuntime, options: {
+    traces?: TraceFeed;
+}) => T): T;

package/ui/lib/studio-console.js

@@ -0,0 +1,9 @@
+import { useMemo } from 'react';
+import { noting } from "./studio-activity.js";
+/** A console's transport: in the browser's runtime when there is one, else through the studio's server. */
+export function useStudioTransport({ payload, runtime = null, traces, onActivity }, onServer, inBrowser) {
+    return useMemo(() => {
+        const made = runtime ? inBrowser(payload, runtime, { traces }) : onServer(payload, { traces });
+        return onActivity ? noting(made, onActivity) : made;
+    }, [payload, runtime, traces, onActivity, onServer, inBrowser]);
+}

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

@@ -0,0 +1,20 @@
+/** Who sealed a kept ref, so it is offered only to a run that can open it. */
+export type ChatSealer = 'page' | 'demo';
+/**
+ * The key this tab's page runs seal their conversations with. It is kept in the tab beside the
+ * refs it opens, so both go when the tab does. A new key forgets the refs the last one sealed.
+ */
+export declare function pageConversationKey(): string;
+/**
+ * Keeps an agent's conversation ref. The ref holds the whole conversation, its media too: one too
+ * big for the tab's storage is not kept, and the agent's last kept ref is forgotten with it.
+ * Never throws.
+ */
+export declare function saveConversation(agentKey: string, sealer: ChatSealer, ref: string): void;
+/**
+ * An agent's kept ref, when `sealer` sealed it. Anything else kept under the agent (a
+ * conversation kept before refs) is forgotten, so it holds no room.
+ */
+export declare function restoreConversation(agentKey: string, sealer: ChatSealer): string | undefined;
+/** Forgets one agent's conversation, or every agent's. */
+export declare function clearConversation(agentKey?: string): void;

package/ui/lib/studio-conversation.js

@@ -0,0 +1,130 @@
+/**
+ * Each agent's preview conversation, kept in this tab's sessionStorage beside the workspace so a
+ * reload resumes it. What is kept is the conversation's ref: the conversation sealed with a key,
+ * which opens only where that key is. A run in the page seals with the tab's own key; the hosted
+ * demo seals on its server.
+ */
+import { newConversationKey } from "../../conversation-key.js";
+import { CHAT_PREFIX, isRecord, session } from "./studio-session.js";
+/** The tab's key for the conversations its page runs seal. */
+const PAGE_KEY = 'theorem.studio.chat-key';
+/** The key, while the tab keeps none: it lasts as long as the page. */
+let pageKeyHeld;
+/**
+ * The key this tab's page runs seal their conversations with. It is kept in the tab beside the
+ * refs it opens, so both go when the tab does. A new key forgets the refs the last one sealed.
+ */
+export function pageConversationKey() {
+    const store = session();
+    try {
+        const kept = store?.getItem(PAGE_KEY);
+        if (kept)
+            return kept;
+    }
+    catch {
+        // Storage refused the read: the page holds its own key.
+    }
+    if (pageKeyHeld)
+        return pageKeyHeld;
+    const key = newConversationKey();
+    pageKeyHeld = key;
+    forgetSealedBy('page');
+    try {
+        store?.setItem(PAGE_KEY, key);
+    }
+    catch {
+        // Over quota or blocked: the key lasts as long as the page, and so do its chats.
+    }
+    return key;
+}
+/** A kept ref, when `raw` is one. */
+function keptRef(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (!isRecord(value) || typeof value.ref !== 'string')
+            return undefined;
+        const { sealer } = value;
+        return sealer === 'page' || sealer === 'demo' ? { sealer, ref: value.ref } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Forgets every ref `sealer` sealed: none of them opens any more. */
+function forgetSealedBy(sealer) {
+    try {
+        const store = session();
+        if (!store)
+            return;
+        for (const key of Object.keys(store)) {
+            if (!key.startsWith(CHAT_PREFIX))
+                continue;
+            const raw = store.getItem(key);
+            if (raw && keptRef(raw)?.sealer === sealer)
+                store.removeItem(key);
+        }
+    }
+    catch {
+        // Nothing to forget.
+    }
+}
+/**
+ * Keeps an agent's conversation ref. The ref holds the whole conversation, its media too: one too
+ * big for the tab's storage is not kept, and the agent's last kept ref is forgotten with it.
+ * Never throws.
+ */
+export function saveConversation(agentKey, sealer, ref) {
+    const store = session();
+    if (!store)
+        return;
+    const key = `${CHAT_PREFIX}${agentKey}`;
+    try {
+        store.setItem(key, JSON.stringify({ sealer, ref }));
+        return;
+    }
+    catch {
+        // Over quota: an older ref is a conversation that already moved on, so none is kept.
+    }
+    try {
+        store.removeItem(key);
+    }
+    catch {
+        // Nothing more to do.
+    }
+}
+/**
+ * An agent's kept ref, when `sealer` sealed it. Anything else kept under the agent (a
+ * conversation kept before refs) is forgotten, so it holds no room.
+ */
+export function restoreConversation(agentKey, sealer) {
+    try {
+        const store = session();
+        const key = `${CHAT_PREFIX}${agentKey}`;
+        const raw = store?.getItem(key);
+        if (!raw)
+            return undefined;
+        const kept = keptRef(raw);
+        if (!kept)
+            store?.removeItem(key);
+        return kept?.sealer === sealer ? kept.ref : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Forgets one agent's conversation, or every agent's. */
+export function clearConversation(agentKey) {
+    try {
+        const store = session();
+        if (!store)
+            return;
+        for (const key of Object.keys(store)) {
+            if (agentKey === undefined ? key.startsWith(CHAT_PREFIX) : key === `${CHAT_PREFIX}${agentKey}`) {
+                store.removeItem(key);
+            }
+        }
+    }
+    catch {
+        // Nothing to clear.
+    }
+}

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

@@ -0,0 +1,31 @@
+/** The ready agents "Load an example" offers. */
+export declare const STUDIO_EXAMPLES: {
+    readonly concierge: {
+        readonly label: "Travel concierge";
+        readonly description: "Text agent with weather, places, currency, and trip tools.";
+    };
+    readonly 'live-concierge': {
+        readonly label: "Live concierge";
+        readonly description: "The concierge as a voice call, with the same tools.";
+    };
+    readonly architect: {
+        readonly label: "Code architect";
+        readonly description: "Reads repos and docs. Brings a Narrator it calls for audio.";
+    };
+    readonly narrator: {
+        readonly label: "Narrator";
+        readonly description: "Reads a script aloud.";
+    };
+    readonly console: {
+        readonly label: "Tool console";
+        readonly description: "No model. Run its tools by hand.";
+    };
+    readonly decision: {
+        readonly label: "Jev decision";
+        readonly description: "Asks Jev about a pantry photo: finds things in it and answers questions.";
+    };
+    readonly 'gemini-embedding-2': {
+        readonly label: "Gemini Embeddings 2";
+        readonly description: "Multimodal embedding preview with Gemini Embeddings 2.";
+    };
+};

package/ui/lib/studio-examples.js

@@ -0,0 +1,25 @@
+/** The ready agents "Load an example" offers. */
+export const STUDIO_EXAMPLES = {
+    concierge: {
+        label: 'Travel concierge',
+        description: 'Text agent with weather, places, currency, and trip tools.',
+    },
+    'live-concierge': {
+        label: 'Live concierge',
+        description: 'The concierge as a voice call, with the same tools.',
+    },
+    architect: {
+        label: 'Code architect',
+        description: 'Reads repos and docs. Brings a Narrator it calls for audio.',
+    },
+    narrator: { label: 'Narrator', description: 'Reads a script aloud.' },
+    console: { label: 'Tool console', description: 'No model. Run its tools by hand.' },
+    decision: {
+        label: 'Jev decision',
+        description: 'Asks Jev about a pantry photo: finds things in it and answers questions.',
+    },
+    'gemini-embedding-2': {
+        label: 'Gemini Embeddings 2',
+        description: 'Multimodal embedding preview with Gemini Embeddings 2.',
+    },
+};

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

@@ -0,0 +1,6 @@
+import type { TheoremLabels } from '@theoremjs/react/ui';
+/**
+ * The studio's own lines: a credential typed at a sign-in gate serves one call and is never
+ * saved, and a message's delivery status reads in lower case like the rest.
+ */
+export declare const STUDIO_LABELS: TheoremLabels;

package/ui/lib/studio-labels.js

@@ -0,0 +1,13 @@
+/**
+ * The studio's own lines: a credential typed at a sign-in gate serves one call and is never
+ * saved, and a message's delivery status reads in lower case like the rest.
+ */
+export const STUDIO_LABELS = {
+    en: {
+        '@theorem.gate.auth.secret_note': "Used for this call only. theorem doesn't store it.",
+        '@astryx.chat.status.sending': 'sending',
+        '@astryx.chat.status.sent': 'sent',
+        '@astryx.chat.status.delivered': 'delivered',
+        '@astryx.chat.status.read': 'read',
+    },
+};

package/ui/lib/studio-map-kept.d.ts

@@ -0,0 +1,17 @@
+/**
+ * How someone left the map, kept in this tab's sessionStorage beside the workspace, a project's
+ * under its own name: where they dragged its nodes, with and without detail, whether it shows
+ * detail, and the node whose family alone it shows.
+ */
+import type { MapPlace } from '../../mod.ts';
+export type MapPlaces = Readonly<Record<string, MapPlace>>;
+export interface KeptMap {
+    tokens: MapPlaces;
+    detail: MapPlaces;
+    expanded: boolean;
+    family?: string;
+}
+/** What was kept; the map as it first opens when nothing was or it cannot be read. */
+export declare function readKeptMap(project: string | undefined): KeptMap;
+/** Keeps `kept`, or forgets it when it is the map as it first opens. Storage that is full or blocked keeps nothing. */
+export declare function writeKeptMap(project: string | undefined, kept: KeptMap): void;