@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/draft-decide.js

@@ -0,0 +1,111 @@
+/**
+ * `POST <base>/decide`: one decision on lent keys. The browser authors the profile and its
+ * questions, so the server takes only the fields a studio decision compiles to, within the keys'
+ * decision limits, and checks the model, the state, and each question against the keys before it
+ * spends anything.
+ *
+ * @module
+ */
+import { TheoremError, validateDecisionRequest, z } from '@theoremjs/agents';
+import { KEY_SLOT_NAME } from '@theoremjs/agents/schema';
+import { readBody } from '@theoremjs/react/server';
+import { runStudioDecision } from "../runtime.js";
+import { defineDraft } from "../runtime-scope.js";
+import { errorJson, noStoreJson } from "./draft-replies.js";
+import { lentRoute, lentVault } from "./lent-draft.js";
+/** The decision request lent keys answer: only the fields a studio decision compiles to, within `limits`. A setting left out stays out. */
+export function decisionRequestSchema(limits) {
+    const name = z.string().trim().min(1).max(limits.nameChars);
+    const id = z.string().trim().min(1).max(limits.idChars);
+    const entry = z.string().trim().min(1).max(limits.criterionChars);
+    const slot = z.string().regex(KEY_SLOT_NAME);
+    const labelled = z
+        .record(name, entry)
+        .refine((record) => Object.keys(record).length > 0 && Object.keys(record).length <= limits.criteria);
+    const instructions = z.string().trim().min(1).max(limits.instructionsChars);
+    const question = z.discriminatedUnion('type', [
+        z.object({ type: z.literal('choice'), instructions, criteria: labelled }),
+        z.object({
+            type: z.literal('score'),
+            instructions,
+            criteria: z.array(entry).min(2).max(limits.criteria),
+        }),
+        z.object({ type: z.literal('noul'), instructions, criteria: labelled.optional() }),
+        z.object({
+            type: z.literal('box'),
+            instructions,
+            image: z.string().trim().min(1).max(limits.instructionsChars).optional(),
+        }),
+    ]);
+    // why: Base64 is four characters for every three bytes, so the byte limit bounds the text before it is decoded.
+    const image = z.object({
+        mimeType: z.enum(['image/png', 'image/jpeg']),
+        data: z.string().max(Math.ceil(limits.imageBytes / 3) * 4),
+    });
+    return z.object({
+        profile: z.object({
+            type: z.literal('decision'),
+            id,
+            identity: z.object({ handle: name }),
+            models: z
+                .record(name, z.object({
+                protocol: z.literal('systemOne'),
+                provider: name,
+                apiId: id,
+                keySlot: slot.optional(),
+                fallbackKeySlot: slot.optional(),
+                options: z.record(z.string(), z.json()).optional(),
+                timeoutMs: z.number().int().min(1).max(limits.timeoutMs).optional(),
+            }))
+                .refine((models) => Object.keys(models).length === 1),
+            inputs: z.object({
+                state: z.literal('json'),
+                maxStateBytes: z.number().int().min(1).max(limits.stateBytes).optional(),
+            }),
+            decision: z.object({ contract: id }),
+            observability: z.record(z.string(), z.unknown()).optional(),
+            labels: z.record(z.string(), z.unknown()).optional(),
+        }),
+        questions: z
+            .record(name, question)
+            .refine((record) => Object.keys(record).length > 0 && Object.keys(record).length <= limits.questions),
+        state: z.unknown(),
+        assets: z
+            .record(name, image)
+            .refine((record) => Object.keys(record).length <= limits.images)
+            .optional(),
+    });
+}
+/** Answers one decision on the lent keys, with the records it wrote; a failed one is traced too. */
+export async function draftDecide(request, options) {
+    let labels;
+    try {
+        const body = await readBody(request, decisionRequestSchema(options.runtime.keys.decision));
+        const profile = defineDraft(body.profile);
+        labels = profile.labels;
+        const selected = lentRoute('decision', profile);
+        const { keys } = options.runtime;
+        const refused = keys.violation(selected)?.message ??
+            keys.stateViolation(selected, body.state) ??
+            Object.values(body.questions)
+                .map((question) => keys.questionViolation(selected, question))
+                .find(Boolean);
+        if (refused)
+            throw new TheoremError('request', `studio decide: ${refused}`);
+        validateDecisionRequest({
+            profile: profile.id,
+            state: body.state,
+            questions: body.questions,
+            assets: body.assets,
+            signal: request.signal,
+        }, profile);
+        const vault = lentVault(options.runtime, profile, 'decide');
+        await options.spend(request);
+        const { result, traces } = await runStudioDecision({ agentId: profile.id, profile: body.profile, customTools: [], questions: body.questions }, body.state, { vault }, request.signal, body.assets);
+        return noStoreJson({ result, traces });
+    }
+    catch (err) {
+        // A failed decision is traced too; the page shows what it left.
+        return errorJson(err, labels);
+    }
+}

package/server/draft-embedding.d.ts

@@ -0,0 +1,3 @@
+import type { LentRuntime } from './draft-handler.ts';
+/** Embeds the input on the lent keys, once the keys allow the profile's model. */
+export declare function draftEmbedding(request: Request, runtime: LentRuntime): Promise<Response>;

package/server/draft-embedding.js

@@ -0,0 +1,35 @@
+/**
+ * `POST <base>/embedding/embed`: one embedding on lent keys, with the records it wrote.
+ *
+ * @module
+ */
+import { TheoremError, z } from '@theoremjs/agents';
+import { embedBodySchema, embedRequest, readBody } from '@theoremjs/react/server';
+import { runStudioEmbedding } from "../runtime.js";
+import { defineDraft } from "../runtime-scope.js";
+import { errorJson, noStoreJson } from "./draft-replies.js";
+import { lentRoute, lentVault } from "./lent-draft.js";
+const embeddingRequestSchema = embedBodySchema.extend({
+    profile: z.record(z.string(), z.unknown()),
+});
+/** Embeds the input on the lent keys, once the keys allow the profile's model. */
+export async function draftEmbedding(request, runtime) {
+    let labels;
+    try {
+        const body = await readBody(request, embeddingRequestSchema);
+        const profile = defineDraft(body.profile);
+        if (profile.type !== 'embedding') {
+            throw new TheoremError('request', 'studio embedding requires an embedding profile.');
+        }
+        labels = profile.labels;
+        const violation = runtime.keys.violation(lentRoute('embedding', profile));
+        if (violation)
+            throw new TheoremError('request', `studio embedding: ${violation.message}`);
+        lentVault(runtime, profile, 'embedding');
+        const { result, traces } = await runStudioEmbedding({ agentId: profile.id, profile: body.profile, customTools: [] }, embedRequest(body), runtime);
+        return noStoreJson({ result, traces });
+    }
+    catch (err) {
+        return errorJson(err, labels);
+    }
+}

package/server/draft-handler.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The studio screen's server: everything the screen asks a server for, from one handler.
+ *
+ * The screen authors each draft in the browser and sends it with every request, so this serves
+ * no project. It always answers the guardrail probe, the key test, and the tool connection test.
+ * Given lent keys, it also runs drafts on them: chats, calls, decisions, and embeddings. Without
+ * them, the screen runs on the builder's own keys in the browser, and those routes answer 404.
+ *
+ * The host keeps its own policy: which keys it lends and how much anyone may spend on them
+ * (`spend`). The handler keeps the plumbing.
+ *
+ * @module
+ */
+import { type ResolveHost } from '@theoremjs/agents';
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+import { type PageToolBroker, type SteerInbox, type TheoremSessionStore } from '@theoremjs/react/server';
+import type { LentKeys } from '../lent-keys.ts';
+import type { StudioRuntime } from '../runtime-scope.ts';
+import { type ProbeEntry } from './draft-probe.ts';
+export type { ProbeEntry } from './draft-probe.ts';
+/** Runs on keys the host lends, and what they are held to. */
+export type LentRuntime = StudioRuntime & {
+    mode: 'demo';
+    keys: LentKeys;
+};
+/** What a request spends of the host's allowance: a decision, a host tool call, or an agent tool's model turn. */
+export type StudioSpend = 'decision' | 'call' | 'agent';
+export type StudioDraftHandlerOptions = {
+    /**
+     * Runs on the keys the host lends: `{ mode: 'demo', keys }`, with `hostOptions` filling each
+     * profile's key slots, and the host's tool handlers. Without it, no draft runs on the server.
+     */
+    lent?: LentRuntime;
+    /**
+     * Spends one of `kind` for whoever sent `request`, before it runs. Throw a `TheoremError` to refuse
+     * it: the screen reads the error's wording. Every decision, host tool call, and agent tool turn on
+     * the lent keys passes through it. Default: nothing is counted.
+     */
+    spend?: (kind: StudioSpend, request: Request) => void | Promise<void>;
+    /**
+     * Resolves the names the tool connection test calls, so the network guard refuses one that
+     * answers a private address. Workers have no DNS lookup: pass `dnsOverHttpsResolver(...)`.
+     * Default: `lent.resolveHost`.
+     */
+    resolveHost?: ResolveHost;
+    /** Gets each probed text some guardrail boundary let through, after the answer. */
+    onProbePassed?: (entry: ProbeEntry, at: Date) => Promise<void>;
+    /** Where visitor sessions are kept. Default: in memory, for this handler's lifetime. */
+    sessionStore?: TheoremSessionStore;
+    /** Where page tool results wait for their run. Default: in memory. */
+    pageToolBroker?: PageToolBroker;
+    /**
+     * Where a running chat's steers queue, by the inbox id the run sends its page. A host on several
+     * isolates needs one store they all reach. Default: in memory.
+     */
+    steer?: SteerInbox;
+    /** The key chat conversations are sealed with. Default: a new one, for this handler's lifetime. */
+    conversationKey?: string;
+    /**
+     * True only when the handler serves the builder alone, on their own machine, as the command's
+     * does: a connection test then keeps to the draft's network guardrail, as the draft's runs do,
+     * private addresses included when it allows them. Otherwise a test reaches public hosts only,
+     * whatever the draft says, so no visitor reaches the host's own network.
+     */
+    draftNetwork?: boolean;
+};
+/**
+ * Answers a request under `STUDIO_BASE`; `defer` keeps work running after the reply (a Worker's
+ * `ctx.waitUntil`). A path it does not serve answers 404.
+ */
+export type StudioDraftHandler = {
+    (request: Request, defer?: (work: Promise<unknown>) => void): Promise<Response>;
+    /**
+     * Opens a chat on `blocks` the host wrote, in the asking visitor's session, read first by the
+     * draft's guardrails: `{ conversation, view }`. The request body is the draft. Needs `lent`.
+     */
+    startConversation(request: Request, blocks: readonly TranscriptBlock[]): Promise<Response>;
+};
+/** Where the screen sends every request: mount the handler here. */
+export declare const STUDIO_BASE = "/api/studio";
+/** Serves the studio screen's requests. */
+export declare function createStudioDraftHandler(options?: StudioDraftHandlerOptions): StudioDraftHandler;

package/server/draft-handler.js

@@ -0,0 +1,213 @@
+/**
+ * The studio screen's server: everything the screen asks a server for, from one handler.
+ *
+ * The screen authors each draft in the browser and sends it with every request, so this serves
+ * no project. It always answers the guardrail probe, the key test, and the tool connection test.
+ * Given lent keys, it also runs drafts on them: chats, calls, decisions, and embeddings. Without
+ * them, the screen runs on the builder's own keys in the browser, and those routes answer 404.
+ *
+ * The host keeps its own policy: which keys it lends and how much anyone may spend on them
+ * (`spend`). The handler keeps the plumbing.
+ *
+ * @module
+ */
+import { TheoremError, z } from '@theoremjs/agents';
+import { clientError } from '@theoremjs/agents/host';
+import { checkRequest, createMemoryPageToolBroker, createMemorySessionStore, createMemorySteerInbox, createSealedConversationStore, createTheoremSessionBoundary, pageToolResultSchema, readBody, steerUnitOf, theoremConversationRequestSchema, theoremHostCallRequestSchema, theoremInvokeRequestSchema, theoremRewindRequestSchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from '@theoremjs/react/server';
+import { newConversationKey } from "../conversation-key.js";
+import { rewindStudio, startStudioConversation, streamStudioCall, streamStudioHostInvoke, streamStudioInvoke, streamStudioTurn, studioConversation, } from "../runtime.js";
+import { draftDecide } from "./draft-decide.js";
+import { draftEmbedding } from "./draft-embedding.js";
+import { draftProbe } from "./draft-probe.js";
+import { errorJson, ndjsonEventStream } from "./draft-replies.js";
+import { testConnection } from "./test-connection.js";
+import { testKey } from "./test-key.js";
+/** A draft's outline: whatever else it holds, `defineProfile` and the tool registry check when the run opens. */
+const record = z.record(z.string(), z.unknown());
+const structuredOutline = z.object({ id: z.string(), spec: record });
+const draftOutline = z.looseObject({
+    profile: record,
+    customTools: z.array(record).optional(),
+    structured: structuredOutline.optional(),
+    dependencies: z
+        .array(z.looseObject({
+        profile: record,
+        customTools: z.array(record),
+        structured: structuredOutline.optional(),
+    }))
+        .optional(),
+});
+/** The tools a page allowed for the rest of its visit, as the browser holds them. */
+const pagePermissions = z.array(z.string().min(1).max(128)).max(256).optional();
+/** The labels a failed request's reply is worded with: its draft's, once the body is read. */
+function draftLabels(draft) {
+    // The body is unchecked when most failures are caught, so the draft may hold anything.
+    return draft?.profile?.labels;
+}
+const notFound = () => Response.json({}, { status: 404 });
+/** Where the screen sends every request: mount the handler here. */
+export const STUDIO_BASE = '/api/studio';
+/** Serves the studio screen's requests. */
+export function createStudioDraftHandler(options = {}) {
+    const { lent, spend } = options;
+    const resolveHost = options.resolveHost ?? lent?.resolveHost;
+    const sessionStore = options.sessionStore ?? createMemorySessionStore();
+    const pageToolBroker = options.pageToolBroker ?? createMemoryPageToolBroker();
+    const steer = options.steer ?? createMemorySteerInbox();
+    const conversationStore = createSealedConversationStore({
+        keys: { 1: options.conversationKey ?? newConversationKey() },
+        keyVersion: 1,
+    });
+    const conversationsOf = (boundary) => ({
+        sessionId: boundary.sessionId,
+        store: conversationStore,
+    });
+    /** Each agent tool call runs a model turn on the lent keys, so it spends first; a refusal is what the calling model reads. */
+    const agentCall = (request) => spend &&
+        (async () => {
+            try {
+                await spend('agent', request);
+                return undefined;
+            }
+            catch (err) {
+                return { refuse: clientError(err).error };
+            }
+        });
+    /** The run's runtime: the lent keys, on this session's tool execution. */
+    const runtimeOf = (lent, boundary, request) => ({
+        ...lent,
+        execution: boundary.toolExecution,
+        pageExecution: boundary.pageExecution,
+        onAgentCall: agentCall(request),
+    });
+    /** A draft as a run takes it. */
+    const draftRun = (lent, draft, boundary, request) => ({
+        profile: draft.profile,
+        customTools: draft.customTools ?? [],
+        structured: draft.structured,
+        dependencies: draft.dependencies,
+        runtime: runtimeOf(lent, boundary, request),
+    });
+    /** A draft request: its body read, its session opened, the cookie set, and a failure worded with the draft's labels. */
+    const draftRequest = async (request, handle) => {
+        let draft;
+        try {
+            draft = (await readBody(request, draftOutline));
+            const boundary = await createTheoremSessionBoundary({
+                request,
+                sessionStore,
+                pageToolBroker,
+            });
+            const response = await handle(draft, boundary);
+            if (boundary.setCookie)
+                response.headers.append('set-cookie', boundary.setCookie);
+            return response;
+        }
+        catch (err) {
+            return errorJson(err, draftLabels(draft));
+        }
+    };
+    /** A run's events, streamed, with each checkpoint the run reaches kept in the session. */
+    const stream = (boundary, draft, events) => ndjsonEventStream(recorded(boundary, events), draft.profile.labels);
+    const lentRoutes = (lent) => ({
+        turn: (request) => draftRequest(request, (draft, boundary) => stream(boundary, draft, streamStudioTurn({
+            ...draftRun(lent, draft, boundary, request),
+            request: checkRequest(theoremTurnRequestSchema, draft, 'request body'),
+            conversations: conversationsOf(boundary),
+            signal: request.signal,
+            steer,
+        }))),
+        invoke: (request) => draftRequest(request, (draft, boundary) => {
+            const answer = checkRequest(theoremInvokeRequestSchema, draft, 'request body');
+            const run = draftRun(lent, draft, boundary, request);
+            return stream(boundary, draft, draft.profile.type === 'host'
+                ? streamStudioHostInvoke({ ...run, answer, signal: request.signal })
+                : streamStudioInvoke({
+                    ...run,
+                    answer,
+                    conversations: conversationsOf(boundary),
+                    signal: request.signal,
+                }));
+        }),
+        conversation: (request) => draftRequest(request, async (draft, boundary) => Response.json(await studioConversation(draftRun(lent, draft, boundary, request), conversationsOf(boundary), checkRequest(theoremConversationRequestSchema, draft, 'request body')))),
+        rewind: (request) => draftRequest(request, async (draft, boundary) => Response.json(await rewindStudio(draftRun(lent, draft, boundary, request), conversationsOf(boundary), checkRequest(theoremRewindRequestSchema, draft, 'request body'), request.signal))),
+        call: (request) => draftRequest(request, async (draft, boundary) => {
+            const call = checkRequest(theoremHostCallRequestSchema, draft, 'request body');
+            const sessionPermissions = checkRequest(pagePermissions, draft.sessionPermissions, 'session permissions');
+            // Counted only once the request is one a host would run.
+            await spend?.('call', request);
+            const { structured: _structured, ...run } = draftRun(lent, draft, boundary, request);
+            return stream(boundary, draft, streamStudioCall({ ...run, call, sessionPermissions, signal: request.signal }));
+        }),
+        'turn/steer': async (request) => {
+            try {
+                // The inbox the server opened for the turn is the turn id the browser steers.
+                const asked = checkRequest(theoremSteerRequestSchema, await readBody(request, z.unknown()), 'request body');
+                if (!(await steer.enqueue(asked.turnId, steerUnitOf(asked)))) {
+                    // labels-exempt: internal diagnostic; the user reads session.turn_ended
+                    throw new TheoremError('request', 'steer: no open run has this inbox', {
+                        copy: { key: 'session.turn_ended' },
+                    });
+                }
+                return Response.json({ ok: true });
+            }
+            catch (err) {
+                return errorJson(err);
+            }
+        },
+        'page-result': async (request) => {
+            try {
+                const boundary = await createTheoremSessionBoundary({
+                    request,
+                    sessionStore,
+                    pageToolBroker,
+                });
+                await boundary.answerPageResult(await readBody(request, pageToolResultSchema));
+                const response = Response.json({ accepted: true });
+                if (boundary.setCookie)
+                    response.headers.append('set-cookie', boundary.setCookie);
+                return response;
+            }
+            catch (err) {
+                return errorJson(err);
+            }
+        },
+        decide: (request) => draftDecide(request, {
+            runtime: lent,
+            spend: async (asked) => await spend?.('decision', asked),
+        }),
+        'embedding/embed': (request) => draftEmbedding(request, lent),
+    });
+    const handler = ((request, defer) => {
+        const path = new URL(request.url).pathname;
+        const route = path.startsWith(`${STUDIO_BASE}/`) ? path.slice(STUDIO_BASE.length + 1) : '';
+        const routes = {
+            probe: (asked) => draftProbe(asked, options.onProbePassed, defer ?? (() => { })),
+            'test-key': testKey,
+            'test-connection': (asked) => testConnection(asked, { resolveHost, draftNetwork: options.draftNetwork }),
+            ...(lent ? lentRoutes(lent) : {}),
+        };
+        if (!Object.hasOwn(routes, route))
+            return Promise.resolve(notFound());
+        if (request.method !== 'POST')
+            return Promise.resolve(new Response(null, { status: 405 }));
+        return routes[route](request);
+    });
+    handler.startConversation = (request, blocks) => {
+        if (!lent)
+            return Promise.resolve(notFound());
+        return draftRequest(request, async (draft, boundary) => Response.json(await startStudioConversation(draftRun(lent, draft, boundary, request), conversationsOf(boundary), blocks)));
+    };
+    return handler;
+}
+/** The run's events, with each checkpoint it reaches kept in the visitor's session. */
+async function* recorded(boundary, events) {
+    for await (const event of events) {
+        if (event.type === 'done' || event.type === 'provider_checkpoint') {
+            const state = event.providerState;
+            if (state)
+                await boundary.recordCheckpoint(state);
+        }
+        yield event;
+    }
+}

package/server/draft-probe.d.ts

@@ -0,0 +1,14 @@
+import { type GuardrailProbeAnswer } from '../guardrail-probe.ts';
+/** A probed text some boundary let through, and what each boundary's guardrails did with it. */
+export type ProbeEntry = {
+    text: string;
+    /** The draft's guardrails as written. */
+    guardrails: unknown;
+    answers: readonly Pick<GuardrailProbeAnswer, 'boundary' | 'status' | 'taint' | 'guardrails' | 'passed'>[];
+};
+/**
+ * Runs the text across every boundary and answers with what the guardrails did at each. A text
+ * some boundary passed, run with every detector and not one of the battery's, goes to `onPassed`
+ * through `defer`, after the answer: one that fails never fails a probe.
+ */
+export declare function draftProbe(request: Request, onPassed: ((entry: ProbeEntry, at: Date) => Promise<void>) | undefined, defer: (work: Promise<unknown>) => void): Promise<Response>;

package/server/draft-probe.js

@@ -0,0 +1,61 @@
+/**
+ * `POST <base>/probe`: one text sent across every guardrail boundary of the draft, each on a
+ * scripted model, so no key is spent and no host is reached. With `only`, the draft reads with that
+ * detector alone: what the others would catch passes there.
+ *
+ * @module
+ */
+import { z } from '@theoremjs/agents';
+import { readBody } from '@theoremjs/react/server';
+import { PROBE_TEXT_LIMIT, runGuardrailProbes, } from "../guardrail-probe.js";
+import { PROBE_BATTERY } from "../probe-battery.js";
+import { errorJson, noStoreJson } from "./draft-replies.js";
+function part() {
+    return z.custom((value) => typeof value === 'object' && value !== null);
+}
+/** The draft as every studio request carries it, and the text to probe with. The kernel checks the draft when it registers it. */
+const probeRequestSchema = z.object({
+    profile: part(),
+    customTools: z.array(part()).optional(),
+    structured: part().optional(),
+    dependencies: z.array(part()).optional(),
+    text: z.string().min(1).max(PROBE_TEXT_LIMIT),
+    only: z.string().min(1).max(200).optional(),
+});
+/** A battery text is known already: what passes it is no news to a reviewer. */
+function isBatteryText(text) {
+    return PROBE_BATTERY.some((entry) => entry.text === text);
+}
+/**
+ * Runs the text across every boundary and answers with what the guardrails did at each. A text
+ * some boundary passed, run with every detector and not one of the battery's, goes to `onPassed`
+ * through `defer`, after the answer: one that fails never fails a probe.
+ */
+export async function draftProbe(request, onPassed, defer) {
+    let labels;
+    try {
+        const body = await readBody(request, probeRequestSchema);
+        labels = body.profile.labels;
+        const answers = await runGuardrailProbes({
+            profile: body.profile,
+            customTools: body.customTools ?? [],
+            structured: body.structured,
+            dependencies: body.dependencies,
+            text: body.text,
+            only: body.only,
+            signal: request.signal,
+        });
+        const isNews = body.only === undefined &&
+            answers.some((answer) => answer.status === 'passed') &&
+            !isBatteryText(body.text);
+        if (onPassed && isNews) {
+            defer(onPassed({ text: body.text, guardrails: body.profile.guardrails, answers }, new Date()).catch((error) => {
+                console.error('studio probe: onPassed failed', error);
+            }));
+        }
+        return noStoreJson({ answers });
+    }
+    catch (err) {
+        return errorJson(err, labels);
+    }
+}

package/server/draft-replies.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How the draft server answers: a run's events as NDJSON, and a failure as JSON, each worded
+ * for a visitor.
+ *
+ * @module
+ */
+import type { ProfileDefinition } from '@theoremjs/agents';
+/**
+ * NDJSON response that streams a run's events, each as a visitor may have it. A failure the run didn't turn into an event itself
+ * (one thrown before the kernel's turn starts, such as registering the profile or creating its
+ * provider) ends the stream as the kernel's own error event, as a visitor may have it: its kind's
+ * wording, from the profile's `labels` when it has one, and never the raw detail.
+ */
+export declare function ndjsonEventStream(source: AsyncIterable<unknown>, labels?: ProfileDefinition['labels']): Response;
+/** A JSON reply the browser never caches. */
+export declare function noStoreJson(body: unknown, status?: number): Response;
+/**
+ * The reply for a failure caught before a route had anything to stream: the status of its kind,
+ * the wording a visitor may read, from the profile's `labels` when the request carried one, and
+ * the traces the failed run left, when it left any.
+ */
+export declare function errorJson(err: unknown, labels?: ProfileDefinition['labels']): Response;

package/server/draft-replies.js

@@ -0,0 +1,46 @@
+import { toErrorEvent, withPublicLabels } from '@theoremjs/agents/guardrails';
+import { caughtStatus, clientError, forClient } from '@theoremjs/agents/host';
+import { failedDecisionTraces } from "../runtime.js";
+const NDJSON_HEADERS = {
+    'content-type': 'application/x-ndjson; charset=utf-8',
+    'cache-control': 'no-store',
+};
+/**
+ * NDJSON response that streams a run's events, each as a visitor may have it. A failure the run didn't turn into an event itself
+ * (one thrown before the kernel's turn starts, such as registering the profile or creating its
+ * provider) ends the stream as the kernel's own error event, as a visitor may have it: its kind's
+ * wording, from the profile's `labels` when it has one, and never the raw detail.
+ */
+export function ndjsonEventStream(source, labels) {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        async start(controller) {
+            try {
+                for await (const event of source) {
+                    const line = event.type === 'conversation'
+                        ? event
+                        : forClient(event);
+                    controller.enqueue(encoder.encode(`${JSON.stringify(line)}\n`));
+                }
+            }
+            catch (err) {
+                controller.enqueue(encoder.encode(`${JSON.stringify(forClient(withPublicLabels(toErrorEvent(err), labels)))}\n`));
+            }
+            controller.close();
+        },
+    });
+    return new Response(stream, { headers: NDJSON_HEADERS });
+}
+/** A JSON reply the browser never caches. */
+export function noStoreJson(body, status = 200) {
+    return Response.json(body, { status, headers: { 'cache-control': 'no-store' } });
+}
+/**
+ * The reply for a failure caught before a route had anything to stream: the status of its kind,
+ * the wording a visitor may read, from the profile's `labels` when the request carried one, and
+ * the traces the failed run left, when it left any.
+ */
+export function errorJson(err, labels) {
+    const traces = failedDecisionTraces(err);
+    return noStoreJson({ ...clientError(err, labels), ...(traces.length > 0 ? { traces } : {}) }, caughtStatus(err));
+}

package/server/edited-session.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { StudioWorkspace } from '../workspace.ts';
+import type { ProjectEdits } from './edits.ts';
+import type { EditedAnswer } from './save-wire.ts';
+/** What the edited load needs from the machine. `Loaded` is one load of the project. */
+export interface EditedHost<Loaded> {
+    /** Loads the project from disk with the edits laid over it. Throws what it printed when it does not start. */
+    load(edits: ProjectEdits): Promise<Loaded>;
+    stop(loaded: Loaded): Promise<void>;
+    /** The workspace a load opened as. */
+    opened(loaded: Loaded): StudioWorkspace;
+}
+export interface EditedSession<Loaded> {
+    /** Makes the running load the one that holds this workspace's edits. `saved` is the files' load. */
+    open(workspace: StudioWorkspace, saved: Loaded): Promise<EditedAnswer>;
+    /** The load that answers now, when there is one. */
+    running(): Loaded | undefined;
+    /** Ends the load: the files changed, so its edits lie over files that are gone. */
+    close(): Promise<void>;
+}
+export declare function createEditedSession<Loaded>(host: EditedHost<Loaded>): EditedSession<Loaded>;