@botbotgo/agent-harness 0.0.251 → 0.0.253

package/dist/flow/export-mermaid.js

@@ -1,5 +1,18 @@
-const PRODUCT_VIEW_KINDS = new Set(["agent", "llm", "tool", "skill"]);
+import { formatAgentName } from "../utils/agent-display.js";
+const PRODUCT_VIEW_KINDS = new Set(["agent", "tool", "skill", "memory"]);
 const STRUCTURAL_EDGE_KINDS = new Set(["sequence", "contains"]);
+const PRODUCT_VIEW_EDGE_KINDS = new Set(["sequence", "approval", "resume", "result"]);
+const GENERIC_PRODUCT_TOOL_FAMILIES = new Set([
+    "ls",
+    "read-file",
+    "write-file",
+    "task",
+    "glob",
+    "grep",
+    "bash",
+    "sh",
+    "cat",
+]);
 function sanitizeMermaidId(value) {
     return value.replace(/[^A-Za-z0-9_]/g, "_");
 }
@@ -25,6 +38,15 @@ function renderNode(node, mermaidId) {
             return `  ${mermaidId}["${label}"]`;
     }
 }
+function renderAgentRoot(label, mermaidId) {
+    return `  ${mermaidId}["${escapeMermaidLabel(label)}"]`;
+}
+function renderStartNode(mermaidId) {
+    return `  ${mermaidId}(("Start"))`;
+}
+function renderEndNode(mermaidId) {
+    return `  ${mermaidId}(("End"))`;
+}
 function renderEdge(edge, fromId, toId) {
     const connector = edge.kind === "retry" || edge.kind === "fallback" ? "-.->" : edge.kind === "resume" ? "==>" : "-->";
     const label = edge.label ?? edge.condition ?? (edge.kind !== "sequence" && edge.kind !== "contains" ? edge.kind : "");
@@ -48,6 +70,133 @@ function collapseEdgePath(source, target, path) {
         sourceEventIds,
     };
 }
+function nodeIdentity(node) {
+    if (node.kind === "agent") {
+        const fromAgentId = typeof node.detail.fromAgentId === "string" ? node.detail.fromAgentId : "agent";
+        const toAgentId = node.agentId ?? "agent";
+        return `${node.kind}:${fromAgentId}:${toAgentId}`;
+    }
+    return `${node.kind}:${node.agentId ?? "-"}:${node.label}`;
+}
+function findCrossAgentBridgeNodeIds(nodes, edges) {
+    const nodeById = new Map(nodes.map((node) => [node.id, node]));
+    const incidentAgentIdsByNodeId = new Map();
+    for (const edge of edges) {
+        const fromNode = nodeById.get(edge.from);
+        const toNode = nodeById.get(edge.to);
+        if (!fromNode || !toNode) {
+            continue;
+        }
+        if (toNode.agentId) {
+            let agentIds = incidentAgentIdsByNodeId.get(fromNode.id);
+            if (!agentIds) {
+                agentIds = new Set();
+                incidentAgentIdsByNodeId.set(fromNode.id, agentIds);
+            }
+            agentIds.add(toNode.agentId);
+        }
+        if (fromNode.agentId) {
+            let agentIds = incidentAgentIdsByNodeId.get(toNode.id);
+            if (!agentIds) {
+                agentIds = new Set();
+                incidentAgentIdsByNodeId.set(toNode.id, agentIds);
+            }
+            agentIds.add(fromNode.agentId);
+        }
+    }
+    const bridgeNodeIds = new Set();
+    for (const node of nodes) {
+        if (node.kind === "agent") {
+            continue;
+        }
+        const agentIds = incidentAgentIdsByNodeId.get(node.id) ?? new Set();
+        if (node.agentId) {
+            agentIds.add(node.agentId);
+        }
+        if (agentIds.size > 1) {
+            bridgeNodeIds.add(node.id);
+        }
+    }
+    return bridgeNodeIds;
+}
+function findDelegationCarrierToolNodeIds(nodes) {
+    const delegationSourceEventIds = new Set(nodes
+        .filter((node) => node.kind === "agent")
+        .flatMap((node) => node.sourceEventIds));
+    return new Set(nodes
+        .filter((node) => node.kind === "tool" && node.sourceEventIds.some((id) => delegationSourceEventIds.has(id)))
+        .map((node) => node.id));
+}
+function selectProductViewNodes(nodes) {
+    const selected = new Map();
+    for (const node of nodes) {
+        const key = nodeIdentity(node);
+        const existing = selected.get(key);
+        if (!existing) {
+            selected.set(key, node);
+            continue;
+        }
+        const existingCompleted = existing.status === "completed";
+        const nodeCompleted = node.status === "completed";
+        const preferCompleted = !existingCompleted && nodeCompleted;
+        const preserveCompleted = existingCompleted && !nodeCompleted;
+        const preferLatest = !preserveCompleted && (existing.sequenceEnd ?? 0) <= (node.sequenceEnd ?? 0);
+        if (preferCompleted || preferLatest) {
+            selected.set(key, node);
+        }
+    }
+    return [...selected.values()].sort((left, right) => (left.sequenceStart ?? 0) - (right.sequenceStart ?? 0));
+}
+function trimToolNodesForProductView(nodes, delegatingAgentIds) {
+    const keptToolKeys = new Set();
+    const orderedToolKeysByAgentId = new Map();
+    const toolKeyByNodeId = new Map();
+    const genericToolKeysByAgentId = new Map();
+    for (const node of nodes) {
+        if (node.kind !== "tool") {
+            continue;
+        }
+        const agentId = node.agentId ?? "";
+        const toolName = (() => {
+            if (typeof node.detail.toolName === "string" && node.detail.toolName.trim().length > 0) {
+                return node.detail.toolName.trim();
+            }
+            const labelMatch = /^(?:Calling|Completed) tool (.+?)(?: \[[^\]]+\])?$/i.exec(node.label);
+            return labelMatch?.[1]?.trim() || node.label;
+        })();
+        const normalizedToolName = toolName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+        const toolKey = `${agentId}:${normalizedToolName}`;
+        toolKeyByNodeId.set(node.id, toolKey);
+        if (GENERIC_PRODUCT_TOOL_FAMILIES.has(normalizedToolName)) {
+            let genericToolKeys = genericToolKeysByAgentId.get(agentId);
+            if (!genericToolKeys) {
+                genericToolKeys = new Set();
+                genericToolKeysByAgentId.set(agentId, genericToolKeys);
+            }
+            genericToolKeys.add(toolKey);
+        }
+        const toolKeys = orderedToolKeysByAgentId.get(agentId);
+        if (toolKeys) {
+            if (!toolKeys.includes(toolKey)) {
+                toolKeys.push(toolKey);
+            }
+        }
+        else {
+            orderedToolKeysByAgentId.set(agentId, [toolKey]);
+        }
+    }
+    for (const [agentId, toolKeys] of orderedToolKeysByAgentId.entries()) {
+        const genericToolKeys = genericToolKeysByAgentId.get(agentId) ?? new Set();
+        const preferredToolKeys = toolKeys.filter((toolKey) => !genericToolKeys.has(toolKey));
+        const selectedToolKeys = preferredToolKeys.length > 0
+            ? preferredToolKeys.slice(-2)
+            : delegatingAgentIds.has(agentId)
+                ? []
+                : toolKeys.slice(-2);
+        selectedToolKeys.forEach((toolKey) => keptToolKeys.add(toolKey));
+    }
+    return nodes.filter((node) => node.kind !== "tool" || keptToolKeys.has(toolKeyByNodeId.get(node.id) ?? ""));
+}
 function collectVisibleEdges(graph, visibleNodes, includedEdgeKinds) {
     const visibleNodeIds = new Set(visibleNodes.map((node) => node.id));
     const candidateEdges = graph.edges.filter((edge) => includedEdgeKinds ? includedEdgeKinds.has(edge.kind) : true);
@@ -94,30 +243,115 @@ function collectVisibleEdges(graph, visibleNodes, includedEdgeKinds) {
     }
     return visibleEdges;
 }
+function getRuntimeSurface(graph) {
+    const runtimeSurface = graph.metadata.runtimeSurface;
+    return Array.isArray(runtimeSurface) ? runtimeSurface : [];
+}
 export function exportFlowGraphToMermaid(graph, options = {}) {
     const direction = options.direction ?? "TD";
     const view = options.view ?? "product";
+    const productView = view === "product";
     const includedKinds = options.includeKinds
         ? new Set(options.includeKinds)
         : view === "debug"
             ? null
             : PRODUCT_VIEW_KINDS;
-    const includedEdgeKinds = options.includeEdgeKinds ? new Set(options.includeEdgeKinds) : null;
+    const includedEdgeKinds = options.includeEdgeKinds
+        ? new Set(options.includeEdgeKinds)
+        : view === "debug"
+            ? null
+            : new Set(PRODUCT_VIEW_EDGE_KINDS);
     const includeGroups = options.includeGroups ?? true;
     const includeDetails = options.includeDetails ?? false;
-    const nodes = graph.nodes.filter((node) => {
+    const allFilteredNodes = graph.nodes.filter((node) => {
         if (!includeDetails && node.layer === "detail") {
             return false;
         }
         return includedKinds ? includedKinds.has(node.kind) : true;
     });
+    const hiddenDelegationNodes = productView
+        ? allFilteredNodes.filter((node) => node.kind === "agent")
+        : [];
+    const delegationCarrierToolNodeIds = productView
+        ? findDelegationCarrierToolNodeIds(allFilteredNodes)
+        : new Set();
+    const delegatingAgentIds = productView
+        ? new Set(allFilteredNodes
+            .filter((node) => node.kind === "agent" && typeof node.detail.fromAgentId === "string")
+            .map((node) => node.detail.fromAgentId))
+        : new Set();
+    const filteredNodes = productView
+        ? allFilteredNodes.filter((node) => node.kind !== "agent" && !delegationCarrierToolNodeIds.has(node.id))
+        : allFilteredNodes;
+    const initiallySelectedNodes = productView
+        ? trimToolNodesForProductView(selectProductViewNodes(filteredNodes), delegatingAgentIds)
+        : filteredNodes;
+    let nodes = initiallySelectedNodes;
+    let edges = collectVisibleEdges(graph, nodes, includedEdgeKinds);
+    if (productView) {
+        const crossAgentBridgeNodeIds = findCrossAgentBridgeNodeIds(nodes, edges);
+        if (crossAgentBridgeNodeIds.size > 0) {
+            nodes = nodes.filter((node) => !crossAgentBridgeNodeIds.has(node.id));
+            edges = collectVisibleEdges(graph, nodes, includedEdgeKinds);
+        }
+    }
+    const nodeById = new Map(nodes.map((node) => [node.id, node]));
     const nodeIdSet = new Set(nodes.map((node) => node.id));
-    const edges = collectVisibleEdges(graph, nodes, includedEdgeKinds);
+    if (productView) {
+        edges = edges.filter((edge) => {
+            const fromNode = nodeById.get(edge.from);
+            const toNode = nodeById.get(edge.to);
+            if (!fromNode || !toNode) {
+                return true;
+            }
+            return !fromNode.agentId || !toNode.agentId || fromNode.agentId === toNode.agentId;
+        });
+    }
     const lines = [`flowchart ${direction}`];
     const mermaidIdByNodeId = new Map();
+    const initialAgentId = typeof graph.metadata.initialAgentId === "string" ? graph.metadata.initialAgentId : null;
+    const startNodeId = productView && initialAgentId ? "graph_start" : null;
+    const endNodeId = productView ? "graph_end" : null;
+    const agentRootIdByAgentId = new Map();
     for (const node of nodes) {
         mermaidIdByNodeId.set(node.id, sanitizeMermaidId(node.id));
     }
+    if (productView) {
+        const seenAgentIds = new Set();
+        for (const node of allFilteredNodes) {
+            const agentId = node.agentId;
+            if (!agentId || seenAgentIds.has(agentId)) {
+                // noop
+            }
+            else {
+                seenAgentIds.add(agentId);
+                agentRootIdByAgentId.set(agentId, sanitizeMermaidId(`agent_root:${agentId}`));
+            }
+            if (node.kind !== "agent") {
+                continue;
+            }
+            const fromAgentId = typeof node.detail.fromAgentId === "string" ? node.detail.fromAgentId : null;
+            if (!fromAgentId || seenAgentIds.has(fromAgentId)) {
+                continue;
+            }
+            seenAgentIds.add(fromAgentId);
+            agentRootIdByAgentId.set(fromAgentId, sanitizeMermaidId(`agent_root:${fromAgentId}`));
+        }
+    }
+    for (const [agentId, mermaidId] of agentRootIdByAgentId) {
+        const representative = nodes.find((node) => node.agentId === agentId
+            || (node.kind === "agent" && typeof node.detail.fromAgentId === "string" && node.detail.fromAgentId === agentId));
+        const representativeName = representative?.agentId === agentId
+            ? representative.agentName
+            : (typeof representative?.detail.fromAgentName === "string" ? representative.detail.fromAgentName : undefined);
+        lines.push(renderAgentRoot(representativeName ?? formatAgentName(agentId), mermaidId));
+    }
+    if (startNodeId) {
+        lines.push(renderStartNode(startNodeId));
+    }
+    if (endNodeId) {
+        lines.push(renderEndNode(endNodeId));
+    }
     if (includeGroups) {
         const groupedNodeIds = new Set();
         for (const group of graph.groups) {
@@ -150,5 +384,81 @@ export function exportFlowGraphToMermaid(graph, options = {}) {
     for (const edge of edges) {
         lines.push(renderEdge(edge, mermaidIdByNodeId.get(edge.from), mermaidIdByNodeId.get(edge.to)));
     }
+    if (productView) {
+        const handoffPairs = new Set();
+        for (const item of getRuntimeSurface(graph)) {
+            if (item.kind !== "agent") {
+                continue;
+            }
+            const fromAgentId = item.ownerAgentId ?? null;
+            const toAgentId = item.agentId ?? null;
+            if (!fromAgentId || !toAgentId) {
+                continue;
+            }
+            const fromRoot = agentRootIdByAgentId.get(fromAgentId);
+            const toRoot = agentRootIdByAgentId.get(toAgentId);
+            if (!fromRoot || !toRoot || fromRoot === toRoot) {
+                continue;
+            }
+            const pairKey = `${fromAgentId}:${toAgentId}`;
+            if (handoffPairs.has(pairKey)) {
+                // noop
+            }
+            else {
+                handoffPairs.add(pairKey);
+                lines.push(renderEdge({
+                    id: `synthetic:handoff:${pairKey}`,
+                    from: `agent_root:${fromAgentId}`,
+                    to: `agent_root:${toAgentId}`,
+                    kind: "spawn",
+                    label: "handoff",
+                    sourceEventIds: item.sourceEventId ? [item.sourceEventId] : [],
+                }, fromRoot, toRoot));
+            }
+        }
+    }
+    if (startNodeId && initialAgentId) {
+        const initialRootId = agentRootIdByAgentId.get(initialAgentId);
+        if (initialRootId) {
+            lines.push(`  ${startNodeId} --> ${initialRootId}`);
+        }
+    }
+    for (const [agentId, rootMermaidId] of agentRootIdByAgentId) {
+        const firstAgentStep = nodes.find((node) => node.agentId === agentId && node.kind !== "agent");
+        if (!firstAgentStep) {
+            continue;
+        }
+        const incomingDelegation = !productView
+            ? hiddenDelegationNodes.find((node) => node.agentId === agentId)
+            : null;
+        if (incomingDelegation) {
+            lines.push(renderEdge({
+                id: `synthetic:${incomingDelegation.id}->agent-root:${agentId}`,
+                from: incomingDelegation.id,
+                to: `agent_root:${agentId}`,
+                kind: "spawn",
+                label: "spawn",
+                sourceEventIds: [],
+            }, mermaidIdByNodeId.get(incomingDelegation.id), rootMermaidId));
+        }
+        lines.push(renderEdge({
+            id: `synthetic:agent-root:${agentId}->${firstAgentStep.id}`,
+            from: `agent_root:${agentId}`,
+            to: firstAgentStep.id,
+            kind: "sequence",
+            sourceEventIds: [],
+        }, rootMermaidId, mermaidIdByNodeId.get(firstAgentStep.id)));
+    }
+    if (endNodeId) {
+        const finalVisibleStep = [...nodes]
+            .filter((node) => node.kind !== "agent")
+            .sort((left, right) => (right.sequenceEnd ?? right.sequenceStart ?? 0) - (left.sequenceEnd ?? left.sequenceStart ?? 0))[0];
+        const finalAnchorId = finalVisibleStep
+            ? mermaidIdByNodeId.get(finalVisibleStep.id)
+            : (initialAgentId ? agentRootIdByAgentId.get(initialAgentId) : undefined);
+        if (finalAnchorId) {
+            lines.push(`  ${finalAnchorId} --> ${endNodeId}`);
+        }
+    }
     return lines.join("\n");
 }

package/dist/flow/export-sequence-mermaid.js

@@ -1,4 +1,15 @@
-const PRODUCT_VIEW_KINDS = new Set(["agent", "llm", "tool", "skill"]);
+const PRODUCT_VIEW_KINDS = new Set(["agent", "tool", "skill", "memory"]);
+const GENERIC_PRODUCT_TOOL_FAMILIES = new Set([
+    "ls",
+    "read-file",
+    "write-file",
+    "task",
+    "glob",
+    "grep",
+    "bash",
+    "sh",
+    "cat",
+]);
 function sanitizeAlias(value) {
     return value.replace(/[^A-Za-z0-9_]/g, "_");
 }
@@ -12,13 +23,99 @@ function formatAgentParticipantLabel(node) {
     }
     return `Agent:${agentId}`;
 }
+function nodeIdentity(node) {
+    if (node.kind === "agent") {
+        const fromAgentId = typeof node.detail.fromAgentId === "string" ? node.detail.fromAgentId : "agent";
+        const toAgentId = node.agentId ?? "agent";
+        return `${node.kind}:${fromAgentId}:${toAgentId}`;
+    }
+    return `${node.kind}:${node.agentId ?? "-"}:${node.label}`;
+}
+function collapseProductNodes(nodes) {
+    const selected = new Map();
+    for (const node of nodes) {
+        const key = nodeIdentity(node);
+        const existing = selected.get(key);
+        if (!existing) {
+            selected.set(key, node);
+            continue;
+        }
+        const existingCompleted = existing.status === "completed";
+        const nodeCompleted = node.status === "completed";
+        const preferCompleted = !existingCompleted && nodeCompleted;
+        const preserveCompleted = existingCompleted && !nodeCompleted;
+        const preferLatest = !preserveCompleted && (existing.sequenceEnd ?? 0) <= (node.sequenceEnd ?? 0);
+        if (preferCompleted || preferLatest) {
+            selected.set(key, node);
+        }
+    }
+    return [...selected.values()].sort((left, right) => (left.sequenceStart ?? 0) - (right.sequenceStart ?? 0));
+}
+function findDelegationCarrierToolNodeIds(nodes) {
+    const delegationSourceEventIds = new Set(nodes
+        .filter((node) => node.kind === "agent")
+        .flatMap((node) => node.sourceEventIds));
+    return new Set(nodes
+        .filter((node) => node.kind === "tool" && node.sourceEventIds.some((id) => delegationSourceEventIds.has(id)))
+        .map((node) => node.id));
+}
+function trimToolNodesForProductView(nodes, delegatingAgentIds) {
+    const keptToolKeys = new Set();
+    const orderedToolKeysByAgentId = new Map();
+    const toolKeyByNodeId = new Map();
+    const genericToolKeysByAgentId = new Map();
+    for (const node of nodes) {
+        if (node.kind !== "tool") {
+            continue;
+        }
+        const agentId = node.agentId ?? "";
+        const toolName = (() => {
+            if (typeof node.detail.toolName === "string" && node.detail.toolName.trim().length > 0) {
+                return node.detail.toolName.trim();
+            }
+            const labelMatch = /^(?:Calling|Completed) tool (.+?)(?: \[[^\]]+\])?$/i.exec(node.label);
+            return labelMatch?.[1]?.trim() || node.label;
+        })();
+        const normalizedToolName = toolName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+        const toolKey = `${agentId}:${normalizedToolName}`;
+        toolKeyByNodeId.set(node.id, toolKey);
+        if (GENERIC_PRODUCT_TOOL_FAMILIES.has(normalizedToolName)) {
+            let genericToolKeys = genericToolKeysByAgentId.get(agentId);
+            if (!genericToolKeys) {
+                genericToolKeys = new Set();
+                genericToolKeysByAgentId.set(agentId, genericToolKeys);
+            }
+            genericToolKeys.add(toolKey);
+        }
+        const toolKeys = orderedToolKeysByAgentId.get(agentId);
+        if (toolKeys) {
+            if (!toolKeys.includes(toolKey)) {
+                toolKeys.push(toolKey);
+            }
+        }
+        else {
+            orderedToolKeysByAgentId.set(agentId, [toolKey]);
+        }
+    }
+    for (const [agentId, toolKeys] of orderedToolKeysByAgentId.entries()) {
+        const genericToolKeys = genericToolKeysByAgentId.get(agentId) ?? new Set();
+        const preferredToolKeys = toolKeys.filter((toolKey) => !genericToolKeys.has(toolKey));
+        const selectedToolKeys = preferredToolKeys.length > 0
+            ? preferredToolKeys.slice(-2)
+            : delegatingAgentIds.has(agentId)
+                ? []
+                : toolKeys.slice(-2);
+        selectedToolKeys.forEach((toolKey) => keptToolKeys.add(toolKey));
+    }
+    return nodes.filter((node) => node.kind !== "tool" || keptToolKeys.has(toolKeyByNodeId.get(node.id) ?? ""));
+}
 function selectNodes(graph, options) {
     const includedKinds = options.includeKinds
         ? new Set(options.includeKinds)
         : options.view === "debug"
             ? null
             : PRODUCT_VIEW_KINDS;
-    return graph.nodes.filter((node) => {
+    const filtered = graph.nodes.filter((node) => {
         if (node.layer === "detail") {
             return false;
         }
@@ -32,8 +129,19 @@ function selectNodes(graph, options) {
             || node.kind === "llm"
             || node.kind === "tool"
             || node.kind === "skill"
+            || node.kind === "memory"
             || node.kind === "artifact";
     });
+    if (options.view === "debug") {
+        return filtered;
+    }
+    const collapsedNodes = collapseProductNodes(filtered);
+    const delegationCarrierToolNodeIds = findDelegationCarrierToolNodeIds(collapsedNodes);
+    const delegatingAgentIds = new Set(collapsedNodes
+        .filter((node) => node.kind === "agent" && typeof node.detail.fromAgentId === "string")
+        .map((node) => node.detail.fromAgentId));
+    const productNodes = collapsedNodes.filter((node) => node.kind === "agent" || !delegationCarrierToolNodeIds.has(node.id));
+    return trimToolNodesForProductView(productNodes, delegatingAgentIds);
 }
 function getParticipantsForNode(node) {
     const runtimeParticipant = { id: "runtime", alias: "Runtime", label: "Runtime" };
@@ -90,6 +198,12 @@ function getParticipantsForNode(node) {
             { id: "skill", alias: "Skill", label: "Skill" },
         ];
     }
+    if (node.kind === "memory") {
+        return [
+            agentParticipant,
+            { id: "memory", alias: "Memory", label: "Memory" },
+        ];
+    }
     if (node.kind === "recovery") {
         return [
             runtimeParticipant,
@@ -152,13 +266,26 @@ function renderArrowForNode(node) {
             dashed: node.status === "completed" || node.status === "failed",
         };
     }
+    if (node.kind === "memory") {
+        return {
+            from: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            to: "Memory",
+            text: node.label,
+            dashed: node.status === "completed" || node.status === "failed",
+        };
+    }
     if (node.kind === "artifact") {
         return { from: "Runtime", to: "ArtifactStore", text: node.label };
     }
     return { from: "Runtime", to: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`), text: node.label };
 }
+function getRuntimeSurface(graph) {
+    const runtimeSurface = graph.metadata.runtimeSurface;
+    return Array.isArray(runtimeSurface) ? runtimeSurface : [];
+}
 export function exportFlowGraphToSequenceMermaid(graph, options = {}) {
     const nodes = selectNodes(graph, options);
+    const productView = (options.view ?? "product") === "product";
     const lines = ["sequenceDiagram"];
     const participants = new Map();
     for (const node of nodes) {
@@ -174,5 +301,25 @@ export function exportFlowGraphToSequenceMermaid(graph, options = {}) {
         const connector = arrow.dashed ? "-->>" : "->>";
         lines.push(`  ${arrow.from}${connector}${arrow.to}: ${escapeLabel(node.label)}`);
     }
+    if (productView) {
+        const seenReturnPairs = new Set();
+        for (const item of getRuntimeSurface(graph)) {
+            if (item.kind !== "agent" || item.status !== "completed") {
+                continue;
+            }
+            const fromAgentId = item.ownerAgentId ?? null;
+            const toAgentId = item.agentId ?? null;
+            if (!fromAgentId || !toAgentId) {
+                continue;
+            }
+            const pairKey = `${fromAgentId}:${toAgentId}`;
+            if (seenReturnPairs.has(pairKey)) {
+                continue;
+            }
+            seenReturnPairs.add(pairKey);
+            const fromAgentName = item.ownerAgentName ?? fromAgentId;
+            lines.push(`  ${sanitizeAlias(`Agent_${toAgentId}`)}-->>${sanitizeAlias(`Agent_${fromAgentId}`)}: Return to ${escapeLabel(fromAgentName)}`);
+        }
+    }
     return lines.join("\n");
 }

package/dist/flow/types.d.ts

@@ -1,5 +1,15 @@
 import type { HarnessEvent, RuntimeTimelineItem } from "../contracts/types.js";
 import type { UpstreamTimelineProjection } from "../upstream-events.js";
+export type BuildFlowGraphRuntimeEvent = HarnessEvent | {
+    eventId: string;
+    eventType: string;
+    timestamp: string;
+    sessionId: string;
+    requestId: string;
+    sequence: number;
+    source: "runtime" | "policy" | "surface" | "worker" | (string & {});
+    payload: Record<string, unknown>;
+};
 export type FlowNodeLayer = "runtime" | "execution" | "attempt" | "detail";
 export type FlowNodeKind = "run" | "agent" | "queue" | "approval" | "recovery" | "artifact" | "llm" | "tool" | "skill" | "memory" | "chain" | "result" | "thinking" | "other";
 export type FlowNodeStatus = "pending" | "started" | "completed" | "failed" | "waiting" | "resolved" | "skipped";
@@ -62,7 +72,7 @@ export type BuildFlowGraphInput = {
     threadId?: string;
     runId?: string;
     scope?: FlowGraph["scope"];
-    runtimeEvents?: readonly HarnessEvent[];
+    runtimeEvents?: readonly BuildFlowGraphRuntimeEvent[];
     runtimeTimeline?: readonly RuntimeTimelineItem[];
     upstreamEvents?: readonly unknown[];
     upstreamProjections?: readonly UpstreamTimelineProjection[];

package/dist/index.d.ts

@@ -1,7 +1,6 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRun, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportFlow, exportSequence, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequest, getHealth, listMemories, listRequestTraceItems, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, AcpStdioClient, AcpStdioClientOptions, } from "./acp.js";
-export type { Approval, ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, OperatorOverview, PublicRunListeners, RequestArtifactListing, RequestEvent, RequestEventType, RequestPackage, RequestPackageInput, RequestResult, RequestUpstreamEventItem, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, SessionListSummary, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
-export type { BuildFlowGraphInput, FlowEdge, FlowEdgeKind, FlowGraph, FlowGraphMermaidOptions, FlowGraphSequenceMermaidOptions, FlowGroup, FlowGroupKind, FlowNode, FlowNodeKind, FlowNodeLayer, FlowNodeStatus, } from "./flow/index.js";
+export type { Approval, ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, OperatorOverview, PublicRunListeners, RequestArtifactListing, RequestEvent, RequestEventType, RequestPackage, RequestPackageInput, RequestFlowGraphInput, RequestResult, RequestTraceItem, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, SessionListSummary, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
 export type { A2aAgentCard, A2aHttpServer, A2aHttpServerOptions, A2aTask, A2aTaskState, AcpHttpServer, AcpHttpServerOptions, AcpStdioServer, AcpStdioServerOptions, AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput, } from "./api.js";
 export type { RuntimeMcpServerOptions, ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRun, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportFlow, exportSequence, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequest, getHealth, listMemories, listRequestTraceItems, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.250";
+export declare const AGENT_HARNESS_VERSION = "0.0.252";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.250";
+export const AGENT_HARNESS_VERSION = "0.0.252";

package/dist/persistence/file-store.d.ts

@@ -15,6 +15,7 @@ export declare class FilePersistence implements RuntimePersistence {
     private approvalIndexPath;
     private runQueuePath;
     private runControlPath;
+    private traceItemsPath;
     initialize(): Promise<void>;
     threadDir(threadId: string): string;
     runDir(threadId: string, runId: string): string;
@@ -61,9 +62,9 @@ export declare class FilePersistence implements RuntimePersistence {
         currentAgentId?: string | null;
         delegationChain?: string[];
         runtimeSnapshot?: RunSummary["runtimeSnapshot"] | null;
-        upstreamEvents?: unknown[];
-        appendUpstreamEvent?: unknown;
     }): Promise<void>;
+    appendRunTraceItem(threadId: string, runId: string, item: unknown): Promise<void>;
+    listRunTraceItems(threadId: string, runId: string): Promise<unknown[]>;
     deleteThread(threadId: string): Promise<boolean>;
     saveRunRequest(threadId: string, runId: string, request: PersistedRunRequest): Promise<void>;
     getRunRequest(threadId: string, runId: string): Promise<PersistedRunRequest | null>;