@botbotgo/agent-harness 0.0.157 → 0.0.158

package/README.md

@@ -450,10 +450,18 @@ const result = await run(runtime, {
     onEvent(event) {
       console.log(event.eventType, event.payload);
     },
+    onUpstreamEvent(event) {
+      console.log("raw upstream event", event);
+    },
+    onUpstreamItem(item) {
+      console.log("upstream agent", item.agentId, item.event);
+    },
   },
 });
 ```
 
+`onUpstreamEvent(...)` preserves the raw upstream event payload. `onUpstreamItem(...)` adds runtime correlation metadata such as `threadId`, `runId`, and the current `agentId`, which is useful for flow-graph capture and delegated sub-agent inspection.
+
 `subscribe(...)` is the read-only observer surface over stored lifecycle events.
 
 The runtime event stream includes:
@@ -563,8 +571,14 @@ Discovery rules:
 - local tools are auto-discovered from `resources/tools/**/*.js|*.mjs|*.cjs` when they export `tool({...})`
 - skills are auto-discovered from `resources/skills/**/SKILL.md`
 
+Example workspaces:
+
+- `examples/hello-skill-app/` keeps the smallest local tool + skill workspace
+- `examples/runtime-flow-demo/` runs one real hosted-model request and exports a Mermaid flowchart from runtime plus upstream events
+
 Workspace-local tool modules in `resources/tools/` should be exported with `tool({...})`.
 Any other local module shape is not supported, and unsupported shapes are rejected at load time.
+When local tools use Zod-authored schemas, keep the workspace or isolated `resources` package on `zod@^4` so raw-shape validators and runtime parsing stay on one supported major version.
 
 Default wiring guidance:
 
@@ -872,3 +886,16 @@ Primary exports:
 - `createToolMcpServer`
 - `serveToolsOverStdio`
 - `stop`
+- `createUpstreamTimelineReducer`
+- `buildFlowGraph`
+- `exportFlowGraphToMermaid`
+- `exportFlowGraphToSequenceMermaid`
+
+Inspection helpers:
+
+- `createUpstreamTimelineReducer()` reduces raw upstream model/tool/chain events into ordered step-like projections for inspection and visualization.
+- `buildFlowGraph(...)` combines persisted runtime timeline items with optional upstream projections into a detailed flow graph utility shape, including best-effort delegated subagent transitions when raw upstream events are available.
+- `exportFlowGraphToMermaid(...)` renders that inspection graph as Mermaid flowchart text. By default it emits the product view: agent and sub-agent delegation plus user-defined model, tool, and skill calls. Use `view: "debug"` to include runtime inspection detail.
+- `exportFlowGraphToSequenceMermaid(...)` renders the same inspection graph as a Mermaid sequence diagram. By default it emits only user-defined participants and calls, while `view: "debug"` includes runtime participants and lifecycle messages.
+
+These helpers are visualization and inspection utilities. They do not introduce a canonical harness-owned execution protocol.

package/README.zh.md

@@ -535,8 +535,14 @@ await stop(runtime);
 - 本地工具会从 `resources/tools/**/*.js|*.mjs|*.cjs` 中自动发现，前提是模块导出 `tool({...})`
 - skills 会从 `resources/skills/**/SKILL.md` 自动发现
 
+示例工作区：
+
+- `examples/hello-skill-app/` 保留最小的本地 tool + skill 工作区
+- `examples/runtime-flow-demo/` 会跑一次真实 hosted model 请求，并把 runtime 与 upstream events 导出为 Mermaid flowchart
+
 `resources/tools/` 下的工作区本地工具模块应统一用 `tool({...})` 导出。
 不支持历史/兼容写法，任何不带该导出形式的工具模块都会在工作区加载时被拒绝。
+若本地工具使用 Zod schema，请让工作区或隔离的 `resources` 包统一使用 `zod@^4`，避免 raw shape validator 与 runtime 解析落在不同 major 版本上。
 
 主要有三层配置：
 
@@ -839,3 +845,16 @@ spec:
 - `createToolMcpServer`
 - `serveToolsOverStdio`
 - `stop`
+- `createUpstreamTimelineReducer`
+- `buildFlowGraph`
+- `exportFlowGraphToMermaid`
+- `exportFlowGraphToSequenceMermaid`
+
+Inspection 辅助工具：
+
+- `createUpstreamTimelineReducer()` 可把上游 model/tool/chain 原始事件归约成有序的 step-like 投影，便于检查和可视化。
+- `buildFlowGraph(...)` 可把持久化 runtime timeline 与可选的 upstream projections 组合成详细 flow graph utility 数据结构；当提供原始 upstream events 时，也会尽力补出 subagent delegation 转移。
+- `exportFlowGraphToMermaid(...)` 可把该 inspection graph 导出为 Mermaid flowchart 文本。默认输出 product 视图，只保留 agent / sub-agent delegation 以及用户定义的 model、tool、skill 调用；传 `view: "debug"` 才会带上 runtime 检查细节。
+- `exportFlowGraphToSequenceMermaid(...)` 可把同一份 inspection graph 导出为 Mermaid sequence diagram。默认只输出用户定义的参与者与调用；传 `view: "debug"` 才会包含 runtime participant 与生命周期消息。
+
+这些 helper 只用于可视化与检查，不代表新的 harness 官方执行协议。

package/dist/api.d.ts

@@ -6,6 +6,7 @@ import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessAcpServer, createAcpServer } from "./acp.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, } from "./acp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
+export { buildFlowGraph, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid } from "./flow/index.js";
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
 export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, UpdateMemoryInput, } from "./contracts/types.js";
 type PublicApprovalRecord = {

package/dist/api.js

@@ -3,6 +3,7 @@ import { normalizeMessageContent } from "./utils/message-content.js";
 import { loadWorkspace } from "./workspace/compile.js";
 export { AgentHarnessAcpServer, createAcpServer } from "./acp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
+export { buildFlowGraph, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid } from "./flow/index.js";
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
 function toSessionSummary(summary) {
     return {

package/dist/contracts/runtime.d.ts

@@ -335,9 +335,16 @@ export type RunResult = {
     metadata?: Record<string, unknown>;
 };
 export type UpstreamRuntimeEvent = unknown;
+export type UpstreamRuntimeEventItem = {
+    threadId: string;
+    runId: string;
+    agentId: string;
+    event: UpstreamRuntimeEvent;
+};
 export type RuntimeListeners = {
     onEvent?: (event: HarnessEvent) => void | Promise<void>;
     onUpstreamEvent?: (event: UpstreamRuntimeEvent) => void | Promise<void>;
+    onUpstreamItem?: (item: UpstreamRuntimeEventItem) => void | Promise<void>;
 };
 export type RunListeners = RuntimeListeners;
 export type MessageContentPart = {

package/dist/flow/build-flow-graph.d.ts

@@ -0,0 +1,2 @@
+import type { BuildFlowGraphInput, FlowGraph } from "./types.js";
+export declare function buildFlowGraph(input: BuildFlowGraphInput): FlowGraph;

package/dist/flow/build-flow-graph.js

@@ -0,0 +1,737 @@
+import { projectRuntimeTimeline } from "../runtime/harness/events/timeline.js";
+import { createUpstreamTimelineReducer } from "../upstream-events.js";
+function asObject(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function extractUpstreamEventEnvelope(value) {
+    const typed = asObject(value);
+    const nestedEvent = typed && Object.prototype.hasOwnProperty.call(typed, "event") ? typed.event : undefined;
+    const event = typed
+        && nestedEvent
+        && typeof nestedEvent === "object"
+        && !Array.isArray(nestedEvent)
+        && Object.prototype.hasOwnProperty.call(typed, "agentId")
+        ? nestedEvent
+        : value;
+    const agentId = readString(typed?.agentId);
+    return { event, agentId: agentId ?? undefined };
+}
+function collectNestedAgentNames(value, names = new Set()) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectNestedAgentNames(item, names);
+        }
+        return names;
+    }
+    const typed = asObject(value);
+    if (!typed) {
+        return names;
+    }
+    const idParts = Array.isArray(typed.id) ? typed.id.filter((item) => typeof item === "string") : [];
+    const kwargs = asObject(typed.kwargs);
+    const kwargsName = idParts.includes("AIMessage") ? readString(kwargs?.name) : null;
+    if (kwargsName && kwargsName !== "assistant") {
+        names.add(kwargsName);
+    }
+    for (const nested of Object.values(typed)) {
+        collectNestedAgentNames(nested, names);
+    }
+    return names;
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || "node";
+}
+function titleCase(value) {
+    return value
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .split(" ")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function normalizeLabel(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function readProjectionLabel(projection) {
+    if (projection.type === "step") {
+        return projection.step;
+    }
+    if (projection.type === "tool-result") {
+        return `Tool result ${titleCase(projection.toolName)}`;
+    }
+    return projection.text;
+}
+function deriveNodeKindFromProjection(projection) {
+    if (projection.type === "tool-result") {
+        return "result";
+    }
+    if (projection.type === "thinking") {
+        return "thinking";
+    }
+    return projection.category;
+}
+function deriveStatusFromProjection(projection) {
+    if (projection.type === "thinking" || projection.type === "tool-result") {
+        return "completed";
+    }
+    return projection.category === "approval" && projection.status === "started" ? "waiting" : projection.status;
+}
+function deriveRuntimeNode(input) {
+    if (input.eventType === "run.created") {
+        return {
+            kind: "run",
+            status: "started",
+            label: "Run created",
+            detail: input.payload,
+        };
+    }
+    if (input.eventType === "run.queued") {
+        return {
+            kind: "queue",
+            status: "waiting",
+            label: "Queued",
+            detail: input.payload,
+        };
+    }
+    if (input.eventType === "run.dequeued") {
+        return {
+            kind: "queue",
+            status: "completed",
+            label: "Dequeued",
+            detail: input.payload,
+        };
+    }
+    if (input.eventType === "approval.requested") {
+        return {
+            kind: "approval",
+            status: "waiting",
+            label: "Approval requested",
+            detail: input.payload,
+        };
+    }
+    if (input.eventType === "approval.resolved") {
+        return {
+            kind: "approval",
+            status: "resolved",
+            label: "Approval resolved",
+            detail: input.payload,
+        };
+    }
+    if (input.eventType === "run.resumed") {
+        return {
+            kind: "recovery",
+            status: "completed",
+            label: "Run resumed",
+            detail: input.payload,
+        };
+    }
+    if (input.eventType === "artifact.created") {
+        return {
+            kind: "artifact",
+            status: "completed",
+            label: "Artifact created",
+            detail: input.payload,
+        };
+    }
+    if (input.eventType === "run.state.changed") {
+        const state = typeof input.payload.state === "string" ? input.payload.state : "";
+        if (state === "waiting_for_approval") {
+            return {
+                kind: "approval",
+                status: "waiting",
+                label: "Waiting for approval",
+                detail: input.payload,
+            };
+        }
+        if (state === "failed") {
+            return {
+                kind: "run",
+                status: "failed",
+                label: "Run failed",
+                detail: input.payload,
+            };
+        }
+        if (state === "completed") {
+            return {
+                kind: "run",
+                status: "completed",
+                label: "Run completed",
+                detail: input.payload,
+            };
+        }
+        return {
+            kind: "run",
+            status: "started",
+            label: state ? `Run ${state}` : "Run state changed",
+            detail: input.payload,
+        };
+    }
+    return {
+        kind: input.kind,
+        status: "completed",
+        label: input.eventType,
+        detail: input.payload,
+    };
+}
+function buildRuntimeNodes(timeline) {
+    const nodes = [];
+    const edges = [];
+    const groups = [];
+    let previousNode = null;
+    let segmentOrdinal = 0;
+    let approvalOrdinal = 0;
+    let activeExecutionGroup = null;
+    let activeApprovalGroup = null;
+    for (const item of timeline) {
+        const mapped = deriveRuntimeNode(item);
+        const node = {
+            id: `rt:${item.runId}:${item.sequence}:${slugify(item.eventType)}`,
+            layer: "runtime",
+            kind: mapped.kind,
+            label: mapped.label,
+            status: mapped.status,
+            threadId: item.threadId,
+            runId: item.runId,
+            startedAt: item.timestamp,
+            endedAt: item.timestamp,
+            sequenceStart: item.sequence,
+            sequenceEnd: item.sequence,
+            sourceEventIds: [item.eventId],
+            detail: { ...mapped.detail, eventType: item.eventType, source: item.source },
+        };
+        nodes.push(node);
+        if (previousNode) {
+            const kind = item.eventType === "approval.resolved"
+                ? "approval"
+                : item.eventType === "run.resumed"
+                    ? "resume"
+                    : "sequence";
+            edges.push({
+                id: `edge:${previousNode.id}->${node.id}`,
+                from: previousNode.id,
+                to: node.id,
+                kind,
+                ...(kind === "approval" ? { label: typeof item.payload.decision === "string" ? item.payload.decision : "resolved" } : {}),
+                sourceEventIds: [previousNode.sourceEventIds[0], item.eventId],
+            });
+        }
+        previousNode = node;
+        if (item.eventType === "run.created" || item.eventType === "run.dequeued" || item.eventType === "run.resumed") {
+            segmentOrdinal += 1;
+            activeExecutionGroup = {
+                id: `group:${item.runId}:segment:${segmentOrdinal}`,
+                kind: "segment",
+                label: item.eventType === "run.created"
+                    ? `Execution segment ${segmentOrdinal}`
+                    : item.eventType === "run.resumed"
+                        ? `Resumed segment ${segmentOrdinal}`
+                        : `Dequeued segment ${segmentOrdinal}`,
+                nodeIds: [node.id],
+                startedAt: item.timestamp,
+                anchorNodeId: node.id,
+            };
+            groups.push(activeExecutionGroup);
+            activeApprovalGroup = null;
+            node.groupId = activeExecutionGroup.id;
+            continue;
+        }
+        if (item.eventType === "approval.requested") {
+            approvalOrdinal += 1;
+            activeApprovalGroup = {
+                id: `group:${item.runId}:approval:${approvalOrdinal}`,
+                kind: "approval-window",
+                label: `Approval window ${approvalOrdinal}`,
+                nodeIds: [node.id],
+                startedAt: item.timestamp,
+                anchorNodeId: node.id,
+            };
+            groups.push(activeApprovalGroup);
+            node.groupId = activeApprovalGroup.id;
+            continue;
+        }
+        if (item.eventType === "approval.resolved") {
+            if (!activeApprovalGroup) {
+                approvalOrdinal += 1;
+                activeApprovalGroup = {
+                    id: `group:${item.runId}:approval:${approvalOrdinal}`,
+                    kind: "approval-window",
+                    label: `Approval window ${approvalOrdinal}`,
+                    nodeIds: [],
+                    anchorNodeId: node.id,
+                };
+                groups.push(activeApprovalGroup);
+            }
+            activeApprovalGroup.nodeIds.push(node.id);
+            activeApprovalGroup.endedAt = item.timestamp;
+            node.groupId = activeApprovalGroup.id;
+            continue;
+        }
+        if (activeApprovalGroup && !activeApprovalGroup.endedAt) {
+            activeApprovalGroup.nodeIds.push(node.id);
+            node.groupId = activeApprovalGroup.id;
+            continue;
+        }
+        if (activeExecutionGroup) {
+            activeExecutionGroup.nodeIds.push(node.id);
+            activeExecutionGroup.endedAt = item.timestamp;
+            node.groupId = activeExecutionGroup.id;
+        }
+    }
+    return { nodes, edges, groups };
+}
+function normalizeAttemptLabel(kind, projection) {
+    if (projection.type === "step") {
+        const label = normalizeLabel(projection.step);
+        if (label) {
+            return label;
+        }
+    }
+    if (projection.type === "tool-result") {
+        return `Tool ${titleCase(projection.toolName)}`;
+    }
+    if (projection.type === "thinking") {
+        return "Model reasoning";
+    }
+    return titleCase(kind);
+}
+function semanticNameFromLabel(kind, label) {
+    const normalized = normalizeLabel(label)
+        .replace(/^Calling LLM\s+/i, "")
+        .replace(/^Completed LLM\s+/i, "")
+        .replace(/^Calling tool\s+/i, "")
+        .replace(/^Completed tool\s+/i, "")
+        .replace(/^Tool\s+/i, "")
+        .replace(/\s+failed$/i, "")
+        .replace(/^Calling skill\s+/i, "")
+        .replace(/^Completed skill\s+/i, "")
+        .replace(/^Accessing memory\s+/i, "")
+        .replace(/^Completed memory\s+/i, "")
+        .replace(/^Running\s+/i, "")
+        .replace(/^Completed\s+/i, "");
+    return `${kind}:${normalized.toLowerCase()}`;
+}
+function normalizeToolIdentity(value) {
+    return value
+        .toLowerCase()
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function buildAttemptKey(kind, label, groupId) {
+    return `${semanticNameFromLabel(kind, label)}:${groupId ?? "ungrouped"}`;
+}
+function deriveInitialAgentId(input, runtimeTimeline) {
+    const candidate = runtimeTimeline.find((item) => {
+        const payload = asObject(item.payload);
+        return typeof payload?.agentId === "string" && payload.agentId.trim().length > 0;
+    });
+    const payload = candidate ? asObject(candidate.payload) : null;
+    const metadataAgentId = typeof input.metadata?.currentAgentId === "string" ? input.metadata.currentAgentId : null;
+    if (metadataAgentId && metadataAgentId.trim().length > 0) {
+        return metadataAgentId.trim();
+    }
+    if (payload?.agentId && typeof payload.agentId === "string" && payload.agentId.trim().length > 0) {
+        return payload.agentId.trim();
+    }
+    return "agent";
+}
+function extractDelegatedAgentId(event) {
+    const typed = asObject(event);
+    if (!typed) {
+        return null;
+    }
+    const eventName = typeof typed.event === "string" ? typed.event : "";
+    const toolName = typeof typed.name === "string" ? typed.name : "";
+    if (toolName !== "task" || (eventName !== "on_tool_start" && !(eventName === "on_chain_start" && typed.run_type === "tool"))) {
+        return null;
+    }
+    const data = asObject(typed.data);
+    const input = asObject(data?.input);
+    const subagentType = typeof input?.subagent_type === "string"
+        ? input.subagent_type
+        : typeof input?.subagentType === "string"
+            ? input.subagentType
+            : null;
+    return subagentType && subagentType.trim().length > 0 ? subagentType.trim() : null;
+}
+function extractAgentFromNestedMessages(event, currentAgentId) {
+    const typed = asObject(event);
+    if (!typed) {
+        return null;
+    }
+    const data = asObject(typed.data);
+    const input = asObject(data?.input);
+    const output = asObject(data?.output);
+    const names = new Set();
+    collectNestedAgentNames(input?.messages, names);
+    collectNestedAgentNames(output?.messages, names);
+    return [...names].find((name) => name !== currentAgentId) ?? null;
+}
+function convertUpstreamEventsWithAgents(upstreamEvents, initialAgentId) {
+    const reducer = createUpstreamTimelineReducer();
+    const projections = [];
+    const delegationNodes = [];
+    let currentAgentId = initialAgentId;
+    let ordinal = 0;
+    upstreamEvents.forEach((event, index) => {
+        const sourceEventId = `upstream:${index + 1}`;
+        const envelope = extractUpstreamEventEnvelope(event);
+        if (envelope.agentId && envelope.agentId !== currentAgentId) {
+            currentAgentId = envelope.agentId;
+        }
+        const nestedAgentId = extractAgentFromNestedMessages(envelope.event, currentAgentId);
+        if (nestedAgentId && nestedAgentId !== currentAgentId) {
+            ordinal += 1;
+            delegationNodes.push({
+                id: `delegate:${slugify(currentAgentId)}:${slugify(nestedAgentId)}:${ordinal}`,
+                layer: "execution",
+                kind: "agent",
+                label: `Delegate to ${titleCase(nestedAgentId)}`,
+                status: "completed",
+                threadId: "",
+                runId: "",
+                agentId: nestedAgentId,
+                sourceEventIds: [sourceEventId],
+                detail: {
+                    fromAgentId: currentAgentId,
+                    toAgentId: nestedAgentId,
+                },
+            });
+            currentAgentId = nestedAgentId;
+        }
+        const emitted = reducer.consume(envelope.event);
+        for (const projection of emitted) {
+            projections.push({
+                projection,
+                agentId: currentAgentId,
+                sourceEventId,
+            });
+        }
+        const delegatedAgentId = extractDelegatedAgentId(envelope.event);
+        if (!delegatedAgentId || delegatedAgentId === currentAgentId) {
+            return;
+        }
+        ordinal += 1;
+        delegationNodes.push({
+            id: `delegate:${slugify(initialAgentId)}:${slugify(delegatedAgentId)}:${ordinal}`,
+            layer: "execution",
+            kind: "agent",
+            label: `Delegate to ${titleCase(delegatedAgentId)}`,
+            status: "completed",
+            threadId: "",
+            runId: "",
+            agentId: delegatedAgentId,
+            sourceEventIds: [sourceEventId],
+            detail: {
+                fromAgentId: currentAgentId,
+                toAgentId: delegatedAgentId,
+            },
+        });
+        currentAgentId = delegatedAgentId;
+    });
+    return { projections, delegationNodes };
+}
+function selectInitialGroup(groups) {
+    return groups.find((group) => group.kind === "segment") ?? groups[0] ?? null;
+}
+function buildAttempts(projectionRecords, delegationNodes, runtimeGroups, threadId, runId) {
+    const nodes = [];
+    const edges = [];
+    const groups = [];
+    const attempts = [];
+    const activeAttemptsByKey = new Map();
+    const toolAttemptsByName = new Map();
+    const attemptSetGroups = new Map();
+    let currentGroup = selectInitialGroup(runtimeGroups);
+    let awaitingResumeAfterApproval = false;
+    let previousAttempt = null;
+    let ordinal = 0;
+    let pendingDelegationNode = null;
+    let delegationIndex = 0;
+    const segmentGroups = runtimeGroups.filter((group) => group.kind === "segment");
+    let nextSegmentIndex = currentGroup && currentGroup.kind === "segment"
+        ? Math.max(segmentGroups.findIndex((group) => group.id === currentGroup?.id), 0)
+        : 0;
+    function promoteToNextSegment() {
+        if (nextSegmentIndex + 1 < segmentGroups.length) {
+            nextSegmentIndex += 1;
+            currentGroup = segmentGroups[nextSegmentIndex] ?? currentGroup;
+        }
+    }
+    function createAttempt(kind, label, projection, agentId) {
+        ordinal += 1;
+        const attempt = {
+            id: `attempt:${runId}:${slugify(kind)}:${slugify(label)}:${ordinal}`,
+            kind,
+            label,
+            status: deriveStatusFromProjection(projection),
+            agentId,
+            groupId: currentGroup?.id,
+            sourceEventIds: [],
+            attemptKey: buildAttemptKey(kind, label, currentGroup?.id),
+            detail: {},
+            projectionKeys: [],
+            ...(projection.type === "tool-result" ? { toolName: projection.toolName } : {}),
+        };
+        attempts.push(attempt);
+        if (kind === "tool" || (projection.type === "tool-result" && projection.toolName)) {
+            const toolName = projection.type === "tool-result"
+                ? normalizeToolIdentity(projection.toolName)
+                : normalizeToolIdentity(semanticNameFromLabel("tool", label).replace(/^tool:/, ""));
+            const existing = toolAttemptsByName.get(toolName) ?? [];
+            if (existing.length > 0) {
+                const prior = existing[existing.length - 1];
+                const edgeKind = prior.status === "failed" ? "retry" : "fallback";
+                edges.push({
+                    id: `edge:${prior.id}->${attempt.id}`,
+                    from: prior.id,
+                    to: attempt.id,
+                    kind: edgeKind,
+                    sourceEventIds: [],
+                    confidence: 0.55,
+                });
+            }
+            existing.push(attempt);
+            toolAttemptsByName.set(toolName, existing);
+        }
+        return attempt;
+    }
+    for (const record of projectionRecords) {
+        const projection = record.projection;
+        if (previousAttempt
+            && previousAttempt.agentId
+            && record.agentId !== previousAttempt.agentId
+            && delegationIndex < delegationNodes.length) {
+            const sourceNode = delegationNodes[delegationIndex];
+            delegationIndex += 1;
+            pendingDelegationNode = {
+                ...sourceNode,
+                threadId,
+                runId,
+                groupId: currentGroup?.id,
+            };
+            nodes.push(pendingDelegationNode);
+            edges.push({
+                id: `edge:${previousAttempt.id}->${pendingDelegationNode.id}`,
+                from: previousAttempt.id,
+                to: pendingDelegationNode.id,
+                kind: "spawn",
+                label: "delegate",
+                sourceEventIds: [...pendingDelegationNode.sourceEventIds],
+                confidence: 0.9,
+            });
+        }
+        if (projection.type === "thinking") {
+            ordinal += 1;
+            const detailNode = {
+                id: `detail:${runId}:thinking:${ordinal}`,
+                layer: "detail",
+                kind: "thinking",
+                label: "Model reasoning",
+                status: "completed",
+                threadId,
+                runId,
+                groupId: currentGroup?.id,
+                sourceEventIds: [],
+                detail: { text: projection.text },
+            };
+            nodes.push(detailNode);
+            if (previousAttempt) {
+                edges.push({
+                    id: `edge:${previousAttempt.id}->${detailNode.id}`,
+                    from: previousAttempt.id,
+                    to: detailNode.id,
+                    kind: "result",
+                    sourceEventIds: [],
+                    confidence: 0.6,
+                });
+            }
+            continue;
+        }
+        const kind = deriveNodeKindFromProjection(projection);
+        const label = normalizeAttemptLabel(kind, projection);
+        if (kind === "approval") {
+            const activeApproval = runtimeGroups.find((group) => group.kind === "approval-window");
+            if (activeApproval) {
+                currentGroup = activeApproval;
+            }
+            awaitingResumeAfterApproval = true;
+        }
+        else if (awaitingResumeAfterApproval && currentGroup?.kind === "approval-window") {
+            promoteToNextSegment();
+            awaitingResumeAfterApproval = false;
+        }
+        const attemptKey = buildAttemptKey(kind, label, currentGroup?.id);
+        let attempt;
+        if (projection.type === "step" && projection.status === "started") {
+            attempt = createAttempt(kind, label, projection, record.agentId);
+            activeAttemptsByKey.set(attemptKey, attempt);
+        }
+        else if (projection.type === "tool-result") {
+            const toolName = normalizeToolIdentity(projection.toolName);
+            const existing = toolAttemptsByName.get(toolName) ?? [];
+            attempt = [...existing].reverse().find((candidate) => candidate.groupId === currentGroup?.id) ?? existing[existing.length - 1];
+            if (!attempt) {
+                attempt = createAttempt("tool", `Calling tool ${titleCase(toolName)}`, projection, record.agentId);
+            }
+        }
+        else {
+            attempt = activeAttemptsByKey.get(attemptKey);
+            if (!attempt) {
+                attempt = createAttempt(kind, label, projection, record.agentId);
+            }
+        }
+        attempt.agentId = attempt.agentId ?? record.agentId;
+        attempt.projectionKeys.push(projection.key);
+        attempt.sourceEventIds.push(record.sourceEventId);
+        if (projection.type === "step") {
+            attempt.status = deriveStatusFromProjection(projection);
+            attempt.detail.category = projection.category;
+            attempt.detail.step = projection.step;
+        }
+        else if (projection.type === "tool-result") {
+            attempt.status = projection.isError ? "failed" : "completed";
+            attempt.toolName = projection.toolName;
+            attempt.detail.toolName = projection.toolName;
+            attempt.detail.result = projection.output;
+            attempt.detail.resultIsError = projection.isError === true;
+            if (projection.isError) {
+                activeAttemptsByKey.delete(buildAttemptKey("tool", attempt.label, attempt.groupId));
+            }
+        }
+        if (!attemptSetGroups.has(`${kind}:${currentGroup?.id ?? "ungrouped"}`)) {
+            attemptSetGroups.set(`${kind}:${currentGroup?.id ?? "ungrouped"}`, {
+                id: `group:${runId}:attempt-set:${slugify(kind)}:${attemptSetGroups.size + 1}`,
+                kind: "attempt-set",
+                label: `${titleCase(kind)} attempts`,
+                nodeIds: [],
+            });
+        }
+        const attemptGroup = attemptSetGroups.get(`${kind}:${currentGroup?.id ?? "ungrouped"}`);
+        if (!attemptGroup.nodeIds.includes(attempt.id)) {
+            attemptGroup.nodeIds.push(attempt.id);
+        }
+        if (pendingDelegationNode && pendingDelegationNode.id !== attempt.id) {
+            edges.push({
+                id: `edge:${pendingDelegationNode.id}->${attempt.id}`,
+                from: pendingDelegationNode.id,
+                to: attempt.id,
+                kind: "spawn",
+                sourceEventIds: [...pendingDelegationNode.sourceEventIds, ...attempt.sourceEventIds],
+                confidence: 0.9,
+            });
+            pendingDelegationNode = null;
+        }
+        else if (previousAttempt && previousAttempt.id !== attempt.id) {
+            edges.push({
+                id: `edge:${previousAttempt.id}->${attempt.id}`,
+                from: previousAttempt.id,
+                to: attempt.id,
+                kind: kind === "approval" ? "approval" : "sequence",
+                sourceEventIds: [],
+                confidence: 0.7,
+            });
+        }
+        else if (!previousAttempt && currentGroup?.anchorNodeId) {
+            edges.push({
+                id: `edge:${currentGroup.anchorNodeId}->${attempt.id}`,
+                from: currentGroup.anchorNodeId,
+                to: attempt.id,
+                kind: "contains",
+                sourceEventIds: [],
+                confidence: 0.8,
+            });
+        }
+        previousAttempt = attempt;
+        if (projection.type === "step" && projection.status !== "started") {
+            activeAttemptsByKey.delete(attemptKey);
+        }
+    }
+    for (const attempt of attempts) {
+        nodes.push({
+            id: attempt.id,
+            layer: "attempt",
+            kind: attempt.kind,
+            label: attempt.label,
+            status: attempt.status,
+            threadId,
+            runId,
+            agentId: attempt.agentId,
+            groupId: attempt.groupId,
+            sequenceStart: attempt.sequenceStart,
+            sequenceEnd: attempt.sequenceEnd,
+            startedAt: attempt.startedAt,
+            endedAt: attempt.endedAt,
+            sourceEventIds: [...new Set(attempt.sourceEventIds)],
+            detail: { ...attempt.detail, projectionKeys: attempt.projectionKeys },
+        });
+    }
+    groups.push(...attemptSetGroups.values());
+    return { nodes, edges, groups };
+}
+function resolveContext(input, runtimeTimeline, projections) {
+    const timelineHead = runtimeTimeline[0];
+    if (input.threadId && input.runId) {
+        return { threadId: input.threadId, runId: input.runId };
+    }
+    if (timelineHead) {
+        return {
+            threadId: input.threadId ?? timelineHead.threadId,
+            runId: input.runId ?? timelineHead.runId,
+        };
+    }
+    const firstProjection = projections[0];
+    if (!input.threadId || !input.runId) {
+        throw new Error(`buildFlowGraph requires threadId and runId when runtime timeline data is absent${firstProjection ? "" : " or empty"}.`);
+    }
+    return { threadId: input.threadId, runId: input.runId };
+}
+export function buildFlowGraph(input) {
+    const runtimeTimeline = input.runtimeTimeline
+        ?? (input.runtimeEvents ? projectRuntimeTimeline(input.runtimeEvents, {
+            ...(input.threadId ? { threadId: input.threadId } : {}),
+            ...(input.runId ? { runId: input.runId } : {}),
+        }) : []);
+    const initialAgentId = deriveInitialAgentId(input, runtimeTimeline);
+    const upstreamContext = input.upstreamEvents
+        ? convertUpstreamEventsWithAgents(input.upstreamEvents, initialAgentId)
+        : { projections: [], delegationNodes: [] };
+    const upstreamProjections = input.upstreamProjections ?? upstreamContext.projections.map((record) => record.projection);
+    const { threadId, runId } = resolveContext(input, runtimeTimeline, upstreamProjections);
+    const { nodes: runtimeNodes, edges: runtimeEdges, groups: runtimeGroups } = buildRuntimeNodes(runtimeTimeline);
+    for (const node of runtimeNodes) {
+        node.agentId = typeof node.detail.agentId === "string" ? node.detail.agentId : initialAgentId;
+    }
+    const projectionRecords = input.upstreamProjections
+        ? input.upstreamProjections.map((projection, index) => ({
+            projection,
+            agentId: initialAgentId,
+            sourceEventId: "key" in projection ? projection.key : `projection:${index + 1}`,
+        }))
+        : upstreamContext.projections;
+    const { nodes: attemptNodes, edges: attemptEdges, groups: attemptGroups } = buildAttempts(projectionRecords, upstreamContext.delegationNodes, runtimeGroups, threadId, runId);
+    return {
+        graphId: `${threadId}/${runId}`,
+        scope: input.scope ?? "run",
+        threadId,
+        runId,
+        nodes: [...runtimeNodes, ...attemptNodes],
+        edges: [...runtimeEdges, ...attemptEdges],
+        groups: [...runtimeGroups, ...attemptGroups],
+        metadata: {
+            runtimeTimelineCount: runtimeTimeline.length,
+            upstreamProjectionCount: upstreamProjections.length,
+            delegationCount: upstreamContext.delegationNodes.length,
+            ...(input.metadata ?? {}),
+        },
+    };
+}

package/dist/flow/export-mermaid.d.ts

@@ -0,0 +1,2 @@
+import type { FlowGraph, FlowGraphMermaidOptions } from "./types.js";
+export declare function exportFlowGraphToMermaid(graph: FlowGraph, options?: FlowGraphMermaidOptions): string;

package/dist/flow/export-mermaid.js

@@ -0,0 +1,96 @@
+const PRODUCT_VIEW_KINDS = new Set(["agent", "llm", "tool", "skill"]);
+function sanitizeMermaidId(value) {
+    return value.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function escapeMermaidLabel(value) {
+    return value.replace(/"/g, '\\"');
+}
+function renderNode(node, mermaidId) {
+    const label = escapeMermaidLabel(`${node.label} [${node.status}]`);
+    switch (node.kind) {
+        case "approval":
+            return `  ${mermaidId}{"${label}"}`;
+        case "queue":
+            return `  ${mermaidId}[/"${label}"/]`;
+        case "recovery":
+            return `  ${mermaidId}{{"${label}"}}`;
+        case "artifact":
+            return `  ${mermaidId}[("${label}")]`;
+        case "skill":
+            return `  ${mermaidId}[["${label}"]]`;
+        case "memory":
+            return `  ${mermaidId}[("${label}")]`;
+        default:
+            return `  ${mermaidId}["${label}"]`;
+    }
+}
+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 : "");
+    return label
+        ? `  ${fromId} ${connector}|"${escapeMermaidLabel(label)}"| ${toId}`
+        : `  ${fromId} ${connector} ${toId}`;
+}
+export function exportFlowGraphToMermaid(graph, options = {}) {
+    const direction = options.direction ?? "TD";
+    const view = options.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 includeGroups = options.includeGroups ?? true;
+    const includeDetails = options.includeDetails ?? false;
+    const nodes = graph.nodes.filter((node) => {
+        if (!includeDetails && node.layer === "detail") {
+            return false;
+        }
+        return includedKinds ? includedKinds.has(node.kind) : true;
+    });
+    const nodeIdSet = new Set(nodes.map((node) => node.id));
+    const edges = graph.edges.filter((edge) => {
+        if (!nodeIdSet.has(edge.from) || !nodeIdSet.has(edge.to)) {
+            return false;
+        }
+        return includedEdgeKinds ? includedEdgeKinds.has(edge.kind) : true;
+    });
+    const lines = [`flowchart ${direction}`];
+    const mermaidIdByNodeId = new Map();
+    for (const node of nodes) {
+        mermaidIdByNodeId.set(node.id, sanitizeMermaidId(node.id));
+    }
+    if (includeGroups) {
+        const groupedNodeIds = new Set();
+        for (const group of graph.groups) {
+            const groupNodes = group.nodeIds.filter((nodeId) => nodeIdSet.has(nodeId));
+            if (groupNodes.length === 0) {
+                continue;
+            }
+            lines.push(`  subgraph ${sanitizeMermaidId(group.id)}["${escapeMermaidLabel(group.label)}"]`);
+            for (const nodeId of groupNodes) {
+                groupedNodeIds.add(nodeId);
+                const node = nodes.find((candidate) => candidate.id === nodeId);
+                if (!node) {
+                    continue;
+                }
+                lines.push(renderNode(node, mermaidIdByNodeId.get(node.id)));
+            }
+            lines.push("  end");
+        }
+        for (const node of nodes) {
+            if (!groupedNodeIds.has(node.id)) {
+                lines.push(renderNode(node, mermaidIdByNodeId.get(node.id)));
+            }
+        }
+    }
+    else {
+        for (const node of nodes) {
+            lines.push(renderNode(node, mermaidIdByNodeId.get(node.id)));
+        }
+    }
+    for (const edge of edges) {
+        lines.push(renderEdge(edge, mermaidIdByNodeId.get(edge.from), mermaidIdByNodeId.get(edge.to)));
+    }
+    return lines.join("\n");
+}

package/dist/flow/export-sequence-mermaid.d.ts

@@ -0,0 +1,3 @@
+import type { FlowGraph } from "./types.js";
+import type { FlowGraphSequenceMermaidOptions } from "./types.js";
+export declare function exportFlowGraphToSequenceMermaid(graph: FlowGraph, options?: FlowGraphSequenceMermaidOptions): string;

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

@@ -0,0 +1,169 @@
+const PRODUCT_VIEW_KINDS = new Set(["agent", "llm", "tool", "skill"]);
+function sanitizeAlias(value) {
+    return value.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function escapeLabel(value) {
+    return value.replace(/"/g, '\\"');
+}
+function selectNodes(graph, options) {
+    const includedKinds = options.includeKinds
+        ? new Set(options.includeKinds)
+        : options.view === "debug"
+            ? null
+            : PRODUCT_VIEW_KINDS;
+    return graph.nodes.filter((node) => {
+        if (node.layer === "detail") {
+            return false;
+        }
+        if (includedKinds) {
+            return includedKinds.has(node.kind);
+        }
+        return node.kind === "run"
+            || node.kind === "agent"
+            || node.kind === "approval"
+            || node.kind === "recovery"
+            || node.kind === "llm"
+            || node.kind === "tool"
+            || node.kind === "skill"
+            || node.kind === "artifact";
+    });
+}
+function getParticipantsForNode(node) {
+    const runtimeParticipant = { id: "runtime", alias: "Runtime", label: "Runtime" };
+    const agentParticipant = {
+        id: `agent:${node.agentId ?? "agent"}`,
+        alias: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+        label: `Agent${node.agentId ? `:${node.agentId}` : ""}`,
+    };
+    if (node.kind === "run") {
+        return [
+            { id: "user", alias: "User", label: "User" },
+            runtimeParticipant,
+            agentParticipant,
+        ];
+    }
+    if (node.kind === "agent") {
+        const fromAgentId = typeof node.detail.fromAgentId === "string" ? node.detail.fromAgentId : "agent";
+        return [
+            {
+                id: `agent:${fromAgentId}`,
+                alias: sanitizeAlias(`Agent_${fromAgentId}`),
+                label: `Agent:${fromAgentId}`,
+            },
+            agentParticipant,
+        ];
+    }
+    if (node.kind === "approval") {
+        return [
+            runtimeParticipant,
+            { id: "operator", alias: "Operator", label: "Operator" },
+        ];
+    }
+    if (node.kind === "llm") {
+        return [
+            agentParticipant,
+            { id: "model", alias: "Model", label: "Model" },
+        ];
+    }
+    if (node.kind === "tool") {
+        return [
+            agentParticipant,
+            {
+                id: `tool:${node.label}`,
+                alias: sanitizeAlias(`Tool_${node.label}`),
+                label: `Tool:${node.label.replace(/\s+\[[^\]]+\]$/, "")}`,
+            },
+        ];
+    }
+    if (node.kind === "skill") {
+        return [
+            agentParticipant,
+            { id: "skill", alias: "Skill", label: "Skill" },
+        ];
+    }
+    if (node.kind === "recovery") {
+        return [
+            runtimeParticipant,
+            agentParticipant,
+        ];
+    }
+    if (node.kind === "artifact") {
+        return [
+            runtimeParticipant,
+            { id: "artifact", alias: "ArtifactStore", label: "ArtifactStore" },
+        ];
+    }
+    return [runtimeParticipant, agentParticipant];
+}
+function renderArrowForNode(node) {
+    if (node.kind === "run" && node.status === "started") {
+        return { from: "User", to: "Runtime", text: node.label };
+    }
+    if (node.kind === "run" && (node.status === "completed" || node.status === "failed")) {
+        return { from: "Runtime", to: "User", text: node.label };
+    }
+    if (node.kind === "agent") {
+        const fromAgentId = typeof node.detail.fromAgentId === "string" ? node.detail.fromAgentId : "agent";
+        return {
+            from: sanitizeAlias(`Agent_${fromAgentId}`),
+            to: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            text: node.label,
+        };
+    }
+    if (node.kind === "approval" && node.status === "waiting") {
+        return { from: "Runtime", to: "Operator", text: node.label };
+    }
+    if (node.kind === "approval" && node.status === "resolved") {
+        return { from: "Operator", to: "Runtime", text: node.label };
+    }
+    if (node.kind === "recovery") {
+        return { from: "Runtime", to: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`), text: node.label };
+    }
+    if (node.kind === "llm") {
+        return {
+            from: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            to: "Model",
+            text: node.label,
+            dashed: node.status === "completed" || node.status === "failed",
+        };
+    }
+    if (node.kind === "tool") {
+        return {
+            from: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            to: sanitizeAlias(`Tool_${node.label}`),
+            text: node.label,
+            dashed: node.status === "completed" || node.status === "failed",
+        };
+    }
+    if (node.kind === "skill") {
+        return {
+            from: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
+            to: "Skill",
+            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 };
+}
+export function exportFlowGraphToSequenceMermaid(graph, options = {}) {
+    const nodes = selectNodes(graph, options);
+    const lines = ["sequenceDiagram"];
+    const participants = new Map();
+    for (const node of nodes) {
+        for (const participant of getParticipantsForNode(node)) {
+            participants.set(participant.id, participant);
+        }
+    }
+    for (const participant of participants.values()) {
+        lines.push(`  participant ${participant.alias} as ${escapeLabel(participant.label)}`);
+    }
+    for (const node of nodes) {
+        const arrow = renderArrowForNode(node);
+        const connector = arrow.dashed ? "-->>" : "->>";
+        lines.push(`  ${arrow.from}${connector}${arrow.to}: ${escapeLabel(node.label)}`);
+    }
+    return lines.join("\n");
+}

package/dist/flow/index.d.ts

@@ -0,0 +1,4 @@
+export { buildFlowGraph } from "./build-flow-graph.js";
+export { exportFlowGraphToMermaid } from "./export-mermaid.js";
+export { exportFlowGraphToSequenceMermaid } from "./export-sequence-mermaid.js";
+export type { BuildFlowGraphInput, FlowEdge, FlowEdgeKind, FlowGraph, FlowGraphMermaidOptions, FlowGraphSequenceMermaidOptions, FlowGroup, FlowGroupKind, FlowNode, FlowNodeKind, FlowNodeLayer, FlowNodeStatus, } from "./types.js";

package/dist/flow/index.js

@@ -0,0 +1,3 @@
+export { buildFlowGraph } from "./build-flow-graph.js";
+export { exportFlowGraphToMermaid } from "./export-mermaid.js";
+export { exportFlowGraphToSequenceMermaid } from "./export-sequence-mermaid.js";

package/dist/flow/types.d.ts

@@ -0,0 +1,75 @@
+import type { HarnessEvent, RuntimeTimelineItem } from "../contracts/types.js";
+import type { UpstreamTimelineProjection } from "../upstream-events.js";
+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";
+export type FlowEdgeKind = "sequence" | "contains" | "approval" | "resume" | "retry" | "fallback" | "result" | "spawn";
+export type FlowGroupKind = "segment" | "approval-window" | "attempt-set" | "agent-scope";
+export type FlowNode = {
+    id: string;
+    layer: FlowNodeLayer;
+    kind: FlowNodeKind;
+    label: string;
+    status: FlowNodeStatus;
+    threadId: string;
+    runId: string;
+    agentId?: string;
+    startedAt?: string;
+    endedAt?: string;
+    sequenceStart?: number;
+    sequenceEnd?: number;
+    parentNodeId?: string;
+    groupId?: string;
+    sourceEventIds: string[];
+    detail: Record<string, unknown>;
+};
+export type FlowEdge = {
+    id: string;
+    from: string;
+    to: string;
+    kind: FlowEdgeKind;
+    label?: string;
+    condition?: string;
+    sourceEventIds: string[];
+    confidence?: number;
+};
+export type FlowGroup = {
+    id: string;
+    kind: FlowGroupKind;
+    label: string;
+    nodeIds: string[];
+    startedAt?: string;
+    endedAt?: string;
+};
+export type FlowGraph = {
+    graphId: string;
+    scope: "run" | "thread";
+    threadId: string;
+    runId: string;
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+    groups: FlowGroup[];
+    metadata: Record<string, unknown>;
+};
+export type BuildFlowGraphInput = {
+    threadId?: string;
+    runId?: string;
+    scope?: FlowGraph["scope"];
+    runtimeEvents?: readonly HarnessEvent[];
+    runtimeTimeline?: readonly RuntimeTimelineItem[];
+    upstreamEvents?: readonly unknown[];
+    upstreamProjections?: readonly UpstreamTimelineProjection[];
+    metadata?: Record<string, unknown>;
+};
+export type FlowGraphMermaidOptions = {
+    view?: "product" | "debug";
+    direction?: "TD" | "LR";
+    includeGroups?: boolean;
+    includeDetails?: boolean;
+    includeKinds?: readonly FlowNodeKind[];
+    includeEdgeKinds?: readonly FlowEdgeKind[];
+};
+export type FlowGraphSequenceMermaidOptions = {
+    view?: "product" | "debug";
+    includeKinds?: readonly FlowNodeKind[];
+};

package/dist/flow/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, } from "./acp.js";
 export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, 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 { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";
 export type { UpstreamTimelineProjection, UpstreamTimelineReducer } from "./upstream-events.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.156";
+export declare const AGENT_HARNESS_VERSION = "0.0.157";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.156";
+export const AGENT_HARNESS_VERSION = "0.0.157";

package/dist/runtime/adapter/tool/resolved-tool.d.ts

@@ -14,5 +14,5 @@ export declare function wrapResolvedToolWithModelFacingName<T>(resolvedTool: T,
 export declare function hasCallableToolHandler(value: unknown): value is ResolvedToolLike;
 export declare function normalizeResolvedToolSchema(resolvedTool: ResolvedToolLike): Record<string, unknown> | {
     parse?: (input: unknown) => unknown;
-} | z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">> | undefined;
+} | z.ZodObject<{}, z.core.$loose> | undefined;
 export declare function asStructuredExecutableTool(resolvedTool: unknown, modelFacingName: string, description: string): unknown;

package/dist/runtime/harness/events/streaming.js

@@ -42,6 +42,12 @@ export async function dispatchRunListeners(stream, listeners, options) {
         }
         if (item.type === "upstream-event") {
             await options.notifyListener(listeners.onUpstreamEvent, item.event);
+            await options.notifyListener(listeners.onUpstreamItem, {
+                threadId: item.threadId,
+                runId: item.runId,
+                agentId: item.agentId,
+                event: item.event,
+            });
             continue;
         }
         if (item.type === "result") {

package/dist/runtime/harness/run/stream-run.js

@@ -85,7 +85,7 @@ export async function* streamHarnessRun(options) {
                     type: "upstream-event",
                     threadId: options.threadId,
                     runId: options.runId,
-                    agentId: options.selectedAgentId,
+                    agentId: currentAgentId,
                     event: normalizedChunk.event,
                 };
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.157",
+  "version": "0.0.158",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -59,7 +59,7 @@
     "mem0ai": "^2.4.4",
     "mustache": "^4.2.0",
     "yaml": "^2.8.1",
-    "zod": "^3.25.67"
+    "zod": "^4.3.6"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
@@ -75,5 +75,9 @@
     "@types/node": "^24.6.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
+  },
+  "overrides": {
+    "@browserbasehq/stagehand": "3.2.0",
+    "openai": "6.33.0"
   }
 }