@nylorun/runtime 0.36.1-beta → 0.37.0-beta

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

@@ -1,5 +1,5 @@
 import type { LiveEvent } from "@nylorun/core/contracts";
-import type { Message, Task } from "./protocol.js";
+import type { Artifact, Message, StreamResponse, Task, TaskState } from "./protocol.js";
 export declare function taskIdOf(contextId: string, turnId: string): string;
 /** The context and turn a task id names, or undefined for anything this Runtime never issued. */
 export declare function parseTaskId(id: string): {
@@ -22,18 +22,75 @@ export interface SessionSnapshot {
     readonly lastOutput?: unknown;
     readonly waits?: unknown;
 }
-/** An interaction the paused turn waits for. */
+/**
+ * An interaction the paused turn waits for, as profile v2 names it (`interactions/v1`):
+ * `approval` (a held tool call or an engine approval, answered with `approve`), `question` (an
+ * ask, answered with `respond`) or `connection` (an ask whose metadata says `kind: "connection"`:
+ * the agent needs an account the person has not connected; answered with `respond`).
+ */
 export interface PendingInteraction {
     readonly id: string;
-    readonly kind: string;
+    readonly kind: "approval" | "question" | "connection";
+    /** The engine's kind: which command answers it. */
+    readonly engineKind: "approval" | "response";
     readonly prompt: string;
+    /** What a person needs to decide: a held call's server, tool and reason; an ask's metadata. */
+    readonly detail?: Record<string, unknown>;
 }
+/** An interaction from a session's waits or a `turn.paused` payload; never a call's input. */
+export declare function interactionOf(raw: unknown): PendingInteraction | undefined;
+/** The interactions a paused session waits for, in order. */
+export declare function pendingInteractions(session: SessionSnapshot): PendingInteraction[];
 /** The first interaction a paused session waits for. */
 export declare function pendingInteraction(session: SessionSnapshot): PendingInteraction | undefined;
+/** The state a task waiting on `interaction` is in (profile v2 §1). */
+export declare function interruptedState(interaction: PendingInteraction): TaskState;
+/** The status message that shows an open interaction, with its `interactions/v1` data. */
+export declare function interactionMessage(interaction: PendingInteraction, contextId: string, taskId: string): Message;
+export declare const ENDED: ReadonlySet<string>;
 /** Events after which a blocking `SendMessage` returns: the turn ended or is interrupted. */
 export declare const SETTLED_EVENTS: ReadonlySet<string>;
 /** The turn's conversation as A2A messages: what the caller sent and what the agent said. */
 export declare function historyOf(events: readonly LiveEvent[], contextId: string, taskId: string): Message[];
+/** How the A2A server shows one task: the ids its caller knows, and where its files are served. */
+export interface TaskView {
+    readonly contextId: string;
+    /** The task id the caller knows: a queued message's own until a turn takes it. */
+    readonly taskId: string;
+    /** The Runtime's public URL, for file artifacts' `url` parts (`/v1/a2a/files/…`). */
+    readonly baseUrl?: string;
+    /** `telemetry/v1`'s trace id: the caller's `traceparent`'s, else the Runtime's own. */
+    readonly traceId?: string;
+}
+/**
+ * `progress/v1` from a `plan.updated` payload (`{ steps }`, the whole plan each time): at most
+ * 20 steps, each a label, a state and an optional note, cut to their lengths. Undefined when the
+ * payload holds no plan.
+ */
+export declare function progressOf(payload: unknown): {
+    steps: Record<string, string>[];
+} | undefined;
+/** `telemetry/v1` from a terminal event's end facts (`totals`) and the task's trace id. */
+export declare function telemetryOf(payload: unknown, traceId: string | undefined): Record<string, unknown> | undefined;
+/** The URL a caller downloads a file artifact's version from (scoped to the caller's subject). */
+export declare function fileUrl(baseUrl: string | undefined, artifactId: string, version: number): string;
+/**
+ * The A2A artifact of a file the turn wrote (`artifact.created`, `artifact.version.created`), with
+ * `files/v1`, or undefined for the caller's own uploads. A folder is served as its zip.
+ */
+export declare function fileArtifact(payload: unknown, baseUrl: string | undefined): Artifact | undefined;
+/**
+ * The single translator from session events to A2A updates (profile v2, pushes): what one event
+ * of the task's turn changes, as `StreamResponse`s. Every status update carries the event's time
+ * as `status.timestamp`; clients order by it. Tool calls, arguments, results and delegations
+ * never show (profile v2 §1): only states, step text, plans, interactions, files and the end.
+ */
+export declare function updatesOf(event: LiveEvent, view: TaskView): StreamResponse[];
+/**
+ * The trace id of a turn the caller started with a `traceparent` (its `command.message`), or
+ * undefined: the Runtime's own then (`traceIdOf`).
+ */
+export declare function callerTraceId(events: readonly LiveEvent[]): string | undefined;
 export interface BuildTaskInput {
     readonly contextId: string;
     readonly turnId: string;
@@ -41,10 +98,21 @@ export interface BuildTaskInput {
     /** Every event of the turn, in stream order. */
     readonly events: readonly LiveEvent[];
     readonly historyLength?: number;
+    /** The id the caller knows the task by, when not the turn's own (a queued message's). */
+    readonly taskId?: string;
+    readonly baseUrl?: string;
+    readonly traceId?: string;
 }
 /**
  * The task for one turn, or undefined when the session never had that turn. An active turn
  * takes its state from the session row; an ended one from its terminal event, or from the row
- * while that event has not reached the stream yet.
+ * while that event has not reached the stream yet. Its metadata holds the latest plan
+ * (`progress/v1`), the uncertain effect (`effects/v1`) and, once it ended, `telemetry/v1`; its
+ * artifacts are the output and the files the turn wrote (`files/v1`).
  */
 export declare function buildTask(input: BuildTaskInput): Task | undefined;
+/**
+ * A queued message's task while it waits (profile v2 §1): `SUBMITTED`, from its `message.queued`
+ * event, until a turn takes it.
+ */
+export declare function submittedTask(contextId: string, taskId: string, queued: LiveEvent): Task;

package/dist/api/a2a/tasks.js

@@ -2,10 +2,14 @@
  * A2A tasks over Nylorun sessions: a context is one session per subject, agent and
  * `contextId`; a task is one turn of it. The task id names both (`t1.<context>.<turn>`) until
  * the turn index lets a turn id stand alone; it is parsed, never trusted, because the session
- * is always derived from the caller's own subject. `buildTask` reads the state from the session
- * row and the turn's events; nothing here touches the store.
+ * is always derived from the caller's own subject; a queued message's task is named by the
+ * message's queue id until a turn takes it. `buildTask` reads the state from the session row and
+ * the turn's events, with the profile v2 data (interactions, progress, telemetry, effects,
+ * files); `updatesOf` is the one translator from a session event to the A2A updates pushes carry.
+ * Nothing here touches the store.
  */
 import { createHash } from "node:crypto";
+import { A2A_EXTENSIONS } from "./extensions.js";
 const TASK_ID_PREFIX = "t1";
 export function taskIdOf(contextId, turnId) {
     return `${TASK_ID_PREFIX}.${Buffer.from(contextId, "utf8").toString("base64url")}.${turnId}`;
@@ -41,23 +45,73 @@ export function newContextId(subject, agentId, messageId) {
         .digest("hex");
     return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
-/** The first interaction a paused session waits for. */
-export function pendingInteraction(session) {
-    if (!Array.isArray(session.waits))
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** An interaction from a session's waits or a `turn.paused` payload; never a call's input. */
+export function interactionOf(raw) {
+    if (!isRecord(raw) || typeof raw.id !== "string")
         return undefined;
-    for (const call of session.waits) {
-        const interaction = call?.interaction;
-        if (call?.status !== "interaction" || typeof interaction?.id !== "string")
-            continue;
-        return {
-            id: interaction.id,
-            kind: typeof interaction.kind === "string" ? interaction.kind : "response",
-            prompt: typeof interaction.prompt === "string" ? interaction.prompt : "",
-        };
+    const engineKind = raw.kind === "approval" ? "approval" : "response";
+    const metadata = isRecord(raw.metadata) ? raw.metadata : undefined;
+    const kind = raw.kind === "connection" || metadata?.kind === "connection"
+        ? "connection"
+        : engineKind === "approval"
+            ? "approval"
+            : "question";
+    let detail;
+    if (engineKind === "approval" && kind === "approval") {
+        // A held tool call names its tool; its arguments stay with the Runtime (profile v2 §1).
+        const held = Object.fromEntries(["server", "tool", "reason"].flatMap((key) => typeof raw[key] === "string" ? [[key, raw[key]]] : []));
+        detail = Object.keys(held).length > 0 ? held : metadata;
     }
-    return undefined;
+    else if (metadata) {
+        const { kind: _kind, ...rest } = metadata;
+        detail = Object.keys(rest).length > 0 ? rest : undefined;
+    }
+    return {
+        id: raw.id,
+        kind,
+        engineKind,
+        prompt: typeof raw.prompt === "string" ? raw.prompt : "",
+        ...(detail ? { detail } : {}),
+    };
 }
-const ENDED = new Set(["turn.completed", "turn.failed", "turn.cancelled"]);
+/** The interactions a paused session waits for, in order. */
+export function pendingInteractions(session) {
+    if (!Array.isArray(session.waits))
+        return [];
+    return session.waits.flatMap((call) => {
+        const interaction = call?.status === "interaction" ? interactionOf(call.interaction) : undefined;
+        return interaction ? [interaction] : [];
+    });
+}
+/** The first interaction a paused session waits for. */
+export function pendingInteraction(session) {
+    return pendingInteractions(session)[0];
+}
+/** The state a task waiting on `interaction` is in (profile v2 §1). */
+export function interruptedState(interaction) {
+    return interaction.kind === "question" ? "TASK_STATE_INPUT_REQUIRED" : "TASK_STATE_AUTH_REQUIRED";
+}
+/** The status message that shows an open interaction, with its `interactions/v1` data. */
+export function interactionMessage(interaction, contextId, taskId) {
+    return {
+        messageId: interaction.id,
+        role: "ROLE_AGENT",
+        parts: [{ text: interaction.prompt }],
+        contextId,
+        taskId,
+        extensions: [A2A_EXTENSIONS.interactions],
+        metadata: {
+            [A2A_EXTENSIONS.interactions]: {
+                interactionId: interaction.id,
+                kind: interaction.kind,
+                prompt: interaction.prompt,
+                ...(interaction.detail ? { detail: interaction.detail } : {}),
+            },
+        },
+    };
+}
+export const ENDED = new Set(["turn.completed", "turn.failed", "turn.cancelled"]);
 /** Events after which a blocking `SendMessage` returns: the turn ended or is interrupted. */
 export const SETTLED_EVENTS = new Set([
     ...ENDED,
@@ -121,14 +175,200 @@ function failureText(code) {
         ? `The agent failed (${code}).`
         : "The agent failed.";
 }
+const UNCERTAIN_TEXT = "An action's outcome is uncertain; the agent's operator must resolve it before the task continues.";
+// ---------------------------------------------------------------------------
+// Profile v2 data
+/** The states of a plan step (`progress/v1`, Contract 1). */
+const STEP_STATES = new Set(["pending", "active", "done", "blocked", "skipped"]);
+const MAX_STEPS = 20;
+const MAX_LABEL = 120;
+const MAX_NOTE = 280;
+/**
+ * `progress/v1` from a `plan.updated` payload (`{ steps }`, the whole plan each time): at most
+ * 20 steps, each a label, a state and an optional note, cut to their lengths. Undefined when the
+ * payload holds no plan.
+ */
+export function progressOf(payload) {
+    if (!isRecord(payload) || !Array.isArray(payload.steps))
+        return undefined;
+    const steps = payload.steps.slice(0, MAX_STEPS).flatMap((step) => {
+        if (!isRecord(step) || typeof step.label !== "string")
+            return [];
+        const state = typeof step.state === "string" && STEP_STATES.has(step.state) ? step.state : "pending";
+        return [
+            {
+                label: step.label.slice(0, MAX_LABEL),
+                state,
+                ...(typeof step.note === "string" && step.note !== "" ? { note: step.note.slice(0, MAX_NOTE) } : {}),
+            },
+        ];
+    });
+    return { steps };
+}
+/** `telemetry/v1` from a terminal event's end facts (`totals`) and the task's trace id. */
+export function telemetryOf(payload, traceId) {
+    const totals = isRecord(payload) && isRecord(payload.totals) ? payload.totals : undefined;
+    const value = {
+        ...(totals
+            ? {
+                totals: {
+                    steps: Number(totals.steps ?? 0),
+                    tokens: Number(totals.tokens ?? 0),
+                    costUsd: Number(totals.costUsd ?? 0),
+                },
+            }
+            : {}),
+        ...(traceId ? { traceId } : {}),
+    };
+    return Object.keys(value).length > 0 ? value : undefined;
+}
+/** The URL a caller downloads a file artifact's version from (scoped to the caller's subject). */
+export function fileUrl(baseUrl, artifactId, version) {
+    return `${baseUrl ?? ""}/v1/a2a/files/${encodeURIComponent(artifactId)}/versions/${version}`;
+}
+/**
+ * The A2A artifact of a file the turn wrote (`artifact.created`, `artifact.version.created`), with
+ * `files/v1`, or undefined for the caller's own uploads. A folder is served as its zip.
+ */
+export function fileArtifact(payload, baseUrl) {
+    if (!isRecord(payload) || typeof payload.artifactId !== "string" || typeof payload.name !== "string")
+        return undefined;
+    if (payload.source === "upload")
+        return undefined;
+    const version = Number(payload.version);
+    const folder = payload.kind === "folder";
+    return {
+        artifactId: `${payload.artifactId}:${payload.name}`,
+        name: payload.name,
+        parts: [
+            {
+                url: fileUrl(baseUrl, payload.artifactId, version),
+                mediaType: folder ? "application/zip" : String(payload.contentType ?? "application/octet-stream"),
+                filename: folder ? `${payload.name}.zip` : payload.name,
+            },
+        ],
+        extensions: [A2A_EXTENSIONS.files],
+        metadata: {
+            [A2A_EXTENSIONS.files]: {
+                kind: folder ? "folder" : "file",
+                path: payload.name,
+                version,
+                size: Number(payload.size ?? 0),
+                sha256: String(payload.sha256 ?? ""),
+                ...(typeof payload.fileCount === "number" ? { fileCount: payload.fileCount } : {}),
+            },
+        },
+    };
+}
+const FILE_EVENTS = new Set(["artifact.created", "artifact.version.created"]);
+function outputArtifact(output) {
+    return output === undefined || output === null
+        ? undefined
+        : { artifactId: "output", name: "output", parts: [outputPart(output)] };
+}
+/**
+ * The single translator from session events to A2A updates (profile v2, pushes): what one event
+ * of the task's turn changes, as `StreamResponse`s. Every status update carries the event's time
+ * as `status.timestamp`; clients order by it. Tool calls, arguments, results and delegations
+ * never show (profile v2 §1): only states, step text, plans, interactions, files and the end.
+ */
+export function updatesOf(event, view) {
+    const { contextId, taskId } = view;
+    const payload = (event.payload ?? {});
+    const status = (state, extra = {}) => ({
+        statusUpdate: {
+            taskId,
+            contextId,
+            status: { state, ...(extra.message ? { message: extra.message } : {}), timestamp: event.time },
+            ...(extra.metadata ? { metadata: extra.metadata } : {}),
+        },
+    });
+    const artifact = (value) => ({
+        artifactUpdate: { taskId, contextId, artifact: value, append: false, lastChunk: true },
+    });
+    switch (event.type) {
+        case "command.message":
+        case "command.approve":
+        case "command.respond":
+            return [status("TASK_STATE_WORKING")];
+        case "plan.updated": {
+            const progress = progressOf(payload);
+            return progress ? [status("TASK_STATE_WORKING", { metadata: { [A2A_EXTENSIONS.progress]: progress } })] : [];
+        }
+        case "message.assistant":
+            // The agent's own step text; an agent used as a tool speaks inside the turn.
+            return !payload.agent && typeof payload.text === "string" && payload.text.trim() !== ""
+                ? [status("TASK_STATE_WORKING", { message: agentMessage(event.eventId, payload.text, contextId, taskId) })]
+                : [];
+        case "effect.uncertain":
+            return [
+                status("TASK_STATE_WORKING", {
+                    message: agentMessage(`${event.eventId}:uncertain`, UNCERTAIN_TEXT, contextId, taskId),
+                    metadata: { [A2A_EXTENSIONS.effects]: { uncertain: String(payload.effectId ?? "") } },
+                }),
+            ];
+        case "turn.paused":
+            return (Array.isArray(payload.interactions) ? payload.interactions : []).flatMap((entry) => {
+                const interaction = interactionOf(entry?.interaction);
+                return interaction
+                    ? [status(interruptedState(interaction), { message: interactionMessage(interaction, contextId, taskId) })]
+                    : [];
+            });
+        case "artifact.created":
+        case "artifact.version.created": {
+            const file = fileArtifact(payload, view.baseUrl);
+            return file ? [artifact(file)] : [];
+        }
+        case "turn.completed":
+        case "turn.failed":
+        case "turn.cancelled": {
+            const telemetry = telemetryOf(payload, view.traceId);
+            const metadata = telemetry ? { [A2A_EXTENSIONS.telemetry]: telemetry } : undefined;
+            if (event.type === "turn.completed") {
+                const output = outputArtifact(payload.output);
+                return [
+                    ...(output ? [artifact(output)] : []),
+                    status("TASK_STATE_COMPLETED", metadata ? { metadata } : {}),
+                ];
+            }
+            if (event.type === "turn.cancelled")
+                return [status("TASK_STATE_CANCELED", metadata ? { metadata } : {})];
+            return [
+                status("TASK_STATE_FAILED", {
+                    message: agentMessage(`${event.turnId}:failed`, failureText(payload.error?.code), contextId, taskId),
+                    ...(metadata ? { metadata } : {}),
+                }),
+            ];
+        }
+        default:
+            return [];
+    }
+}
+/**
+ * The trace id of a turn the caller started with a `traceparent` (its `command.message`), or
+ * undefined: the Runtime's own then (`traceIdOf`).
+ */
+export function callerTraceId(events) {
+    for (const event of events) {
+        if (event.type !== "command.message")
+            continue;
+        const traceparent = event.payload?.trace?.traceparent;
+        const match = typeof traceparent === "string" ? /^[0-9a-f]{2}-([0-9a-f]{32})-/.exec(traceparent) : null;
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
 /**
  * The task for one turn, or undefined when the session never had that turn. An active turn
  * takes its state from the session row; an ended one from its terminal event, or from the row
- * while that event has not reached the stream yet.
+ * while that event has not reached the stream yet. Its metadata holds the latest plan
+ * (`progress/v1`), the uncertain effect (`effects/v1`) and, once it ended, `telemetry/v1`; its
+ * artifacts are the output and the files the turn wrote (`files/v1`).
  */
 export function buildTask(input) {
     const { contextId, turnId, session, events } = input;
-    const taskId = taskIdOf(contextId, turnId);
+    const taskId = input.taskId ?? taskIdOf(contextId, turnId);
     const active = session.activeTurnId === turnId;
     const terminal = [...events].reverse().find((event) => ENDED.has(event.type));
     const latest = session.lastTurnId === turnId && !active;
@@ -136,22 +376,27 @@ export function buildTask(input) {
         return undefined;
     let state;
     let message;
-    let artifacts;
-    const complete = (output) => {
+    let output;
+    const metadata = {};
+    const complete = (value) => {
         state = "TASK_STATE_COMPLETED";
-        if (output !== undefined && output !== null)
-            artifacts = [{ artifactId: "output", name: "output", parts: [outputPart(output)] }];
+        output = outputArtifact(value);
     };
     if (active) {
         const pending = session.status === "paused" ? pendingInteraction(session) : undefined;
         if (pending) {
-            state = "TASK_STATE_INPUT_REQUIRED";
-            message = agentMessage(pending.id, pending.prompt, contextId, taskId);
+            state = interruptedState(pending);
+            message = interactionMessage(pending, contextId, taskId);
         }
         else {
             state = "TASK_STATE_WORKING";
-            if (session.status === "uncertain")
-                message = agentMessage(`${turnId}:uncertain`, "An action's outcome is uncertain; the agent's operator must resolve it before the task continues.", contextId, taskId);
+            if (session.status === "uncertain") {
+                message = agentMessage(`${turnId}:uncertain`, UNCERTAIN_TEXT, contextId, taskId);
+                const uncertain = [...events].reverse().find((event) => event.type === "effect.uncertain");
+                const effectId = uncertain?.payload?.effectId;
+                if (typeof effectId === "string")
+                    metadata[A2A_EXTENSIONS.effects] = { uncertain: effectId };
+            }
         }
     }
     else if (terminal) {
@@ -164,6 +409,9 @@ export function buildTask(input) {
             state = "TASK_STATE_FAILED";
             message = agentMessage(`${turnId}:failed`, failureText(payload.error?.code), contextId, taskId);
         }
+        const telemetry = telemetryOf(payload, input.traceId);
+        if (telemetry)
+            metadata[A2A_EXTENSIONS.telemetry] = telemetry;
     }
     else if (latest && session.status === "completed")
         complete(session.lastOutput);
@@ -175,6 +423,23 @@ export function buildTask(input) {
     }
     else
         state = "TASK_STATE_WORKING";
+    // The latest plan, and the files the turn wrote (the latest version of each, none deleted).
+    const files = new Map();
+    for (const event of events) {
+        if (event.type === "plan.updated") {
+            const progress = progressOf(event.payload);
+            if (progress)
+                metadata[A2A_EXTENSIONS.progress] = progress;
+        }
+        else if (FILE_EVENTS.has(event.type)) {
+            const file = fileArtifact(event.payload, input.baseUrl);
+            if (file)
+                files.set(String(event.payload.artifactId), file);
+        }
+        else if (event.type === "artifact.deleted")
+            files.delete(String(event.payload.artifactId));
+    }
+    const artifacts = [...(output ? [output] : []), ...files.values()];
     const timestamp = events.at(-1)?.time;
     const history = historyOf(events, contextId, taskId);
     const limit = input.historyLength;
@@ -186,7 +451,20 @@ export function buildTask(input) {
             ...(message ? { message } : {}),
             ...(timestamp ? { timestamp } : {}),
         },
-        ...(artifacts ? { artifacts } : {}),
+        ...(artifacts.length > 0 ? { artifacts } : {}),
         ...(limit === 0 ? {} : { history: limit === undefined ? history : history.slice(-limit) }),
+        ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+    };
+}
+/**
+ * A queued message's task while it waits (profile v2 §1): `SUBMITTED`, from its `message.queued`
+ * event, until a turn takes it.
+ */
+export function submittedTask(contextId, taskId, queued) {
+    return {
+        id: taskId,
+        contextId,
+        status: { state: "TASK_STATE_SUBMITTED", timestamp: queued.time },
+        history: [],
     };
 }