@aparte/runner-ag-ui 0.21.0 → 0.22.0

package/dist/index.js

@@ -1,10 +1,23 @@
-import { contentToText, uuid, AparteError, AparteErrorCode } from "@aparte/core";
-function toAgUiMessages(messages) {
+import { contentToText, AparteError, AparteErrorCode, uuid } from "@aparte/core";
+function imagePart(part) {
+  const data = /^data:([^;,]*)(?:;[^;,]*)*;base64,(.*)$/s.exec(part.image);
+  if (data) return { type: "image", source: { type: "data", value: data[2], mimeType: part.mimeType ?? (data[1] || "application/octet-stream") } };
+  return { type: "image", source: { type: "url", value: part.image, ...part.mimeType ? { mimeType: part.mimeType } : {} } };
+}
+function toAgUiMessages(messages, flatten, warn) {
   const out = [];
-  messages.forEach((m, index) => {
-    const id = `aparte-${index}`;
+  messages.forEach((m, index2) => {
+    const id = `aparte-${index2}`;
     const content = contentToText(m.content);
-    if (m.role === "system" || m.role === "user") {
+    const images = Array.isArray(m.content) && m.content.some((part) => part.type === "image");
+    if (m.role === "user" && images && !flatten) {
+      out.push({
+        id,
+        role: "user",
+        content: m.content.map((part) => part.type === "image" ? imagePart(part) : { type: "text", text: part.text })
+      });
+    } else if (m.role === "system" || m.role === "user") {
+      if (images) warn(`the agent's AG-UI version takes text only, which DROPS non-text parts: the images of message ${index2} are not sent.`);
       out.push({ id, role: m.role, content });
     } else if (m.role === "assistant") {
       out.push({
@@ -28,6 +41,465 @@ function toAgUiMessages(messages) {
 function toAgUiTools(tools) {
   return (tools ?? []).map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.inputSchema }));
 }
+const BASE = ["type", "timestamp", "rawEvent", "metadata"];
+const EVENT_KEYS = {
+  RUN_STARTED: ["threadId", "runId", "parentRunId", "protocolVersion", "input"],
+  RUN_FINISHED: ["threadId", "runId", "outcome", "result", "usage"],
+  RUN_ERROR: ["message", "code", "usage"],
+  STEP_STARTED: ["stepName", "subagentRunId"],
+  STEP_FINISHED: ["stepName", "subagentRunId"],
+  TEXT_MESSAGE_START: ["messageId", "role", "name", "subagentRunId"],
+  TEXT_MESSAGE_CONTENT: ["messageId", "delta", "subagentRunId"],
+  TEXT_MESSAGE_END: ["messageId", "subagentRunId"],
+  TEXT_MESSAGE_CHUNK: ["messageId", "role", "name", "delta", "subagentRunId"],
+  TOOL_CALL_START: ["toolCallId", "toolCallName", "parentMessageId", "subagentRunId"],
+  TOOL_CALL_ARGS: ["toolCallId", "delta", "subagentRunId"],
+  TOOL_CALL_END: ["toolCallId", "subagentRunId"],
+  TOOL_CALL_CHUNK: ["toolCallId", "toolCallName", "parentMessageId", "delta", "subagentRunId"],
+  TOOL_CALL_RESULT: ["messageId", "toolCallId", "content", "role", "subagentRunId"],
+  REASONING_START: ["messageId", "subagentRunId"],
+  REASONING_END: ["messageId", "subagentRunId"],
+  REASONING_MESSAGE_START: ["messageId", "role", "subagentRunId"],
+  REASONING_MESSAGE_CONTENT: ["messageId", "delta", "subagentRunId"],
+  REASONING_MESSAGE_END: ["messageId", "subagentRunId"],
+  REASONING_MESSAGE_CHUNK: ["messageId", "delta", "subagentRunId"],
+  REASONING_ENCRYPTED_VALUE: ["subtype", "entityId", "encryptedValue", "subagentRunId"],
+  STATE_SNAPSHOT: ["snapshot", "subagentRunId"],
+  STATE_DELTA: ["delta", "subagentRunId"],
+  MESSAGES_SNAPSHOT: ["messages"],
+  ACTIVITY_SNAPSHOT: ["messageId", "activityType", "content", "replace", "subagentRunId"],
+  ACTIVITY_DELTA: ["messageId", "activityType", "patch", "subagentRunId"],
+  RAW: ["event", "source", "subagentRunId"],
+  CUSTOM: ["name", "value", "subagentRunId"],
+  SUBAGENT_STARTED: ["subagentRunId", "name", "description", "parentMessageId", "parentToolCallId", "parentSubagentRunId"],
+  SUBAGENT_FINISHED: ["subagentRunId", "outcome", "result"],
+  SUBAGENT_ERROR: ["subagentRunId", "message", "code"]
+};
+const TEXT_ROLES = /* @__PURE__ */ new Set(["developer", "system", "assistant", "user"]);
+const OUTCOMES = /* @__PURE__ */ new Set(["success", "interrupt", "cancelled"]);
+const CONTENT_PARTS = /* @__PURE__ */ new Set(["text", "image", "audio", "video", "document"]);
+function enforce(event, warn) {
+  const keys = EVENT_KEYS[event.type];
+  if (!keys) {
+    warn(`dropped an event of a type this runner does not know: ${event.type}.`);
+    return void 0;
+  }
+  const out = { ...event };
+  for (const key of Object.keys(out)) {
+    if (!BASE.includes(key) && !keys.includes(key)) {
+      delete out[key];
+      warn(`stripped /${key} from ${event.type}: AG-UI 1.0 does not describe it.`);
+    }
+  }
+  if ((out.type === "TEXT_MESSAGE_START" || out.type === "TEXT_MESSAGE_CHUNK") && typeof out["role"] === "string" && !TEXT_ROLES.has(out["role"])) {
+    warn(`stripped /role from ${out.type}: "${out["role"]}" is not a message role.`);
+    delete out["role"];
+  }
+  const outcome = out["outcome"];
+  if (out.type === "RUN_FINISHED" && outcome && typeof outcome === "object" && !Array.isArray(outcome) && !OUTCOMES.has(String(outcome.type))) {
+    warn(`stripped /outcome from RUN_FINISHED: "${String(outcome.type)}" is not an outcome AG-UI 1.0 describes; the run ends as a plain one.`);
+    delete out["outcome"];
+  }
+  if (out.type === "MESSAGES_SNAPSHOT" && Array.isArray(out["messages"])) {
+    out["messages"] = out["messages"].map((message, i) => {
+      const content = message?.content;
+      if (!Array.isArray(content)) return message;
+      const kept = content.filter((part, j) => {
+        const known = CONTENT_PARTS.has(String(part?.type));
+        if (!known) warn(`stripped /messages/${i}/content/${j} from MESSAGES_SNAPSHOT: "${String(part?.type)}" is not a content part.`);
+        return known;
+      });
+      return { ...message, content: kept };
+    });
+  }
+  return out;
+}
+const OPS = /* @__PURE__ */ new Set(["add", "remove", "replace", "move", "copy", "test"]);
+function tokens(pointer) {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) throw new Error(`"${pointer}" is not a JSON Pointer`);
+  return pointer.slice(1).split("/").map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+function isContainer(value) {
+  return typeof value === "object" && value !== null;
+}
+function index(list, token, append) {
+  if (append && token === "-") return list.length;
+  if (!/^(0|[1-9]\d*)$/.test(token)) throw new Error(`"${token}" is not an array index`);
+  const i = Number(token);
+  if (i > list.length || !append && i === list.length) throw new Error(`index ${i} is out of range`);
+  return i;
+}
+function parentOf(doc, path) {
+  const all = tokens(path);
+  const key = all.pop();
+  let node = doc;
+  for (const t of all) {
+    if (!isContainer(node)) throw new Error(`"${path}" does not resolve`);
+    node = Array.isArray(node) ? node[index(node, t, false)] : Object.hasOwn(node, t) ? node[t] : void 0;
+    if (node === void 0) throw new Error(`"${path}" does not resolve`);
+  }
+  if (!isContainer(node)) throw new Error(`"${path}" does not resolve`);
+  return { parent: node, key };
+}
+function get(doc, path) {
+  if (path === "") return doc;
+  const { parent, key } = parentOf(doc, path);
+  const value = Array.isArray(parent) ? parent[index(parent, key, false)] : Object.hasOwn(parent, key) ? parent[key] : void 0;
+  if (value === void 0) throw new Error(`"${path}" does not resolve`);
+  return value;
+}
+function add(doc, path, value) {
+  if (path === "") return value;
+  const { parent, key } = parentOf(doc, path);
+  if (Array.isArray(parent)) parent.splice(index(parent, key, true), 0, value);
+  else parent[key] = value;
+  return doc;
+}
+function remove(doc, path) {
+  if (path === "") throw new Error("the whole document cannot be removed");
+  const { parent, key } = parentOf(doc, path);
+  if (Array.isArray(parent)) parent.splice(index(parent, key, false), 1);
+  else if (Object.hasOwn(parent, key)) delete parent[key];
+  else throw new Error(`"${path}" does not resolve`);
+  return doc;
+}
+function replace(doc, path, value) {
+  if (path === "") return value;
+  const { parent, key } = parentOf(doc, path);
+  if (Array.isArray(parent)) parent[index(parent, key, false)] = value;
+  else if (Object.hasOwn(parent, key)) parent[key] = value;
+  else throw new Error(`"${path}" does not resolve`);
+  return doc;
+}
+function equal(a, b) {
+  if (a === b) return true;
+  if (!isContainer(a) || !isContainer(b) || Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) return a.length === b.length && a.every((v, i) => equal(v, b[i]));
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  return ka.length === kb.length && ka.every((k) => Object.hasOwn(b, k) && equal(a[k], b[k]));
+}
+function step(doc, op) {
+  const path = op["path"];
+  if (typeof path !== "string") throw new Error("an operation has no path");
+  const from = typeof op["from"] === "string" ? op["from"] : void 0;
+  if ((op["op"] === "add" || op["op"] === "replace" || op["op"] === "test") && !("value" in op)) throw new Error(`${String(op["op"])} has no value`);
+  switch (op["op"]) {
+    case "add":
+      return add(doc, path, structuredClone(op["value"]));
+    case "remove":
+      return remove(doc, path);
+    case "replace":
+      return replace(doc, path, structuredClone(op["value"]));
+    case "move": {
+      if (from === void 0) throw new Error("move has no from");
+      if (path.startsWith(`${from}/`)) throw new Error(`"${from}" cannot move into its own child "${path}"`);
+      const value = get(doc, from);
+      return add(remove(doc, from), path, value);
+    }
+    case "copy": {
+      if (from === void 0) throw new Error("copy has no from");
+      return add(doc, path, structuredClone(get(doc, from)));
+    }
+    case "test":
+      if (!equal(get(doc, path), op["value"])) throw new Error(`test failed at "${path}"`);
+      return doc;
+    default:
+      throw new Error(`unknown operation "${String(op["op"])}"`);
+  }
+}
+function applyStateDelta(state, delta, warn) {
+  if (!Array.isArray(delta)) {
+    warn("Failed to apply state patch: STATE_DELTA carried no list of operations; the state is left as it was.");
+    return state;
+  }
+  const ops = [];
+  delta.forEach((op, i) => {
+    if (isContainer(op) && !Array.isArray(op) && OPS.has(String(op["op"]))) ops.push(op);
+    else warn(`dropped /delta/${i}: ${JSON.stringify(op)} is not a JSON Patch operation.`);
+  });
+  try {
+    let doc = structuredClone(state);
+    for (const op of ops) doc = step(doc, op);
+    return doc;
+  } catch (error) {
+    warn(`Failed to apply state patch: ${error.message}; the state is left as it was.`);
+    return state;
+  }
+}
+function compare(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const d = (a[i] ?? 0) - (b[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+function createTranslator(peer, warn) {
+  const beforeSubagents = peer !== void 0 && compare(peer, [0, 0, 57]) <= 0;
+  let thought = 0;
+  let span;
+  let message;
+  const warned = /* @__PURE__ */ new Set();
+  const once = (key, text) => {
+    if (warned.has(key)) return;
+    warned.add(key);
+    warn(text);
+  };
+  return (event) => {
+    switch (event.type) {
+      case "THINKING_START":
+        span = `thinking-${++thought}`;
+        once("THINKING_START", `translated the retired THINKING_START into REASONING_START${typeof event["title"] === "string" ? `, dropping its title "${event["title"]}"` : ""}; the agent should send REASONING_* events.`);
+        return [{ type: "REASONING_START", messageId: span }];
+      case "THINKING_END": {
+        const id = span ?? `thinking-${++thought}`;
+        span = void 0;
+        return [{ type: "REASONING_END", messageId: id }];
+      }
+      case "THINKING_TEXT_MESSAGE_START":
+        message = `thinking-message-${++thought}`;
+        return [{ type: "REASONING_MESSAGE_START", messageId: message, role: "reasoning" }];
+      case "THINKING_TEXT_MESSAGE_CONTENT":
+        return [{ type: "REASONING_MESSAGE_CONTENT", messageId: message ?? `thinking-message-${thought}`, delta: event["delta"] }];
+      case "THINKING_TEXT_MESSAGE_END": {
+        const id = message ?? `thinking-message-${thought}`;
+        message = void 0;
+        return [{ type: "REASONING_MESSAGE_END", messageId: id }];
+      }
+    }
+    if (beforeSubagents) {
+      if (event.type.startsWith("SUBAGENT_")) {
+        once(event.type, `dropping ${event.type}: the agent's AG-UI version predates subagents (0.0.57 or older).`);
+        return [];
+      }
+      if ("subagentRunId" in event) {
+        const { subagentRunId: _dropped, ...rest } = event;
+        return [rest];
+      }
+    }
+    return [event];
+  };
+}
+function malformed(reason) {
+  return new AparteError(`The agent stream is malformed: ${reason}.`, AparteErrorCode.PROVIDER_ERROR, { agUi: "malformed" });
+}
+const STRING_DELTA = /* @__PURE__ */ new Set([
+  "TEXT_MESSAGE_CONTENT",
+  "TEXT_MESSAGE_CHUNK",
+  "TOOL_CALL_ARGS",
+  "TOOL_CALL_CHUNK",
+  "REASONING_MESSAGE_CONTENT",
+  "REASONING_MESSAGE_CHUNK"
+]);
+const STRING_FIELDS = [
+  "messageId",
+  "toolCallId",
+  "toolCallName",
+  "parentMessageId",
+  "stepName",
+  "subagentRunId",
+  "threadId",
+  "runId",
+  "parentRunId",
+  "protocolVersion",
+  "name",
+  "role",
+  "message",
+  "code",
+  "activityType",
+  "entityId",
+  "encryptedValue",
+  "subtype",
+  "description",
+  "parentToolCallId",
+  "parentSubagentRunId"
+];
+const REQUIRED = {
+  TEXT_MESSAGE_START: ["messageId"],
+  TEXT_MESSAGE_CONTENT: ["messageId", "delta"],
+  TEXT_MESSAGE_END: ["messageId"],
+  TOOL_CALL_START: ["toolCallId", "toolCallName"],
+  TOOL_CALL_ARGS: ["toolCallId", "delta"],
+  TOOL_CALL_END: ["toolCallId"],
+  TOOL_CALL_RESULT: ["toolCallId"],
+  REASONING_START: ["messageId"],
+  REASONING_END: ["messageId"],
+  REASONING_MESSAGE_START: ["messageId"],
+  REASONING_MESSAGE_CONTENT: ["messageId", "delta"],
+  REASONING_MESSAGE_END: ["messageId"],
+  STEP_STARTED: ["stepName"],
+  STEP_FINISHED: ["stepName"],
+  SUBAGENT_STARTED: ["subagentRunId"],
+  SUBAGENT_FINISHED: ["subagentRunId"],
+  SUBAGENT_ERROR: ["subagentRunId"]
+};
+const FRAMING_HINT = " (TanStack AI frames runs this way: give createAgUiRunner relaxedRunFraming: true to read it)";
+function createVerifier(relaxed) {
+  let seen = false;
+  let running = false;
+  let closed;
+  const text = /* @__PURE__ */ new Map();
+  const reasoning = /* @__PURE__ */ new Map();
+  const tools = /* @__PURE__ */ new Map();
+  const steps = /* @__PURE__ */ new Set();
+  const subagents = /* @__PURE__ */ new Set();
+  const chunks = /* @__PURE__ */ new Map();
+  const ownerOf = (event) => typeof event["subagentRunId"] === "string" ? event["subagentRunId"] : "";
+  const stepKey = (owner, name) => `${owner}\0${name}`;
+  const nothingOpen = () => {
+    text.clear();
+    reasoning.clear();
+    tools.clear();
+    steps.clear();
+    subagents.clear();
+    chunks.clear();
+  };
+  const stillOpen = () => [...text.keys()].map((id) => `text message "${id}"`).concat([...reasoning.keys()].map((id) => `reasoning message "${id}"`)).concat([...tools.keys()].map((id) => `tool call "${id}"`)).concat([...steps].map((key) => `step "${key.split("\0")[1]}"`)).concat([...subagents].map((id) => `subagent "${id}"`));
+  const agrees = (id, opened, event) => {
+    const by = event["subagentRunId"];
+    if (by === void 0) return;
+    const at = opened.get(id);
+    if (at !== void 0 && at !== by) throw malformed(`${event.type} for "${id}" is attributed to "${String(by)}", but "${id}" started attributed to "${String(at)}"`);
+  };
+  const verify = ((event) => {
+    const type = event.type;
+    const first = !seen;
+    seen = true;
+    for (const key of REQUIRED[type] ?? []) if (event[key] === void 0) throw malformed(`${type} needs "${key}"`);
+    for (const key of STRING_FIELDS) if (key in event && event[key] !== void 0 && typeof event[key] !== "string") throw malformed(`"${key}" must be a string on ${type}`);
+    if (STRING_DELTA.has(type) && "delta" in event && typeof event["delta"] !== "string") throw malformed(`"delta" must be a string on ${type}`);
+    if (type === "RUN_STARTED") {
+      if (running && !relaxed) throw malformed("RUN_STARTED while a run is still active");
+      running = true;
+      closed = void 0;
+      nothingOpen();
+      return;
+    }
+    if (!relaxed) {
+      if (first && type !== "RUN_ERROR") throw malformed(`the first event must be RUN_STARTED, not ${type}${FRAMING_HINT}`);
+      if (closed === "finished" && type !== "RUN_ERROR") throw malformed(`${type} after the run finished${FRAMING_HINT}`);
+      if (closed === "error") throw malformed(`${type} after the run ended with RUN_ERROR`);
+    }
+    if (type === "RUN_ERROR") {
+      running = false;
+      if (closed !== "finished") closed = "error";
+      nothingOpen();
+      return;
+    }
+    const owner = ownerOf(event);
+    const open = chunks.get(owner);
+    if (open && type !== open.type && type !== "RAW") chunks.delete(owner);
+    if (type === "SUBAGENT_FINISHED" || type === "SUBAGENT_ERROR") chunks.delete(String(event["subagentRunId"]));
+    switch (type) {
+      case "TEXT_MESSAGE_START":
+        text.set(String(event["messageId"]), event["subagentRunId"]);
+        break;
+      case "TEXT_MESSAGE_CONTENT":
+      case "TEXT_MESSAGE_END": {
+        const id = String(event["messageId"]);
+        if (!text.has(id)) throw malformed(`${type} for "${id}", but no open text message has that id`);
+        agrees(id, text, event);
+        if (type === "TEXT_MESSAGE_END") text.delete(id);
+        break;
+      }
+      case "TEXT_MESSAGE_CHUNK":
+      case "REASONING_MESSAGE_CHUNK": {
+        const id = typeof event["messageId"] === "string" ? event["messageId"] : void 0;
+        const role = typeof event["role"] === "string" ? event["role"] : void 0;
+        const current = chunks.get(owner);
+        if (!current || id !== void 0 && id !== current.id) {
+          if (id === void 0) throw malformed(`the first ${type} of a stream needs a messageId`);
+          chunks.set(owner, { type, id, ...role !== void 0 ? { label: role } : {} });
+        } else if (role !== void 0 && current.label !== void 0 && role !== current.label) {
+          throw malformed(`${type} changes its role from "${current.label}" to "${role}" in the middle of message "${current.id}"`);
+        }
+        break;
+      }
+      case "TOOL_CALL_CHUNK": {
+        const id = typeof event["toolCallId"] === "string" ? event["toolCallId"] : void 0;
+        const name = typeof event["toolCallName"] === "string" ? event["toolCallName"] : void 0;
+        const current = chunks.get(owner);
+        if (!current || id !== void 0 && id !== current.id) {
+          if (id === void 0 || name === void 0) throw malformed("the first TOOL_CALL_CHUNK of a call needs a toolCallId and a toolCallName");
+          chunks.set(owner, { type, id, label: name });
+        } else if (name !== void 0 && name !== current.label) {
+          throw malformed(`TOOL_CALL_CHUNK changes its toolCallName from "${current.label}" to "${name}" in the middle of call "${current.id}"`);
+        }
+        break;
+      }
+      case "TOOL_CALL_START":
+        tools.set(String(event["toolCallId"]), event["subagentRunId"]);
+        break;
+      case "TOOL_CALL_ARGS":
+      case "TOOL_CALL_END": {
+        const id = String(event["toolCallId"]);
+        if (!tools.has(id)) throw malformed(`${type} for "${id}", but no open tool call has that id`);
+        agrees(id, tools, event);
+        if (type === "TOOL_CALL_END") tools.delete(id);
+        break;
+      }
+      case "REASONING_MESSAGE_START": {
+        const id = String(event["messageId"]);
+        if (event["role"] !== void 0 && event["role"] !== "reasoning") {
+          throw malformed(`REASONING_MESSAGE_START "${id}" has the role "${String(event["role"])}", where only role "reasoning" is allowed`);
+        }
+        reasoning.set(id, event["subagentRunId"]);
+        break;
+      }
+      case "REASONING_MESSAGE_CONTENT":
+      case "REASONING_MESSAGE_END": {
+        const id = String(event["messageId"]);
+        if (!reasoning.has(id)) throw malformed(`${type} for "${id}", but no open reasoning message has that id`);
+        agrees(id, reasoning, event);
+        if (type === "REASONING_MESSAGE_END") reasoning.delete(id);
+        break;
+      }
+      case "STEP_STARTED":
+        steps.add(stepKey(owner, String(event["stepName"])));
+        break;
+      case "STEP_FINISHED": {
+        const key = stepKey(owner, String(event["stepName"]));
+        if (!steps.has(key)) throw malformed(`STEP_FINISHED for step "${String(event["stepName"])}", which was not started${owner ? ` by "${owner}"` : ""}`);
+        steps.delete(key);
+        break;
+      }
+      case "SUBAGENT_STARTED": {
+        const id = String(event["subagentRunId"]);
+        if (typeof event["name"] !== "string" || !event["name"]) throw malformed(`SUBAGENT_STARTED "${id}" needs a name`);
+        subagents.add(id);
+        break;
+      }
+      case "SUBAGENT_FINISHED":
+      case "SUBAGENT_ERROR": {
+        const id = String(event["subagentRunId"]);
+        if (!subagents.has(id)) throw malformed(`${type} for subagent "${id}", which was not started`);
+        subagents.delete(id);
+        break;
+      }
+      case "RUN_FINISHED": {
+        const outcome = event["outcome"];
+        if (outcome !== void 0 && (typeof outcome !== "object" || outcome === null || Array.isArray(outcome))) {
+          throw malformed("RUN_FINISHED.outcome must be an object");
+        }
+        if (!relaxed) {
+          const left = stillOpen();
+          if (left.length) throw malformed(`${left.join(", ")} still running at RUN_FINISHED`);
+          closed = "finished";
+        }
+        chunks.clear();
+        running = false;
+        break;
+      }
+    }
+  });
+  verify.end = () => {
+    if (!relaxed) return;
+    const left = stillOpen();
+    if (left.length) throw malformed(`${left.join(", ")} still running at the end of the stream`);
+  };
+  return verify;
+}
 async function* readAgUiEvents(body, contentType) {
   const ndjson = Boolean(contentType && /ndjson|jsonl/i.test(contentType));
   const reader = body.getReader();
@@ -81,6 +553,17 @@ async function* readAgUiEvents(body, contentType) {
     reader.releaseLock();
   }
 }
+const PROTOCOL_VERSION = "1.0";
+function versionParts(version) {
+  return /^\d+(\.\d+)*$/.test(version) ? version.split(".").map(Number) : void 0;
+}
+function compareVersions(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const d = (a[i] ?? 0) - (b[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
 function readTicket(token) {
   if (!token) return void 0;
   try {
@@ -119,6 +602,10 @@ function parseArgs(args) {
 function resultText(content) {
   if (typeof content === "string") return content;
   if (content === void 0 || content === null) return "";
+  if (Array.isArray(content)) {
+    const text = content.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text);
+    if (text.length) return text.join("\n");
+  }
   return JSON.stringify(content);
 }
 function rejectionText(decision) {
@@ -152,16 +639,24 @@ function resumeItem(interrupt, outcome) {
   };
 }
 function createAgUiRunner(options) {
-  return async (opts) => {
+  const warn = options.onWarning ?? ((message) => console.warn(`[aparte] AG-UI: ${message}`));
+  const peer = options.peerProtocolVersion ? versionParts(options.peerProtocolVersion) : void 0;
+  const declare = !peer || compareVersions(peer, [1, 0]) >= 0;
+  const flatten = peer !== void 0 && compareVersions(peer, [0, 0, 39]) <= 0;
+  const states = /* @__PURE__ */ new Map();
+  const stableThread = options.threadId !== void 0;
+  const unanswered = /* @__PURE__ */ new Map();
+  const runOnce = async (opts, track) => {
     const doFetch = options.fetch ?? fetch;
     const headers = typeof options.headers === "function" ? await options.headers() : options.headers ?? {};
     const request = opts.baseRequest;
     const ticket = readTicket(opts.deferral?.token);
     const outcomes = opts.deferral?.outcomes ?? {};
     const threadId = ticket?.threadId ?? (typeof options.threadId === "function" ? options.threadId(opts) : options.threadId) ?? `aparte-${uuid()}`;
+    track.threadId = threadId;
     const runId = `aparte-run-${uuid()}`;
     const interrupted = new Set((ticket?.interrupts ?? []).map((i) => i.toolCallId));
-    const messages = toAgUiMessages(request.messages);
+    const messages = toAgUiMessages(request.messages, flatten, warn);
     for (const [toolCallId, outcome] of Object.entries(outcomes)) {
       if (interrupted.has(toolCallId)) continue;
       if (outcome.kind === "decision" && outcome.approved) continue;
@@ -172,12 +667,15 @@ function createAgUiRunner(options) {
         content: outcome.kind === "failed" ? `Error: ${outcome.error}` : outcome.kind === "decision" ? rejectionText(outcome) : outcome.content
       });
     }
-    const resume = ticket?.interrupts.length ? ticket.interrupts.map((interrupt) => resumeItem(interrupt, outcomes[interrupt.toolCallId])) : void 0;
+    const left = ticket ? [] : unanswered.get(threadId) ?? [];
+    unanswered.delete(threadId);
+    const resume = ticket?.interrupts.length ? ticket.interrupts.map((interrupt) => resumeItem(interrupt, interrupt.kind === "unanswerable" ? void 0 : outcomes[interrupt.toolCallId])) : left.length ? left.map((interruptId) => ({ interruptId, status: "cancelled" })) : void 0;
     const body = {
       threadId,
       runId,
+      ...declare ? { protocolVersion: PROTOCOL_VERSION } : {},
       ...ticket ? { parentRunId: ticket.runId } : {},
-      state: {},
+      state: states.has(threadId) ? states.get(threadId) : {},
       messages,
       tools: toAgUiTools(request.tools),
       context: options.context ?? [],
@@ -210,6 +708,7 @@ function createAgUiRunner(options) {
     const rejected = /* @__PURE__ */ new Set();
     const settledByPage = /* @__PURE__ */ new Set();
     let textOpen = false;
+    let runError;
     let usage;
     let finished;
     const emit = opts.emitter;
@@ -274,12 +773,39 @@ function createAgUiRunner(options) {
         }
       }
     };
-    for await (const event of readAgUiEvents(response.body, response.headers.get("content-type"))) {
+    const verify = createVerifier(!declare || options.relaxedRunFraming === true);
+    const translate = createTranslator(peer, warn);
+    async function* incoming(body2, contentType) {
+      for await (const raw of readAgUiEvents(body2, contentType)) {
+        for (const translated of translate(raw)) {
+          const event = enforce(translated, warn);
+          if (event) yield event;
+        }
+      }
+    }
+    for await (const event of incoming(response.body, response.headers.get("content-type"))) {
+      verify(event);
       begin();
       if (/^(TEXT_MESSAGE|REASONING|TOOL_CALL)_/.test(event.type)) endedOnFinish = false;
       switch (event.type) {
-        case "RUN_STARTED":
+        case "RUN_STARTED": {
+          if (runError) {
+            warn(`the agent's run failed ("${runError.message}") and the stream ran it again; the reply shows the new run.`);
+            for (const [toolCallId] of started) {
+              if (answered.has(toolCallId)) continue;
+              emit({ type: "tool-aborted", toolCallId });
+              answered.add(toolCallId);
+            }
+            runError = void 0;
+          }
+          const declared = event["protocolVersion"];
+          if (typeof declared === "string") {
+            const parts = versionParts(declared);
+            if (!parts) warn(`the agent declares protocol version "${declared}", which this runner cannot interpret; reading its stream as ${PROTOCOL_VERSION}.`);
+            else if (compareVersions(parts, versionParts(PROTOCOL_VERSION)) > 0) warn(`the agent speaks AG-UI ${declared}, newer than the ${PROTOCOL_VERSION} this runner speaks; reading its stream as ${PROTOCOL_VERSION}.`);
+          }
           break;
+        }
         case "TEXT_MESSAGE_START":
         case "REASONING_START":
         case "REASONING_MESSAGE_START":
@@ -344,17 +870,25 @@ function createAgUiRunner(options) {
           if (meta?.tanstack?.state === "output-error") {
             emit({ type: "tool-failed", toolCallId, error: content });
           } else {
-            emit({ type: "tool-resolved", toolCallId, result: content });
+            const parts = Array.isArray(event["content"]) ? { structuredResult: event["content"] } : {};
+            emit({ type: "tool-resolved", toolCallId, result: content, ...parts });
           }
           break;
         }
         case "RUN_ERROR": {
-          throw new AparteError(
+          runError = new AparteError(
             typeof event["message"] === "string" && event["message"] ? event["message"] : "The agent run failed.",
             AparteErrorCode.PROVIDER_ERROR,
-            typeof event["code"] === "string" ? { code: event["code"] } : void 0
+            { agUi: "run-error", ...typeof event["code"] === "string" ? { code: event["code"] } : {} }
           );
+          break;
         }
+        case "STATE_SNAPSHOT":
+          states.set(threadId, event["snapshot"]);
+          break;
+        case "STATE_DELTA":
+          states.set(threadId, applyStateDelta(states.has(threadId) ? states.get(threadId) : {}, event["delta"], warn));
+          break;
         case "RUN_FINISHED": {
           for (const id of calls.keys()) startTool(id);
           if (textOpen) {
@@ -373,23 +907,28 @@ function createAgUiRunner(options) {
       }
     }
     if (opts.signal.aborted) return usage;
+    if (runError) {
+      for (const [toolCallId] of started) if (!answered.has(toolCallId)) emit({ type: "tool-aborted", toolCallId });
+      if (textOpen) emit({ type: "text-flush" });
+      throw runError;
+    }
     if (!finished) {
       throw new AparteError("The agent stream ended without RUN_FINISHED.", AparteErrorCode.PROVIDER_ERROR);
     }
     if (!endedOnFinish) {
       throw new AparteError("The agent stream was cut: it ended in the middle of a step, after a RUN_FINISHED.", AparteErrorCode.PROVIDER_ERROR);
     }
+    verify.end();
     if (textOpen) emit({ type: "text-flush" });
     const pending = [];
     const interrupts = [];
+    const unanswerable = [];
     if (finished.outcome?.type === "interrupt") {
       for (const interrupt of finished.outcome.interrupts ?? []) {
         const kind = interruptKind(interrupt);
         if (!kind || !interrupt.toolCallId) {
-          throw new AparteError(
-            `The agent paused for something aparté cannot answer yet (interrupt reason "${interrupt.reason}").`,
-            AparteErrorCode.PROVIDER_ERROR
-          );
+          unanswerable.push(interrupt.id);
+          continue;
         }
         const call = callOf(interrupt);
         if (kind === "approval") {
@@ -409,13 +948,24 @@ function createAgUiRunner(options) {
       }
     }
     if (pending.length > 0) {
-      const next = { v: 1, threadId, runId: finished.runId, interrupts };
+      const cancelled = unanswerable.map((id) => ({ id, toolCallId: "", kind: "unanswerable" }));
+      const next = { v: 1, threadId, runId: finished.runId, interrupts: [...interrupts, ...cancelled] };
+      track.suspended = true;
       emit({ type: "run-suspended", pending, ...usage ? { usage } : {}, ticket: JSON.stringify(next) });
     } else {
+      if (unanswerable.length && stableThread) unanswered.set(threadId, unanswerable);
       emit({ type: "run-done", ...usage ? { usage } : {} });
     }
     return usage;
   };
+  return async (opts) => {
+    const track = { suspended: false };
+    try {
+      return await runOnce(opts, track);
+    } finally {
+      if (track.threadId && !stableThread && !track.suspended) states.delete(track.threadId);
+    }
+  };
 }
 export {
   createAgUiRunner