@botbotgo/agent-harness 0.0.309 → 0.0.311

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

@@ -0,0 +1,56 @@
+import type { RuntimeTimelineItem, RuntimeSurfaceItem } from "../contracts/types.js";
+import type { BuildFlowGraphInput, BuildFlowGraphRuntimeEvent, FlowGroup, FlowNode, FlowNodeKind, FlowNodeStatus } from "./types.js";
+import type { UpstreamTimelineProjection } from "../projections/upstream-events.js";
+export type ProjectionRecord = {
+    projection: UpstreamTimelineProjection;
+    agentId: string;
+    agentName: string;
+    sourceEventId: string;
+};
+export type UpstreamEventEnvelope = {
+    event: unknown;
+    agentId?: string;
+    agentName?: string;
+    surfaceItem?: Partial<RuntimeSurfaceItem>;
+};
+export type InternalAttemptRecord = {
+    id: string;
+    kind: FlowNodeKind;
+    label: string;
+    status: FlowNodeStatus;
+    agentId?: string;
+    agentName?: string;
+    groupId?: string;
+    sourceEventIds: string[];
+    startedAt?: string;
+    endedAt?: string;
+    sequenceStart?: number;
+    sequenceEnd?: number;
+    detail: Record<string, unknown>;
+    attemptKey: string;
+    toolName?: string;
+    projectionKeys: string[];
+};
+export type InternalGroupState = FlowGroup & {
+    anchorNodeId?: string;
+};
+export declare function asObject(value: unknown): Record<string, unknown> | null;
+export declare function readString(value: unknown): string | null;
+export declare function extractUpstreamEventEnvelope(value: unknown): UpstreamEventEnvelope;
+export declare function normalizeRuntimeEvents(events: readonly BuildFlowGraphRuntimeEvent[]): import("../contracts/types.js").HarnessEvent[];
+export declare function collectNestedAgentNames(value: unknown, names?: Set<string>): Set<string>;
+export declare function slugify(value: string): string;
+export declare function titleCase(value: string): string;
+export declare function normalizeLabel(value: string): string;
+export declare function readSessionId(input: BuildFlowGraphInput): string | undefined;
+export declare function readRequestId(input: BuildFlowGraphInput): string | undefined;
+export declare function readProjectionLabel(projection: UpstreamTimelineProjection): string;
+export declare function deriveNodeKindFromProjection(projection: UpstreamTimelineProjection): FlowNodeKind;
+export declare function deriveStatusFromProjection(projection: UpstreamTimelineProjection): FlowNodeStatus;
+export declare function deriveRuntimeNode(input: RuntimeTimelineItem): Pick<FlowNode, "kind" | "status" | "label" | "detail">;
+export declare function normalizeAttemptLabel(kind: FlowNodeKind, projection: UpstreamTimelineProjection): string;
+export declare function semanticNameFromLabel(kind: FlowNodeKind, label: string): string;
+export declare function normalizeToolIdentity(value: string): string;
+export declare function buildAttemptKey(kind: FlowNodeKind, label: string, groupId?: string): string;
+export declare function deriveInitialAgentId(input: BuildFlowGraphInput, runtimeTimeline: readonly RuntimeTimelineItem[]): string;
+export declare function deriveAgentName(agentId: string, explicitName?: string): string;

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

@@ -0,0 +1,214 @@
+import { formatAgentName } from "../utils/agent-display.js";
+export function asObject(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}
+export function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+export function extractUpstreamEventEnvelope(value) {
+    const typed = asObject(value);
+    const nestedEvent = typed && Object.prototype.hasOwnProperty.call(typed, "event") ? typed.event : undefined;
+    const surfaceItem = asObject(typed?.surfaceItem);
+    const event = typed
+        && nestedEvent
+        && typeof nestedEvent === "object"
+        && !Array.isArray(nestedEvent)
+        ? nestedEvent
+        : value;
+    const agentId = readString(typed?.agentId) ?? readString(surfaceItem?.agentId);
+    const agentName = readString(typed?.agentName) ?? readString(surfaceItem?.agentName);
+    return {
+        event,
+        agentId: agentId ?? undefined,
+        agentName: agentName ?? undefined,
+        ...(surfaceItem ? { surfaceItem } : {}),
+    };
+}
+function normalizeRuntimeEventType(eventType) {
+    return eventType;
+}
+export function normalizeRuntimeEvents(events) {
+    return events.map((event) => {
+        const typed = event;
+        const sessionId = readString(typed.sessionId) ?? "";
+        const requestId = readString(typed.requestId) ?? "";
+        return {
+            eventId: String(event.eventId),
+            eventType: normalizeRuntimeEventType(String(event.eventType)),
+            timestamp: String(event.timestamp),
+            sessionId,
+            requestId,
+            sequence: Number(event.sequence),
+            source: event.source,
+            payload: event.payload ?? {},
+        };
+    });
+}
+export 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;
+}
+export function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || "node";
+}
+export function titleCase(value) {
+    return value
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .split(" ")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+export function normalizeLabel(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+export function readSessionId(input) {
+    return input.sessionId;
+}
+export function readRequestId(input) {
+    return input.requestId;
+}
+export function readProjectionLabel(projection) {
+    if (projection.type === "step") {
+        return projection.step;
+    }
+    if (projection.type === "tool-result") {
+        return `Tool result ${titleCase(projection.toolName)}`;
+    }
+    return projection.text;
+}
+export function deriveNodeKindFromProjection(projection) {
+    if (projection.type === "tool-result") {
+        return "result";
+    }
+    if (projection.type === "thinking") {
+        return "thinking";
+    }
+    return projection.category;
+}
+export function deriveStatusFromProjection(projection) {
+    if (projection.type === "thinking" || projection.type === "tool-result") {
+        return "completed";
+    }
+    return projection.category === "approval" && projection.status === "started" ? "waiting" : projection.status;
+}
+export function deriveRuntimeNode(input) {
+    if (input.eventType === "request.created") {
+        return { kind: "request", status: "started", label: "Request created", detail: input.payload };
+    }
+    if (input.eventType === "request.queued") {
+        return { kind: "queue", status: "waiting", label: "Queued", detail: input.payload };
+    }
+    if (input.eventType === "request.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 === "request.resumed") {
+        return { kind: "recovery", status: "completed", label: "Request resumed", detail: input.payload };
+    }
+    if (input.eventType === "artifact.created") {
+        return { kind: "artifact", status: "completed", label: "Artifact created", detail: input.payload };
+    }
+    if (input.eventType === "request.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: "request", status: "failed", label: "Request failed", detail: input.payload };
+        }
+        if (state === "completed") {
+            return { kind: "request", status: "completed", label: "Request completed", detail: input.payload };
+        }
+        return { kind: "request", status: "started", label: state ? `Request ${state}` : "Request state changed", detail: input.payload };
+    }
+    return { kind: input.kind, status: "completed", label: input.eventType, detail: input.payload };
+}
+export 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);
+}
+export 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()}`;
+}
+export function normalizeToolIdentity(value) {
+    return value
+        .toLowerCase()
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function buildAttemptKey(kind, label, groupId) {
+    return `${semanticNameFromLabel(kind, label)}:${groupId ?? "ungrouped"}`;
+}
+export 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";
+}
+export function deriveAgentName(agentId, explicitName) {
+    return explicitName && explicitName.trim().length > 0 ? explicitName.trim() : formatAgentName(agentId);
+}

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

@@ -0,0 +1,8 @@
+import type { RuntimeTimelineItem } from "../contracts/types.js";
+import type { FlowEdge, FlowNode } from "./types.js";
+import { type InternalGroupState } from "./flow-graph-normalization.js";
+export declare function buildRuntimeNodes(timeline: readonly RuntimeTimelineItem[]): {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+    groups: InternalGroupState[];
+};

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

@@ -0,0 +1,107 @@
+import { deriveRuntimeNode, slugify } from "./flow-graph-normalization.js";
+export 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.requestId}:${item.sequence}:${slugify(item.eventType)}`,
+            layer: "runtime",
+            kind: mapped.kind,
+            label: mapped.label,
+            status: mapped.status,
+            sessionId: item.sessionId,
+            requestId: item.requestId,
+            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 === "request.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 === "request.created" || item.eventType === "request.dequeued" || item.eventType === "request.resumed") {
+            segmentOrdinal += 1;
+            activeExecutionGroup = {
+                id: `group:${item.requestId}:segment:${segmentOrdinal}`,
+                kind: "segment",
+                label: item.eventType === "request.created"
+                    ? `Execution segment ${segmentOrdinal}`
+                    : item.eventType === "request.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.requestId}: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.requestId}: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 };
+}

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

@@ -0,0 +1,18 @@
+import type { RuntimeSurfaceItem, RuntimeTimelineItem } from "../contracts/types.js";
+import { type UpstreamTimelineProjection } from "../projections/upstream-events.js";
+import type { BuildFlowGraphInput, FlowEdge, FlowGroup, FlowNode } from "./types.js";
+import { type InternalGroupState, type ProjectionRecord } from "./flow-graph-normalization.js";
+export declare function convertUpstreamEventsWithAgents(upstreamEvents: readonly unknown[], initialAgentId: string): {
+    projections: ProjectionRecord[];
+    delegationNodes: FlowNode[];
+};
+export declare function buildAttempts(projectionRecords: readonly ProjectionRecord[], delegationNodes: readonly FlowNode[], runtimeGroups: readonly InternalGroupState[], sessionId: string, requestId: string): {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+    groups: FlowGroup[];
+};
+export declare function resolveContext(input: BuildFlowGraphInput, runtimeTimeline: readonly RuntimeTimelineItem[], projections: readonly UpstreamTimelineProjection[]): {
+    sessionId: string;
+    requestId: string;
+};
+export declare function buildRuntimeSurface(nodes: readonly FlowNode[]): RuntimeSurfaceItem[];