@theoremjs/studio 0.0.0-stage → 0.3.2

package/runtime.js

@@ -0,0 +1,387 @@
+import { labelText, registerTraceDestination, resolveObservabilityPolicy, TheoremError, z, } from '@theoremjs/agents';
+import { gatedToolsFromEvents, interfaceFromProfile, promotedToolIdsFromEvents, toolSnapshotFromEvents, } from '@theoremjs/agents/interface';
+import { answerGatedCall, memoryCredentialSource, } from '@theoremjs/agents/kernel';
+import { decisionAssets, withFailedTraces, } from '@theoremjs/react/client';
+import { answerReply, checkRequest, conversationView, messageReply, openConversation, postedMessage, readerConversationHost, rewindConversation, startConversation, statelessRefusal, steerStage, waitingCalls, } from '@theoremjs/react/server';
+import { STUDIO_TRACE_DESTINATION } from "./policy.js";
+import { studioReader } from "./reader.js";
+import { agentCallHook, runtimeProvider, studioScope, } from "./runtime-scope.js";
+import { createStudioTraceRouter } from "./traces.js";
+// Profiles that write to the studio destination get their records back on the run's own stream.
+export const studioTraces = createStudioTraceRouter();
+registerTraceDestination(STUDIO_TRACE_DESTINATION, studioTraces.sink);
+/**
+ * Streams one run's lines, then the trace records it wrote. The kernel writes
+ * a run's records before the run returns or throws, so a failed run still
+ * delivers them ahead of its failure.
+ */
+async function* withRunTraces(run) {
+    const records = [];
+    const traces = studioTraces.route((record) => records.push(record));
+    let failure;
+    try {
+        yield* run(traces.metadata);
+    }
+    catch (error) {
+        failure = { error };
+    }
+    finally {
+        traces.close();
+    }
+    for (const record of records)
+        yield { type: 'trace', record };
+    if (failure)
+        throw failure.error;
+}
+function assertNotLiveProfile(profileType, action) {
+    if (profileType === 'live') {
+        throw new TheoremError('request', `Studio ${action} does not support live profiles.`);
+    }
+}
+export { newConversationKey } from "./conversation-key.js";
+/** The draft's scope and its chat: the conversation host, or none for a stateless profile. */
+async function studioChat(draft, conversations) {
+    const { scope, profile } = await studioScope(draft.profile, draft.customTools, draft.structured, draft.runtime, draft.dependencies);
+    assertNotLiveProfile(profile.type, 'turn runner — use runSession');
+    const iface = interfaceFromProfile(profile, scope.tools);
+    if (iface.type === 'live') {
+        // labels-exempt: internal diagnostic; the user reads error.request
+        throw new TheoremError('request', 'A studio chat does not run a live profile.');
+    }
+    const host = iface.providerContinuation?.history === 'stateless'
+        ? undefined
+        : readerConversationHost({
+            ...conversations,
+            profile,
+            clientEvents: studioReader(draft.runtime),
+        });
+    return { scope, profile, iface, host };
+}
+/** How a chat request runs the model for a reply, on the draft's scope. */
+function studioRunner(args) {
+    const { scope, profile, runtime, metadata, signal } = args;
+    return {
+        run: (turn) => scope.runTurn({
+            profile: profile.id,
+            execution: runtime.execution,
+            pageExecution: runtime.pageExecution,
+            metadata,
+            input: turn.input,
+            providerState: turn.providerState,
+            sessionPermissions: args.sessionPermissions,
+            resolveHost: runtime.resolveHost,
+            signal,
+            ...(turn.model ? { model: turn.model } : {}),
+            ...(turn.effort ? { effort: turn.effort } : {}),
+            ...(args.onStage ? { onStage: args.onStage } : {}),
+            onAgentCall: agentCallHook(scope, runtime),
+        }, runtimeProvider(runtime, scope, profile, turn.model)),
+        async compact(history, tokens, model) {
+            const compacted = await scope.compactHistory({ profile: profile.id, history, tokens, signal, ...(model ? { model } : {}) }, runtimeProvider(runtime, scope, profile, model));
+            return compacted?.history;
+        },
+        ...(args.model ? { model: args.model } : {}),
+        ...(args.effort ? { effort: args.effort } : {}),
+        signal,
+    };
+}
+/**
+ * The paused call as the stored reply holds it, answered. The studio keeps no
+ * session, so the call's gate comes from the draft's registered tool; only the
+ * permissions the page granted come from the browser.
+ */
+function answerPaused(scope, profile, opened, request, sessionPermissions, runtime) {
+    const events = opened.conversation.paused?.events ?? [];
+    const call = gatedToolsFromEvents(events).find((gated) => gated.callId === request.callId && gated.operationId === request.operationId);
+    // labels-exempt: internal diagnostic; the user reads error.internal
+    if (!call)
+        throw new TheoremError('internal', `the paused reply holds no call ${request.callId}`);
+    return answerReplayed(scope, profile, request, {
+        name: call.name,
+        input: call.arguments,
+        gateKind: call.gateKind,
+        snapshot: toolSnapshotFromEvents(events),
+        promoted: promotedToolIdsFromEvents(events),
+        ...(opened.conversation.paused?.model ? { model: opened.conversation.paused.model } : {}),
+        ...(sessionPermissions ? { sessionPermissions } : {}),
+    }, runtime);
+}
+/**
+ * One message, run against the conversation the host keeps: the paused calls it
+ * walks away from settle first, then the reply runs.
+ */
+export async function* streamStudioTurn(args) {
+    const { request, runtime, signal } = args;
+    const { scope, profile, iface, host } = await studioChat(args, args.conversations);
+    const message = postedMessage(iface, request.input);
+    const sessionPermissions = request.replay?.sessionPermissions;
+    if (!host && request.conversation !== undefined)
+        throw statelessRefusal('continue');
+    if (!host && request.abandon)
+        throw statelessRefusal('walk away from');
+    const opened = host
+        ? await openConversation(host, request.conversation, { kind: 'message', ...(request.abandon ? { abandon: request.abandon } : {}) }, 
+        // why: The draft is the visitor's own, so the page's transcript is as much theirs as the store's copy.
+        request.transcript ? { profile, blocks: request.transcript } : undefined)
+        : undefined;
+    // Answered up front, so a refused call starts nothing.
+    const walked = opened
+        ? (request.abandon ?? []).map((reference) => ({
+            reference,
+            invoke: answerPaused(scope, profile.id, opened, { ...reference, decision: 'abandon' }, sessionPermissions, runtime),
+        }))
+        : [];
+    // Random and picked here, so only the run's own browser can steer it.
+    const inbox = globalThis.crypto.randomUUID();
+    await args.steer.open(inbox);
+    const steerLine = { type: 'steer_inbox', inbox };
+    yield steerLine;
+    try {
+        yield* withRunTraces((metadata) => {
+            const runner = studioRunner({
+                scope,
+                profile,
+                runtime,
+                metadata,
+                sessionPermissions,
+                ...(request.model ? { model: request.model } : {}),
+                ...(request.effort ? { effort: request.effort } : {}),
+                signal,
+                onStage: steerStage(args.steer, inbox),
+            });
+            if (!host || !opened) {
+                return runner.run({ input: message.input, model: request.model, effort: request.effort });
+            }
+            const walkAway = walked.map(({ reference, invoke }) => ({
+                ...reference,
+                events: scope.invokeTool({ ...invoke, metadata, signal }),
+            }));
+            return messageReply({ host, opened, message, walkAway, runner });
+        });
+    }
+    finally {
+        await args.steer.close(inbox);
+    }
+}
+/** The model's input to the paused call, as the browser replays it. */
+const modelArguments = z.record(z.string(), z.unknown());
+/** The gate a tool waits on: its permission tier, and the slot a sign-in gate fills. */
+function heldGate(tool) {
+    const auth = 'auth' in tool ? tool.auth : undefined;
+    return {
+        permission: tool.permission,
+        ...(auth
+            ? {
+                auth: { slot: auth.slot, authType: auth.type, service: auth.service },
+            }
+            : {}),
+    };
+}
+/**
+ * The user's answer to a paused call, as `replay` holds it. The studio keeps no
+ * session; its gate comes from the draft's registered tool, and the answer
+ * settles it by the rule every Theorem host uses. Returns the run that settles
+ * it, less its trace metadata.
+ */
+function answerReplayed(scope, profile, request, replay, runtime) {
+    const tool = replay.name === undefined ? undefined : scope.tools.get(replay.name);
+    if (!tool) {
+        // labels-exempt: internal diagnostic; the user reads error.request
+        throw new TheoremError('request', 'invoke: the paused call names no tool in this draft');
+    }
+    const answered = answerGatedCall(request, {
+        name: tool.name,
+        arguments: checkRequest(modelArguments, replay.input, 'replayed call input'),
+        gateKind: replay.gateKind,
+        ...heldGate(tool),
+    }, replay.sessionPermissions ?? []);
+    return {
+        profile,
+        name: tool.name,
+        callId: request.callId,
+        operationId: request.operationId,
+        input: answered.input,
+        resume: answered.resume,
+        ...(answered.page ? { page: answered.page } : {}),
+        sessionPermissions: answered.sessionPermissions,
+        ...(answered.typed
+            ? {
+                credentials: memoryCredentialSource({
+                    [answered.typed.slot]: answered.typed.credential,
+                }),
+            }
+            : {}),
+        snapshot: replay.snapshot,
+        promoted: replay.promoted,
+        model: replay.model,
+        resolveHost: runtime.resolveHost,
+        execution: runtime.execution,
+        pageExecution: runtime.pageExecution,
+        onAgentCall: agentCallHook(scope, runtime),
+    };
+}
+function answerOf(answer) {
+    const { gateId, operationId, decision, input, secret, page } = answer;
+    return { callId: gateId, operationId, decision, input, secret, page };
+}
+/** A paused call the browser replays, answered: a host draft's call, or a stateless chat's. */
+function replayedInvoke(scope, profile, answer, runtime, signal) {
+    const invoke = answerReplayed(scope, profile, answerOf(answer), answer.replay ?? {}, runtime);
+    return withRunTraces((metadata) => scope.invokeTool({ ...invoke, metadata, signal }));
+}
+/**
+ * The user's answer to a paused call. In a kept conversation the reply goes on
+ * in the same stream once no call waits; otherwise the stream is the call's.
+ */
+export async function* streamStudioInvoke(args) {
+    const { answer, runtime, signal } = args;
+    const { scope, profile, host } = await studioChat(args, args.conversations);
+    const request = answerOf(answer);
+    const sessionPermissions = answer.replay?.sessionPermissions;
+    if (!host) {
+        if (answer.conversation !== undefined)
+            throw statelessRefusal('continue');
+        yield* replayedInvoke(scope, profile.id, answer, runtime, signal);
+        return;
+    }
+    if (answer.conversation === undefined)
+        throw statelessRefusal('continue');
+    const opened = await openConversation(host, answer.conversation, {
+        kind: 'answer',
+        call: { callId: request.callId, operationId: request.operationId },
+    });
+    const invoke = answerPaused(scope, profile.id, opened, request, sessionPermissions, runtime);
+    yield* withRunTraces((metadata) => answerReply({
+        host,
+        opened,
+        call: { callId: request.callId, operationId: request.operationId },
+        settling: scope.invokeTool({ ...invoke, metadata, signal }),
+        runner: studioRunner({
+            scope,
+            profile,
+            runtime,
+            metadata,
+            sessionPermissions,
+            signal,
+        }),
+    }));
+}
+/** A conversation that opens on blocks the page wrote, read first by the draft's guardrails: its ref and view. */
+export async function startStudioConversation(draft, conversations, blocks) {
+    const { profile, host } = await studioChat(draft, conversations);
+    if (!host)
+        throw statelessRefusal('start');
+    const { ref, view } = await startConversation(host, profile, blocks);
+    return { conversation: ref, view };
+}
+/** The conversation under a ref, as the page draws it. */
+export async function studioConversation(draft, conversations, request) {
+    const { host } = await studioChat(draft, conversations);
+    if (!host)
+        throw statelessRefusal('read');
+    const opened = await openConversation(host, request.conversation, { kind: 'read' });
+    return conversationView(host, opened.conversation);
+}
+/** The conversation cut after one block; a reply that waits on gates is walked away from first. */
+export async function rewindStudio(draft, conversations, request, signal) {
+    const { scope, profile, host } = await studioChat(draft, conversations);
+    if (!host)
+        throw statelessRefusal('rewind');
+    const opened = await openConversation(host, request.conversation, {
+        kind: 'rewind',
+        at: request.at,
+    });
+    const walkAway = waitingCalls(opened.conversation).map((reference) => {
+        const invoke = answerPaused(scope, profile.id, opened, { ...reference, decision: 'abandon' }, undefined, draft.runtime);
+        return { ...reference, events: scope.invokeTool({ ...invoke, signal }) };
+    });
+    const next = await rewindConversation({ host, opened, at: request.at, walkAway });
+    if (next.ref === null)
+        throw new TheoremError('internal', labelText('error.internal'));
+    return { conversation: next.ref, view: conversationView(host, next.conversation) };
+}
+/** The user's answer to a host draft's paused call: the studio keeps no session, so the browser replays it. */
+export async function* streamStudioHostInvoke(args) {
+    const { scope, profile } = await hostScope(args);
+    yield* replayedInvoke(scope, profile.id, args.answer, args.runtime, args.signal);
+}
+/** A host draft's scope; any other profile is refused. */
+async function hostScope(draft) {
+    const opened = await studioScope(draft.profile, draft.customTools, undefined, draft.runtime, draft.dependencies);
+    if (opened.profile.type !== 'host') {
+        // labels-exempt: internal diagnostic; the user reads error.request
+        throw new TheoremError('request', 'Studio calls run host profiles only.');
+    }
+    return opened;
+}
+/** One call of a host draft's tool, streamed. */
+export async function* streamStudioCall(args) {
+    const { scope, profile } = await hostScope(args);
+    yield* withRunTraces((metadata) => scope.invokeTool({
+        profile: profile.id,
+        execution: args.runtime.execution,
+        pageExecution: args.runtime.pageExecution,
+        name: args.call.name,
+        input: args.call.input,
+        sessionPermissions: args.sessionPermissions,
+        resolveHost: args.runtime.resolveHost,
+        onAgentCall: agentCallHook(scope, args.runtime),
+        signal: args.signal,
+        metadata,
+    }));
+}
+export { studioScope } from "./runtime-scope.js";
+/** The records a preview writes, and the sink that keeps them when its profile records traces. */
+function collectTraces(observability) {
+    const traces = [];
+    if (!observability || !resolveObservabilityPolicy(observability).record)
+        return { traces };
+    const sink = {
+        write: (record) => {
+            traces.push(record);
+            return Promise.resolve();
+        },
+    };
+    return { traces, sink };
+}
+/** Both hosts run decisions through the kernel; the browser supplies its provider vault. */
+export async function runStudioDecision(payload, state, options, signal, assets) {
+    const { scope, profile } = await studioScope(payload.profile, [], undefined, {
+        mode: 'byok',
+    });
+    const { traces, sink } = collectTraces(profile.observability);
+    try {
+        const result = await scope.runDecision({
+            profile: profile.id,
+            state,
+            questions: payload.questions ?? {},
+            assets: decisionAssets(payload.images, assets),
+            signal,
+        }, { ...options, ...(sink ? { sink } : {}) });
+        return { result, traces };
+    }
+    catch (err) {
+        // The kernel traces a decision however it ends; the failure carries what it left.
+        throw withFailedTraces(err, traces);
+    }
+}
+/** Runs one embedding preview and returns its normalized result with the records it wrote. */
+export async function runStudioEmbedding(payload, request, runtime) {
+    const { scope, profile } = await studioScope(payload.profile, payload.customTools, payload.structured, runtime, payload.dependencies);
+    if (profile.type !== 'embedding') {
+        throw new TheoremError('request', 'Studio embedding runs require an embedding profile.');
+    }
+    const { traces, sink } = collectTraces(profile.observability);
+    try {
+        const result = await scope.runEmbedding({ ...request, profile: profile.id }, {
+            ...runtimeProvider(runtime, scope, profile, request.model),
+            ...(sink ? { sink } : {}),
+        });
+        return { result, traces };
+    }
+    catch (err) {
+        throw withFailedTraces(err, traces);
+    }
+}
+export { failedDecisionTraces, withFailedTraces } from '@theoremjs/react/client';
+export { studioKeySlots } from "./browser-connection.js";

package/section-notes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a section of the studio's profile editor says that the catalog doc
+ * of the field it edits does not: how the editor works, and what the
+ * studio does. The catalog doc is on the field's hover; a note never repeats it.
+ */
+declare const SECTION_NOTES: {
+    readonly models: "Add a model here, then select its binding in the tree to configure it.";
+    readonly 'models.decision': "A decision uses one model. Select its binding in the tree to configure it.";
+    readonly decisionModel: "This binding answers the questions configured under Decision.";
+    readonly slots: "Each slot's picker sets what the preview sends. It is not saved in the profile.";
+    readonly context: "Preview is what the studio sends as the page. It is not saved in the profile.";
+    readonly compaction: "The studio's chat compacts only before a turn.";
+    readonly quota: "Studio runs are not counted.";
+    readonly 'detect.mixed': "Actions differ by boundary.";
+    readonly 'detect.source.theorem': "Theorem's patterns only.";
+    readonly 'detect.source.mine': "Your patterns only.";
+    readonly 'detect.source.both': "Theorem's patterns and yours.";
+    readonly 'detect.own': "Detectors you define.";
+    readonly 'detect.try': "Sample text is not saved.";
+    readonly 'detect.try.off': "Set to Ignore at every boundary tested. Nothing reads the sample.";
+    readonly 'traces.storage': "Your host's trace store uses these. The studio's stores nothing.";
+    readonly 'tools.host': "What the host runs. Each call names one.";
+    readonly 'tool.test.http': "Sends one real {method} request with the sample input.";
+    readonly 'tool.test.mcp': "Asks the server which tools it has.";
+    readonly 'tool.host': "What a call runs, and what the console says it does.";
+    readonly 'tool.headers': "Headers are saved in the profile, so keep secrets under Auth.";
+    readonly 'tool.auth': "The studio stores no credential: at a sign-in gate you type one for that call only.";
+    readonly 'decision.questions': "Asked together in one call, answered in this order.";
+    readonly connection: "Kept in this tab. Sent directly to the provider.";
+};
+/** The note for `id`, each `{name}` in `fill` replaced by its value. */
+declare function sectionNote(id: keyof typeof SECTION_NOTES, fill?: Readonly<Record<string, string>>): string;
+export { sectionNote };

package/section-notes.js

@@ -0,0 +1,38 @@
+/**
+ * What a section of the studio's profile editor says that the catalog doc
+ * of the field it edits does not: how the editor works, and what the
+ * studio does. The catalog doc is on the field's hover; a note never repeats it.
+ */
+const SECTION_NOTES = {
+    models: 'Add a model here, then select its binding in the tree to configure it.',
+    'models.decision': 'A decision uses one model. Select its binding in the tree to configure it.',
+    decisionModel: 'This binding answers the questions configured under Decision.',
+    slots: "Each slot's picker sets what the preview sends. It is not saved in the profile.",
+    context: 'Preview is what the studio sends as the page. It is not saved in the profile.',
+    compaction: "The studio's chat compacts only before a turn.",
+    quota: 'Studio runs are not counted.',
+    'detect.mixed': 'Actions differ by boundary.',
+    'detect.source.theorem': "Theorem's patterns only.",
+    'detect.source.mine': 'Your patterns only.',
+    'detect.source.both': "Theorem's patterns and yours.",
+    'detect.own': 'Detectors you define.',
+    'detect.try': 'Sample text is not saved.',
+    'detect.try.off': 'Set to Ignore at every boundary tested. Nothing reads the sample.',
+    'traces.storage': "Your host's trace store uses these. The studio's stores nothing.",
+    'tools.host': 'What the host runs. Each call names one.',
+    'tool.test.http': 'Sends one real {method} request with the sample input.',
+    'tool.test.mcp': 'Asks the server which tools it has.',
+    'tool.host': 'What a call runs, and what the console says it does.',
+    'tool.headers': 'Headers are saved in the profile, so keep secrets under Auth.',
+    'tool.auth': 'The studio stores no credential: at a sign-in gate you type one for that call only.',
+    'decision.questions': 'Asked together in one call, answered in this order.',
+    connection: 'Kept in this tab. Sent directly to the provider.',
+};
+/** The note for `id`, each `{name}` in `fill` replaced by its value. */
+function sectionNote(id, fill = {}) {
+    let note = SECTION_NOTES[id];
+    for (const [name, value] of Object.entries(fill))
+        note = note.replaceAll(`{${name}}`, value);
+    return note;
+}
+export { sectionNote };

package/serve-page.mjs

@@ -0,0 +1,96 @@
+/**
+ * Serves the installed package's built page, as Vite serves the sources in the repo:
+ *
+ *   node serve-page.mjs --port <port> --project <the project server's /api/studio address>
+ *
+ * Only this machine reaches it. Every response carries the page's headers (`page.mjs`). A path
+ * that names no file is the page itself, so a run tab's address opens the screen.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BUILT_PAGE, PAGE_BASE, PAGE_HEADERS, PROJECT_PLACEHOLDER } from './page.mjs';
+
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), BUILT_PAGE);
+const PAGE_FILE = path.join(root, 'index.html');
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.wasm': 'application/wasm',
+};
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const at = args.indexOf(`--${name}`);
+  return at === -1 ? undefined : args[at + 1];
+};
+const port = Number(flag('port'));
+const project = flag('project');
+if (!Number.isInteger(port) || !project) {
+  console.error('usage: node serve-page.mjs --port <port> --project <address>');
+  process.exit(2);
+}
+
+const page = readFileSync(PAGE_FILE, 'utf8').replaceAll(PROJECT_PLACEHOLDER, project);
+
+/** The build's files, each with the path a request names it by, less the page (served with its project filled in). Nothing else is ever read. */
+const FILES = [];
+(function list(dir, named) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory()) list(file, `${named}${entry.name}/`);
+    else if (entry.isFile() && file !== PAGE_FILE) FILES.push([`${named}${entry.name}`, file]);
+  }
+})(root, '');
+
+/** The built file a request names, or undefined for the page itself (a malformed path too). */
+function fileFor(pathname) {
+  let relative;
+  try {
+    relative = decodeURIComponent(pathname.slice(PAGE_BASE.length));
+  } catch {
+    return undefined;
+  }
+  // why: the request only picks among the build's own files; what is read comes from the list, never from the address.
+  for (const [name, file] of FILES) {
+    if (name === relative) return { body: readFileSync(file), type: TYPES[path.extname(file)] };
+  }
+  return undefined;
+}
+
+/** What a request is answered: the way to the page, nothing, or a built file or the page. */
+function answerFor(method, pathname) {
+  if (pathname === '/' || `${pathname}/` === PAGE_BASE) {
+    return { status: 302, headers: { ...PAGE_HEADERS, Location: PAGE_BASE } };
+  }
+  if (!readsPage(method, pathname)) return { status: 404, headers: PAGE_HEADERS };
+  return served(method, pathname);
+}
+
+/** Whether a request reads something of the page's. */
+function readsPage(method, pathname) {
+  return (method === 'GET' || method === 'HEAD') && pathname.startsWith(PAGE_BASE);
+}
+
+/** The built file a read names, or the page itself; a HEAD has no body. */
+function served(method, pathname) {
+  const file = fileFor(pathname);
+  const type = file ? (file.type ?? 'application/octet-stream') : TYPES['.html'];
+  const body = method === 'HEAD' ? undefined : (file?.body ?? page);
+  return { status: 200, headers: { ...PAGE_HEADERS, 'Content-Type': type }, body };
+}
+
+createServer((request, response) => {
+  const { pathname } = new URL(request.url ?? '/', 'http://localhost');
+  const { status, headers, body } = answerFor(request.method, pathname);
+  response.writeHead(status, headers).end(body);
+}).listen(port, '127.0.0.1');

package/server/draft-decide.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `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 { z } from '@theoremjs/agents';
+import type { LentDecisionLimits } from '../lent-keys.ts';
+import type { LentRuntime } from './draft-handler.ts';
+/** The decision request lent keys answer: only the fields a studio decision compiles to, within `limits`. A setting left out stays out. */
+export declare function decisionRequestSchema(limits: LentDecisionLimits): z.ZodObject<{
+    profile: z.ZodObject<{
+        type: z.ZodLiteral<"decision">;
+        id: z.ZodString;
+        identity: z.ZodObject<{
+            handle: z.ZodString;
+        }, z.core.$strip>;
+        models: z.ZodRecord<z.ZodString, z.ZodObject<{
+            protocol: z.ZodLiteral<"systemOne">;
+            provider: z.ZodString;
+            apiId: z.ZodString;
+            keySlot: z.ZodOptional<z.ZodString>;
+            fallbackKeySlot: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        inputs: z.ZodObject<{
+            state: z.ZodLiteral<"json">;
+            maxStateBytes: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        decision: z.ZodObject<{
+            contract: z.ZodString;
+        }, z.core.$strip>;
+        observability: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    questions: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"choice">;
+        instructions: z.ZodString;
+        criteria: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"score">;
+        instructions: z.ZodString;
+        criteria: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"noul">;
+        instructions: z.ZodString;
+        criteria: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"box">;
+        instructions: z.ZodString;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>;
+    state: z.ZodUnknown;
+    assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        mimeType: z.ZodEnum<{
+            "image/jpeg": "image/jpeg";
+            "image/png": "image/png";
+        }>;
+        data: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** What a decision on lent keys runs with. */
+export type DraftDecideOptions = {
+    runtime: LentRuntime;
+    /** Spends the decision once the request is one the keys would answer; throws to refuse it. */
+    spend: (request: Request) => Promise<void>;
+};
+/** Answers one decision on the lent keys, with the records it wrote; a failed one is traced too. */
+export declare function draftDecide(request: Request, options: DraftDecideOptions): Promise<Response>;