@aparte/runner-ag-ui 1.5.0 → 1.7.0

package/dist/index.js

@@ -210,24 +210,139 @@ function step(doc, 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;
+  return applyPatch(state, delta, warn, { event: "STATE_DELTA", field: "delta", what: "state" });
+}
+function applyActivityDelta(content, patch, warn) {
+  return applyPatch(content, patch, warn, { event: "ACTIVITY_DELTA", field: "patch", what: "activity" });
+}
+function applyPatch(doc, patch, warn, names) {
+  const { event, field, what } = names;
+  if (!Array.isArray(patch)) {
+    warn(`Failed to apply ${what} patch: ${event} carried no list of operations; the ${what} is left as it was.`);
+    return doc;
   }
   const ops = [];
-  delta.forEach((op, i) => {
+  patch.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.`);
+    else warn(`dropped /${field}/${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;
+    let next = structuredClone(doc);
+    for (const op of ops) next = step(next, op);
+    return next;
   } catch (error) {
-    warn(`Failed to apply state patch: ${error.message}; the state is left as it was.`);
-    return state;
+    warn(`Failed to apply ${what} patch: ${error.message}; the ${what} is left as it was.`);
+    return doc;
   }
 }
+function createSubagentHistory(from = []) {
+  const records = new Map(from.map((r) => [r.id, JSON.parse(JSON.stringify(r))]));
+  const record = (id) => {
+    let at = records.get(id);
+    if (!at) {
+      at = { id, name: "subagent", status: "running", messages: [] };
+      records.set(id, at);
+    }
+    return at;
+  };
+  const assistantCall = (owner, toolCallId) => {
+    for (const m of record(owner).messages) {
+      if (m.role !== "assistant") continue;
+      const call = m.toolCalls?.find((c) => c.id === toolCallId);
+      if (call) return call;
+    }
+    return void 0;
+  };
+  return {
+    /** Announced (again, by a resumed run: the same invocation going on). */
+    start(id, info) {
+      const at = record(id);
+      Object.assign(at, info);
+      at.status = "running";
+      delete at.interruptIds;
+    },
+    end(id, status, interruptIds) {
+      const at = record(id);
+      at.status = status;
+      if (interruptIds?.length) at.interruptIds = interruptIds;
+      else delete at.interruptIds;
+    },
+    text(owner, messageId, delta) {
+      const messages = record(owner).messages;
+      let at = messages.find((m) => m.role === "assistant" && m.id === messageId);
+      if (!at) {
+        at = { id: messageId, role: "assistant", content: "" };
+        messages.push(at);
+      }
+      at.content = (at.content ?? "") + delta;
+    },
+    /** A call joins the assistant message that ends the transcript, as one model step writes text then calls. */
+    call(owner, toolCallId, name) {
+      const known = assistantCall(owner, toolCallId);
+      if (known) {
+        if (name) known.function.name = name;
+        return;
+      }
+      const messages = record(owner).messages;
+      const last = messages.at(-1);
+      let host;
+      if (last?.role === "assistant") {
+        host = last;
+      } else {
+        host = { id: `${toolCallId}:call`, role: "assistant" };
+        messages.push(host);
+      }
+      host.toolCalls = [...host.toolCalls ?? [], { id: toolCallId, type: "function", function: { name, arguments: "" } }];
+    },
+    args(owner, toolCallId, delta) {
+      const call = assistantCall(owner, toolCallId);
+      if (call) call.function.arguments += delta;
+    },
+    result(owner, messageId, toolCallId, content) {
+      record(owner).messages.push({ id: messageId ?? `${toolCallId}:result`, role: "tool", toolCallId, content });
+    },
+    /** The run's sub-agents, `tanstack` set on each when the run was TanStack AI's. */
+    records(tanstack = false) {
+      return [...records.values()].map((r) => tanstack ? { ...r, tanstack: true } : r);
+    }
+  };
+}
+function subagentMessages(records, answers = /* @__PURE__ */ new Map()) {
+  return records.filter((r) => r.tanstack).flatMap((r) => withAnswers(r.messages, answers).map((m, i) => {
+    if (m.role !== "assistant" && m.role !== "tool") return m;
+    const card = i === 0 ? {
+      metadata: {
+        tanstack: {
+          subagent: {
+            name: r.name,
+            status: r.status,
+            ...r.description !== void 0 ? { description: r.description } : {},
+            ...r.parentToolCallId !== void 0 ? { parentToolCallId: r.parentToolCallId } : {},
+            ...r.parentSubagentRunId !== void 0 ? { parentSubagentRunId: r.parentSubagentRunId } : {},
+            ...r.interruptIds ? { interruptIds: r.interruptIds } : {},
+            ...r.metadata ? { metadata: r.metadata } : {}
+          }
+        }
+      }
+    } : {};
+    return { ...m, subagentRunId: r.id, ...card };
+  }));
+}
+function withAnswers(messages, answers) {
+  if (answers.size === 0) return [...messages];
+  const out = [];
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    out.push(m);
+    if (m.role !== "assistant" || !m.toolCalls?.length) continue;
+    while (messages[i + 1]?.role === "tool") out.push(messages[++i]);
+    for (const call of m.toolCalls) {
+      const answer = answers.get(call.id);
+      if (answer) out.push(answer);
+    }
+  }
+  return out;
+}
 function compare(a, b) {
   for (let i = 0; i < Math.max(a.length, b.length); i++) {
     const d = (a[i] ?? 0) - (b[i] ?? 0);
@@ -357,10 +472,10 @@ function createVerifier(relaxed) {
   };
   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 by2 = event["subagentRunId"];
+    if (by2 === 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)}"`);
+    if (at !== void 0 && at !== by2) throw malformed(`${event.type} for "${id}" is attributed to "${String(by2)}", but "${id}" started attributed to "${String(at)}"`);
   };
   const verify = ((event) => {
     const type = event.type;
@@ -573,14 +688,25 @@ function readTicket(token) {
     return void 0;
   }
 }
+const PARENT = "";
+function by(owner) {
+  return owner ? { agentId: owner } : {};
+}
+function routerPlanOf(event) {
+  const tanstack = event["metadata"]?.tanstack;
+  const steps = tanstack?.subagentPlan?.steps;
+  if (!Array.isArray(steps)) return void 0;
+  const names = steps.map((step2) => Array.isArray(step2?.names) ? step2.names.filter((n) => typeof n === "string" && n !== "") : []).filter((step2) => step2.length > 0);
+  return names.length ? names : void 0;
+}
 function interruptKind(interrupt) {
   if (interrupt.reason === "tool_call" || interrupt.reason === "confirmation" || interrupt.reason === "approval_required") return "approval";
   if (/client_tool/.test(interrupt.reason)) return "external";
   return void 0;
 }
-function readUsage(value) {
+function readUsage(value, pick = "last") {
   const entries = (Array.isArray(value) ? value : value && typeof value === "object" ? [value] : []).filter((u) => Boolean(u) && typeof u === "object");
-  const last = entries.at(-1);
+  const last = pick === "first" ? entries[0] : entries.at(-1);
   if (!last) return void 0;
   const num = (key) => typeof last[key] === "number" ? last[key] : 0;
   const cached = num("cachedInputTokens");
@@ -658,16 +784,23 @@ function createAgUiRunner(options) {
     const runId = `aparte-run-${uuid()}`;
     const interrupted = new Set((ticket?.interrupts ?? []).map((i) => i.toolCallId));
     const messages = toAgUiMessages(request.messages, flatten, warn);
+    const pausedAgents = Array.isArray(ticket?.subagents) ? ticket.subagents : [];
+    const sentBack = new Set(pausedAgents.filter((r) => r.tanstack).map((r) => r.id));
+    const answers = /* @__PURE__ */ new Map();
     for (const [toolCallId, outcome] of Object.entries(outcomes)) {
       if (interrupted.has(toolCallId)) continue;
       if (outcome.kind === "decision" && outcome.approved) continue;
-      messages.push({
+      const answer = {
         id: `aparte-result-${toolCallId}`,
         role: "tool",
         toolCallId,
         content: outcome.kind === "failed" ? `Error: ${outcome.error}` : outcome.kind === "decision" ? rejectionText(outcome) : outcome.content
-      });
+      };
+      const owner = ticket?.agents?.[toolCallId];
+      if (owner !== void 0 && sentBack.has(owner)) answers.set(toolCallId, answer);
+      else messages.push(answer);
     }
+    messages.push(...subagentMessages(pausedAgents, answers));
     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;
@@ -708,32 +841,112 @@ function createAgUiRunner(options) {
     const answered = /* @__PURE__ */ new Set();
     const rejected = /* @__PURE__ */ new Set();
     const settledByPage = /* @__PURE__ */ new Set();
-    let textOpen = false;
     let runError;
     let usage;
     let finished;
     const emit = opts.emitter;
+    const lanes = /* @__PURE__ */ new Map();
+    const lane = (owner) => {
+      let at = lanes.get(owner);
+      if (!at) {
+        at = { textOpen: false, stepEnded: false };
+        lanes.set(owner, at);
+      }
+      return at;
+    };
+    const messageOwners = /* @__PURE__ */ new Map();
+    const chunkMessages = /* @__PURE__ */ new Map();
+    const lastCall = /* @__PURE__ */ new Map();
+    const ticketAgents = new Map(Object.entries(ticket?.agents ?? {}).filter((entry) => typeof entry[1] === "string"));
+    const agents = /* @__PURE__ */ new Map();
+    const transcripts = createSubagentHistory(pausedAgents);
+    let tanstackRun = false;
+    let ownStep = false;
+    const tagOf = (event) => typeof event["subagentRunId"] === "string" ? event["subagentRunId"] : void 0;
+    const messageOwner = (event) => {
+      let id = typeof event["messageId"] === "string" ? event["messageId"] : void 0;
+      if (event.type.endsWith("_CHUNK")) {
+        const key = `${event.type}\0${tagOf(event) ?? PARENT}`;
+        if (id !== void 0) chunkMessages.set(key, id);
+        else id = chunkMessages.get(key);
+      }
+      const opened = id !== void 0 ? messageOwners.get(id) : void 0;
+      if (opened !== void 0) return opened;
+      const owner = tagOf(event) ?? PARENT;
+      if (id !== void 0) messageOwners.set(id, owner);
+      return owner;
+    };
+    const newCallOwner = (event) => tagOf(event) ?? (typeof event["parentMessageId"] === "string" ? messageOwners.get(event["parentMessageId"]) : void 0) ?? PARENT;
+    const callOwner = (toolCallId) => calls.get(toolCallId)?.owner ?? ticketAgents.get(toolCallId);
+    const flush = (owner) => {
+      const at = lanes.get(owner);
+      if (at?.textOpen) {
+        emit({ type: "text-flush", ...by(owner) });
+        at.textOpen = false;
+      }
+    };
+    const meet = (agentId) => {
+      if (agents.has(agentId)) return;
+      agents.set(agentId, { open: true });
+      emit({ type: "agent-start", agentId });
+    };
+    const openSteps = [];
+    const closeSteps = (owner) => {
+      for (let i = openSteps.length - 1; i >= 0; i -= 1) {
+        const step2 = openSteps[i];
+        if (owner !== void 0 && step2.owner !== owner) continue;
+        openSteps.splice(i, 1);
+        emit({ type: "step-end", name: step2.name, ...by(step2.owner) });
+      }
+    };
+    track.closeSteps = closeSteps;
+    const activities = /* @__PURE__ */ new Map();
+    const showActivity = (id, at) => {
+      activities.set(id, at);
+      emit({ type: "activity", id, activityType: at.activityType, content: at.content, ...by(at.owner) });
+    };
+    const paused = ticket?.plan;
+    let routerPlan = paused && Array.isArray(paused.steps) ? { steps: paused.steps, status: new Map(Object.entries(paused.status ?? {})) } : void 0;
+    const planId = typeof paused?.id === "string" ? paused.id : `router-plan:${runId}`;
+    const tickRouterPlan = (name, status) => {
+      const at = name === void 0 ? -1 : routerPlan?.steps.findIndex((step2) => step2.includes(name)) ?? -1;
+      if (!routerPlan || at < 0) return;
+      if (status === "in-progress") {
+        for (const before of routerPlan.steps.slice(0, at).flat()) if (routerPlan.status.get(before) !== "failed") routerPlan.status.set(before, "done");
+      }
+      routerPlan.status.set(name, status);
+      const steps = routerPlan.steps.flat().map((title) => ({ title, status: routerPlan.status.get(title) ?? "pending" }));
+      showActivity(planId, { activityType: "plan", content: { steps }, owner: PARENT });
+    };
+    const endAgent = (agentId, status, detail = {}) => {
+      closeSteps(agentId);
+      const agent = agents.get(agentId);
+      if (agent) agent.open = false;
+      emit({ type: "agent-end", agentId, status, ...detail, ...agent?.parent ? { parentAgentId: agent.parent } : {} });
+      if (agent && !agent.parent) tickRouterPlan(agent.name, status === "waiting" ? "blocked" : status);
+    };
+    const failOpenAgents = (error) => {
+      for (const [agentId, agent] of [...agents].reverse()) {
+        if (!agent.open) continue;
+        flush(agentId);
+        endAgent(agentId, "failed", { error });
+      }
+    };
     const startTool = (toolCallId) => {
       const call = calls.get(toolCallId);
       if (!call || started.has(toolCallId) || known.has(toolCallId)) return;
       const input = parseArgs(call.args);
-      started.set(toolCallId, { name: call.name, input });
-      if (textOpen) {
-        emit({ type: "text-flush" });
-        textOpen = false;
-      }
-      emit({ type: "tool-start", toolCallId, name: call.name, input });
-      stepEnded = true;
+      started.set(toolCallId, { name: call.name, input, owner: call.owner });
+      flush(call.owner);
+      emit({ type: "tool-start", toolCallId, name: call.name, input, ...by(call.owner) });
+      lane(call.owner).stepEnded = true;
     };
-    let stepEnded = false;
-    const nextStep = () => {
-      if (!stepEnded) return;
-      stepEnded = false;
-      if (textOpen) {
-        emit({ type: "text-flush" });
-        textOpen = false;
-      }
-      emit({ type: "turn-start" });
+    const nextStep = (owner) => {
+      const at = lane(owner);
+      if (!at.stepEnded) return;
+      at.stepEnded = false;
+      flush(owner);
+      emit({ type: "turn-start", ...by(owner) });
     };
     const callOf = (interrupt) => {
       const here = started.get(interrupt.toolCallId) ?? history.get(interrupt.toolCallId);
@@ -751,25 +964,28 @@ function createAgUiRunner(options) {
       emit({ type: "run-start" });
       emit({ type: "turn-start" });
       for (const [toolCallId, outcome] of Object.entries(outcomes)) {
+        const owner = ticketAgents.get(toolCallId) ?? PARENT;
+        if (owner) lane(owner).stepEnded = true;
         if (outcome.kind === "result") {
           emit({
             type: "tool-resolved",
             toolCallId,
             result: outcome.content,
-            ...outcome.structuredContent !== void 0 ? { structuredResult: outcome.structuredContent } : {}
+            ...outcome.structuredContent !== void 0 ? { structuredResult: outcome.structuredContent } : {},
+            ...by(owner)
           });
           settledByPage.add(toolCallId);
           continue;
         }
         if (outcome.kind === "failed") {
-          emit({ type: "tool-failed", toolCallId, error: outcome.error });
+          emit({ type: "tool-failed", toolCallId, error: outcome.error, ...by(owner) });
           settledByPage.add(toolCallId);
           continue;
         }
         if (outcome.approved) {
-          emit({ type: "tool-approved", toolCallId });
+          emit({ type: "tool-approved", toolCallId, ...by(owner) });
         } else {
-          emit({ type: "tool-rejected", toolCallId, ...toolRefusal(outcome) });
+          emit({ type: "tool-rejected", toolCallId, ...toolRefusal(outcome), ...by(owner) });
           rejected.add(toolCallId);
         }
       }
@@ -788,15 +1004,20 @@ function createAgUiRunner(options) {
       verify(event);
       begin();
       if (/^(TEXT_MESSAGE|REASONING|TOOL_CALL)_/.test(event.type)) endedOnFinish = false;
+      const tag = tagOf(event);
+      if (tag !== void 0 && !event.type.startsWith("SUBAGENT_")) meet(tag);
+      const metadata = event.metadata;
+      if (metadata && typeof metadata === "object" && typeof metadata.tanstack === "object") tanstackRun = true;
       switch (event.type) {
         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) {
+            for (const [toolCallId, call] of started) {
               if (answered.has(toolCallId)) continue;
-              emit({ type: "tool-aborted", toolCallId });
+              emit({ type: "tool-aborted", toolCallId, ...by(call.owner) });
               answered.add(toolCallId);
             }
+            failOpenAgents(runError.message);
             runError = void 0;
           }
           const declared = event["protocolVersion"];
@@ -809,52 +1030,75 @@ function createAgUiRunner(options) {
         }
         case "TEXT_MESSAGE_START":
         case "REASONING_START":
-        case "REASONING_MESSAGE_START":
-          nextStep();
+        case "REASONING_MESSAGE_START": {
+          const owner = messageOwner(event);
+          if (owner === PARENT) ownStep = true;
+          nextStep(owner);
           break;
+        }
         case "TEXT_MESSAGE_CONTENT":
         case "TEXT_MESSAGE_CHUNK": {
+          const owner = messageOwner(event);
           const delta = typeof event["delta"] === "string" ? event["delta"] : "";
+          if (owner === PARENT) ownStep = true;
           if (delta) {
-            nextStep();
-            emit({ type: "text-delta", delta });
-            textOpen = true;
+            nextStep(owner);
+            emit({ type: "text-delta", delta, ...by(owner) });
+            lane(owner).textOpen = true;
           }
+          const id = typeof event["messageId"] === "string" ? event["messageId"] : chunkMessages.get(`${event.type}\0${tag ?? PARENT}`);
+          if (owner !== PARENT && delta && id !== void 0) transcripts.text(owner, id, delta);
           break;
         }
-        case "TEXT_MESSAGE_END": {
-          if (textOpen) {
-            emit({ type: "text-flush" });
-            textOpen = false;
-          }
+        case "TEXT_MESSAGE_END":
+          flush(messageOwner(event));
           break;
-        }
         case "REASONING_MESSAGE_CONTENT":
         case "REASONING_MESSAGE_CHUNK": {
+          const owner = messageOwner(event);
           const delta = typeof event["delta"] === "string" ? event["delta"] : "";
           if (delta) {
-            nextStep();
-            emit({ type: "thinking-delta", delta });
+            nextStep(owner);
+            emit({ type: "thinking-delta", delta, ...by(owner) });
           }
           break;
         }
         case "TOOL_CALL_START": {
           const id = String(event["toolCallId"]);
-          calls.set(id, { name: String(event["toolCallName"] ?? ""), args: "" });
+          if (!calls.has(id)) lastCall.set(tag ?? PARENT, id);
+          const owner = newCallOwner(event);
+          const name = String(event["toolCallName"] ?? "");
+          calls.set(id, { name, args: "", owner });
+          if (owner === PARENT) ownStep = true;
+          else transcripts.call(owner, id, name);
           break;
         }
         case "TOOL_CALL_ARGS": {
-          const call = calls.get(String(event["toolCallId"]));
-          if (call && typeof event["delta"] === "string") call.args += event["delta"];
+          const id = String(event["toolCallId"]);
+          const call = calls.get(id);
+          if (call && typeof event["delta"] === "string") {
+            call.args += event["delta"];
+            if (call.owner !== PARENT) transcripts.args(call.owner, id, event["delta"]);
+          }
           break;
         }
         case "TOOL_CALL_CHUNK": {
-          const id = typeof event["toolCallId"] === "string" ? event["toolCallId"] : [...calls.keys()].at(-1);
+          const id = typeof event["toolCallId"] === "string" ? event["toolCallId"] : lastCall.get(tag ?? PARENT);
           if (!id) break;
-          const call = calls.get(id) ?? { name: "", args: "" };
+          let call = calls.get(id);
+          if (!call) {
+            call = { name: "", args: "", owner: newCallOwner(event) };
+            calls.set(id, call);
+            lastCall.set(tag ?? PARENT, id);
+          }
           if (typeof event["toolCallName"] === "string" && event["toolCallName"]) call.name = event["toolCallName"];
           if (typeof event["delta"] === "string") call.args += event["delta"];
-          calls.set(id, call);
+          if (call.owner === PARENT) {
+            ownStep = true;
+          } else {
+            transcripts.call(call.owner, id, call.name);
+            if (typeof event["delta"] === "string") transcripts.args(call.owner, id, event["delta"]);
+          }
           break;
         }
         case "TOOL_CALL_END": {
@@ -866,13 +1110,66 @@ function createAgUiRunner(options) {
           startTool(toolCallId);
           if (rejected.has(toolCallId) || settledByPage.has(toolCallId)) break;
           answered.add(toolCallId);
+          const owner = callOwner(toolCallId) ?? tag ?? PARENT;
           const content = resultText(event["content"]);
+          if (owner !== PARENT) transcripts.result(owner, typeof event["messageId"] === "string" ? event["messageId"] : void 0, toolCallId, content);
           const meta = event["metadata"];
           if (meta?.tanstack?.state === "output-error") {
-            emit({ type: "tool-failed", toolCallId, error: content });
+            emit({ type: "tool-failed", toolCallId, error: content, ...by(owner) });
           } else {
             const parts = Array.isArray(event["content"]) ? { structuredResult: event["content"] } : {};
-            emit({ type: "tool-resolved", toolCallId, result: content, ...parts });
+            emit({ type: "tool-resolved", toolCallId, result: content, ...parts, ...by(owner) });
+          }
+          break;
+        }
+        case "SUBAGENT_STARTED": {
+          const agentId = String(event["subagentRunId"]);
+          const toolCallId = typeof event["parentToolCallId"] === "string" ? event["parentToolCallId"] : void 0;
+          const parent = typeof event["parentSubagentRunId"] === "string" ? event["parentSubagentRunId"] : void 0;
+          if (toolCallId) startTool(toolCallId);
+          const name = String(event["name"]);
+          agents.set(agentId, { open: true, name, ...parent ? { parent } : {} });
+          const metadata2 = event["metadata"];
+          transcripts.start(agentId, {
+            name,
+            ...typeof event["description"] === "string" ? { description: event["description"] } : {},
+            ...toolCallId ? { parentToolCallId: toolCallId } : {},
+            ...parent ? { parentSubagentRunId: parent } : {},
+            ...metadata2 && typeof metadata2 === "object" && !Array.isArray(metadata2) ? { metadata: metadata2 } : {}
+          });
+          if (!parent) {
+            if (!routerPlan) {
+              const steps = routerPlanOf(event);
+              if (steps) routerPlan = { steps, status: /* @__PURE__ */ new Map() };
+            }
+            tickRouterPlan(name, "in-progress");
+          }
+          emit({
+            type: "agent-start",
+            agentId,
+            name,
+            ...typeof event["description"] === "string" ? { description: event["description"] } : {},
+            ...toolCallId ? { toolCallId } : {},
+            ...parent ? { parentAgentId: parent } : {}
+          });
+          break;
+        }
+        case "SUBAGENT_FINISHED":
+        case "SUBAGENT_ERROR": {
+          const agentId = String(event["subagentRunId"]);
+          flush(agentId);
+          for (const [id, call] of calls) if (call.owner === agentId) startTool(id);
+          const outcome = event["outcome"];
+          if (event.type === "SUBAGENT_ERROR") {
+            transcripts.end(agentId, "error");
+            endAgent(agentId, "failed", { error: typeof event["message"] === "string" && event["message"] ? event["message"] : "The sub-agent failed." });
+          } else if (outcome?.type === "suspended") {
+            const ids = Array.isArray(outcome.interruptIds) ? outcome.interruptIds.filter((id) => typeof id === "string") : [];
+            transcripts.end(agentId, "suspended", ids);
+            endAgent(agentId, "waiting");
+          } else {
+            transcripts.end(agentId, "finished");
+            endAgent(agentId, "done", event["result"] !== void 0 ? { result: resultText(event["result"]) } : {});
           }
           break;
         }
@@ -884,6 +1181,9 @@ function createAgUiRunner(options) {
           );
           break;
         }
+        // State is run-scoped in AG-UI 1.0: a sub-agent's STATE_* updates the run's state
+        // exactly as the parent's does — its `subagentRunId` is provenance, and the
+        // protocol forbids withholding the update because a sub-agent sent it.
         case "STATE_SNAPSHOT":
           states.set(threadId, event["snapshot"]);
           break;
@@ -892,12 +1192,12 @@ function createAgUiRunner(options) {
           break;
         case "RUN_FINISHED": {
           for (const id of calls.keys()) startTool(id);
-          if (textOpen) {
-            emit({ type: "text-flush" });
-            textOpen = false;
-          }
-          usage = readUsage(event["usage"]) ?? usage;
-          stepEnded = true;
+          for (const owner of lanes.keys()) flush(owner);
+          if (agents.size === 0) usage = readUsage(event["usage"]) ?? usage;
+          else if (ownStep) usage = readUsage(event["usage"], "first") ?? usage;
+          ownStep = false;
+          lane(PARENT).stepEnded = true;
+          for (const at of lanes.values()) at.stepEnded = true;
           endedOnFinish = true;
           finished = {
             runId: typeof event["runId"] === "string" ? event["runId"] : runId,
@@ -905,12 +1205,57 @@ function createAgUiRunner(options) {
           };
           break;
         }
+        // A step is a name with a start and an end, its owner's: shown while it lasts
+        // (the waiting indicator, a sub-agent's line). Steps may nest and overlap, and
+        // one ends the latest open step of its name under the same owner.
+        case "STEP_STARTED": {
+          const owner = tag ?? PARENT;
+          const name = String(event["stepName"] ?? "");
+          openSteps.push({ owner, name });
+          emit({ type: "step-start", name, ...by(owner) });
+          break;
+        }
+        case "STEP_FINISHED": {
+          const owner = tag ?? PARENT;
+          const name = String(event["stepName"] ?? "");
+          for (let i = openSteps.length - 1; i >= 0; i -= 1) {
+            if (openSteps[i].owner !== owner || openSteps[i].name !== name) continue;
+            openSteps.splice(i, 1);
+            emit({ type: "step-end", name, ...by(owner) });
+            break;
+          }
+          break;
+        }
+        // An activity is structured progress, drawn by the renderer the app registered for
+        // its type. A snapshot overwrites it unless it says `replace: false` (AG-UI 1.0:
+        // "only an explicit false asks a consumer to leave what is already there") — its
+        // type included; a delta patches what is held. Either way the page gets it whole.
+        case "ACTIVITY_SNAPSHOT": {
+          const id = String(event["messageId"] ?? "");
+          const held = activities.get(id);
+          if (held && event["replace"] === false) break;
+          showActivity(id, { activityType: String(event["activityType"] ?? ""), content: event["content"], owner: held?.owner ?? tag ?? PARENT });
+          break;
+        }
+        case "ACTIVITY_DELTA": {
+          const id = String(event["messageId"] ?? "");
+          const held = activities.get(id);
+          if (!held) {
+            warn(`ACTIVITY_DELTA for "${id}", an activity no ACTIVITY_SNAPSHOT created: skipped.`);
+            break;
+          }
+          const content = applyActivityDelta(held.content, event["patch"], warn);
+          if (content !== held.content) showActivity(id, { ...held, content });
+          break;
+        }
       }
     }
+    closeSteps();
     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" });
+      for (const [toolCallId, call] of started) if (!answered.has(toolCallId)) emit({ type: "tool-aborted", toolCallId, ...by(call.owner) });
+      for (const owner of lanes.keys()) flush(owner);
+      failOpenAgents(runError.message);
       throw runError;
     }
     if (!finished) {
@@ -920,7 +1265,7 @@ function createAgUiRunner(options) {
       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" });
+    for (const owner of lanes.keys()) flush(owner);
     const pending = [];
     const interrupts = [];
     const unanswerable = [];
@@ -932,11 +1277,12 @@ function createAgUiRunner(options) {
           continue;
         }
         const call = callOf(interrupt);
+        const owner = interrupt.subagentRunId ?? callOwner(interrupt.toolCallId) ?? PARENT;
         if (kind === "approval") {
-          emit({ type: "tool-awaiting-approval", toolCallId: interrupt.toolCallId, name: call.name, input: call.input });
+          emit({ type: "tool-awaiting-approval", toolCallId: interrupt.toolCallId, name: call.name, input: call.input, ...by(owner) });
         }
         interrupts.push({ id: interrupt.id, toolCallId: interrupt.toolCallId, kind });
-        pending.push({ toolCallId: interrupt.toolCallId, name: call.name, input: call.input, reason: kind });
+        pending.push({ toolCallId: interrupt.toolCallId, name: call.name, input: call.input, reason: kind, ...by(owner) });
       }
     } else {
       const outcome = finished.outcome;
@@ -944,13 +1290,25 @@ function createAgUiRunner(options) {
       for (const [toolCallId, call] of started) {
         if (answered.has(toolCallId)) continue;
         const forPage = outcome?.type !== "cancelled" && (named ? named.has(toolCallId) : browserTools.has(call.name));
-        if (forPage) pending.push({ toolCallId, name: call.name, input: call.input, reason: "external" });
-        else emit({ type: "tool-aborted", toolCallId });
+        if (forPage) pending.push({ toolCallId, name: call.name, input: call.input, reason: "external", ...by(call.owner) });
+        else emit({ type: "tool-aborted", toolCallId, ...by(call.owner) });
       }
     }
+    for (const [agentId, agent] of [...agents].reverse()) {
+      if (agent.open) endAgent(agentId, pending.some((p) => p.agentId === agentId) ? "waiting" : "done");
+    }
     if (pending.length > 0) {
       const cancelled = unanswerable.map((id) => ({ id, toolCallId: "", kind: "unanswerable" }));
-      const next = { v: 1, threadId, runId: finished.runId, interrupts: [...interrupts, ...cancelled] };
+      const owned = pending.filter((p) => p.agentId).map((p) => [p.toolCallId, p.agentId]);
+      const next = {
+        v: 1,
+        threadId,
+        runId: finished.runId,
+        interrupts: [...interrupts, ...cancelled],
+        ...owned.length ? { agents: Object.fromEntries(owned) } : {},
+        ...transcripts.records().length ? { subagents: transcripts.records(tanstackRun) } : {},
+        ...routerPlan ? { plan: { id: planId, steps: routerPlan.steps, status: Object.fromEntries(routerPlan.status) } } : {}
+      };
       track.suspended = true;
       emit({ type: "run-suspended", pending, ...usage ? { usage } : {}, ticket: JSON.stringify(next) });
     } else {
@@ -965,6 +1323,7 @@ function createAgUiRunner(options) {
       return await runOnce(opts, track);
     } finally {
       if (track.threadId && !stableThread && !track.suspended) states.delete(track.threadId);
+      track.closeSteps?.();
     }
   };
 }