@nylorun/runtime 0.12.0-beta → 0.14.0-beta

package/dist/api/a2a/card.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The Agent Card of one agent, from its manifest: name, description and one skill, never its
+ * instructions, tools or MCP servers. The Runtime does not know where callers reach it, so
+ * `supportedInterfaces` is empty: whoever publishes the card (the gateway in v1) adds its own
+ * URL, provider and security schemes.
+ */
+export interface CardDefinition {
+    readonly manifest: {
+        id?: unknown;
+        name?: unknown;
+        description?: unknown;
+    };
+    readonly implementationVersion: string;
+}
+export declare function agentCard(agentId: string, definition: CardDefinition): Record<string, unknown>;

package/dist/api/a2a/card.js

@@ -0,0 +1,24 @@
+/**
+ * The Agent Card of one agent, from its manifest: name, description and one skill, never its
+ * instructions, tools or MCP servers. The Runtime does not know where callers reach it, so
+ * `supportedInterfaces` is empty: whoever publishes the card (the gateway in v1) adds its own
+ * URL, provider and security schemes.
+ */
+const MODES = ["text/plain", "application/json"];
+export function agentCard(agentId, definition) {
+    const { manifest } = definition;
+    const name = typeof manifest.name === "string" && manifest.name !== "" ? manifest.name : agentId;
+    const description = typeof manifest.description === "string" && manifest.description !== ""
+        ? manifest.description
+        : name;
+    return {
+        name,
+        description,
+        supportedInterfaces: [],
+        version: definition.implementationVersion,
+        capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
+        defaultInputModes: MODES,
+        defaultOutputModes: MODES,
+        skills: [{ id: agentId, name, description, tags: [] }],
+    };
+}

package/dist/api/a2a/endpoint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The A2A endpoint's routes (`/v1/a2a/agents/{agentId}[/card]`), declared for serving and for
+ * the Runtime's OpenAPI document. What each does is in `routes.ts`. The JSON-RPC operations are
+ * A2A's (specification 1.0); the document describes the envelope and links the specification.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../http/app.js";
+export declare function a2aRoutes(api: OpenAPIHono<TenantEnv>): void;

package/dist/api/a2a/endpoint.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { readText } from "../http/body.js";
+import { tenantRoute } from "../http/define.js";
+import { jsonResponse } from "../http/respond.js";
+import { a2aCall, a2aCard } from "./routes.js";
+const A2A_SPECIFICATION = {
+    description: "The A2A specification",
+    url: "https://a2a-protocol.org/latest/specification/",
+};
+const agentId = z.object({ agentId: z.string() });
+const TAGS = ["A2A"];
+const JsonRpcRequest = z
+    .looseObject({
+    jsonrpc: z.literal("2.0"),
+    id: z.union([z.string(), z.number(), z.null()]).optional(),
+    method: z
+        .string()
+        .meta({ description: "`SendMessage`, `GetTask` or `CancelTask`; others answer their A2A error" }),
+    params: z.unknown().optional(),
+})
+    .meta({ id: "A2aJsonRpcRequest" });
+const JsonRpcResponse = z
+    .looseObject({
+    jsonrpc: z.literal("2.0"),
+    id: z.union([z.string(), z.number(), z.null()]),
+    result: z.unknown().optional(),
+    error: z
+        .object({ code: z.number().int(), message: z.string(), data: z.unknown().optional() })
+        .optional(),
+})
+    .meta({ id: "A2aJsonRpcResponse" });
+const AgentCard = z
+    .looseObject({ name: z.string(), description: z.string().optional(), skills: z.array(z.unknown()).optional() })
+    .meta({ id: "A2aAgentCard", description: "The agent's A2A card, without interfaces" });
+export function a2aRoutes(api) {
+    tenantRoute(api, {
+        credentials: ["application", "subject", "token"],
+        scopes: ["agents:read", "sessions:own"],
+    }, {
+        method: "get",
+        path: "/v1/a2a/agents/{agentId}/card",
+        tags: TAGS,
+        summary: "Get an agent's A2A card",
+        externalDocs: A2A_SPECIFICATION,
+        request: { params: agentId },
+        responses: {
+            200: { description: "The card", content: { "application/json": { schema: AgentCard } } },
+        },
+    }, async (c) => {
+        const scope = c.get("scope");
+        return jsonResponse(200, await a2aCard(c.env.tenant, scope, c.req.param("agentId")));
+    });
+    tenantRoute(api, { credentials: ["subject", "token"], scopes: ["sessions:own"] }, {
+        method: "post",
+        path: "/v1/a2a/agents/{agentId}",
+        tags: TAGS,
+        summary: "Call an agent over A2A",
+        description: "A2A 1.0 JSON-RPC, for a subject: `SendMessage` (blocking up to 5 minutes, or `returnImmediately`), `GetTask` and `CancelTask`. A context is one session per subject, agent and `contextId`; a task is one turn. JSON-RPC errors are answered with 200; limits, scopes and unavailable streams stay HTTP errors.",
+        externalDocs: A2A_SPECIFICATION,
+        request: {
+            params: agentId,
+            query: z.object({
+                "A2A-Version": z.string().optional().meta({ description: "Or the `A2A-Version` header: `1.0`" }),
+            }),
+            body: { required: true, content: { "application/json": { schema: JsonRpcRequest } } },
+        },
+        responses: {
+            200: {
+                description: "The JSON-RPC answer: a result, or an A2A error",
+                content: { "application/json": { schema: JsonRpcResponse } },
+            },
+        },
+    }, async (c) => {
+        const scope = c.get("scope");
+        const version = c.env.incoming.headers["a2a-version"];
+        return jsonResponse(200, await a2aCall(c.env.tenant, scope, c.req.param("agentId"), {
+            body: () => readText(c.req.raw),
+            version: typeof version === "string" ? version : (c.req.query("A2A-Version") ?? null),
+        }, c.env.outgoing));
+    });
+}

package/dist/api/a2a/protocol.d.ts

@@ -0,0 +1,144 @@
+/**
+ * A2A 1.0 over JSON-RPC: the wire types the Runtime answers with, the envelope, the error
+ * codes and the parameter checks (Host feature `a2a-endpoint`). Only what v1 serves is typed:
+ * text and data parts, tasks, the card. Field names are the spec's ProtoJSON (camelCase,
+ * enum values such as `TASK_STATE_WORKING`). No Tenant state is read here.
+ */
+/** The A2A version this endpoint speaks (`A2A-Version`, Major.Minor). */
+export declare const A2A_VERSION = "1.0";
+export type TaskState = "TASK_STATE_SUBMITTED" | "TASK_STATE_WORKING" | "TASK_STATE_INPUT_REQUIRED" | "TASK_STATE_AUTH_REQUIRED" | "TASK_STATE_COMPLETED" | "TASK_STATE_FAILED" | "TASK_STATE_CANCELED" | "TASK_STATE_REJECTED";
+export declare const TERMINAL_STATES: ReadonlySet<TaskState>;
+export type Part = {
+    text: string;
+    mediaType?: string;
+    metadata?: Record<string, unknown>;
+} | {
+    data: unknown;
+    mediaType?: string;
+    metadata?: Record<string, unknown>;
+};
+export interface Message {
+    messageId: string;
+    role: "ROLE_USER" | "ROLE_AGENT";
+    parts: Part[];
+    contextId?: string;
+    taskId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface Artifact {
+    artifactId: string;
+    name?: string;
+    parts: Part[];
+}
+export interface TaskStatus {
+    state: TaskState;
+    message?: Message;
+    timestamp?: string;
+}
+export interface Task {
+    id: string;
+    contextId: string;
+    status: TaskStatus;
+    artifacts?: Artifact[];
+    history?: Message[];
+}
+/** The standard JSON-RPC codes and the A2A codes (spec §5.4, §9.5). */
+export declare const A2A_ERRORS: {
+    readonly parse: {
+        readonly code: -32700;
+        readonly reason: "INVALID_JSON";
+    };
+    readonly invalidRequest: {
+        readonly code: -32600;
+        readonly reason: "INVALID_REQUEST";
+    };
+    readonly methodNotFound: {
+        readonly code: -32601;
+        readonly reason: "METHOD_NOT_FOUND";
+    };
+    readonly invalidParams: {
+        readonly code: -32602;
+        readonly reason: "INVALID_PARAMS";
+    };
+    readonly internal: {
+        readonly code: -32603;
+        readonly reason: "INTERNAL";
+    };
+    readonly taskNotFound: {
+        readonly code: -32001;
+        readonly reason: "TASK_NOT_FOUND";
+    };
+    readonly taskNotCancelable: {
+        readonly code: -32002;
+        readonly reason: "TASK_NOT_CANCELABLE";
+    };
+    readonly pushNotSupported: {
+        readonly code: -32003;
+        readonly reason: "PUSH_NOTIFICATION_NOT_SUPPORTED";
+    };
+    readonly unsupportedOperation: {
+        readonly code: -32004;
+        readonly reason: "UNSUPPORTED_OPERATION";
+    };
+    readonly contentTypeNotSupported: {
+        readonly code: -32005;
+        readonly reason: "CONTENT_TYPE_NOT_SUPPORTED";
+    };
+    readonly versionNotSupported: {
+        readonly code: -32009;
+        readonly reason: "VERSION_NOT_SUPPORTED";
+    };
+};
+export type A2aErrorKind = keyof typeof A2A_ERRORS;
+/** An error answered in the JSON-RPC body, with `google.rpc.ErrorInfo` (and `BadRequest`). */
+export declare class A2aError extends Error {
+    readonly kind: A2aErrorKind;
+    readonly metadata: Readonly<Record<string, string>>;
+    /** `google.rpc.BadRequest` field violations, for invalid parameters. */
+    readonly field?: string | undefined;
+    constructor(kind: A2aErrorKind, message: string, metadata?: Readonly<Record<string, string>>, 
+    /** `google.rpc.BadRequest` field violations, for invalid parameters. */
+    field?: string | undefined);
+}
+export declare const a2aFail: (kind: A2aErrorKind, message: string, metadata?: Record<string, string>, field?: string) => never;
+export type JsonRpcId = string | number | null;
+export interface JsonRpcRequest {
+    id: JsonRpcId;
+    method: string;
+    params: Record<string, unknown>;
+}
+export declare function jsonRpcResult(id: JsonRpcId, result: unknown): unknown;
+export declare function jsonRpcError(id: JsonRpcId, error: A2aError): unknown;
+/** A JSON-RPC 2.0 request object, or an `A2aError` (`id` recovered when possible). */
+export declare function parseEnvelope(text: string): {
+    ok: true;
+    request: JsonRpcRequest;
+} | {
+    ok: false;
+    id: JsonRpcId;
+    error: A2aError;
+};
+/** `A2A-Version` as Major.Minor; empty means 0.3 (spec §3.6.2). */
+export declare function checkVersion(value: string | null | undefined): void;
+/** A client's message reduced to what the Runtime runs: text, or one JSON value. */
+export type MessageInput = {
+    content: string;
+} | {
+    data: unknown;
+};
+export interface SendParams {
+    messageId: string;
+    contextId?: string;
+    taskId?: string;
+    input: MessageInput;
+    returnImmediately: boolean;
+    historyLength?: number;
+}
+export declare function parseHistoryLength(value: unknown, field: string): number | undefined;
+/** `SendMessage` params (spec §3.2.1), checked in the order a client can fix them. */
+export declare function parseSendParams(params: Record<string, unknown>): SendParams;
+/** `GetTask` and `CancelTask` params: the task id (and `historyLength` for `GetTask`). */
+export declare function parseTaskParams(params: Record<string, unknown>): {
+    id: string;
+    historyLength?: number;
+};

package/dist/api/a2a/protocol.js

@@ -0,0 +1,188 @@
+/**
+ * A2A 1.0 over JSON-RPC: the wire types the Runtime answers with, the envelope, the error
+ * codes and the parameter checks (Host feature `a2a-endpoint`). Only what v1 serves is typed:
+ * text and data parts, tasks, the card. Field names are the spec's ProtoJSON (camelCase,
+ * enum values such as `TASK_STATE_WORKING`). No Tenant state is read here.
+ */
+/** The A2A version this endpoint speaks (`A2A-Version`, Major.Minor). */
+export const A2A_VERSION = "1.0";
+export const TERMINAL_STATES = new Set([
+    "TASK_STATE_COMPLETED",
+    "TASK_STATE_FAILED",
+    "TASK_STATE_CANCELED",
+    "TASK_STATE_REJECTED",
+]);
+/** The standard JSON-RPC codes and the A2A codes (spec §5.4, §9.5). */
+export const A2A_ERRORS = {
+    parse: { code: -32700, reason: "INVALID_JSON" },
+    invalidRequest: { code: -32600, reason: "INVALID_REQUEST" },
+    methodNotFound: { code: -32601, reason: "METHOD_NOT_FOUND" },
+    invalidParams: { code: -32602, reason: "INVALID_PARAMS" },
+    internal: { code: -32603, reason: "INTERNAL" },
+    taskNotFound: { code: -32001, reason: "TASK_NOT_FOUND" },
+    taskNotCancelable: { code: -32002, reason: "TASK_NOT_CANCELABLE" },
+    pushNotSupported: { code: -32003, reason: "PUSH_NOTIFICATION_NOT_SUPPORTED" },
+    unsupportedOperation: { code: -32004, reason: "UNSUPPORTED_OPERATION" },
+    contentTypeNotSupported: { code: -32005, reason: "CONTENT_TYPE_NOT_SUPPORTED" },
+    versionNotSupported: { code: -32009, reason: "VERSION_NOT_SUPPORTED" },
+};
+/** An error answered in the JSON-RPC body, with `google.rpc.ErrorInfo` (and `BadRequest`). */
+export class A2aError extends Error {
+    kind;
+    metadata;
+    field;
+    constructor(kind, message, metadata = {}, 
+    /** `google.rpc.BadRequest` field violations, for invalid parameters. */
+    field) {
+        super(message);
+        this.kind = kind;
+        this.metadata = metadata;
+        this.field = field;
+        this.name = "A2aError";
+    }
+}
+export const a2aFail = (kind, message, metadata, field) => {
+    throw new A2aError(kind, message, metadata, field);
+};
+export function jsonRpcResult(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+export function jsonRpcError(id, error) {
+    const { code, reason } = A2A_ERRORS[error.kind];
+    const data = [
+        {
+            "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+            reason,
+            domain: "a2a-protocol.org",
+            metadata: { ...error.metadata },
+        },
+    ];
+    if (error.field !== undefined)
+        data.push({
+            "@type": "type.googleapis.com/google.rpc.BadRequest",
+            fieldViolations: [{ field: error.field, description: error.message }],
+        });
+    return { jsonrpc: "2.0", id, error: { code, message: error.message, data } };
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A JSON-RPC 2.0 request object, or an `A2aError` (`id` recovered when possible). */
+export function parseEnvelope(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, id: null, error: new A2aError("parse", "Invalid JSON payload") };
+    }
+    const invalid = (id, message) => ({
+        ok: false,
+        id,
+        error: new A2aError("invalidRequest", message),
+    });
+    if (!isObject(body))
+        return invalid(null, "The body must be one JSON-RPC request object");
+    const id = body.id;
+    const validId = typeof id === "string" || (typeof id === "number" && Number.isFinite(id)) || id === null;
+    const safeId = validId ? id : null;
+    if (body.jsonrpc !== "2.0")
+        return invalid(safeId, 'jsonrpc must be "2.0"');
+    // A2A has no notifications: every request is answered, so it needs an id.
+    if (!("id" in body) || !validId)
+        return invalid(null, "The request needs an id");
+    if (typeof body.method !== "string" || body.method === "")
+        return invalid(safeId, "The request needs a method");
+    if (body.params !== undefined && !isObject(body.params))
+        return invalid(safeId, "params must be an object");
+    return {
+        ok: true,
+        request: {
+            id: safeId,
+            method: body.method,
+            params: body.params ?? {},
+        },
+    };
+}
+/** `A2A-Version` as Major.Minor; empty means 0.3 (spec §3.6.2). */
+export function checkVersion(value) {
+    const trimmed = (value ?? "").trim();
+    const [major, minor] = trimmed === "" ? ["0", "3"] : trimmed.split(".");
+    if (`${major}.${minor}` !== A2A_VERSION)
+        a2aFail("versionNotSupported", `A2A version ${trimmed === "" ? "0.3" : trimmed} is not supported; send A2A-Version: ${A2A_VERSION}`, { supportedVersions: A2A_VERSION });
+}
+const MAX_ID = 200;
+const VISIBLE = /^[\x21-\x7e]+$/;
+function checkId(value, field, required) {
+    if (value === undefined && !required)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0)
+        return a2aFail("invalidParams", `${field} must be a non-empty string`, {}, field);
+    if (value.length > MAX_ID || !VISIBLE.test(value))
+        return a2aFail("invalidParams", `${field} must be 1 to ${MAX_ID} visible ASCII characters`, {}, field);
+    return value;
+}
+export function parseHistoryLength(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0)
+        return a2aFail("invalidParams", `${field} must be a non-negative integer`, {}, field);
+    return value;
+}
+/** The input of one part: exactly one of `text`, `raw`, `url`, `data` (spec §4.1.6). */
+function partKind(part, field) {
+    if (!isObject(part))
+        return a2aFail("invalidParams", `${field} must be an object`, {}, field);
+    const kinds = ["text", "raw", "url", "data"].filter((k) => part[k] !== undefined);
+    if (kinds.length !== 1)
+        return a2aFail("invalidParams", `${field} must contain exactly one of text, raw, url, data`, {}, field);
+    if (kinds[0] === "text" && typeof part.text !== "string")
+        return a2aFail("invalidParams", `${field}.text must be a string`, {}, `${field}.text`);
+    return kinds[0] === "raw" || kinds[0] === "url" ? "file" : kinds[0];
+}
+/** `SendMessage` params (spec §3.2.1), checked in the order a client can fix them. */
+export function parseSendParams(params) {
+    const message = params.message;
+    if (!isObject(message))
+        return a2aFail("invalidParams", "message is required", {}, "message");
+    const messageId = checkId(message.messageId, "message.messageId", true);
+    if (message.role !== "ROLE_USER")
+        a2aFail("invalidParams", 'message.role must be "ROLE_USER"', {}, "message.role");
+    const contextId = checkId(message.contextId, "message.contextId", false);
+    const taskId = checkId(message.taskId, "message.taskId", false);
+    if (!Array.isArray(message.parts) || message.parts.length === 0)
+        a2aFail("invalidParams", "At least one part is required", {}, "message.parts");
+    const parts = message.parts;
+    const kinds = parts.map((part, index) => partKind(part, `message.parts[${index}]`));
+    const configuration = params.configuration;
+    if (configuration !== undefined && !isObject(configuration))
+        a2aFail("invalidParams", "configuration must be an object", {}, "configuration");
+    const config = (configuration ?? {});
+    if (config.taskPushNotificationConfig !== undefined && config.taskPushNotificationConfig !== null)
+        a2aFail("pushNotSupported", "Push notifications are not supported");
+    if (config.returnImmediately !== undefined && typeof config.returnImmediately !== "boolean")
+        a2aFail("invalidParams", "configuration.returnImmediately must be a boolean", {}, "configuration.returnImmediately");
+    const historyLength = parseHistoryLength(config.historyLength, "configuration.historyLength");
+    let input;
+    if (kinds.every((kind) => kind === "text"))
+        input = { content: parts.map((part) => part.text).join("\n") };
+    else if (kinds.length === 1 && kinds[0] === "data")
+        input = { data: parts[0].data };
+    else
+        return a2aFail("contentTypeNotSupported", "This agent accepts text parts, or a single data part; files are not supported", { accepted: "text/plain,application/json" });
+    if ("content" in input && input.content.trim() === "")
+        a2aFail("invalidParams", "The message has no text", {}, "message.parts");
+    return {
+        messageId,
+        ...(contextId !== undefined ? { contextId } : {}),
+        ...(taskId !== undefined ? { taskId } : {}),
+        input,
+        returnImmediately: config.returnImmediately === true,
+        ...(historyLength !== undefined ? { historyLength } : {}),
+    };
+}
+/** `GetTask` and `CancelTask` params: the task id (and `historyLength` for `GetTask`). */
+export function parseTaskParams(params) {
+    if (typeof params.id !== "string" || params.id === "")
+        return a2aFail("invalidParams", "id is required", {}, "id");
+    const historyLength = parseHistoryLength(params.historyLength, "historyLength");
+    return { id: params.id, ...(historyLength !== undefined ? { historyLength } : {}) };
+}

package/dist/api/a2a/routes.d.ts

@@ -0,0 +1,19 @@
+import type { ServerResponse } from "node:http";
+import { type AuthScope, type TenantContext } from "../../tenant/context.js";
+/**
+ * How long a blocking `SendMessage` waits for the task to end or ask for input. After it, the
+ * task is returned `WORKING` and keeps running; the caller polls `GetTask`.
+ */
+export declare const A2A_BLOCKING_WAIT_MS: number;
+/** `GET /v1/a2a/agents/:agent/card`: the agent's card, for a caller who may use the agent. */
+export declare function a2aCard(ctx: TenantContext, scope: AuthScope, agentId: string): Promise<unknown>;
+/**
+ * `POST /v1/a2a/agents/:agent`: one A2A JSON-RPC call, for a subject. JSON-RPC answers (errors
+ * included) are the body to send with 200; HTTP-level refusals (unknown agent, no subject,
+ * limits) are thrown as `HttpError` like any Tenant route. `body` is read once the agent is
+ * known to be the caller's; closing `response` stops a blocking wait, never the task.
+ */
+export declare function a2aCall(ctx: TenantContext, scope: AuthScope, agentId: string, input: {
+    body: () => Promise<string>;
+    version: string | null;
+}, response: ServerResponse): Promise<unknown>;