@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/project.d.ts

@@ -0,0 +1,22 @@
+/**
+ * One load of the project: its setup module run, and its profiles and tools
+ * served on a port only the studio's server calls. `serve.ts` starts this, and
+ * starts it again after a Save, because a module that is loaded is not read
+ * from disk a second time.
+ *
+ *   deno run -A studio/server/project.ts <setup-module> --port <port> --page <origins>
+ *
+ * It reads a `ProjectLoad` from its input: the key its chats are sealed with, and the builder's
+ * unsaved edits when there are some. Edits are laid over what the setup registered, before it
+ * serves: the load that answers as the project would after a Save.
+ *
+ * @module
+ */
+import { type ProjectEdits } from './edits.ts';
+/** What `serve.ts` hands each load on its input. The key never touches disk. */
+export type ProjectLoad = {
+    conversationKey: string;
+    edits?: ProjectEdits;
+};
+/** The line this prints once it listens. `serve.ts` waits for it. */
+export declare const PROJECT_READY = "theorem-studio-project-ready";

package/server/project.js

@@ -0,0 +1,56 @@
+/**
+ * One load of the project: its setup module run, and its profiles and tools
+ * served on a port only the studio's server calls. `serve.ts` starts this, and
+ * starts it again after a Save, because a module that is loaded is not read
+ * from disk a second time.
+ *
+ *   deno run -A studio/server/project.ts <setup-module> --port <port> --page <origins>
+ *
+ * It reads a `ProjectLoad` from its input: the key its chats are sealed with, and the builder's
+ * unsaved edits when there are some. Edits are laid over what the setup registered, before it
+ * serves: the load that answers as the project would after a Save.
+ *
+ * @module
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { basename, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { defaultKernelScope } from '@theoremjs/agents';
+import { editedImages, editedQuestions, registerEdits } from "./edits.js";
+import { createStudioHandler } from "./handler.js";
+/** The line this prints once it listens. `serve.ts` waits for it. */
+export const PROJECT_READY = 'theorem-studio-project-ready';
+if (import.meta.main) {
+    const [setupPath = '', ...flags] = Deno.args;
+    const flag = (name) => flags[flags.indexOf(`--${name}`) + 1] ?? '';
+    const port = Number(flag('port'));
+    const setup = await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(setupPath)).href));
+    await setup.default?.();
+    const load = await new Response(Deno.stdin.readable).json();
+    let { questions, images } = setup;
+    if (load.edits) {
+        await registerEdits(defaultKernelScope, load.edits);
+        questions = editedQuestions(load.edits, questions);
+        images = editedImages(load.edits, images);
+    }
+    const handler = createStudioHandler({
+        project: basename(Deno.cwd()),
+        pageOrigins: flag('page').split(','),
+        listenHost: `127.0.0.1:${port}`,
+        ...(setup.host ? { host: setup.host } : {}),
+        ...(setup.people !== undefined ? { people: setup.people } : {}),
+        ...(setup.provider ? { provider: setup.provider } : {}),
+        ...(questions ? { questions } : {}),
+        ...(images ? { images } : {}),
+        upgrade: (request) => Deno.upgradeWebSocket(request),
+        conversationKey: load.conversationKey,
+    });
+    Deno.serve({ hostname: '127.0.0.1', port, onListen: () => console.log(PROJECT_READY) }, handler);
+}

package/server/run-traces.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A run's trace, sent to the page behind the run's own events, as the playground sends a draft's.
+ * A run made in the studio is a test, so its records go to the page and stay out of the store the
+ * profile writes to. A profile that records nothing sends nothing, and what the profile keeps
+ * private stays out, as in any trace.
+ *
+ * @module
+ */
+import { type Profile } from '@theoremjs/agents';
+/** Where a profile served by the studio writes its records. */
+export declare const STUDIO_RUN_TRACES = "theorem-studio-run";
+/** The profile as the studio serves it: one that records writes to the run it is in. */
+export declare function tracedToPage<P extends Profile>(profile: P): P;
+/** Serves a profile with each run's records sent behind its events. */
+export declare function withRunTraces(serve: (request: Request) => Promise<Response>): (request: Request) => Promise<Response>;
+/**
+ * Serves a decision or embedding profile with each call's records in its reply, where the page
+ * reads them. Each answers in one JSON body, so its records ride in it instead of behind a stream.
+ */
+export declare function withJsonTraces(serve: (request: Request) => Promise<Response>): (request: Request) => Promise<Response>;

package/server/run-traces.js

@@ -0,0 +1,96 @@
+/**
+ * A run's trace, sent to the page behind the run's own events, as the playground sends a draft's.
+ * A run made in the studio is a test, so its records go to the page and stay out of the store the
+ * profile writes to. A profile that records nothing sends nothing, and what the profile keeps
+ * private stays out, as in any trace.
+ *
+ * @module
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { registerTraceDestination, resolveObservabilityPolicy, } from '@theoremjs/agents';
+import { eachLine, NDJSON } from "../stream-lines.js";
+/** Where a profile served by the studio writes its records. */
+export const STUDIO_RUN_TRACES = 'theorem-studio-run';
+/** The records of the run in progress. The kernel writes a record inside the run that made it. */
+const runs = new AsyncLocalStorage();
+/** The profile as the studio serves it: one that records writes to the run it is in. */
+export function tracedToPage(profile) {
+    if (!resolveObservabilityPolicy(profile.observability).record)
+        return profile;
+    registerTraceDestination(STUDIO_RUN_TRACES, {
+        write: (record) => {
+            runs.getStore()?.push(record);
+            return Promise.resolve();
+        },
+    });
+    return { ...profile, observability: { ...profile.observability, writeTo: STUDIO_RUN_TRACES } };
+}
+/** Whether a line of the stream is the failure that ends it. */
+function isFailure(line) {
+    try {
+        return JSON.parse(line).type === 'error';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Passes a run's lines through and adds its records as the stream ends. The kernel writes a run's
+ * records before the run returns or throws, and a page stops reading at a failure, so the records
+ * go ahead of the failure that ends the stream.
+ */
+function recordsBeforeEnd(records) {
+    let failure;
+    /** A failure is held until the next line shows it did not end the stream. */
+    const release = (send) => {
+        if (failure !== undefined)
+            send(failure);
+        failure = undefined;
+    };
+    return eachLine((line, send) => {
+        release(send);
+        if (isFailure(line))
+            failure = line;
+        else
+            send(line);
+    }, (send) => {
+        for (const record of records) {
+            const line = { type: 'trace', record };
+            send(JSON.stringify(line));
+        }
+        release(send);
+    });
+}
+/** Serves each request as its own run, and hands the reply and the run's records to `reply`. */
+function recorded(serve, reply) {
+    return async (request) => {
+        const records = [];
+        return reply(await runs.run(records, () => serve(request)), records);
+    };
+}
+/** Serves a profile with each run's records sent behind its events. */
+export function withRunTraces(serve) {
+    return recorded(serve, (response, records) => {
+        if (!response.body || !response.headers.get('content-type')?.startsWith(NDJSON))
+            return response;
+        return new Response(response.body.pipeThrough(recordsBeforeEnd(records)), {
+            status: response.status,
+            headers: response.headers,
+        });
+    });
+}
+/**
+ * Serves a decision or embedding profile with each call's records in its reply, where the page
+ * reads them. Each answers in one JSON body, so its records ride in it instead of behind a stream.
+ */
+export function withJsonTraces(serve) {
+    return recorded(serve, async (response, records) => {
+        // A failed call is traced too, so its failure's body carries the records the same way.
+        if (records.length === 0 || !response.headers.get('content-type')?.includes('json'))
+            return response;
+        const reply = await response.json();
+        const headers = new Headers(response.headers);
+        headers.delete('content-length');
+        return Response.json({ ...reply, traces: records }, { status: response.status, headers });
+    });
+}

package/server/save-new.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What Save writes for a profile or tool the builder added in the studio: a
+ * new file beside the project's others, and the lines in the setup that import
+ * and register it. A scope checks a profile against the tools registered
+ * before it, and an agent tool against the profile it runs, so each line goes
+ * where that order holds.
+ *
+ * @module
+ */
+import type { CompiledStudio } from '../compile.ts';
+import type { StudioProvider } from '../providers.ts';
+import type { ToolRegistration } from '../registrations.ts';
+import { type ProjectSource } from './project-source.ts';
+import { type SavePlan } from './save-plan.ts';
+/** A profile, tool, or provider the studio added, as it compiles. `agents` is every agent of the workspace, in the order a scope registers them. */
+export interface NewSubjects {
+    agents: readonly CompiledStudio[];
+    /** The ids of the agents that are new. */
+    profiles: readonly string[];
+    /** The tools that are new, each once. */
+    tools: readonly ToolRegistration[];
+    /** The providers that are new. */
+    providers: readonly StudioProvider[];
+}
+/**
+ * Plans the files and setup lines for what the studio added. `exists` says whether a path is
+ * taken. A change it cannot write says why, and nothing is planned for it.
+ */
+export declare function planNew(project: ProjectSource, added: NewSubjects, exists: (path: string) => boolean): SavePlan;