@botbotgo/agent-harness 0.0.156 → 0.0.158

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 ?? {}),
+        },
+    };
+}