@theoremjs/studio 0.0.0-stage → 0.3.2

package/people.js

@@ -0,0 +1,110 @@
+/**
+ * Who a studio run acts as. The application names the places its data lives in and the people a
+ * run may act as there; the studio shows who and where, and carries the builder's pick to the
+ * application with every run. The studio knows nothing of sign-in, accounts or clean-up: making a
+ * fresh person, finding existing ones, and whether a place is safe to use are the application's.
+ *
+ * A run with no pick acts as no one.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** The header each run carries the builder's pick in. No header is no one. */
+export const ACTING_AS_HEADER = 'x-theorem-studio-acting-as';
+/** The session a run acting as no one is in. */
+export const NO_ONE_SESSION = 'theorem-studio-local';
+const nameSchema = z.object({ id: z.string().min(1), label: z.string().min(1) });
+const actingAsSchema = z.object({ place: z.string().min(1), person: nameSchema });
+const peopleSchema = z.object({
+    places: z.array(nameSchema).min(1),
+    existing: z.unknown().optional(),
+    fresh: z.unknown().optional(),
+    start: actingAsSchema.optional(),
+});
+/** The pick as a header value: the label may be any text, and a header holds only some. */
+export function actingAsHeader(actingAs) {
+    return encodeURIComponent(JSON.stringify(actingAs));
+}
+/** The headers a run sends for a pick: none for no one. */
+export function actingAsHeaders(actingAs) {
+    return actingAs ? { [ACTING_AS_HEADER]: actingAsHeader(actingAs) } : {};
+}
+/**
+ * The session a pick's runs share. Each person has their own, so one person's chat, held calls
+ * and answers are never another's; the label is left out, so renaming a person keeps their chat.
+ */
+export function actingAsSession(actingAs) {
+    if (!actingAs)
+        return NO_ONE_SESSION;
+    return `${NO_ONE_SESSION}:${encodeURIComponent(actingAs.place)}:${encodeURIComponent(actingAs.person.id)}`;
+}
+/** Reads a run's pick and checks its place is one the setup offers. */
+export function readActingAs(request, people) {
+    const sent = request.headers.get(ACTING_AS_HEADER);
+    if (sent === null)
+        return { ok: true, actingAs: undefined };
+    let value;
+    try {
+        value = JSON.parse(decodeURIComponent(sent));
+    }
+    catch {
+        return { ok: false, message: 'The person this run acts as could not be read.' };
+    }
+    return readPick(value, people?.places ?? []);
+}
+/** Reads a pick from wherever it was kept, and checks its place is one of `places`. */
+export function readPick(value, places) {
+    const parsed = actingAsSchema.safeParse(value);
+    if (!parsed.success)
+        return { ok: false, message: 'The person this run acts as could not be read.' };
+    const read = readPlace(parsed.data.place, places);
+    return read.ok ? { ok: true, actingAs: parsed.data } : read;
+}
+/** `place` when it is one of `places`, or why it is not. */
+export function readPlace(place, places) {
+    if (typeof place !== 'string' || place === '')
+        return { ok: false, message: 'The setup file needs a place to look in.' };
+    return places.some((offered) => offered.id === place)
+        ? { ok: true, place }
+        : { ok: false, message: `The setup file offers no place '${place}'.` };
+}
+/**
+ * Why the people a setup file exports cannot be offered, or nothing. A setup file is not always
+ * type-checked, so the studio reads what it exports before it trusts it.
+ */
+export function peopleFault(people) {
+    const parsed = peopleSchema.safeParse(people);
+    if (!parsed.success) {
+        return 'The people the setup file exports need places: a list of { id, label }, at least one.';
+    }
+    const { places, existing, fresh, start } = parsed.data;
+    const ids = places.map((place) => place.id);
+    if (new Set(ids).size !== ids.length)
+        return 'The places the setup file exports share an id.';
+    if (existing !== undefined && typeof existing !== 'function') {
+        return "The people the setup file exports have an 'existing' that is not a function.";
+    }
+    if (fresh !== undefined && typeof fresh !== 'function') {
+        return "The people the setup file exports have a 'fresh' that is not a function.";
+    }
+    if (start && !ids.includes(start.place)) {
+        return `The setup file starts in a place it does not offer: '${start.place}'.`;
+    }
+    return undefined;
+}
+/** What the page is told of the people a setup file offers. */
+export function peopleOffer(people) {
+    return {
+        places: people.places.map(({ id, label }) => ({ id, label })),
+        existing: people.existing !== undefined,
+        fresh: people.fresh !== undefined,
+        ...(people.start ? { start: people.start } : {}),
+    };
+}
+/** Reads what the application answered for a person, so the page never shows a malformed one. */
+export function readPerson(value, from) {
+    const parsed = nameSchema.safeParse(value);
+    if (!parsed.success)
+        throw new Error(`The setup file's ${from} answered a person without an id and a label.`);
+    return parsed.data;
+}

package/policy.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What the studio sets for itself, and how it reads a binding on what it runs on. What a page's
+ * lent keys allow is the page's own (`LentKeys`); nothing here knows a hosted model list.
+ */
+import type { ModelBindingDraft } from './draft.ts';
+import type { LentBinding, ModelBindingViolation, ModelProfileType, ModelStart, StudioRunsOn } from './lent-keys.ts';
+import { type ModelRoute, type StudioProvider } from './providers.ts';
+export type StudioConnectionMode = StudioRunsOn['mode'];
+/** Each record goes back to the run tab's inspector; the server keeps nothing. */
+export declare const STUDIO_TRACE_DESTINATION = "studio";
+/**
+ * What the studio fills in where a profile leaves a setting out, by path: a profile that names no
+ * place for its records is recorded to the studio, so a test run's trace shows. Written, the
+ * setting is the profile's, and any other value is a difference.
+ */
+export declare const STUDIO_POLICY_UNSET: Readonly<Record<string, unknown>>;
+/**
+ * `profile` as a file holds it: each value the studio fills in (`STUDIO_POLICY_UNSET`) is taken
+ * out, and a section left empty by that goes too. Writing a profile never writes the studio's own.
+ */
+export declare function withoutStudioFills<P extends object>(profile: P): P;
+/** A model spoken to in one of Gemini's protocols. */
+export declare function isGoogleRoute(route: Pick<ModelRoute, 'protocol'>): boolean;
+/** A model spoken to in one of OpenRouter's protocols. */
+export declare function isOpenRouterRoute(route: Pick<ModelRoute, 'protocol'>): boolean;
+export declare function isProviderBuiltinId(name: string): boolean;
+/**
+ * Whether the studio runs agents of `type` on a provider: on lent keys, what the keys run; on
+ * the builder's own keys or machine, whether the provider serves the type.
+ */
+export declare function studioRunsProvider(type: ModelProfileType, provider: StudioProvider | undefined, on: StudioRunsOn): boolean;
+/**
+ * The binding a new model of `type` starts on: where `start` puts it, or with none a kernel
+ * provider and no model yet, for the builder to pick.
+ */
+export declare function startingBinding(type: ModelProfileType, start?: ModelStart): Pick<ModelBindingDraft, 'modelId' | 'protocol' | 'provider' | 'apiId'>;
+/** The studio provider `id`, on the first protocol it serves agents of `type` on. */
+export declare function firstServed(id: string, type: ModelProfileType): {
+    protocol: string;
+    provider: string;
+};
+/** `null` when `binding` can run on `on`: a local run on local models, a lent run on what the keys allow. */
+export declare function modelBindingViolation(binding: LentBinding, on: StudioRunsOn): ModelBindingViolation | null;

package/policy.js

@@ -0,0 +1,102 @@
+/**
+ * What the studio sets for itself, and how it reads a binding on what it runs on. What a page's
+ * lent keys allow is the page's own (`LentKeys`); nothing here knows a hosted model list.
+ */
+import { GOOGLE_BUILTIN_TOOLS } from '@theoremjs/agents/presets/google';
+import { geminiInteractions, geminiLive, openRouter, openRouterImages, } from '@theoremjs/agents/providers';
+import { LOCAL_PROVIDER_ID, STUDIO_PROVIDERS, servedProtocols, servesProfileType, } from "./providers.js";
+/** Each record goes back to the run tab's inspector; the server keeps nothing. */
+export const STUDIO_TRACE_DESTINATION = 'studio';
+/**
+ * What the studio fills in where a profile leaves a setting out, by path: a profile that names no
+ * place for its records is recorded to the studio, so a test run's trace shows. Written, the
+ * setting is the profile's, and any other value is a difference.
+ */
+export const STUDIO_POLICY_UNSET = {
+    'observability.writeTo': STUDIO_TRACE_DESTINATION,
+};
+/**
+ * `profile` as a file holds it: each value the studio fills in (`STUDIO_POLICY_UNSET`) is taken
+ * out, and a section left empty by that goes too. Writing a profile never writes the studio's own.
+ */
+export function withoutStudioFills(profile) {
+    return Object.entries(STUDIO_POLICY_UNSET).reduce((held, [path, fill]) => withoutFill(held, path.split('.'), fill), profile);
+}
+function withoutFill(value, [key, ...rest], fill) {
+    if (key === undefined || !Object.hasOwn(value, key))
+        return value;
+    const inner = value[key];
+    if (!rest.length) {
+        return inner === fill
+            ? Object.fromEntries(Object.entries(value).filter(([at]) => at !== key))
+            : value;
+    }
+    if (typeof inner !== 'object' || inner === null || Array.isArray(inner))
+        return value;
+    const kept = withoutFill(inner, rest, fill);
+    if (kept === inner)
+        return value;
+    return Object.fromEntries(Object.entries(value).flatMap(([at, held]) => at !== key ? [[at, held]] : Object.keys(kept).length ? [[at, kept]] : []));
+}
+/** Provider builtin ids — they belong on `models.*.builtInTools`, never on a custom tool. */
+const GOOGLE_BUILTIN_IDS = new Set(GOOGLE_BUILTIN_TOOLS.map((tool) => tool.name));
+/** A model spoken to in one of Gemini's protocols. */
+export function isGoogleRoute(route) {
+    return route.protocol === geminiInteractions.id || route.protocol === geminiLive.id;
+}
+/** A model spoken to in one of OpenRouter's protocols. */
+export function isOpenRouterRoute(route) {
+    return route.protocol === openRouter.id || route.protocol === openRouterImages.id;
+}
+export function isProviderBuiltinId(name) {
+    return GOOGLE_BUILTIN_IDS.has(name);
+}
+/**
+ * Whether the studio runs agents of `type` on a provider: on lent keys, what the keys run; on
+ * the builder's own keys or machine, whether the provider serves the type.
+ */
+export function studioRunsProvider(type, provider, on) {
+    return on.mode === 'demo'
+        ? on.keys.runs(type, provider?.definition)
+        : servesProfileType(provider, type);
+}
+/** The model id a new binding of `type` takes. */
+const MODEL_IDS = {
+    text: 'fast',
+    image: 'image',
+    speech: 'voice',
+    live: 'live',
+    decision: 'decision',
+    embedding: 'embedding',
+};
+/**
+ * The binding a new model of `type` starts on: where `start` puts it, or with none a kernel
+ * provider and no model yet, for the builder to pick.
+ */
+export function startingBinding(type, start) {
+    const begun = start?.(type) ?? {
+        ...firstServed(type === 'decision' ? 'typesafe' : 'gemini', type),
+        apiId: '',
+    };
+    return { modelId: MODEL_IDS[type], ...begun };
+}
+/** The studio provider `id`, on the first protocol it serves agents of `type` on. */
+export function firstServed(id, type) {
+    const provider = STUDIO_PROVIDERS.find((each) => each.id === id);
+    const protocol = provider && servedProtocols(provider, type)?.[0];
+    if (!protocol)
+        throw new Error(`The studio provider '${id}' serves no ${type} agents.`); // labels-exempt: developer contract error
+    return { protocol: protocol.id, provider: id };
+}
+/** `null` when `binding` can run on `on`: a local run on local models, a lent run on what the keys allow. */
+export function modelBindingViolation(binding, on) {
+    if (on.mode === 'demo')
+        return on.keys.violation(binding);
+    if (on.mode === 'local' && binding.provider !== LOCAL_PROVIDER_ID) {
+        return {
+            field: 'provider',
+            message: 'Local runs require local models. Switch the model provider to Local.',
+        };
+    }
+    return null;
+}

package/ports.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Where a setup opens: on the pair a studio already has it open on, else the first free pair.
+ * Nothing when every pair is taken.
+ * @param {string} setup the setup's file, in full
+ * @param {readonly Held[]} held every pair, in order
+ * @returns {{ pair: Pair, running: boolean } | undefined}
+ */
+export function placeFor(setup: string, held: readonly Held[]): {
+    pair: Pair;
+    running: boolean;
+} | undefined;
+/** @returns {Promise<Held[]>} */
+export function heldPairs(): Promise<Held[]>;
+/** Where a studio's server says which setup it is open on. */
+export const RUNNING_PATH: "/api/studio/running";
+export function pairAt(at: number): Pair;
+export function pairs(): Pair[];
+export function pageAddress(pair: Pair): string;
+export function serverAddress(pair: Pair): string;
+export type Pair = {
+    server: number;
+    page: number;
+};
+/**
+ * what a pair holds: the setup a
+ *  studio there is open on, and whether both ports are free
+ */
+export type Held = {
+    pair: Pair;
+    setup?: string;
+    free: boolean;
+};

package/ports.mjs

@@ -0,0 +1,85 @@
+/**
+ * Where a studio listens. A studio takes a pair of ports on this machine: the project's server,
+ * and the page one above it. The first pair is the one a project opens on; a second project opened
+ * beside it takes the next pair that is free.
+ */
+import { createServer } from 'node:net';
+
+const FIRST_SERVER_PORT = 4983;
+/** How many studios can be open at once. */
+const PAIRS = 10;
+/** Where a studio's server says which setup it is open on. */
+export const RUNNING_PATH = '/api/studio/running';
+/** How long a server has to say so. One on this machine answers at once. */
+const ANSWER_MS = 1000;
+
+/**
+ * @typedef {{ server: number, page: number }} Pair
+ * @typedef {{ pair: Pair, setup?: string, free: boolean }} Held what a pair holds: the setup a
+ *   studio there is open on, and whether both ports are free
+ */
+
+/** @param {number} at @returns {Pair} */
+export const pairAt = (at) => ({
+  server: FIRST_SERVER_PORT + 2 * at,
+  page: FIRST_SERVER_PORT + 2 * at + 1,
+});
+
+/** @returns {Pair[]} */
+export const pairs = () => Array.from({ length: PAIRS }, (_, at) => pairAt(at));
+
+/** @param {Pair} pair */
+export const pageAddress = (pair) => `http://127.0.0.1:${String(pair.page)}`;
+/** @param {Pair} pair */
+export const serverAddress = (pair) => `http://127.0.0.1:${String(pair.server)}`;
+
+/**
+ * Where a setup opens: on the pair a studio already has it open on, else the first free pair.
+ * Nothing when every pair is taken.
+ * @param {string} setup the setup's file, in full
+ * @param {readonly Held[]} held every pair, in order
+ * @returns {{ pair: Pair, running: boolean } | undefined}
+ */
+export function placeFor(setup, held) {
+  const running = held.find((one) => one.setup === setup);
+  if (running) return { pair: running.pair, running: true };
+  const free = held.find((one) => one.free);
+  return free && { pair: free.pair, running: false };
+}
+
+/** @param {number} port @returns {Promise<boolean>} */
+function isFree(port) {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once('error', () => resolve(false));
+    probe.listen(port, '127.0.0.1', () => probe.close(() => resolve(true)));
+  });
+}
+
+/** The setup the studio on a pair is open on, or nothing when no studio answers there. */
+async function runningOn(pair) {
+  try {
+    const response = await fetch(serverAddress(pair) + RUNNING_PATH, {
+      signal: AbortSignal.timeout(ANSWER_MS),
+    });
+    const said = response.ok ? await response.json() : undefined;
+    return typeof said?.setup === 'string' ? said.setup : undefined;
+  } catch {
+    // Nothing listens there, or what does is not a studio.
+    return undefined;
+  }
+}
+
+/** @returns {Promise<Held[]>} */
+export function heldPairs() {
+  return Promise.all(
+    pairs().map(async (pair) => {
+      const [setup, server, page] = await Promise.all([
+        runningOn(pair),
+        isFree(pair.server),
+        isFree(pair.page),
+      ]);
+      return { pair, ...(setup === undefined ? {} : { setup }), free: server && page };
+    }),
+  );
+}

package/probe-battery.d.ts

@@ -0,0 +1,13 @@
+import type { ProbeBoundary } from './guardrail-probe.ts';
+export interface ProbeBatteryCase {
+    id: string;
+    boundary: ProbeBoundary;
+    title: string;
+    text: string;
+    /** What a guardrail should do: act on the text (`hit`) or leave it alone (`pass`). */
+    want: 'hit' | 'pass';
+    /** What makes the text hard. */
+    why: string;
+}
+/** Every case, grouped by boundary in the order of `PROBE_BOUNDARIES`. */
+export declare const PROBE_BATTERY: readonly ProbeBatteryCase[];