@manta-eu/horns-server 0.1.3 → 0.2.0

package/dist/studio-agent.js

@@ -0,0 +1,44 @@
+import { tool } from "ai";
+import { isPresent } from "@manta-eu/lib/present";
+import { studioToolDefinitions, studioToolSchemas, studioToolsByMode, } from "@manta-eu/horns/studio";
+/** What a tool call does, apart from the SDK wrapper around it. Generic, so input and handler stay bound. */
+export async function runStudioTool(handler, input, args) {
+    const outcome = await handler(input, {
+        draft: args.draft(),
+        mode: args.mode,
+        ...(args.signal ? { signal: args.signal } : {}),
+    });
+    if (isPresent(outcome.draft))
+        args.onDraft(outcome.draft);
+    return outcome.content;
+}
+function studioTool(name, description, handler, args) {
+    return tool({
+        description,
+        inputSchema: studioToolSchemas[name],
+        execute: (input) => runStudioTool(handler, input, args),
+    });
+}
+/**
+ * Tools the page runs, not the worker. Declared with no `execute`, so the harness sends the call to the
+ * browser and waits for what it answers.
+ */
+export function pageToolSet(names) {
+    const described = new Map(studioToolDefinitions("build").map((one) => [one.function.name, one.function.description]));
+    return Object.fromEntries(names.map((name) => [name, pageTool(name, described.get(name) ?? name)]));
+}
+function pageTool(name, description) {
+    return tool({ description, inputSchema: studioToolSchemas[name] });
+}
+/** The tools a mode offers, as the SDK wants them: zod in, the handler's words out. */
+export function studioToolSet(args) {
+    const described = new Map(studioToolDefinitions(args.mode).map((definition) => [definition.function.name, definition.function.description]));
+    const entries = studioToolsByMode[args.mode].flatMap((name) => {
+        const handler = args.handlers[name];
+        // A tool with no handler costs the model a step and teaches it to distrust the list.
+        if (handler === undefined)
+            return [];
+        return [[name, studioTool(name, described.get(name) ?? name, handler, args)]];
+    });
+    return Object.fromEntries(entries);
+}

package/dist/studio-deps.d.ts

@@ -0,0 +1,15 @@
+import type { Realm } from "@manta-eu/horns";
+import type { Shape } from "@manta-eu/horns/shapes";
+import type { ComponentApiLookup, TypeProblem } from "@manta-eu/horns/studio";
+export type StudioDeps = {
+    /** The realm's SHACL shapes, which is what a turn reads classes from. */
+    shapes: (realm: Realm) => readonly Shape[];
+    componentApi?: ComponentApiLookup;
+    typecheck?: (source: string) => readonly TypeProblem[];
+};
+/**
+ * A Durable Object is built by the runtime, so it takes no constructor arguments: a host registers what
+ * the Studio reads at module scope instead, beside where it exports the agent.
+ */
+export declare function provideStudioDeps(deps: StudioDeps): void;
+export declare function studioDeps(): StudioDeps;

package/dist/studio-deps.js

@@ -0,0 +1,14 @@
+let registered;
+/**
+ * A Durable Object is built by the runtime, so it takes no constructor arguments: a host registers what
+ * the Studio reads at module scope instead, beside where it exports the agent.
+ */
+export function provideStudioDeps(deps) {
+    registered = deps;
+}
+export function studioDeps() {
+    if (registered === undefined) {
+        throw new Error("provideStudioDeps was never called; the Studio has no shapes to read.");
+    }
+    return registered;
+}

package/dist/studio-model.d.ts

@@ -0,0 +1,30 @@
+import type { LanguageModel } from "ai";
+export declare const aiGatewayHost = "gateway.ai.cloudflare.com";
+export type StudioModelEnv = {
+    HORNS_CRITIC_BASE_URL?: string;
+    HORNS_CRITIC_MODEL?: string;
+    HORNS_LLM_BASE_URL?: string;
+    HORNS_LLM_MODEL?: string;
+    CLOUDFLARE_AI_GATEWAY_TOKEN?: string;
+    CLOUDFLARE_ENV?: string;
+    GOOGLE_VERTEX_PROJECT?: string;
+    GOOGLE_VERTEX_LOCATION?: string;
+    GOOGLE_VERTEX_MODEL?: string;
+    VERTEX_SERVICE_ACCOUNT?: string;
+};
+/** `monitored` says whether the call lands in the AI Gateway's log. */
+export type StudioModelChoice = {
+    ok: true;
+    model: LanguageModel;
+    monitored: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Vertex where a realm's agreement bars the gateway, the gateway otherwise. */
+export declare function studioModel(env: StudioModelEnv, fetcher?: typeof fetch): StudioModelChoice;
+/**
+ * The critic: its own route where one is named, the Studio's own model otherwise. It judges a picture, so
+ * name a route where the Studio's model has no image input.
+ */
+export declare function criticModel(env: StudioModelEnv, fetcher?: typeof fetch): StudioModelChoice;

package/dist/studio-model.js

@@ -0,0 +1,104 @@
+import { createVertexAnthropic } from "@ai-sdk/google-vertex/anthropic/edge";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { isPresent } from "@manta-eu/lib/present";
+import { createVertexAccessTokens, parseVertexServiceAccount } from "@manta-eu/horns/studio";
+export const aiGatewayHost = "gateway.ai.cloudflare.com";
+const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
+function vertexModel(env, fetcher) {
+    const project = env.GOOGLE_VERTEX_PROJECT;
+    const location = env.GOOGLE_VERTEX_LOCATION;
+    const model = env.GOOGLE_VERTEX_MODEL;
+    const serviceAccount = env.VERTEX_SERVICE_ACCOUNT;
+    const named = [project, location, model, serviceAccount].filter(isPresent).length;
+    if (named === 0)
+        return undefined;
+    if (!isPresent(project) || !isPresent(location) || !isPresent(model) || !isPresent(serviceAccount)) {
+        return {
+            ok: false,
+            reason: "Vertex needs GOOGLE_VERTEX_PROJECT, GOOGLE_VERTEX_LOCATION, GOOGLE_VERTEX_MODEL and VERTEX_SERVICE_ACCOUNT.",
+        };
+    }
+    try {
+        const vertex = createVertexAnthropic({
+            project,
+            location,
+            generateAuthToken: createVertexAccessTokens({
+                account: parseVertexServiceAccount(serviceAccount),
+                ...(fetcher ? { fetch: fetcher } : {}),
+            }),
+            ...(fetcher ? { fetch: fetcher } : {}),
+        });
+        // Not in the gateway's log because it never reaches it, which is the point where a realm's agreement
+        // bars that log. Google Cloud's audit log accounts for these.
+        return { ok: true, monitored: false, model: vertex(model) };
+    }
+    catch (caught) {
+        // Only the service account's shape can fail here, and it must not be echoed.
+        return { ok: false, reason: caught instanceof Error ? caught.message : "The Vertex service account is unusable." };
+    }
+}
+/** Vertex where a realm's agreement bars the gateway, the gateway otherwise. */
+export function studioModel(env, fetcher) {
+    const vertex = vertexModel(env, fetcher);
+    if (vertex !== undefined)
+        return vertex;
+    const baseURL = env.HORNS_LLM_BASE_URL;
+    const model = env.HORNS_LLM_MODEL;
+    if (!isPresent(baseURL) || !isPresent(model)) {
+        return { ok: false, reason: "HORNS_LLM_BASE_URL and HORNS_LLM_MODEL must both be set." };
+    }
+    if (!URL.canParse(baseURL))
+        return { ok: false, reason: "HORNS_LLM_BASE_URL is not a URL." };
+    const { hostname, protocol } = new URL(baseURL);
+    // A stub on this machine, which tests point at. Unmonitored by definition: there is no gateway in front.
+    if (loopbackHosts.has(hostname)) {
+        const local = createOpenAICompatible({ name: "horns-local", baseURL, ...(fetcher ? { fetch: fetcher } : {}) });
+        return { ok: true, monitored: false, model: local(model) };
+    }
+    if (protocol !== "https:" || hostname !== aiGatewayHost) {
+        return {
+            ok: false,
+            reason: `HORNS_LLM_BASE_URL must be the AI Gateway (${aiGatewayHost}) so model calls are logged, not ${hostname}.`,
+        };
+    }
+    const gatewayToken = env.CLOUDFLARE_AI_GATEWAY_TOKEN;
+    if (!isPresent(gatewayToken)) {
+        return { ok: false, reason: "CLOUDFLARE_AI_GATEWAY_TOKEN must be set to call the AI Gateway." };
+    }
+    const gateway = createOpenAICompatible({
+        name: "horns-gateway",
+        baseURL,
+        // The gateway holds the provider key; one of ours would override it.
+        headers: {
+            "cf-aig-authorization": `Bearer ${gatewayToken}`,
+            // No user identifiers: the log is shared.
+            "cf-aig-metadata": JSON.stringify({ app: "manta-horns", environment: env.CLOUDFLARE_ENV ?? "local" }),
+        },
+        ...(fetcher ? { fetch: fetcher } : {}),
+    });
+    return { ok: true, monitored: true, model: gateway(model) };
+}
+/**
+ * The critic: its own route where one is named, the Studio's own model otherwise. It judges a picture, so
+ * name a route where the Studio's model has no image input.
+ */
+export function criticModel(env, fetcher) {
+    const baseURL = env.HORNS_CRITIC_BASE_URL;
+    const model = env.HORNS_CRITIC_MODEL;
+    if (!isPresent(baseURL) && !isPresent(model))
+        return studioModel(env, fetcher);
+    // One of the pair alone is a misconfiguration, and falling back would hide it.
+    if (!isPresent(baseURL) || !isPresent(model)) {
+        return { ok: false, reason: "HORNS_CRITIC_BASE_URL and HORNS_CRITIC_MODEL must both be set, or neither." };
+    }
+    // Every Vertex setting cleared: a named critic route is the route.
+    return studioModel({
+        ...env,
+        HORNS_LLM_BASE_URL: baseURL,
+        HORNS_LLM_MODEL: model,
+        GOOGLE_VERTEX_PROJECT: undefined,
+        GOOGLE_VERTEX_LOCATION: undefined,
+        GOOGLE_VERTEX_MODEL: undefined,
+        VERTEX_SERVICE_ACCOUNT: undefined,
+    }, fetcher);
+}

package/dist/studio-opening.d.ts

@@ -0,0 +1,42 @@
+import { type Realm } from "@manta-eu/horns";
+import { type DevSessionEnv } from "./dev-session.ts";
+import { type MantaSessionState } from "./session.ts";
+/** Handed over when the connection opens: the worker has already authorized it. */
+export type StudioAgentProps = {
+    session: MantaSessionState;
+    datastoreId: string;
+    /** Narrowed below: props cross a boundary, so this arrives as whatever the host sent. */
+    realm: string;
+};
+export type StudioOpening = {
+    session: MantaSessionState;
+    datastoreId: string;
+    realm: Realm;
+};
+/**
+ * The header a turn's authorization rides on.
+ *
+ * Not `onStart` props: those arrive when the object starts, so a reconnect to a live one keeps whatever
+ * the first connection brought. A header is read per request and cannot go stale.
+ */
+export declare const studioAuthHeader = "x-horns-studio-auth";
+export declare function serializeStudioOpening(opening: StudioOpening): string;
+export declare function readStudioOpening(request: Request): StudioOpening | undefined;
+/** What the worker handed over, checked. A turn without it is a turn nobody authorized. */
+export declare function studioOpening(props: StudioAgentProps | undefined): StudioOpening;
+export type StudioConversationEnv = DevSessionEnv & {
+    VITE_KEYCLOAK_REALM?: string;
+    MANTA_AGENTS_URL?: string;
+};
+/** One object per conversation per datastore: a name that crossed datastores would carry a draft with it. */
+export declare function studioConversationName(datastoreId: string, conversation: string): string;
+/**
+ * Who may open a Studio conversation, decided before the object is reached rather than inside it.
+ */
+export declare function authorizeStudioConversation(request: Request, env: StudioConversationEnv, datastoreId: string): Promise<{
+    ok: true;
+    props: StudioOpening;
+} | {
+    ok: false;
+    response: Response;
+}>;

package/dist/studio-opening.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { isRealm } from "@manta-eu/horns";
+import { isPresent } from "@manta-eu/lib/present";
+import { sameOriginDeniedResponse, signedOutMessage } from "./agents-proxy.js";
+import { datastoreAccessFor, datastoreNotGrantedMessage, grantsDatastore } from "./datastore-access.js";
+import { requestSession } from "./dev-session.js";
+import { isSignedIn } from "./session.js";
+/**
+ * The header a turn's authorization rides on.
+ *
+ * Not `onStart` props: those arrive when the object starts, so a reconnect to a live one keeps whatever
+ * the first connection brought. A header is read per request and cannot go stale.
+ */
+export const studioAuthHeader = "x-horns-studio-auth";
+export function serializeStudioOpening(opening) {
+    return JSON.stringify(opening);
+}
+export function readStudioOpening(request) {
+    const sent = request.headers.get(studioAuthHeader);
+    if (!isPresent(sent))
+        return undefined;
+    try {
+        const parsed = JSON.parse(sent);
+        return studioOpening(openingSchema.parse(parsed));
+    }
+    catch {
+        return undefined;
+    }
+}
+const openingSchema = z.object({
+    session: z.object({ upstreamCookies: z.record(z.string(), z.string()) }),
+    datastoreId: z.string().min(1),
+    realm: z.string().min(1),
+});
+/** What the worker handed over, checked. A turn without it is a turn nobody authorized. */
+export function studioOpening(props) {
+    if (props === undefined)
+        throw new Error("This Studio was reached without a session.");
+    if (!isRealm(props.realm))
+        throw new Error("This deployment has no realm configured.");
+    return { session: props.session, datastoreId: props.datastoreId, realm: props.realm };
+}
+/** One object per conversation per datastore: a name that crossed datastores would carry a draft with it. */
+export function studioConversationName(datastoreId, conversation) {
+    return `${datastoreId}/${conversation}`;
+}
+/**
+ * Who may open a Studio conversation, decided before the object is reached rather than inside it.
+ */
+export async function authorizeStudioConversation(request, env, datastoreId) {
+    const denied = sameOriginDeniedResponse(request);
+    if (denied)
+        return { ok: false, response: denied };
+    const session = requestSession(request, env);
+    if (!isPresent(session) || !isSignedIn(session)) {
+        return { ok: false, response: Response.json({ error: signedOutMessage }, { status: 401 }) };
+    }
+    const realm = env.VITE_KEYCLOAK_REALM;
+    if (!isPresent(realm) || !isRealm(realm)) {
+        return {
+            ok: false,
+            response: Response.json({ error: "This deployment has no realm configured." }, { status: 500 }),
+        };
+    }
+    const resolved = await datastoreAccessFor(env, session);
+    if (!resolved.ok)
+        return { ok: false, response: Response.json({ error: signedOutMessage }, { status: 401 }) };
+    if (!grantsDatastore(resolved.access, datastoreId)) {
+        return { ok: false, response: Response.json({ error: datastoreNotGrantedMessage }, { status: 403 }) };
+    }
+    return { ok: true, props: { session, datastoreId, realm } };
+}

package/dist/studio-routes.d.ts

@@ -2,11 +2,13 @@ import { Hono } from "hono";
 import { type Realm } from "@manta-eu/horns";
 import { type ComponentApiLookup, type TypeProblem } from "@manta-eu/horns/studio";
 import { type Shape } from "@manta-eu/horns/shapes";
-import { type StudioModelEnv, type StudioModelResult } from "./llm.ts";
+import { type UpstreamFetcher } from "./agents-proxy.ts";
+import { type StudioModelChoice, type StudioModelEnv } from "./studio-model.ts";
 import { type DevSessionEnv } from "./dev-session.ts";
 export type StudioRoutesEnv = DevSessionEnv & StudioModelEnv & {
     MANTA_AGENTS_URL?: string;
     VITE_KEYCLOAK_REALM?: string;
+    UPSTREAM?: UpstreamFetcher;
 };
 export type StudioRoutesDeps<Env extends StudioRoutesEnv> = {
     /** The realm's SHACL shapes, which is what a turn reads classes from. Absent shapes answer no classes. */
@@ -19,13 +21,20 @@ export type StudioRoutesDeps<Env extends StudioRoutesEnv> = {
     model?: (env: Env, context: {
         feature: string;
         datastoreId: string;
-    }) => StudioModelResult;
+    }) => StudioModelChoice;
     /** The critic's model, which can look at a picture. Absent, the critic reads the card as text instead. */
     criticModel?: (env: Env, context: {
         feature: string;
         datastoreId: string;
-    }) => StudioModelResult;
+    }) => StudioModelChoice;
 };
+/**
+ * How many model rounds one request may take.
+ *
+ * Twenty-four ran out on real work — fifteen queries and three repairs and the turn is over, which costs
+ * the person a whole round trip to say "continue". dyad allows a hundred tool-call steps and keeps only the
+ * last few chat turns in context; this is the same trade, sized for a worker request rather than a desktop.
+ */
 /**
  * How much of the conversation goes back to the model.
  *

package/dist/studio-routes.js

@@ -2,15 +2,14 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { isPresent } from "@manta-eu/lib/present";
 import { hornSchema, isRealm } from "@manta-eu/horns";
-import { acceptedSpecs, assembleStudioMessages, createDryRun, evaluateProposal, formatFailures, hornPatchOpSchema, buildUsefulContext, builtInSkills, datastoreFacts, evaluateShapeViewOnZoo, selectSkills, runShapeCoverage, runShapeViewTurn, adviseOnHorn, runStudioTurn, sampleShapeFillRates, studioReadHandlers, studioSystemPrompt, studioWriteHandlers, } from "@manta-eu/horns/studio";
+import { acceptedSpecs, createDryRun, evaluateProposal, formatFailures, hornPatchOpSchema, evaluateShapeViewOnZoo, runShapeCoverage, runShapeViewTurn, adviseOnHorn, sampleShapeFillRates, } from "@manta-eu/horns/studio";
 import { shapeLinks, shapeViewSpecSchema, termNotes } from "@manta-eu/horns/shapes";
 import { mantaReactCatalog } from "@manta-eu/horns-kit/catalog";
 import { shapeViewSpecs } from "@manta-eu/horns-kit/shape-views";
 import { sameOriginDeniedResponse, signedOutMessage } from "./agents-proxy.js";
 import { datastoreAccessFor, datastoreAccessUnavailableMessage, datastoreNotGrantedMessage, forgetDatastoreAccess, grantsDatastore, } from "./datastore-access.js";
 import { parseBody } from "./authorize.js";
-import { stageRule } from "./manta-rules.js";
-import { criticModelFromEnv, studioModelFromEnv } from "./llm.js";
+import { criticModel, studioModel } from "./studio-model.js";
 import { requestSession } from "./dev-session.js";
 import { ndjsonResponse } from "./ndjson.js";
 import { isSignedIn } from "./session.js";
@@ -23,7 +22,6 @@ const noStore = { "cache-control": "no-store" };
  * the person a whole round trip to say "continue". dyad allows a hundred tool-call steps and keeps only the
  * last few chat turns in context; this is the same trade, sized for a worker request rather than a desktop.
  */
-const turnStepLimit = 48;
 /**
  * How much of the conversation goes back to the model.
  *
@@ -52,10 +50,6 @@ const viewTurnRequestSchema = z.object({
     spec: shapeViewSpecSchema,
     messages: messagesSchema,
 });
-const turnRequestSchema = z.object({
-    horn: hornSchema,
-    messages: messagesSchema,
-});
 // One shape is a minute or two of watching. Three is the most anyone waits at a page before it stops being
 // live and becomes a job, and a job is what the script is for.
 const coverageRequestSchema = z.object({ limit: z.number().int().min(1).max(3).optional() });
@@ -107,85 +101,6 @@ export function studioRoutes(deps) {
         }
         return { ok: true, session, realm: configured, datastoreId };
     };
-    routes.post("/api/d/:datastoreId/studio", async (c) => {
-        const allowed = await context(c);
-        if (!allowed.ok)
-            return allowed.response;
-        const { session, realm, datastoreId } = allowed;
-        const parsed = await parseBody(c.req.raw, turnRequestSchema);
-        if (!parsed.ok)
-            return parsed.response;
-        const { horn, messages } = parsed.data;
-        if (horn.datastoreId !== datastoreId) {
-            return c.json({ error: `This Horn belongs to the "${horn.datastoreId}" datastore.` }, 400);
-        }
-        const model = (deps.model ?? studioModelFromEnv)(c.env, { feature: "horns-studio", datastoreId });
-        if (!model.ok)
-            return c.json({ error: model.reason }, 503);
-        const select = agentsSparqlSelect({
-            agentsUrl: c.env.MANTA_AGENTS_URL,
-            session,
-            datastoreId,
-        });
-        const typed = realm;
-        const shapes = deps.shapes(typed);
-        const [latest, ...earlier] = [...messages].reverse();
-        // Newest first here, so this keeps the most recent exchanges and drops the oldest.
-        const carried = earlier.slice(0, maxHistoryTurns * 2);
-        const asked = latest?.content ?? "";
-        // Streamed like a shape view's turn: each event as the loop records it, then the result. A turn that
-        // looks at the data before it changes anything is a minute of work, and that minute should be visible.
-        return ndjsonResponse(async (emit) => {
-            emit({ type: "progress", event: { type: "reading" } });
-            // A class's shape is what a platform sends; what Manta's rules work out about it is on nothing's property
-            // list, so the turn is given it up front rather than left to discover that half of the graph exists.
-            const useful = buildUsefulContext({
-                realm: typed,
-                prompt: asked,
-                horn,
-                ...(await datastoreFacts({ realm: typed, select, shapes, prompt: asked, signal: c.req.raw.signal })),
-                library: [],
-                catalog: mantaReactCatalog,
-                skills: selectSkills(asked, builtInSkills),
-            });
-            const turn = await runStudioTurn({
-                model: model.model,
-                mode: "build",
-                draft: horn,
-                messages: assembleStudioMessages({
-                    system: studioSystemPrompt({ mode: "build", realm: typed }),
-                    history: [...carried].reverse(),
-                    usefulContext: useful.text,
-                    userMessage: asked,
-                }),
-                handlers: {
-                    ...studioReadHandlers({
-                        realm: typed,
-                        select,
-                        shapes,
-                        views: shapeViewSpecs,
-                        model: model.model,
-                        ...(deps.componentApi ? { componentApi: deps.componentApi } : {}),
-                        // The investigation is a loop of its own; without this it is one line that takes a minute.
-                        onEvent: (event) => emit({ type: "progress", event }),
-                    }),
-                    ...studioWriteHandlers({
-                        realm: typed,
-                        select,
-                        catalog: mantaReactCatalog,
-                        lookup: () => undefined,
-                        ...(deps.typecheck ? { typecheck: deps.typecheck } : {}),
-                        // As the viewer: staging a rule is attributed to a person, and agents refuses it otherwise.
-                        stageRule: (rule) => stageRule({ agentsUrl: c.env.MANTA_AGENTS_URL, session, datastoreId }, rule),
-                    }),
-                },
-                maxSteps: turnStepLimit,
-                signal: c.req.raw.signal,
-                onEvent: (event) => emit({ type: "progress", event }),
-            });
-            emit({ type: "result", horn: turn.draft, reply: turn.reply, status: turn.status, steps: turn.steps });
-        }, noStore);
-    });
     /**
      * One turn of talking to a shape's view. The same lane as a Horn's, over a smaller thing: a view is a card
      * and the fields it reads, and its gate is the zoo — the gate the coverage runs already judge by, so a view
@@ -215,7 +130,7 @@ export function studioRoutes(deps) {
         // Never the Studio's own model as a fallback, unlike the shape critic: that one can read a card as text,
         // and this one has only a picture. Qwen would be shown an image it cannot see and would answer about
         // nothing. Unconfigured means no reviewer, and the caller is told why.
-        const critic = (deps.criticModel ?? criticModelFromEnv)(c.env, { feature: "horn-critic", datastoreId });
+        const critic = (deps.criticModel ?? ((env) => criticModel(env)))(c.env, { feature: "horn-critic", datastoreId });
         if (!critic.ok)
             return c.json({ error: critic.reason }, 503);
         const advice = await adviseOnHorn({
@@ -240,6 +155,7 @@ export function studioRoutes(deps) {
         }
         const select = agentsSparqlSelect({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             session,
             datastoreId,
         });
@@ -268,7 +184,7 @@ export function studioRoutes(deps) {
         const parsed = coverageRequestSchema.safeParse(body ?? {});
         if (!parsed.success)
             return c.json({ error: "The request is invalid — limit must be between 1 and 3." }, 400);
-        const model = (deps.model ?? studioModelFromEnv)(c.env, { feature: "shape-coverage", datastoreId });
+        const model = (deps.model ?? ((env) => studioModel(env)))(c.env, { feature: "shape-coverage", datastoreId });
         if (!model.ok)
             return c.json({ error: model.reason }, 503);
         // Optional: with no critic route it is the Studio's own model. Either way it reads the card as text —
@@ -276,6 +192,7 @@ export function studioRoutes(deps) {
         const critic = deps.criticModel?.(c.env, { feature: "shape-critic", datastoreId });
         const select = agentsSparqlSelect({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             session,
             datastoreId,
         });
@@ -334,11 +251,12 @@ export function studioRoutes(deps) {
         if (parsed.data.spec.schema !== schema) {
             return c.json({ error: `That view is for ${parsed.data.spec.schema}, not ${schema}.` }, 400);
         }
-        const model = (deps.model ?? studioModelFromEnv)(c.env, { feature: "horns-shape-view", datastoreId });
+        const model = (deps.model ?? ((env) => studioModel(env)))(c.env, { feature: "horns-shape-view", datastoreId });
         if (!model.ok)
             return c.json({ error: model.reason }, 503);
         const select = agentsSparqlSelect({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             session,
             datastoreId,
         });

package/dist/studio-worker.d.ts

@@ -0,0 +1,12 @@
+import type { Shape } from "@manta-eu/horns/shapes";
+import type { Env } from "./env.ts";
+import { type TypecheckFs } from "./typecheck.ts";
+import { type HornsWorkerOptions } from "./worker.ts";
+export { HornStudioAgent } from "./studio-agent-class.ts";
+export type HornsStudioWorkerOptions = Omit<HornsWorkerOptions, "shapes" | "typecheck"> & {
+    /** The realm's shapes, built by `hornsShapeCatalog`: a worker cannot import the SDK's schema entry. */
+    shapes: () => readonly Shape[];
+    /** The declarations a written view is checked against, from `virtual:horns/typecheck-fs`. */
+    typecheckFs?: TypecheckFs;
+};
+export declare function createHornsStudioWorker(options: HornsStudioWorkerOptions): ExportedHandler<Env, unknown, unknown, unknown>;

package/dist/studio-worker.js

@@ -0,0 +1,34 @@
+// A whole Horns worker, Studio included, from the three things a build has to hand it.
+//
+// `worker.ts` cannot reach the Studio itself: the conversation object imports `cloudflare:workers`, which
+// that module must stay clear of so Node can load it. This entry may, so it does the wiring a host would
+// otherwise repeat — registering what the Studio reads, and mounting its routes.
+import { Hono } from "hono";
+import { createTypecheck } from "./typecheck.js";
+import { createHornsWorker } from "./worker.js";
+import { provideStudioDeps, studioAgentRoutes } from "./studio-agent-routes.js";
+export { HornStudioAgent } from "./studio-agent-class.js";
+export function createHornsStudioWorker(options) {
+    const { shapes, componentApi, typecheckFs, routes, ...rest } = options;
+    const typecheck = typecheckFs === undefined ? undefined : createTypecheck(typecheckFs);
+    const parts = {
+        shapes,
+        ...(componentApi ? { componentApi } : {}),
+        ...(typecheck ? { typecheck } : {}),
+    };
+    // Registered rather than passed: the conversation object is built by the runtime, not by this call.
+    provideStudioDeps(parts);
+    return createHornsWorker({
+        ...rest,
+        ...parts,
+        routes: mount(routes),
+    });
+}
+// Hono's `route` mutates what it is called on, so a host's own app is composed into a fresh one rather than
+// having the Studio's routes added to it. The host's come first.
+function mount(routes) {
+    const app = new Hono();
+    if (routes !== undefined)
+        app.route("/", routes);
+    return app.route("/", studioAgentRoutes());
+}

package/dist/worker.d.ts

@@ -2,13 +2,18 @@ import { Hono } from "hono";
 import type { Env } from "./env.ts";
 import { type StudioRoutesDeps } from "./studio-routes.ts";
 export type { Env };
-export type HornsWorkerOptions = Pick<StudioRoutesDeps<Env>, "shapes" | "componentApi" | "typecheck"> & Partial<Pick<StudioRoutesDeps<Env>, "criticModel">>;
+export type HornsWorkerOptions = Pick<StudioRoutesDeps<Env>, "shapes" | "componentApi" | "typecheck"> & Partial<Pick<StudioRoutesDeps<Env>, "criticModel">> & {
+    /** A host's own routes, mounted before the assets catch-all. */
+    routes?: Hono<{
+        Bindings: Env;
+    }>;
+};
 /**
  * The Horns worker as a Hono app. `shapes` is the host's: the catalog describes a realm's data model, so
  * Horns takes it rather than shipping one.
  */
-export declare function createHornsApp({ shapes, componentApi, typecheck, criticModel, }: HornsWorkerOptions): Hono<{
+export declare function createHornsApp({ shapes, componentApi, typecheck, routes, criticModel, }: HornsWorkerOptions): Hono<{
     Bindings: Env;
 }, import("hono/types").BlankSchema, "/">;
 /** The same app behind Sentry, ready to be a Worker's default export. */
-export declare function createHornsWorker(options: HornsWorkerOptions): ExportedHandler<Env, QueueHandlerMessage, CfHostMetadata>;
+export declare function createHornsWorker(options: HornsWorkerOptions): ExportedHandler<Env, unknown, unknown, unknown>;

package/dist/worker.js

@@ -8,7 +8,7 @@ import { hornRoutes } from "./horn-routes.js";
 import { actionPlanRoutes } from "./action-plan-routes.js";
 import { studioRoutes } from "./studio-routes.js";
 import { contentSecurityPolicy } from "./csp.js";
-import { criticModelFromEnv } from "./llm.js";
+import { criticModel as criticModelFromEnv } from "./studio-model.js";
 import { requestSession } from "./dev-session.js";
 import { sessionCookiePrefixOf } from "./session.js";
 import { asJsonRequest, followedLink, noPageToOpen, signInFirst } from "./entity-links.js";
@@ -18,7 +18,7 @@ import { sentryOptionsForDeploy } from "./sentry.js";
  * The Horns worker as a Hono app. `shapes` is the host's: the catalog describes a realm's data model, so
  * Horns takes it rather than shipping one.
  */
-export function createHornsApp({ shapes, componentApi, typecheck, criticModel = criticModelFromEnv, }) {
+export function createHornsApp({ shapes, componentApi, typecheck, routes, criticModel = (env) => criticModelFromEnv(env), }) {
     const app = new Hono();
     // On the document only: a JSON answer nobody renders has nothing to protect, and the header is not small.
     app.use("*", async (c, next) => {
@@ -180,6 +180,10 @@ export function createHornsApp({ shapes, componentApi, typecheck, criticModel =
         ...(componentApi ? { componentApi } : {}),
         ...(typecheck ? { typecheck } : {}),
     }));
+    // A host's own routes, mounted before the assets catch-all. The Studio conversation arrives this way:
+    // importing it pulls in `cloudflare:workers`, which this module must not do.
+    if (routes)
+        app.route("/", routes);
     app.all("*", (c) => c.env.ASSETS.fetch(c.req.raw));
     app.onError((err, c) => {
         captureException(err, { tags: { path: c.req.routePath, method: c.req.method } });