@nylorun/agents 0.7.0-beta → 0.9.0-beta

package/dist/ag-ui/handler.js

@@ -0,0 +1,397 @@
+/**
+ * An AG-UI endpoint over the Tenant's agents, as web-standard `Request` → `Response`
+ * handlers. The host authenticates people (`subject`); the handler maps each AG-UI thread to
+ * one session per subject, agent and thread, and streams the session's transcript events as
+ * AG-UI events. It never trusts a session id from the client, and it calls the Runtime as the
+ * subject (`client.as`), so the Runtime itself keeps one subject out of another's sessions.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { EventType } from "@ag-ui/core";
+import { RunAgentInputSchema } from "@ag-ui/core/schemas";
+import { parseSubjectHeaders, } from "@nylorun/core/contracts";
+import { createClient, } from "../client.js";
+import { IncompatibleRuntimeError, RuntimeError } from "../http.js";
+import { messagesFromEvents } from "./history.js";
+import { SSE_CONTENT_TYPE, SSE_HEARTBEAT, sseFrame } from "./sse.js";
+import { RunTranslator } from "./translate.js";
+const HEARTBEAT_MS = 15_000;
+/** Host features the handler needs: the chat transcript, and acting for each subject. */
+const REQUIRED_FEATURES = ["transcript-events", "subject-headers"];
+const DEFAULT_SCOPES = ["sessions:own"];
+const TERMINAL = new Set([
+    "turn.completed",
+    "turn.paused",
+    "turn.failed",
+    "turn.cancelled",
+]);
+class Problem extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+function problem(status, message, code) {
+    return Response.json({ error: message, ...(code ? { code } : {}) }, { status });
+}
+function problemOf(error) {
+    if (error instanceof Problem)
+        return error;
+    if (error instanceof RuntimeError) {
+        if (error.status === 404)
+            return new Problem(404, "Not found");
+        // The Runtime refused what the client sent (e.g. a cursor it cannot read).
+        if (error.status === 400)
+            return new Problem(400, "The request was rejected", "invalid_request");
+        if (error.status === 409)
+            return new Problem(409, "The agent is busy or waiting for an answer to an open interrupt", "session_busy");
+        return new Problem(502, "The agent service failed", "runtime_error");
+    }
+    if (error instanceof IncompatibleRuntimeError)
+        return new Problem(502, error.message, "runtime_incompatible");
+    return new Problem(500, "Internal error");
+}
+/** A session per subject, agent and thread; one subject can never name another's session. */
+export function sessionIdFor(subject, agentId, threadId) {
+    return createHash("sha256")
+        .update(`${subject}\u0000${agentId}\u0000${threadId}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+/** The trailing user message: the Runtime keeps the transcript, AG-UI resends all of it. */
+function lastUserMessage(messages) {
+    const last = messages.at(-1);
+    if (!last || last.role !== "user")
+        throw new Problem(400, "The run's last message must be a user message");
+    const text = typeof last.content === "string"
+        ? last.content
+        : last.content
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join("\n");
+    if (!text.trim())
+        throw new Problem(400, "The user message has no text");
+    return { id: last.id, text };
+}
+function normalizeBase(basePath = "/") {
+    const trimmed = basePath.replace(/\/+$/, "");
+    return trimmed === "" ? "" : trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+export function createAgUiHandler(options) {
+    const allowed = new Set(options.agents.map((agent) => (typeof agent === "string" ? agent : agent.id)));
+    const base = normalizeBase(options.basePath);
+    const scopes = options.scopes ?? DEFAULT_SCOPES;
+    const checked = parseSubjectHeaders("probe", scopes.join(" "));
+    if (!checked.ok)
+        throw new TypeError(`createAgUiHandler: ${checked.message}`);
+    let ready;
+    /** The client, once the Runtime is known to have every required feature. Retries after a failure. */
+    function connected() {
+        ready ??= (async () => {
+            const client = await (options.client ?? createClient());
+            const features = await client.hostFeatures();
+            const missing = REQUIRED_FEATURES.filter((f) => !features.includes(f));
+            if (missing.length > 0)
+                throw new Problem(502, `The Runtime does not support ${missing.join(", ")}; upgrade the stack (nylorun up).`, "runtime_feature_missing");
+            return client;
+        })();
+        ready.catch(() => {
+            ready = undefined;
+        });
+        return ready;
+    }
+    /** The client acting for `subject`: the Runtime limits it to the subject's own sessions. */
+    async function clientFor(subject) {
+        const client = await connected();
+        try {
+            return client.as(subject, { scopes });
+        }
+        catch (error) {
+            // The host's `subject` returned something the Runtime cannot name (see `as`).
+            throw new Problem(500, error.message, "subject_invalid");
+        }
+    }
+    async function subjectOf(request) {
+        const subject = await options.subject(request);
+        if (!subject)
+            throw new Problem(401, "Sign in required");
+        return subject;
+    }
+    function assertAgent(agentId) {
+        if (!allowed.has(agentId))
+            throw new Problem(404, "Not found");
+    }
+    async function sessionFor(request, agentId, threadId) {
+        assertAgent(agentId);
+        const subject = await subjectOf(request);
+        const client = await clientFor(subject);
+        return {
+            client,
+            subject,
+            session: client.session(sessionIdFor(subject, agentId, threadId)),
+        };
+    }
+    async function submit(session, input) {
+        if (input.resume?.length) {
+            let cursor = null;
+            // The interaction's kind is on the pending view, not in its id.
+            const pending = await session.pending();
+            const waits = Array.isArray(pending) ? pending : [];
+            for (const entry of input.resume) {
+                const wait = waits.find((w) => w?.interaction?.id === entry.interruptId);
+                const key = `${input.runId}:${entry.interruptId}`;
+                const payload = entry.payload;
+                const accepted = (wait?.interaction?.kind ?? "approval") === "approval"
+                    ? await session.approve(entry.interruptId, entry.status === "resolved" &&
+                        (payload === true ||
+                            (typeof payload === "object" && payload?.approved === true)), { idempotencyKey: key })
+                    : entry.status === "cancelled"
+                        ? await session.cancel({ idempotencyKey: key, reason: "interrupt cancelled" })
+                        : await session.respond(entry.interruptId, (entry.payload ?? null), {
+                            idempotencyKey: key,
+                        });
+                cursor ??= accepted.cursor;
+            }
+            return cursor;
+        }
+        const message = lastUserMessage(input.messages);
+        // The AG-UI message id is the idempotency key: a retried run replays the same turn,
+        // and history gives the message back its client id.
+        const accepted = await session.input(message.text, {
+            idempotencyKey: message.id,
+        });
+        return accepted.cursor;
+    }
+    /** Streams translated events until the run ends. Closing the response stops the read only. */
+    function stream(request, translator, source, preface = []) {
+        const reading = new AbortController();
+        request.signal.addEventListener("abort", () => reading.abort(), { once: true });
+        const bytes = new TextEncoder();
+        const body = new ReadableStream({
+            async start(controller) {
+                const write = (text) => {
+                    try {
+                        controller.enqueue(bytes.encode(text));
+                    }
+                    catch {
+                        reading.abort();
+                    }
+                };
+                const heartbeat = setInterval(() => write(SSE_HEARTBEAT), HEARTBEAT_MS);
+                try {
+                    write(sseFrame(translator.started()));
+                    for (const event of preface)
+                        write(sseFrame(event));
+                    if (source)
+                        for await (const event of source(reading.signal)) {
+                            const step = translator.translate(event);
+                            step.events.forEach((out, index) => write(sseFrame(out, index === step.events.length - 1 ? event.cursor : undefined)));
+                            if (step.finished || reading.signal.aborted)
+                                break;
+                        }
+                }
+                catch (error) {
+                    if (!reading.signal.aborted) {
+                        const failure = problemOf(error);
+                        write(sseFrame({
+                            type: EventType.RUN_ERROR,
+                            message: failure.message,
+                            ...(failure.code ? { code: failure.code } : {}),
+                        }));
+                    }
+                }
+                finally {
+                    clearInterval(heartbeat);
+                    reading.abort();
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        /* the client is gone */
+                    }
+                }
+            },
+            cancel() {
+                reading.abort();
+            },
+        });
+        return new Response(body, {
+            headers: {
+                "content-type": SSE_CONTENT_TYPE,
+                "cache-control": "no-cache, no-transform",
+                "x-accel-buffering": "no",
+            },
+        });
+    }
+    async function run(request, agentId) {
+        try {
+            assertAgent(agentId);
+            const subject = await subjectOf(request);
+            const parsed = RunAgentInputSchema.safeParse(await request.json().catch(() => undefined));
+            if (!parsed.success)
+                throw new Problem(400, "Invalid RunAgentInput");
+            const input = parsed.data;
+            // Nylorun tools run in the Runtime or the app's executor; the browser runs none.
+            if (input.tools?.length)
+                throw new Problem(400, "Frontend tools are not supported");
+            const client = await clientFor(subject);
+            const extra = (await options.session?.(subject, agentId)) ?? {};
+            const translator = new RunTranslator(input.threadId, input.runId);
+            let session;
+            try {
+                // The host's parameters first: they never replace the session's identity.
+                session = await client.createSession({
+                    ...extra,
+                    id: sessionIdFor(subject, agentId, input.threadId),
+                    agentId,
+                    ownerUserId: subject,
+                });
+            }
+            catch (error) {
+                if (error instanceof RuntimeError && error.status === 409)
+                    throw new Problem(409, "The thread's session was opened with other parameters", "session_conflict");
+                throw error;
+            }
+            let cursor;
+            try {
+                cursor = await submit(session, input);
+            }
+            catch (error) {
+                const failure = problemOf(error);
+                // A busy or paused session is a run that could not start, not a transport failure.
+                if (failure.status !== 409)
+                    throw failure;
+                return stream(request, translator, undefined, [
+                    {
+                        type: EventType.RUN_ERROR,
+                        message: failure.message,
+                        code: failure.code,
+                    },
+                ]);
+            }
+            return stream(request, translator, (signal) => session.observe({ ...(cursor ? { cursor } : {}), signal }));
+        }
+        catch (error) {
+            const failure = problemOf(error);
+            return problem(failure.status, failure.message, failure.code);
+        }
+    }
+    async function history(request, agentId, threadId) {
+        try {
+            const { session } = await sessionFor(request, agentId, threadId);
+            const items = [];
+            let cursor;
+            try {
+                for (;;) {
+                    const page = await session.history({ ...(cursor ? { cursor } : {}) });
+                    items.push(...page.items);
+                    if (!page.cursor || page.cursor === cursor || page.items.length === 0)
+                        break;
+                    cursor = page.cursor;
+                }
+            }
+            catch (error) {
+                // A thread that never ran has no session yet.
+                if (error instanceof RuntimeError && error.status === 404)
+                    return Response.json([]);
+                throw error;
+            }
+            return Response.json(messagesFromEvents(items));
+        }
+        catch (error) {
+            const failure = problemOf(error);
+            return problem(failure.status, failure.message, failure.code);
+        }
+    }
+    async function reattach(request, agentId, threadId) {
+        try {
+            const { session } = await sessionFor(request, agentId, threadId);
+            const url = new URL(request.url);
+            const cursor = request.headers.get("last-event-id") ?? url.searchParams.get("cursor");
+            if (!cursor)
+                throw new Problem(400, "Last-Event-ID or ?cursor= is required");
+            const view = await session.inspect();
+            const runId = url.searchParams.get("runId") ??
+                view.activeTurnId ??
+                (typeof view.lastTurnId === "string" ? view.lastTurnId : randomUUID());
+            const translator = new RunTranslator(threadId, runId, { reattached: true });
+            if (view.activeTurnId)
+                return stream(request, translator, (signal) => session.observe({ cursor, signal }));
+            // No turn is running: send what the client missed, if the run ended after the cursor.
+            const missed = [];
+            let from = cursor;
+            for (;;) {
+                const page = await session.history({ cursor: from });
+                missed.push(...page.items);
+                if (!page.cursor || page.cursor === from || page.items.length === 0)
+                    break;
+                from = page.cursor;
+            }
+            if (!missed.some((event) => TERMINAL.has(event.type)))
+                return new Response(null, { status: 204 });
+            return stream(request, translator, () => iterate(missed));
+        }
+        catch (error) {
+            const failure = problemOf(error);
+            return problem(failure.status, failure.message, failure.code);
+        }
+    }
+    async function cancel(request, agentId, threadId) {
+        try {
+            const { session } = await sessionFor(request, agentId, threadId);
+            await session.cancel({ idempotencyKey: `cancel:${randomUUID()}` });
+            return new Response(null, { status: 204 });
+        }
+        catch (error) {
+            const failure = problemOf(error);
+            return problem(failure.status, failure.message, failure.code);
+        }
+    }
+    async function route(request) {
+        const path = new URL(request.url).pathname;
+        if (path !== base && !path.startsWith(`${base}/`))
+            return problem(404, "Not found");
+        let segments;
+        try {
+            segments = path
+                .slice(base.length)
+                .split("/")
+                .slice(1)
+                .map((segment) => decodeURIComponent(segment));
+        }
+        catch {
+            return problem(404, "Not found");
+        }
+        if (segments.some((segment) => segment === ""))
+            return problem(404, "Not found");
+        const [agentId, threads, threadId, action] = segments;
+        const method = request.method.toUpperCase();
+        const operation = (allow, handle) => {
+            if (!agentId || !allowed.has(agentId))
+                return problem(404, "Not found");
+            if (method !== allow)
+                return new Response(JSON.stringify({ error: "Method not allowed" }), {
+                    status: 405,
+                    headers: { allow, "content-type": "application/json" },
+                });
+            return handle();
+        };
+        if (segments.length === 1)
+            return operation("POST", () => run(request, agentId));
+        if (segments.length === 4 && threads === "threads") {
+            if (action === "messages")
+                return operation("GET", () => history(request, agentId, threadId));
+            if (action === "events")
+                return operation("GET", () => reattach(request, agentId, threadId));
+            if (action === "cancel")
+                return operation("POST", () => cancel(request, agentId, threadId));
+        }
+        return problem(404, "Not found");
+    }
+    return { fetch: route, run, history, reattach, cancel };
+}
+async function* iterate(items) {
+    yield* items;
+}

package/dist/ag-ui/history.d.ts

@@ -0,0 +1,7 @@
+/**
+ * An AG-UI transcript rebuilt from a session's log, with the ids a live run gave each
+ * message (see `translate.ts`), usable as `HttpAgent`'s `initialMessages`.
+ */
+import type { Message } from "@ag-ui/core";
+import { type LiveEvent } from "@nylorun/core/contracts";
+export declare function messagesFromEvents(items: readonly LiveEvent[]): Message[];

package/dist/ag-ui/history.js

@@ -0,0 +1,60 @@
+import { parseTranscriptEvent } from "@nylorun/core/contracts";
+import { outputText, toolResultOf } from "./translate.js";
+export function messagesFromEvents(items) {
+    const messages = [];
+    const results = new Set();
+    let sawAssistant = false;
+    for (const raw of items) {
+        if (raw.type === "command.message") {
+            const p = (raw.payload ?? {});
+            messages.push({
+                // The handler sends the client's message id as the idempotency key.
+                id: p.idempotencyKey ?? raw.eventId,
+                role: "user",
+                content: typeof p.content === "string" ? p.content : JSON.stringify(p.data),
+            });
+            sawAssistant = false;
+            continue;
+        }
+        const event = parseTranscriptEvent(raw);
+        if (!event)
+            continue;
+        const result = toolResultOf(event);
+        if (result) {
+            if (results.has(result.callId))
+                continue;
+            results.add(result.callId);
+            messages.push({
+                id: `${result.callId}:result`,
+                role: "tool",
+                toolCallId: result.callId,
+                content: result.content,
+            });
+            continue;
+        }
+        if (event.type === "message.assistant" && !event.payload.agent) {
+            const p = event.payload;
+            sawAssistant = true;
+            const message = { id: p.invocationId, role: "assistant" };
+            if (p.text)
+                message.content = p.text;
+            if (p.toolCalls.length)
+                message.toolCalls = p.toolCalls.map((call) => ({
+                    id: call.callId,
+                    type: "function",
+                    function: { name: call.name, arguments: JSON.stringify(call.input ?? {}) },
+                }));
+            messages.push(message);
+        }
+        else if (event.type === "turn.completed" && !sawAssistant) {
+            const output = event.payload.output;
+            if (output !== undefined && output !== null && outputText(output))
+                messages.push({
+                    id: raw.eventId,
+                    role: "assistant",
+                    content: outputText(output),
+                });
+        }
+    }
+    return messages;
+}

package/dist/ag-ui/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@nylorun/agents/ag-ui`: serve the Tenant's agents to AG-UI clients from the app's own
+ * server. The only entry point that loads `@ag-ui/core`.
+ */
+export { createAgUiHandler } from "./handler.js";
+export type { AgUiHandler, AgUiHandlerOptions, AgUiSessionOptions, } from "./handler.js";
+export { toNodeListener } from "./node.js";

package/dist/ag-ui/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@nylorun/agents/ag-ui`: serve the Tenant's agents to AG-UI clients from the app's own
+ * server. The only entry point that loads `@ag-ui/core`.
+ */
+export { createAgUiHandler } from "./handler.js";
+export { toNodeListener } from "./node.js";

package/dist/ag-ui/node.d.ts

@@ -0,0 +1,5 @@
+/** `node:http` and Express adapter for a fetch-style handler. */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function toNodeListener(handler: {
+    readonly fetch: (request: Request) => Promise<Response>;
+}): (req: IncomingMessage, res: ServerResponse) => void;

package/dist/ag-ui/node.js

@@ -0,0 +1,51 @@
+import { Readable } from "node:stream";
+export function toNodeListener(handler) {
+    return (req, res) => {
+        void (async () => {
+            // A closed connection aborts the request, which stops the read, never the turn.
+            const controller = new AbortController();
+            res.on("close", () => controller.abort());
+            const host = req.headers.host ?? "localhost";
+            const url = new URL(req.url ?? "/", `http://${host}`);
+            const headers = new Headers();
+            for (const [name, value] of Object.entries(req.headers)) {
+                if (value === undefined)
+                    continue;
+                for (const item of Array.isArray(value) ? value : [value])
+                    headers.append(name, item);
+            }
+            const hasBody = req.method !== "GET" && req.method !== "HEAD";
+            const request = new Request(url, {
+                method: req.method,
+                headers,
+                signal: controller.signal,
+                ...(hasBody
+                    ? {
+                        body: Readable.toWeb(req),
+                        duplex: "half",
+                    }
+                    : {}),
+            });
+            let response;
+            try {
+                response = await handler.fetch(request);
+            }
+            catch {
+                response = new Response(JSON.stringify({ error: "Internal error" }), {
+                    status: 500,
+                    headers: { "content-type": "application/json" },
+                });
+            }
+            res.writeHead(response.status, Object.fromEntries(response.headers));
+            if (!response.body) {
+                res.end();
+                return;
+            }
+            res.flushHeaders();
+            const body = Readable.fromWeb(response.body);
+            body.on("error", () => res.destroy());
+            res.on("close", () => body.destroy());
+            body.pipe(res);
+        })();
+    };
+}

package/dist/ag-ui/sse.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AG-UI over server-sent events: one `data:` line of JSON per event. The last AG-UI event
+ * made from a Runtime event carries that event's cursor as `id:`, so a client that resumes
+ * from `Last-Event-ID` never lands inside a group.
+ */
+import type { BaseEvent } from "@ag-ui/core";
+export declare const SSE_CONTENT_TYPE = "text/event-stream";
+export declare function sseFrame(event: BaseEvent, id?: string): string;
+export declare const SSE_HEARTBEAT = ": keep-alive\n\n";

package/dist/ag-ui/sse.js

@@ -0,0 +1,7 @@
+export const SSE_CONTENT_TYPE = "text/event-stream";
+export function sseFrame(event, id) {
+    // Cursors are opaque base64; a line break would end the field early.
+    const idLine = id && !/[\r\n]/.test(id) ? `id: ${id}\n` : "";
+    return `${idLine}data: ${JSON.stringify(event)}\n\n`;
+}
+export const SSE_HEARTBEAT = ": keep-alive\n\n";

package/dist/ag-ui/translate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Runtime transcript events → AG-UI 1.0 events for one run. Ids: an assistant message is its
+ * model call's `invocationId`, a tool call is the model's `callId`, a tool result is
+ * `<callId>:result`, so live runs and `messagesFromEvents` agree.
+ */
+import { type BaseEvent } from "@ag-ui/core";
+import { type LiveEvent, type TranscriptEvent } from "@nylorun/core/contracts";
+/** The text a tool result shows; `undefined` while there is no result yet. */
+export declare function toolResultText(result: unknown): string | undefined;
+export declare function outputText(output: unknown): string;
+/** One Runtime event's result for a run: AG-UI events, and whether the run ended. */
+export interface Step {
+    readonly events: BaseEvent[];
+    readonly finished: boolean;
+}
+/** A tool result from any of the three places a call can end. */
+export declare function toolResultOf(event: TranscriptEvent): {
+    callId: string;
+    content: string;
+} | undefined;
+export declare class RunTranslator {
+    private readonly threadId;
+    private readonly runId;
+    /** Tool invocation → the model's call id, for interrupts that name the invocation. */
+    private readonly callIds;
+    private readonly closed;
+    private sawAssistant;
+    /**
+     * `reattached`: the run continues from a cursor, so earlier assistant messages already
+     * reached the client and a workflow's output is not repeated as text.
+     */
+    constructor(threadId: string, runId: string, options?: {
+        reattached?: boolean;
+    });
+    translate(raw: LiveEvent): Step;
+    started(): BaseEvent;
+    private finished;
+}