@nylorun/runtime 0.1.2-beta → 0.2.1-beta

package/dist/server/host.js

@@ -3,348 +3,373 @@ import { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { agUiEvents, sse } from "./ag-ui.js";
 import { observedPayload } from "./digests.js";
-import { memoryHistory, scrub, } from "../adapters/journal.js";
+import { localJsonl, scrub } from "../adapters/journal.js";
+import { jsonlObserver } from "../adapters/observe.js";
 import { IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, } from "../adapters/media.js";
 import { projectSecrets } from "../model/settings.js";
-export async function createRuntime(options) {
-    const agents = [...options.agents];
-    const byId = new Map(agents.map((agent) => [agent.id, agent]));
-    if (byId.size !== agents.length)
-        throw new Error("Agent IDs must be unique.");
-    for (const agent of agents) {
-        if (!/^[a-zA-Z0-9_-]+$/.test(agent.id))
-            throw new Error(`Invalid agent ID: ${agent.id}`);
-        if (agent.id !== agent.manifest.id || agent.name !== agent.manifest.name)
-            throw new Error("Agent identity must match its manifest.");
+import { piModel } from "../model/pi-model.js";
+const kServe = Symbol("serve");
+export class Runtime {
+    #config;
+    #served = false;
+    #closing;
+    #shutdown;
+    constructor(options = {}) {
+        this.#config = options;
     }
-    const media = options.media;
-    const journal = options.persistence ?? memoryHistory();
-    const redact = (value) => scrub(value, projectSecrets());
-    const live = new Map();
-    const app = new Hono();
-    app.onError((error, context) => context.json({ error: String(redact(error.message)) }, error instanceof HTTPException ? error.status : 500));
-    app.use("*", async (context, next) => {
-        await next();
-        if (context.res.headers.get("content-type")?.includes("application/json")) {
-            const value = await context.res.json();
-            context.res = new Response(JSON.stringify(redact(value)), {
-                status: context.res.status,
-                headers: context.res.headers,
-            });
-        }
-    });
-    app.use("*", async (context, next) => {
-        const origin = context.req.header("origin");
-        if (origin && permitted(origin, options.origins ?? [])) {
-            context.header("access-control-allow-origin", origin);
-            context.header("access-control-allow-headers", "content-type");
-            context.header("access-control-allow-methods", "GET, POST, OPTIONS");
-            context.header("vary", "origin");
+    close = () => (this.#closing ??= this.#shutdown?.() ?? Promise.resolve());
+    [kServe](options) {
+        if (this.#served)
+            throw new Error("A Runtime may only be served once.");
+        this.#served = true;
+        const agents = [...options.agents];
+        const byId = new Map(agents.map((agent) => [agent.id, agent]));
+        if (byId.size !== agents.length)
+            throw new Error("Agent IDs must be unique.");
+        for (const agent of agents) {
+            if (!/^[a-zA-Z0-9_-]+$/.test(agent.id))
+                throw new Error(`Invalid agent ID: ${agent.id}`);
+            if (agent.id !== agent.manifest.id || agent.name !== agent.manifest.name)
+                throw new Error("Agent identity must match its manifest.");
         }
-        if (context.req.method === "OPTIONS")
-            return context.body(null, 204);
-        await next();
-    });
-    app.get("/v1/agents", (context) => context.json({
-        protocolVersion: 2,
-        agents: agents.map((agent) => ({
-            id: agent.id,
-            manifestUrl: `/agents/${agent.id}/manifest.json`,
-        })),
-    }));
-    app.get("/agents/:agentId/manifest.json", (context) => {
-        const agent = byId.get(context.req.param("agentId"));
-        return agent === undefined
-            ? context.json({ error: "unknown agent" }, 404)
-            : context.json(manifest(agent, media !== undefined));
-    });
-    app.get("/agents/:agentId/v1/media/:session/:assetId", async (context) => {
-        const agent = requireAgent(context.req.param("agentId"));
-        if (!agent)
-            return context.json({ error: "unknown agent" }, 404);
-        const asset = await media?.read(agent.id, context.req.param("session"), context.req.param("assetId"));
-        if (!asset)
-            return context.json({ error: "unknown media asset" }, 404);
-        context.header("cache-control", "no-store");
-        return context.body(asset.bytes, 200, {
-            "content-type": asset.asset.mediaType,
+        const media = this.#config.media;
+        const onModelCall = this.#config.onModelCall ?? piModel({ media });
+        const journal = this.#config.durability ?? localJsonl();
+        const configuredObserver = this.#config.observer;
+        const redact = (value) => scrub(value, projectSecrets());
+        const live = new Map();
+        let publicPath = (path) => path;
+        const routerOptions = options;
+        const app = new Hono();
+        app.onError((error, context) => context.json({ error: String(redact(error.message)) }, error instanceof HTTPException ? error.status : 500));
+        app.use("*", async (context, next) => {
+            await next();
+            if (context.res.headers.get("content-type")?.includes("application/json")) {
+                const value = await context.res.json();
+                context.res = new Response(JSON.stringify(redact(value)), {
+                    status: context.res.status,
+                    headers: context.res.headers,
+                });
+            }
         });
-    });
-    app.get("/agents/:agentId/v1/sessions", async (context) => {
-        const agent = requireAgent(context.req.param("agentId"));
-        if (agent === undefined)
-            return context.json({ error: "unknown agent" }, 404);
-        const listed = await journal.list(agent.id);
-        return context.json({
-            sessions: listed.map((summary) => {
-                const found = live.get(keyOf(agent.id, summary.session));
-                if (found?.status === "running")
-                    return { ...summary, status: "running" };
-                if (found?.status === "waiting")
-                    return { ...summary, status: "waiting" };
-                return summary;
-            }),
+        publicPath = (path) => `${normalizeBasePath(routerOptions.basePath)}${path}`;
+        app.get("/v1/agents", (context) => context.json({
+            protocolVersion: 2,
+            agents: agents.map((agent) => ({
+                id: agent.id,
+                manifestUrl: publicPath(`/${agent.id}/manifest.json`),
+            })),
+        }));
+        app.get("/:agentId/manifest.json", (context) => {
+            const agent = byId.get(context.req.param("agentId"));
+            return agent === undefined
+                ? context.json({ error: "unknown agent" }, 404)
+                : context.json(manifest(agent, media !== undefined, publicPath));
         });
-    });
-    app.get("/agents/:agentId/v1/sessions/:session", async (context) => {
-        const agent = requireAgent(context.req.param("agentId"));
-        if (!agent)
-            return context.json({ error: "unknown agent" }, 404);
-        const key = keyOf(agent.id, context.req.param("session"));
-        const found = live.get(key);
-        const events = found?.events ??
-            (await journal.events(agent.id, context.req.param("session")));
-        if (!found && events.length === 0)
-            return context.json({ error: "unknown session" }, 404);
-        return context.json({
-            id: context.req.param("session"),
-            state: found?.status ?? status(events),
-            pending_interaction: pending(events),
+        app.get("/:agentId/v1/media/:session/:assetId", async (context) => {
+            const agent = requireAgent(context.req.param("agentId"));
+            if (!agent)
+                return context.json({ error: "unknown agent" }, 404);
+            const asset = await media?.read(agent.id, context.req.param("session"), context.req.param("assetId"));
+            if (!asset)
+                return context.json({ error: "unknown media asset" }, 404);
+            context.header("cache-control", "no-store");
+            return context.body(asset.bytes, 200, {
+                "content-type": asset.asset.mediaType,
+            });
         });
-    });
-    app.post("/agents/:agentId/v1/sessions/:session", async (context) => {
-        const agent = requireAgent(context.req.param("agentId"));
-        if (!agent)
-            return context.json({ error: "unknown agent" }, 404);
-        const found = live.get(keyOf(agent.id, context.req.param("session")));
-        if (!found)
-            return context.json({ error: "session is no longer live" }, 409);
-        const payload = await context.req
-            .json()
-            .catch(() => undefined);
-        const interaction = payload?.interaction;
-        if (!interaction || typeof interaction.id !== "string")
-            return context.json({ error: "expected interaction" }, 400);
-        const waiting = pending(found.events);
-        if (found.status !== "waiting" || !waiting || waiting.id !== interaction.id)
-            return context.json({ error: "interaction is no longer pending" }, 409);
-        if (interaction.kind === "approval") {
-            if (typeof interaction.approved !== "boolean")
-                return context.json({ error: "expected approval interaction" }, 400);
-            found.status = "running";
-            await submit(found, {
-                kind: "approve",
-                interactionId: interaction.id,
-                approved: interaction.approved,
+        app.get("/:agentId/v1/sessions", async (context) => {
+            const agent = requireAgent(context.req.param("agentId"));
+            if (agent === undefined)
+                return context.json({ error: "unknown agent" }, 404);
+            const listed = await journal.list(agent.id);
+            return context.json({
+                sessions: listed.map((summary) => {
+                    const found = live.get(keyOf(agent.id, summary.session));
+                    if (found?.status === "running")
+                        return { ...summary, status: "running" };
+                    if (found?.status === "waiting")
+                        return { ...summary, status: "waiting" };
+                    return summary;
+                }),
             });
-            return context.json({ session_id: context.req.param("session"), state: found.status }, 202);
-        }
-        if (interaction.kind === "respond") {
-            if (!("value" in interaction))
-                return context.json({ error: "expected respond interaction" }, 400);
-            found.status = "running";
-            await submit(found, {
-                kind: "respond",
-                interactionId: interaction.id,
-                value: interaction.value,
+        });
+        app.get("/:agentId/v1/sessions/:session", async (context) => {
+            const agent = requireAgent(context.req.param("agentId"));
+            if (!agent)
+                return context.json({ error: "unknown agent" }, 404);
+            const key = keyOf(agent.id, context.req.param("session"));
+            const found = live.get(key);
+            const events = found?.events ??
+                (await journal.events(agent.id, context.req.param("session")));
+            if (!found && events.length === 0)
+                return context.json({ error: "unknown session" }, 404);
+            return context.json({
+                id: context.req.param("session"),
+                state: found?.status ?? status(events),
+                pending_interaction: pending(events),
             });
-            return context.json({ session_id: context.req.param("session"), state: found.status }, 202);
-        }
-        return context.json({ error: "expected approval or respond interaction" }, 400);
-    });
-    app.get("/agents/:agentId/v1/sessions/:session/events", async (context) => {
-        const agent = requireAgent(context.req.param("agentId"));
-        if (!agent)
-            return context.json({ error: "unknown agent" }, 404);
-        const after = Number(context.req.query("after") ?? "0");
-        const session = context.req.param("session");
-        const events = live.get(keyOf(agent.id, session))?.events ??
-            (await journal.events(agent.id, session));
-        return context.json({
-            events: events.filter((event) => event.seq > after),
-            next_cursor: events.at(-1)?.seq ?? after,
         });
-    });
-    app.get("/agents/:agentId/v1/ag-ui/sessions/:session", async (context) => {
-        const agent = requireAgent(context.req.param("agentId"));
-        if (!agent)
-            return context.json({ error: "unknown agent" }, 404);
-        const found = live.get(keyOf(agent.id, context.req.param("session")));
-        return context.json({
-            messages: found?.messages ??
-                messages(agent.id, await journal.events(agent.id, context.req.param("session"))),
+        app.post("/:agentId/v1/sessions/:session", async (context) => {
+            const agent = requireAgent(context.req.param("agentId"));
+            if (!agent)
+                return context.json({ error: "unknown agent" }, 404);
+            const found = live.get(keyOf(agent.id, context.req.param("session")));
+            if (!found)
+                return context.json({ error: "session is no longer live" }, 409);
+            const payload = await context.req
+                .json()
+                .catch(() => undefined);
+            const interaction = payload?.interaction;
+            if (!interaction || typeof interaction.id !== "string")
+                return context.json({ error: "expected interaction" }, 400);
+            const waiting = pending(found.events);
+            if (found.status !== "waiting" ||
+                !waiting ||
+                waiting.id !== interaction.id)
+                return context.json({ error: "interaction is no longer pending" }, 409);
+            if (interaction.kind === "approval") {
+                if (typeof interaction.approved !== "boolean")
+                    return context.json({ error: "expected approval interaction" }, 400);
+                found.status = "running";
+                await submit(found, {
+                    kind: "approve",
+                    interactionId: interaction.id,
+                    approved: interaction.approved,
+                });
+                return context.json({ session_id: context.req.param("session"), state: found.status }, 202);
+            }
+            if (interaction.kind === "respond") {
+                if (!("value" in interaction))
+                    return context.json({ error: "expected respond interaction" }, 400);
+                found.status = "running";
+                await submit(found, {
+                    kind: "respond",
+                    interactionId: interaction.id,
+                    value: interaction.value,
+                });
+                return context.json({ session_id: context.req.param("session"), state: found.status }, 202);
+            }
+            return context.json({ error: "expected approval or respond interaction" }, 400);
         });
-    });
-    app.post("/agents/:agentId/v1/ag-ui", async (context) => {
-        const agent = requireAgent(context.req.param("agentId"));
-        if (!agent)
-            return context.json({ error: "unknown agent" }, 404);
-        const payload = await context.req
-            .json()
-            .catch(() => undefined);
-        const threadId = typeof payload?.threadId === "string" && payload.threadId
-            ? payload.threadId
-            : randomUUID();
-        if (!isSessionId(threadId))
+        app.get("/:agentId/v1/sessions/:session/events", async (context) => {
+            const agent = requireAgent(context.req.param("agentId"));
+            if (!agent)
+                return context.json({ error: "unknown agent" }, 404);
+            const after = Number(context.req.query("after") ?? "0");
+            const session = context.req.param("session");
+            const events = live.get(keyOf(agent.id, session))?.events ??
+                (await journal.events(agent.id, session));
             return context.json({
-                error: "threadId may only contain letters, digits, '.', '_' and '-'",
-            }, 400);
-        const runId = typeof payload?.runId === "string" && payload.runId
-            ? payload.runId
-            : randomUUID();
-        let message;
-        try {
-            message = await latestMessage(payload?.messages, media, agent.id, threadId);
-        }
-        catch (error) {
+                events: events.filter((event) => event.seq > after),
+                next_cursor: events.at(-1)?.seq ?? after,
+            });
+        });
+        app.get("/:agentId/v1/ag-ui/sessions/:session", async (context) => {
+            const agent = requireAgent(context.req.param("agentId"));
+            if (!agent)
+                return context.json({ error: "unknown agent" }, 404);
+            const found = live.get(keyOf(agent.id, context.req.param("session")));
             return context.json({
-                error: error instanceof Error
-                    ? error.message
-                    : "Invalid AG-UI user message",
-            }, 400);
+                messages: found?.messages ??
+                    messages(agent.id, await journal.events(agent.id, context.req.param("session"))),
+            });
+        });
+        app.post("/:agentId/v1/ag-ui", async (context) => {
+            const agent = requireAgent(context.req.param("agentId"));
+            if (!agent)
+                return context.json({ error: "unknown agent" }, 404);
+            const payload = await context.req
+                .json()
+                .catch(() => undefined);
+            const threadId = typeof payload?.threadId === "string" && payload.threadId
+                ? payload.threadId
+                : randomUUID();
+            if (!isSessionId(threadId))
+                return context.json({
+                    error: "threadId may only contain letters, digits, '.', '_' and '-'",
+                }, 400);
+            const runId = typeof payload?.runId === "string" && payload.runId
+                ? payload.runId
+                : randomUUID();
+            let message;
+            let actor;
+            try {
+                actor = await routerOptions.getActor?.(context);
+                const metadata = await routerOptions.getRequestMetadata?.(context);
+                message = await latestMessage(payload?.messages, media, agent.id, threadId, metadata);
+            }
+            catch (error) {
+                return context.json({
+                    error: error instanceof Error
+                        ? error.message
+                        : "Invalid AG-UI user message",
+                }, 400);
+            }
+            const found = await begin(agent, threadId, message, actor);
+            const start = found.events.length;
+            await submit(found, message.input);
+            return sse(agUiEvents(found.events.slice(start), threadId, runId), context.res.headers);
+        });
+        function requireAgent(id) {
+            return byId.get(id);
         }
-        const found = await begin(agent, threadId, message);
-        const start = found.events.length;
-        await submit(found, message.input);
-        return sse(agUiEvents(found.events.slice(start), threadId, runId), context.res.headers);
-    });
-    function requireAgent(id) {
-        return byId.get(id);
-    }
-    async function begin(agent, sessionId, message) {
-        const key = keyOf(agent.id, sessionId);
-        const existing = live.get(key);
-        if (existing) {
-            existing.messages.push(message.chat);
-            return existing;
+        async function begin(agent, sessionId, message, actor) {
+            const key = keyOf(agent.id, sessionId);
+            const existing = live.get(key);
+            if (existing) {
+                existing.messages.push(message.chat);
+                return existing;
+            }
+            const archived = await journal.events(agent.id, sessionId);
+            const concurrent = live.get(key);
+            if (concurrent) {
+                concurrent.messages.push(message.chat);
+                return concurrent;
+            }
+            if (archived.length)
+                throw new HTTPException(409, {
+                    message: "This session is archived. Start a new conversation.",
+                });
+            let entry;
+            const observer = configuredObserver ?? jsonlObserver({ agentId: agent.id, sessionId });
+            const session = agent.run({
+                id: sessionId,
+                onModelCall,
+                observer: (event) => {
+                    const image = generatedImageMessage(event, agent.id, sessionId);
+                    if (image)
+                        entry.messages.push(image);
+                    add(entry, agent.id, event.type, observedPayload(event));
+                    void Promise.resolve(observer(event)).catch(() => { });
+                },
+                ...(actor === undefined ? {} : { userId: actor.id }),
+                ...(actor?.context === undefined ? {} : { context: actor.context }),
+            });
+            entry = {
+                session,
+                events: [],
+                messages: [message.chat],
+                status: "running",
+                sequence: 0,
+                writes: Promise.resolve(),
+            };
+            live.set(key, entry);
+            return entry;
         }
-        const archived = await journal.events(agent.id, sessionId);
-        const concurrent = live.get(key);
-        if (concurrent) {
-            concurrent.messages.push(message.chat);
-            return concurrent;
+        function add(entry, agentId, type, payload) {
+            const event = {
+                session: entry.session.id,
+                seq: ++entry.sequence,
+                ts: new Date().toISOString(),
+                type,
+                payload: redact(payload),
+            };
+            entry.events.push(event);
+            entry.writes = entry.writes.then(() => journal.append(agentId, event));
+            // The submit/close paths observe durability errors; avoid an unhandled rejection meanwhile.
+            void entry.writes.catch(() => { });
         }
-        if (archived.length)
-            throw new HTTPException(409, {
-                message: "This session is archived. Start a new conversation.",
+        async function submit(entry, input) {
+            const agentId = [...live]
+                .find(([, value]) => value === entry)[0]
+                .split(":")[0];
+            entry.status = "running";
+            const inputEvent = typeof input === "string"
+                ? { kind: "user-message", text: input }
+                : "kind" in input
+                    ? input
+                    : { kind: "user-message", ...input };
+            const message = chatFromInput(inputEvent, agentId, entry.session.id);
+            add(entry, agentId, "session.run.started", {
+                input_kind: inputEvent.kind,
+                input: message ? firstText(message) : undefined,
+                ...(message ? { message } : {}),
+                ...("approved" in inputEvent ? { approved: inputEvent.approved } : {}),
+                ...("value" in inputEvent ? { value: inputEvent.value } : {}),
             });
-        const session = agent.run({ id: sessionId });
-        const entry = {
-            session,
-            events: [],
-            messages: [message.chat],
-            status: "running",
-            sequence: 0,
-            writes: Promise.resolve(),
-            unsubscribe: () => { },
-        };
-        live.set(key, entry);
-        entry.unsubscribe = session.observe((event) => {
-            const image = generatedImageMessage(event, agent.id, sessionId);
-            if (image)
-                entry.messages.push(image);
-            add(entry, agent.id, event.type, observedPayload(event));
-        });
-        return entry;
-    }
-    function add(entry, agentId, type, payload) {
-        const event = {
-            session: entry.session.id,
-            seq: ++entry.sequence,
-            ts: new Date().toISOString(),
-            type,
-            payload: redact(payload),
-        };
-        entry.events.push(event);
-        entry.writes = entry.writes.then(() => journal.append(agentId, event));
-        // The submit/close paths observe persistence errors; avoid an unhandled rejection meanwhile.
-        void entry.writes.catch(() => { });
-    }
-    async function submit(entry, input) {
-        const agentId = [...live]
-            .find(([, value]) => value === entry)[0]
-            .split(":")[0];
-        entry.status = "running";
-        const inputEvent = typeof input === "string"
-            ? { kind: "user-message", text: input }
-            : "kind" in input
-                ? input
-                : { kind: "user-message", ...input };
-        const message = chatFromInput(inputEvent, agentId, entry.session.id);
-        add(entry, agentId, "session.run.started", {
-            input_kind: inputEvent.kind,
-            input: message ? firstText(message) : undefined,
-            ...(message ? { message } : {}),
-            ...("approved" in inputEvent ? { approved: inputEvent.approved } : {}),
-            ...("value" in inputEvent ? { value: inputEvent.value } : {}),
-        });
-        const start = entry.events.length;
-        try {
-            const result = await entry.session.input(input).completed;
-            for (const event of result.events) {
-                if (event.type === "final" && event.output !== undefined) {
-                    entry.messages.push({
-                        id: randomUUID(),
-                        role: "assistant",
-                        content: finalContent(event.output),
-                    });
-                    add(entry, agentId, "final", { output: event.output });
+            const start = entry.events.length;
+            try {
+                const result = await entry.session.input(input).completed;
+                for (const event of result.events) {
+                    if (event.type === "final" && event.output !== undefined) {
+                        entry.messages.push({
+                            id: randomUUID(),
+                            role: "assistant",
+                            content: finalContent(event.output),
+                        });
+                        add(entry, agentId, "final", { output: event.output });
+                    }
+                    else if (event.type === "interaction.required") {
+                        add(entry, agentId, event.type, { interaction: event.interaction });
+                    }
                 }
-                else if (event.type === "interaction.required") {
-                    add(entry, agentId, event.type, { interaction: event.interaction });
+                const observedFailure = entry.events
+                    .slice(start)
+                    .some((event) => event.type === "error" || event.type === "tripwire");
+                const completionFailure = result.events.find((event) => event.type === "error" || event.type === "tripwire");
+                const failed = observedFailure ||
+                    completionFailure !== undefined ||
+                    (result.status !== "completed" && result.status !== "waiting");
+                if (!observedFailure && completionFailure) {
+                    add(entry, agentId, completionFailure.type, observedPayload(completionFailure));
                 }
+                else if (!observedFailure && failed) {
+                    add(entry, agentId, "error", {
+                        message: `Agent run ${result.status}.`,
+                    });
+                }
+                entry.status = failed
+                    ? "failed"
+                    : result.status === "waiting"
+                        ? "waiting"
+                        : "completed";
+                await entry.writes;
             }
-            const observedFailure = entry.events
-                .slice(start)
-                .some((event) => event.type === "error" || event.type === "tripwire");
-            const completionFailure = result.events.find((event) => event.type === "error" || event.type === "tripwire");
-            const failed = observedFailure ||
-                completionFailure !== undefined ||
-                (result.status !== "completed" && result.status !== "waiting");
-            if (!observedFailure && completionFailure) {
-                add(entry, agentId, completionFailure.type, observedPayload(completionFailure));
-            }
-            else if (!observedFailure && failed) {
+            catch (error) {
+                entry.status = "failed";
                 add(entry, agentId, "error", {
-                    message: `Agent run ${result.status}.`,
+                    message: error instanceof Error ? error.message : String(error),
                 });
+                await entry.writes;
+                throw error;
             }
-            entry.status = failed
-                ? "failed"
-                : result.status === "waiting"
-                    ? "waiting"
-                    : "completed";
-            await entry.writes;
-        }
-        catch (error) {
-            entry.status = "failed";
-            add(entry, agentId, "error", {
-                message: error instanceof Error ? error.message : String(error),
-            });
-            await entry.writes;
-            throw error;
         }
-    }
-    let closing;
-    return Object.freeze({
-        app,
-        hasSession: (agentId, sessionId) => live.has(keyOf(agentId, sessionId)),
-        close: () => (closing ??= (async () => {
+        this.#shutdown = async () => {
             const sessions = await Promise.allSettled([...live.values()].map(async (entry) => {
                 try {
                     await entry.session.stop();
                     await entry.writes;
                 }
                 finally {
-                    entry.unsubscribe();
                 }
             }));
             const resources = await Promise.allSettled(agents.map((agent) => agent.close?.()));
             const failure = [...sessions, ...resources].find((result) => result.status === "rejected");
             if (failure?.status === "rejected")
                 throw failure.reason;
-        })()),
-    });
+        };
+        return app;
+    }
+}
+/** Create the Hono protocol mount for a runtime. Applications may close it during graceful shutdown. */
+// `any` avoids leaking a second physical Hono installation through a peer boundary.
+// The returned value is the caller's Hono router at runtime.
+export function serveAgents(options) {
+    if (!(options.runtime instanceof Runtime))
+        throw new Error("serveAgents requires a Runtime.");
+    const { runtime, ...rest } = options;
+    return runtime[kServe](rest);
 }
-function manifest(agent, media) {
+function manifest(agent, media, publicPath) {
     return {
         protocolVersion: 2,
         id: agent.manifest.id,
         name: agent.manifest.name,
         manifest: agent.manifest,
         endpoints: {
-            agUi: `/agents/${agent.id}/v1/ag-ui`,
-            sessions: `/agents/${agent.id}/v1/sessions`,
+            agUi: publicPath(`/${agent.id}/v1/ag-ui`),
+            sessions: publicPath(`/${agent.id}/v1/sessions`),
         },
         ...(media
             ? {
@@ -359,14 +384,14 @@ function manifest(agent, media) {
 function keyOf(agent, session) {
     return `${agent}:${session}`;
 }
-async function latestMessage(value, media, agentId, sessionId) {
+async function latestMessage(value, media, agentId, sessionId, metadata) {
     if (!Array.isArray(value))
         throw new Error("AG-UI requires a user message.");
     for (let i = value.length - 1; i >= 0; i -= 1) {
         const item = value[i];
         if (item?.role !== "user")
             continue;
-        const content = await incomingContent(item.content, media, agentId, sessionId);
+        const content = await incomingContent(item.content, media, agentId, sessionId, metadata);
         if (content)
             return content;
     }
@@ -409,7 +434,7 @@ function messages(agentId, events) {
                 ? [generatedImageFromEvent(event, agentId)]
                 : []);
 }
-async function incomingContent(value, media, agentId, sessionId) {
+async function incomingContent(value, media, agentId, sessionId, metadata) {
     const parts = [];
     const chat = [];
     if (typeof value === "string") {
@@ -459,7 +484,10 @@ async function incomingContent(value, media, agentId, sessionId) {
     if (parts.length === 0)
         return undefined;
     return Object.freeze({
-        input: { content: Object.freeze(parts) },
+        input: {
+            content: Object.freeze(parts),
+            ...(metadata === undefined ? {} : { metadata }),
+        },
         chat: { id: randomUUID(), role: "user", content: Object.freeze(chat) },
     });
 }
@@ -565,42 +593,12 @@ function isSessionId(value) {
     return value !== "." && value !== ".." && /^[a-zA-Z0-9._-]+$/u.test(value);
 }
 function mediaUrl(agentId, sessionId, assetId) {
-    return `/agents/${encodeURIComponent(agentId)}/v1/media/${encodeURIComponent(sessionId)}/${encodeURIComponent(assetId)}`;
-}
-/** Host headers a loopback bind answers to, on the port actually in use. */
-export function loopbackHosts(port) {
-    return [`localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`];
+    return `media/${encodeURIComponent(sessionId)}/${encodeURIComponent(assetId)}`;
 }
-/**
- * Decide whether a request's Host header is served. Entries are exact
- * `host:port` values or bare host names that accept any port; `*` accepts all.
- */
-export function allowedHost(header, allowed) {
-    if (allowed.includes("*"))
-        return true;
-    if (!header)
-        return false;
-    let hostname;
-    try {
-        hostname = new URL(`http://${header}`).hostname;
-    }
-    catch {
-        return false;
-    }
-    const bare = hostname.replace(/^\[(.*)\]$/u, "$1");
-    return allowed.some((entry) => entry.toLowerCase() === header.toLowerCase() ||
-        entry.toLowerCase() === hostname ||
-        entry.toLowerCase() === bare);
-}
-function permitted(origin, configured) {
-    try {
-        const url = new URL(origin);
-        return (configured.includes(origin) ||
-            url.hostname === "localhost" ||
-            url.hostname.endsWith(".localhost") ||
-            url.hostname === "127.0.0.1");
-    }
-    catch {
-        return false;
-    }
+function normalizeBasePath(value) {
+    if (!value || value === "/")
+        return "";
+    if (!value.startsWith("/") || value.endsWith("/"))
+        throw new Error("basePath must start with / and must not end with /.");
+    return value;
 }