@manta-eu/horns-server 0.1.3 → 0.2.0

package/dist/action-plan-routes.d.ts

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import { type UpstreamFetcher } from "./agents-proxy.ts";
 import type { HornRoutesEnv } from "./horn-routes.ts";
 import type { MantaSessionState } from "./session.ts";
 export declare const planNotFoundMessage = "There is no plan like that in this datastore.";
@@ -12,6 +13,7 @@ export type PlanRunResult = {
 };
 export declare function executeActionPlan(args: {
     agentsUrl: string | undefined;
+    upstream?: UpstreamFetcher | undefined;
     session: MantaSessionState;
     datastoreId: string;
     plan: string;

package/dist/action-plan-routes.js

@@ -24,7 +24,7 @@ const executeAnswerSchema = z.object({
     error: z.string().nullish(),
 });
 export async function executeActionPlan(args) {
-    const sent = await agentsGraphql({ agentsUrl: args.agentsUrl, session: args.session, datastoreId: args.datastoreId }, executeActionPlanMutation, { input: { namedGraphIri: args.plan, dryRun: args.preview } }, "executeActionPlan");
+    const sent = await agentsGraphql({ agentsUrl: args.agentsUrl, upstream: args.upstream, session: args.session, datastoreId: args.datastoreId }, executeActionPlanMutation, { input: { namedGraphIri: args.plan, dryRun: args.preview } }, "executeActionPlan");
     // Being signed out and having no address are about the caller, so they are said plainly. What agents
     // answered is about the plan, so it is said as such.
     if (!sent.ok) {
@@ -58,6 +58,7 @@ export function actionPlanRoutes() {
         try {
             const found = await agentsSparqlSelect({
                 agentsUrl: c.env.MANTA_AGENTS_URL,
+                upstream: c.env.UPSTREAM,
                 session: authorized.session,
                 datastoreId,
             })(isPlanQuery(realm, body.data.plan), undefined);
@@ -69,6 +70,7 @@ export function actionPlanRoutes() {
         }
         const started = await executeActionPlan({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             session: authorized.session,
             datastoreId,
             plan: body.data.plan,

package/dist/agents-proxy.d.ts

@@ -1,9 +1,18 @@
 import { type MantaSessionState } from "./session.ts";
 export { checkReadOnlySparql, crossOriginBlockedMessage, evaluateProxyPolicy, isAllowedProxyPath, isAuthProxyPath, isReadOnlySparql, originAllowsRequest, proxyMethodBlockedMessage, proxyPathBlockedMessage, sameOriginDeniedResponse, sparqlEmptyMessage, sparqlFederationBlockedMessage, sparqlParseFailedMessage, sparqlWriteBlockedMessage, } from "./manta-proxy-policy.ts";
 export declare const missingAgentsUrlMessage = "MANTA_AGENTS_URL is not set \u2014 the live data source has no address.";
+/**
+ * How this worker reaches the upstream, where a host has a way of its own. A host that is the upstream passes
+ * itself, so a call stays in the process rather than leaving through the public hostname; a service binding fits too.
+ */
+export type UpstreamFetcher = {
+    fetch: (request: Request) => Response | Promise<Response>;
+};
+export declare function fetchUpstream(upstream: UpstreamFetcher | undefined, url: URL, init: RequestInit): Promise<Response>;
 export declare const signedOutMessage = "Not signed in \u2014 sign in to Manta to reach the live data source.";
 export type AgentsCaller = {
     agentsUrl: string | undefined;
+    upstream?: UpstreamFetcher | undefined;
     session: MantaSessionState;
     datastoreId: string;
 };

package/dist/agents-proxy.js

@@ -5,6 +5,9 @@ import { forwardedOriginHeader, logoutPath } from "./auth-routes.js";
 import { captureUpstreamCookies, clearSessionSetCookies, isSignedIn, requestIsSecure, sessionSetCookies, sessionsDiffer, setCookieHeadersOf, upstreamCookieHeader, } from "./session.js";
 export { checkReadOnlySparql, crossOriginBlockedMessage, evaluateProxyPolicy, isAllowedProxyPath, isAuthProxyPath, isReadOnlySparql, originAllowsRequest, proxyMethodBlockedMessage, proxyPathBlockedMessage, sameOriginDeniedResponse, sparqlEmptyMessage, sparqlFederationBlockedMessage, sparqlParseFailedMessage, sparqlWriteBlockedMessage, } from "./manta-proxy-policy.js";
 export const missingAgentsUrlMessage = "MANTA_AGENTS_URL is not set — the live data source has no address.";
+export async function fetchUpstream(upstream, url, init) {
+    return isPresent(upstream) ? upstream.fetch(new Request(url, init)) : fetch(url, init);
+}
 export const signedOutMessage = "Not signed in — sign in to Manta to reach the live data source.";
 // The one viewer-attributed GraphQL call. Both writers the worker has — staging a rule, uploading a file —
 // go through it, so a timeout or a request id is added once. `status` is carried for the caller that answers
@@ -13,7 +16,7 @@ export async function agentsGraphql(caller, query, variables, field, signal) {
     if (!isPresent(caller.agentsUrl))
         return { ok: false, status: 500, error: missingAgentsUrlMessage };
     const url = agentsPathUrl(caller.agentsUrl, "/graphql");
-    const response = await fetch(url, {
+    const response = await fetchUpstream(caller.upstream, url, {
         method: "POST",
         headers: {
             cookie: upstreamCookieHeader(caller.session),

package/dist/datastore-access.d.ts

@@ -1,6 +1,8 @@
+import { type UpstreamFetcher } from "./agents-proxy.ts";
 import { type MantaSessionState } from "./session.ts";
 export type DatastoreAccessEnv = {
     MANTA_AGENTS_URL?: string;
+    UPSTREAM?: UpstreamFetcher;
 };
 export type DatastoreAccess = {
     active?: string;

package/dist/datastore-access.js

@@ -1,6 +1,6 @@
 import { isPresent } from "@manta-eu/lib/present";
 import { isRecord } from "@manta-eu/horns";
-import { agentsPathUrl } from "./agents-proxy.js";
+import { agentsPathUrl, fetchUpstream } from "./agents-proxy.js";
 import { CustomerDatastoresDocument } from "@manta-eu/client";
 import { upstreamCookieHeader } from "./session.js";
 export const datastoreNotGrantedMessage = "That datastore is not one this session can open.";
@@ -57,7 +57,7 @@ async function customerDatastores(env, cookie, active) {
     if (!isPresent(env.MANTA_AGENTS_URL))
         return [];
     try {
-        const response = await fetch(agentsPathUrl(env.MANTA_AGENTS_URL, "/graphql"), {
+        const response = await fetchUpstream(env.UPSTREAM, agentsPathUrl(env.MANTA_AGENTS_URL, "/graphql"), {
             method: "POST",
             headers: {
                 cookie,
@@ -93,7 +93,7 @@ export async function datastoreAccessFor(env, session) {
     const url = agentsPathUrl(env.MANTA_AGENTS_URL, "/api/data/context");
     let response;
     try {
-        response = await fetch(url, { headers: { cookie, accept: "application/json" } });
+        response = await fetchUpstream(env.UPSTREAM, url, { headers: { cookie, accept: "application/json" } });
     }
     catch {
         return { ok: false, reason: "unavailable" };

package/dist/dev-session.d.ts

@@ -3,5 +3,8 @@ export type DevSessionEnv = {
     DEV_AGENTS_COOKIE?: string;
     /** A host that signs people in itself names its own session cookies here. Defaults to Horns' own. */
     HORNS_SESSION_COOKIE_PREFIX?: string;
+    /** `upstream` when the host is the upstream itself: the session is its own sign-in cookies, read as they are. */
+    HORNS_SESSION_SOURCE?: string;
 };
+export declare const upstreamSessionSource = "upstream";
 export declare function requestSession(request: Request, env: DevSessionEnv): MantaSessionState | undefined;

package/dist/dev-session.js

@@ -1,10 +1,27 @@
 import { isPresent } from "@manta-eu/lib/present";
-import { agentsJwtCookieName, parseCookieHeader, readSessionState, sessionCookiePrefixOf, } from "./session.js";
+import { agentsJwtCookieName, isForwardableCookie, parseCookieHeader, readSessionState, sessionCookiePrefixOf, } from "./session.js";
+export const upstreamSessionSource = "upstream";
+/** The upstream's access token and the session id it refreshes it with: all a call needs from the browser. */
+const upstreamSessionCookies = [agentsJwtCookieName, `${agentsJwtCookieName}_sid`];
+function upstreamSession(request) {
+    const jar = parseCookieHeader(request.headers.get("cookie"));
+    const upstreamCookies = Object.fromEntries(upstreamSessionCookies.flatMap((name) => {
+        const value = jar[name];
+        return isPresent(value) && isForwardableCookie(name, value) ? [[name, value]] : [];
+    }));
+    return isPresent(upstreamCookies[agentsJwtCookieName]) ? { upstreamCookies } : undefined;
+}
 const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
 // HireManta staging will not send a sign-in back to localhost, so `pnpm dev` can borrow a staging agents session
 // captured by `dev:borrow-session`. It stands in only for requests to this machine that carry no Horns session
 // yet (agents' token refreshes then land in a real one), and production builds drop it with import.meta.env.DEV.
 export function requestSession(request, env) {
+    if (isPresent(env.HORNS_SESSION_SOURCE)) {
+        if (env.HORNS_SESSION_SOURCE !== upstreamSessionSource) {
+            throw new Error(`HORNS_SESSION_SOURCE must be "${upstreamSessionSource}" or unset, not "${env.HORNS_SESSION_SOURCE}".`);
+        }
+        return upstreamSession(request);
+    }
     const session = readSessionState(request.headers.get("cookie"), sessionCookiePrefixOf(env));
     if (isPresent(session) || !import.meta.env.DEV || !isPresent(env.DEV_AGENTS_COOKIE))
         return session;

package/dist/env.d.ts

@@ -1,8 +1,11 @@
 import type { HornRoutesEnv } from "./horn-routes.ts";
 import type { StudioRoutesEnv } from "./studio-routes.ts";
-import type { StudioModelEnv } from "./llm.ts";
+import type { StudioModelEnv } from "./studio-model.ts";
+import type { HornStudioAgent } from "./studio-agent-class.ts";
 /** Everything the assembled worker reads. A host mounting only some routes needs only those routes' env. */
 export type Env = HornRoutesEnv & StudioRoutesEnv & StudioModelEnv & {
+    /** The Studio conversation object, where a host binds one. */
+    HORN_STUDIO?: DurableObjectNamespace<HornStudioAgent>;
     SITE_PASSWORD?: string;
     SENTRY_DSN?: string;
     CF_VERSION_METADATA?: {

package/dist/horn-routes.d.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { type RevisionLookup } from "@manta-eu/horns";
 import type { DevSessionEnv } from "./dev-session.ts";
+import type { UpstreamFetcher } from "./agents-proxy.ts";
 export declare const maxScreenshotBytes: number;
 type AssetFetcher = {
     fetch: (request: Request) => Response | Promise<Response>;
@@ -8,6 +9,7 @@ type AssetFetcher = {
 export type HornRoutesEnv = DevSessionEnv & {
     ASSETS: AssetFetcher;
     MANTA_AGENTS_URL?: string;
+    UPSTREAM?: UpstreamFetcher;
     VITE_KEYCLOAK_REALM?: string;
     SPARQL_UPDATE_PSK?: string;
 };

package/dist/horn-routes.js

@@ -43,6 +43,7 @@ async function realmLibraryLookup(args) {
     try {
         const results = await agentsSparqlSelect({
             agentsUrl: args.env.MANTA_AGENTS_URL,
+            upstream: args.env.UPSTREAM,
             session: args.session,
             datastoreId: args.realm,
         })(libraryItemsQuery(args.realm), undefined);
@@ -91,6 +92,7 @@ export function hornRoutes(deps = {}) {
                 horn: args.body.horn,
                 select: agentsSparqlSelect({
                     agentsUrl: args.env.MANTA_AGENTS_URL,
+                    upstream: args.env.UPSTREAM,
                     session: args.session,
                     datastoreId: args.datastoreId,
                 }),
@@ -132,6 +134,7 @@ export function hornRoutes(deps = {}) {
         try {
             const found = await agentsSparqlSelect({
                 agentsUrl: c.env.MANTA_AGENTS_URL,
+                upstream: c.env.UPSTREAM,
                 session: authorized.session,
                 datastoreId,
             })(hornsInDatastoreQuery(realm), undefined);
@@ -172,6 +175,7 @@ export function hornRoutes(deps = {}) {
             return refuse(500, "This deployment has no realm configured.").response;
         const select = agentsSparqlSelect({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             session: authorized.session,
             datastoreId,
         });
@@ -215,11 +219,13 @@ export function hornRoutes(deps = {}) {
         const slug = c.req.param("slug");
         const select = agentsSparqlSelect({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             session: authorized.session,
             datastoreId,
         });
         const update = agentsSparqlUpdate({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             datastoreId,
             updateKey: c.env.SPARQL_UPDATE_PSK,
             purpose: { kind: "horn-save", realm },
@@ -496,6 +502,7 @@ export function hornRoutes(deps = {}) {
             return refuse(400, `"${about}" is not an IRI.`).response;
         const select = agentsSparqlSelect({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             session: authorized.session,
             datastoreId,
         });
@@ -590,6 +597,7 @@ export function hornRoutes(deps = {}) {
         const slug = c.req.param("slug");
         const select = agentsSparqlSelect({
             agentsUrl: c.env.MANTA_AGENTS_URL,
+            upstream: c.env.UPSTREAM,
             session: authorized.session,
             datastoreId,
         });
@@ -601,12 +609,13 @@ export function hornRoutes(deps = {}) {
             if (!isPresent(revision))
                 return refuse(404, `There is no Horn called "${slug}" here.`).response;
             const number = Number(current?.["number"]?.value) || 1;
-            const uploaded = await uploadPng({ agentsUrl: c.env.MANTA_AGENTS_URL, session: authorized.session, datastoreId }, { fileName: `horn-${slug}-r${number}.png`, bytes });
+            const uploaded = await uploadPng({ agentsUrl: c.env.MANTA_AGENTS_URL, upstream: c.env.UPSTREAM, session: authorized.session, datastoreId }, { fileName: `horn-${slug}-r${number}.png`, bytes });
             if (!uploaded.ok)
                 return refuse(uploaded.status, uploaded.error).response;
             const capturedAt = (deps.now?.() ?? new Date()).toISOString();
             await agentsSparqlUpdate({
                 agentsUrl: c.env.MANTA_AGENTS_URL,
+                upstream: c.env.UPSTREAM,
                 datastoreId,
                 updateKey: c.env.SPARQL_UPDATE_PSK,
                 purpose: { kind: "horn-save", realm },

package/dist/index.d.ts

@@ -6,14 +6,16 @@ export { studioRoutes, maxHistoryTurns, type StudioRoutesDeps, type StudioRoutes
 export { actionPlanRoutes } from "./action-plan-routes.ts";
 export { authUnavailableResponse, callbackPath, localSignOutResponse, loginPath, loginRequestWithMarker, logoutPath, logoutResponseReturningTo, } from "./auth-routes.ts";
 export { signedInParam } from "./auth-params.ts";
-export { proxyToMantaAgents, sameOriginDeniedResponse, signedOutMessage } from "./agents-proxy.ts";
+export { proxyToMantaAgents, sameOriginDeniedResponse, signedOutMessage, type UpstreamFetcher, } from "./agents-proxy.ts";
+export { contentSecurityPolicy } from "./csp.ts";
 export { datastoreAccessFor, datastoreAccessUnavailableMessage, datastoreNotGrantedMessage, forgetDatastoreAccess, grantsDatastore, resetDatastoreAccessCache, } from "./datastore-access.ts";
 export { agentsSparqlSelect } from "./sparql-select.ts";
 export { agentsSparqlUpdate, WriteRefusedError } from "./sparql-update.ts";
-export { criticModelFromEnv, studioModelFromEnv, type StudioModelEnv, type StudioModelResult } from "./llm.ts";
+export { criticModel, studioModel, type StudioModelEnv, type StudioModelChoice } from "./studio-model.ts";
 export { badSessionCookiePrefixMessage, isSignedIn, sessionCookiePrefix, sessionCookiePrefixOf, sessionSetCookies, type MantaSessionState, } from "./session.ts";
 export { requestSession, type DevSessionEnv } from "./dev-session.ts";
 export { hornTemplatePath, renderHornDocument } from "./render-document.ts";
 export { sentryOptionsForDeploy } from "./sentry.ts";
 export { withoutPiiErrorEvent } from "./pii.ts";
 export { asJsonRequest, followedLink, noPageToOpen, signInFirst } from "./entity-links.ts";
+export { authorizeStudioConversation, studioConversationName, studioOpening, type StudioAgentProps, type StudioConversationEnv, type StudioOpening, } from "./studio-opening.ts";

package/dist/index.js

@@ -5,16 +5,20 @@ export { studioRoutes, maxHistoryTurns } from "./studio-routes.js";
 export { actionPlanRoutes } from "./action-plan-routes.js";
 export { authUnavailableResponse, callbackPath, localSignOutResponse, loginPath, loginRequestWithMarker, logoutPath, logoutResponseReturningTo, } from "./auth-routes.js";
 export { signedInParam } from "./auth-params.js";
-export { proxyToMantaAgents, sameOriginDeniedResponse, signedOutMessage } from "./agents-proxy.js";
+export { proxyToMantaAgents, sameOriginDeniedResponse, signedOutMessage, } from "./agents-proxy.js";
+// A host serving Horns' pages from its own documents sends the same policy, since connect-src 'self' is part
+// of what holds a written view in.
+export { contentSecurityPolicy } from "./csp.js";
 export { datastoreAccessFor, datastoreAccessUnavailableMessage, datastoreNotGrantedMessage, forgetDatastoreAccess, grantsDatastore, resetDatastoreAccessCache, } from "./datastore-access.js";
 export { agentsSparqlSelect } from "./sparql-select.js";
 export { agentsSparqlUpdate, WriteRefusedError } from "./sparql-update.js";
-// Also its own entry, `@manta-eu/horns-server/llm`: building a model client must not drag in the render
+// Also its own entry, `@manta-eu/horns-server/studio-model`: building a model must not drag in the render
 // path, which is JSX and which a Node script cannot load.
-export { criticModelFromEnv, studioModelFromEnv } from "./llm.js";
+export { criticModel, studioModel } from "./studio-model.js";
 export { badSessionCookiePrefixMessage, isSignedIn, sessionCookiePrefix, sessionCookiePrefixOf, sessionSetCookies, } from "./session.js";
 export { requestSession } from "./dev-session.js";
 export { hornTemplatePath, renderHornDocument } from "./render-document.js";
 export { sentryOptionsForDeploy } from "./sentry.js";
 export { withoutPiiErrorEvent } from "./pii.js";
 export { asJsonRequest, followedLink, noPageToOpen, signInFirst } from "./entity-links.js";
+export { authorizeStudioConversation, studioConversationName, studioOpening, } from "./studio-opening.js";

package/dist/sparql-update.d.ts

@@ -1,4 +1,5 @@
 import { type WritePurpose } from "@manta-eu/horns";
+import { type UpstreamFetcher } from "./agents-proxy.ts";
 export declare const updateKeyHeader = "x-sparql-update-key";
 export declare const missingUpdateKeyMessage = "SPARQL_UPDATE_PSK is not set \u2014 this deployment cannot write.";
 export declare class WriteRefusedError extends Error {
@@ -7,6 +8,7 @@ export declare class WriteRefusedError extends Error {
 export type SparqlUpdate = (update: string) => Promise<void>;
 export declare function agentsSparqlUpdate(args: {
     agentsUrl: string | undefined;
+    upstream?: UpstreamFetcher | undefined;
     datastoreId: string;
     updateKey: string | undefined;
     purpose: WritePurpose;

package/dist/sparql-update.js

@@ -1,6 +1,6 @@
 import { isPresent } from "@manta-eu/lib/present";
 import { checkWrite } from "@manta-eu/horns";
-import { agentsPathUrl, missingAgentsUrlMessage } from "./agents-proxy.js";
+import { agentsPathUrl, fetchUpstream, missingAgentsUrlMessage } from "./agents-proxy.js";
 // Agents' `/d/:ds/sparql-update` authorizes on the pre-shared key alone and does not restrict `GRAPH`, so this
 // worker is the write-authorization boundary. The guard runs here rather than at each call site: there is one
 // way to send an update and it cannot be the way that forgot to check.
@@ -23,7 +23,7 @@ export function agentsSparqlUpdate(args) {
         if (args.updateKey === undefined)
             throw new Error(missingUpdateKeyMessage);
         const url = agentsPathUrl(args.agentsUrl, `/d/${encodeURIComponent(args.datastoreId)}/sparql-update`);
-        const response = await fetch(url, {
+        const response = await fetchUpstream(args.upstream, url, {
             method: "POST",
             headers: {
                 [updateKeyHeader]: args.updateKey,

package/dist/studio-agent-class.d.ts

@@ -0,0 +1,41 @@
+import { Think } from "@cloudflare/think";
+import type { Connection, ConnectionContext } from "agents";
+import { type LanguageModel, type ModelMessage } from "ai";
+import { type Horn } from "@manta-eu/horns";
+import { type StudioMode } from "@manta-eu/horns/studio";
+import type { UpstreamFetcher } from "./agents-proxy.ts";
+import { type StudioModelEnv } from "./studio-model.ts";
+export { studioOpening, type StudioAgentProps, type StudioOpening } from "./studio-opening.ts";
+export type StudioAgentEnv = StudioModelEnv & {
+    MANTA_AGENTS_URL?: string;
+    VITE_KEYCLOAK_REALM?: string;
+    UPSTREAM?: UpstreamFetcher;
+};
+export type StudioAgentState = {
+    draft: Horn | null;
+    mode: StudioMode;
+};
+export declare class HornStudioAgent extends Think<StudioAgentEnv, StudioAgentState> {
+    #private;
+    initialState: StudioAgentState;
+    maxSteps: number;
+    onRequest(request: Request): Promise<Response>;
+    onConnect(connection: Connection, ctx: ConnectionContext): void | Promise<void>;
+    private get opened();
+    private get realm();
+    private select;
+    getModel(): LanguageModel;
+    /** Where the draft has got to: nothing drawn is designing, drawn but unbound is hydrating. */
+    private get stage();
+    beforeStep(): {
+        activeTools: string[];
+        system: string;
+    } | undefined;
+    beforeTurn(): Promise<{
+        instructions: string;
+        messages: ModelMessage[];
+        tools: {
+            [x: string]: (import("ai").Tool<never, never, any> | import("ai").Tool<any, any, any> | import("ai").Tool<any, never, any> | import("ai").Tool<never, any, any>) & Pick<import("ai").Tool<any, any, any>, "execute" | "onInputAvailable" | "onInputStart" | "onInputDelta" | "needsApproval">;
+        };
+    }>;
+}

package/dist/studio-agent-class.js

@@ -0,0 +1,171 @@
+import { Think } from "@cloudflare/think";
+import { convertToModelMessages } from "ai";
+import { isPresent } from "@manta-eu/lib/present";
+import { hornSchema } from "@manta-eu/horns";
+import { z } from "zod";
+import { mantaReactCatalog } from "@manta-eu/horns-kit";
+import { shapeViewSpecs } from "@manta-eu/horns-kit/shape-views";
+import { buildUsefulContext, datastoreFacts, builtInSkills, selectSkills, studioReadHandlers, studioSystemPrompt, studioWriteHandlers, stageGuidance, stageOf, toolsForStage, } from "@manta-eu/horns/studio";
+import { agentsSparqlSelect } from "./sparql-select.js";
+import { stageRule } from "./manta-rules.js";
+import { studioDeps } from "./studio-deps.js";
+import { pageToolSet, studioToolSet } from "./studio-agent.js";
+import { studioModel } from "./studio-model.js";
+import { readStudioOpening } from "./studio-opening.js";
+export { studioOpening } from "./studio-opening.js";
+const openRequestSchema = z.object({
+    horn: hornSchema,
+    mode: z.enum(["plan", "build", "investigate"]).optional(),
+});
+export class HornStudioAgent extends Think {
+    initialState = { draft: null, mode: "build" };
+    maxSteps = 24;
+    /** In memory only: a session must not outlive the connection that sent it. */
+    #opened;
+    async onRequest(request) {
+        const opened = readStudioOpening(request);
+        if (opened !== undefined)
+            this.#opened = opened;
+        return this.#answer(request);
+    }
+    onConnect(connection, ctx) {
+        const opened = readStudioOpening(ctx.request);
+        if (opened !== undefined)
+            this.#opened = opened;
+        return super.onConnect(connection, ctx);
+    }
+    get opened() {
+        if (this.#opened === undefined)
+            throw new Error("This Studio was reached without a session.");
+        return this.#opened;
+    }
+    get realm() {
+        return this.opened.realm;
+    }
+    select() {
+        return agentsSparqlSelect({
+            agentsUrl: this.env.MANTA_AGENTS_URL,
+            upstream: this.env.UPSTREAM,
+            session: this.opened.session,
+            datastoreId: this.opened.datastoreId,
+        });
+    }
+    getModel() {
+        const chosen = studioModel(this.env);
+        if (!chosen.ok)
+            throw new Error(chosen.reason);
+        return chosen.model;
+    }
+    /** The Horn this conversation is about. One draft, so a turn and an edit cannot disagree. */
+    async #answer(request) {
+        const url = new URL(request.url);
+        if (!url.pathname.endsWith("/open") || request.method !== "POST")
+            return super.onRequest(request);
+        const body = await request.json().catch(() => undefined);
+        const opened = openRequestSchema.safeParse(body);
+        if (!opened.success)
+            return Response.json({ error: "Send the Horn to open." }, { status: 400 });
+        this.setState({ ...this.state, draft: opened.data.horn, mode: opened.data.mode ?? this.state.mode });
+        return Response.json({ opened: true });
+    }
+    /** Where the draft has got to: nothing drawn is designing, drawn but unbound is hydrating. */
+    get stage() {
+        const views = this.state.draft?.views ?? [];
+        const drawn = views.length > 0 && views.every((view) => "ref" in view || isPresent(view.render));
+        const bound = drawn && views.every((view) => "ref" in view || isPresent(view.binding));
+        return stageOf({ drawn, bound });
+    }
+    beforeStep() {
+        if (!isPresent(this.state.draft))
+            return undefined;
+        const stage = this.stage;
+        return { activeTools: [...toolsForStage(stage)], system: stageGuidance(stage) };
+    }
+    async beforeTurn() {
+        const draft = this.state.draft;
+        if (!isPresent(draft))
+            throw new Error("This Studio has no Horn open.");
+        const { mode } = this.state;
+        const realm = this.realm;
+        const select = this.select();
+        const shapes = studioDeps().shapes(realm);
+        const deps = studioDeps();
+        const asked = userWords(this.messages);
+        const useful = buildUsefulContext({
+            realm,
+            prompt: asked,
+            horn: draft,
+            ...(await datastoreFacts({ realm, select, shapes, prompt: asked })),
+            library: [],
+            catalog: mantaReactCatalog,
+            skills: selectSkills(asked, builtInSkills),
+        });
+        const handlers = {
+            ...studioReadHandlers({
+                realm,
+                select,
+                shapes,
+                views: shapeViewSpecs,
+                model: this.getModel(),
+                ...(deps.componentApi ? { componentApi: deps.componentApi } : {}),
+            }),
+            ...studioWriteHandlers({
+                realm,
+                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: this.env.MANTA_AGENTS_URL,
+                    session: this.opened.session,
+                    datastoreId: this.opened.datastoreId,
+                }, rule),
+            }),
+        };
+        return {
+            instructions: studioSystemPrompt({ mode, realm }),
+            // Inside the last thing the user said, so the ask and the context are read as one.
+            messages: withUsefulContext(await convertToModelMessages(this.messages), useful.text),
+            tools: {
+                ...studioToolSet({
+                    mode,
+                    handlers,
+                    draft: () => this.state.draft ?? draft,
+                    onDraft: (next) => this.setState({ ...this.state, draft: next }),
+                }),
+                // Drawing a Horn needs the design system and a browser, so the page runs this one.
+                ...pageToolSet(["look_at_it"]),
+            },
+        };
+    }
+}
+// Every ask, not just the latest: the context is ranked against this.
+function userWords(messages) {
+    return messages
+        .filter((message) => message.role === "user")
+        .flatMap((message) => (message.parts ?? []).flatMap((part) => typeof part === "object" && part !== null && "type" in part && part.type === "text" && "text" in part
+        ? [String(part.text)]
+        : []))
+        .join("\n");
+}
+/** Puts the context into the last thing the user said, leaving earlier messages alone. */
+function withUsefulContext(messages, context) {
+    const at = messages.map((message) => message.role).lastIndexOf("user");
+    if (at < 0)
+        return [...messages, { role: "user", content: context }];
+    return messages.map((message, index) => {
+        if (index !== at || message.role !== "user")
+            return message;
+        return { role: "user", content: `${wordsOf(message.content)}\n\n${context}` };
+    });
+}
+/** A converted message carries parts; what is sent must be one string. */
+function wordsOf(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .flatMap((part) => (part.type === "text" ? [part.text] : []))
+        .join("\n")
+        .trim();
+}

package/dist/studio-agent-routes.d.ts

@@ -0,0 +1,18 @@
+import { Hono } from "hono";
+export { provideStudioDeps, type StudioDeps } from "./studio-deps.ts";
+import type { HornStudioAgent, StudioAgentEnv } from "./studio-agent-class.ts";
+import { type StudioConversationEnv } from "./studio-opening.ts";
+export declare const studioUnboundMessage = "This deployment has no Studio: bind HORN_STUDIO to the HornStudioAgent class and add its migration.";
+export type StudioAgentRoutesEnv = StudioAgentEnv & StudioConversationEnv & {
+    /** The Durable Object a host binds `HornStudioAgent` to. Absent until a host adds it. */
+    HORN_STUDIO?: DurableObjectNamespace<HornStudioAgent>;
+};
+/**
+ * The Studio conversation, addressed the way every other Horns route is.
+ *
+ * Not `routeAgentRequest`: its `/agents/:binding/:name` shape carries no datastore, and the grant is
+ * checked before the object is reached rather than inside it.
+ */
+export declare function studioAgentRoutes<Env extends StudioAgentRoutesEnv>(): Hono<{
+    Bindings: Env;
+}, import("hono/types").BlankSchema, "/">;

package/dist/studio-agent-routes.js

@@ -0,0 +1,37 @@
+import { Hono } from "hono";
+// Beside the route a host mounts: the object cannot be handed its dependencies, so it is told them.
+export { provideStudioDeps } from "./studio-deps.js";
+import { getAgentByName } from "agents";
+import { authorizeStudioConversation, serializeStudioOpening, studioAuthHeader, studioConversationName, } from "./studio-opening.js";
+export const studioUnboundMessage = "This deployment has no Studio: bind HORN_STUDIO to the HornStudioAgent class and add its migration.";
+/**
+ * The Studio conversation, addressed the way every other Horns route is.
+ *
+ * Not `routeAgentRequest`: its `/agents/:binding/:name` shape carries no datastore, and the grant is
+ * checked before the object is reached rather than inside it.
+ */
+export function studioAgentRoutes() {
+    const routes = new Hono();
+    // The conversation and everything under it: the socket is the path itself, and the chat and `open`
+    // hang below it.
+    const reach = async (c) => {
+        const studio = c.env.HORN_STUDIO;
+        if (studio === undefined)
+            return c.json({ error: studioUnboundMessage }, 503);
+        const datastoreId = c.req.param("datastoreId") ?? "";
+        const conversation = c.req.param("conversation") ?? "";
+        if (datastoreId === "" || conversation === "")
+            return c.json({ error: "No conversation named." }, 404);
+        const allowed = await authorizeStudioConversation(c.req.raw, c.env, datastoreId);
+        if (!allowed.ok)
+            return allowed.response;
+        const agent = await getAgentByName(studio, studioConversationName(datastoreId, conversation));
+        // `new Request(request, { headers })` keeps a WebSocket upgrade intact; building one from parts does not.
+        const headers = new Headers(c.req.raw.headers);
+        headers.set(studioAuthHeader, serializeStudioOpening(allowed.props));
+        return agent.fetch(new Request(c.req.raw, { headers }));
+    };
+    routes.all("/api/d/:datastoreId/studio/:conversation", reach);
+    routes.all("/api/d/:datastoreId/studio/:conversation/*", reach);
+    return routes;
+}

package/dist/studio-agent.d.ts

@@ -0,0 +1,20 @@
+import { type ToolSet } from "ai";
+import type { Horn } from "@manta-eu/horns";
+import { type StudioMode, type StudioToolHandlers, type StudioToolInput, type StudioToolName } from "@manta-eu/horns/studio";
+export type StudioToolSetArgs = {
+    mode: StudioMode;
+    handlers: StudioToolHandlers;
+    draft: () => Horn;
+    /** A proposal that passed the gate carries the new draft; nothing else may change it. */
+    onDraft: (draft: Horn) => void;
+    signal?: AbortSignal;
+};
+/** What a tool call does, apart from the SDK wrapper around it. Generic, so input and handler stay bound. */
+export declare function runStudioTool<Name extends StudioToolName>(handler: NonNullable<StudioToolHandlers[Name]>, input: StudioToolInput<Name>, args: StudioToolSetArgs): Promise<string>;
+/**
+ * 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 declare function pageToolSet(names: readonly StudioToolName[]): ToolSet;
+/** The tools a mode offers, as the SDK wants them: zod in, the handler's words out. */
+export declare function studioToolSet(args: StudioToolSetArgs): ToolSet;