@botbotgo/agent-harness 0.0.249 → 0.0.250

package/dist/api.d.ts

@@ -33,6 +33,7 @@ export type RequestUpstreamEventItem = {
     requestId: string;
     agentId: string;
     agentName?: string;
+    surfaceItems?: import("./contracts/types.js").RuntimeSurfaceItem[];
     event: unknown;
 };
 export type PublicRunListeners = {

package/dist/api.js

@@ -66,6 +66,7 @@ function toPublicRunListeners(listeners) {
                 requestId: item.runId,
                 agentId: item.agentId,
                 agentName: item.agentName,
+                surfaceItems: item.surfaceItems,
                 event: item.event,
             })
             : undefined,

package/dist/contracts/runtime.d.ts

@@ -98,6 +98,17 @@ export type RuntimeHistoryItem = {
     isError?: boolean;
     key: string;
 };
+export type RuntimeSurfaceKind = "agent" | "llm" | "memory" | "skill" | "tool";
+export type RuntimeSurfaceItem = {
+    kind: RuntimeSurfaceKind;
+    id: string;
+    name: string;
+    label: string;
+    status: "started" | "completed" | "failed";
+    ownerAgentId?: string;
+    ownerAgentName?: string;
+    sourceEventId?: string;
+};
 export type AgentReference = {
     id: string;
     name: string;
@@ -419,6 +430,7 @@ export type UpstreamRuntimeEventItem = {
     runId: string;
     agentId: string;
     agentName?: string;
+    surfaceItems?: RuntimeSurfaceItem[];
     event: UpstreamRuntimeEvent;
 };
 export type RuntimeListeners = {
@@ -467,6 +479,7 @@ export type HarnessStreamItem = {
     runId: string;
     agentId: string;
     agentName?: string;
+    surfaceItems?: RuntimeSurfaceItem[];
     event: UpstreamRuntimeEvent;
 } | {
     type: "result";
@@ -507,6 +520,7 @@ export type RequestSummary = Omit<ThreadRunRecord, "threadId" | "runId"> & {
 };
 export type RequestRecord = RequestSummary & {
     history?: RuntimeHistoryItem[];
+    runtimeSurface?: RuntimeSurfaceItem[];
     upstreamEvents?: unknown[];
     runtimeTimeline?: RuntimeTimelineItem[];
 };
@@ -519,6 +533,7 @@ export type RunSummary = Omit<RequestSummary, "sessionId" | "requestId"> & {
 };
 export type RunRecord = RunSummary & {
     history?: RuntimeHistoryItem[];
+    runtimeSurface?: RuntimeSurfaceItem[];
     upstreamEvents?: unknown[];
     runtimeTimeline?: RuntimeTimelineItem[];
 };

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

@@ -50,6 +50,9 @@ function slugify(value) {
         .replace(/^-+|-+$/g, "")
         .slice(0, 80) || "node";
 }
+function buildSurfaceId(kind, value) {
+    return `${kind}:${slugify(value)}`;
+}
 function titleCase(value) {
     return value
         .replace(/[_-]+/g, " ")
@@ -765,6 +768,36 @@ export function buildFlowGraph(input) {
         }))
         : upstreamContext.projections;
     const { nodes: attemptNodes, edges: attemptEdges, groups: attemptGroups } = buildAttempts(projectionRecords, upstreamContext.delegationNodes, runtimeGroups, sessionId, requestId);
+    const runtimeSurface = [...upstreamContext.delegationNodes, ...attemptNodes]
+        .filter((node) => node.layer !== "detail"
+        && (node.kind === "agent" || node.kind === "llm" || node.kind === "memory" || node.kind === "skill" || node.kind === "tool"))
+        .map((node) => ({
+        kind: node.kind,
+        id: buildSurfaceId(node.kind, node.kind === "agent" ? (node.agentId ?? node.agentName ?? "agent") : node.label),
+        name: node.kind === "agent"
+            ? (node.agentName ?? node.agentId ?? "Agent")
+            : normalizeLabel(node.label)
+                .replace(/^Delegate to\s+/i, "")
+                .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, ""),
+        label: node.label,
+        status: node.status === "resolved" ? "completed" : node.status,
+        ownerAgentId: node.kind === "agent"
+            ? (typeof node.detail.fromAgentId === "string" ? node.detail.fromAgentId : node.agentId)
+            : node.agentId,
+        ownerAgentName: node.kind === "agent"
+            ? (typeof node.detail.fromAgentName === "string" ? node.detail.fromAgentName : node.agentName)
+            : node.agentName,
+        sourceEventId: node.sourceEventIds[0],
+    }));
     return {
         graphId: `${sessionId}/${requestId}`,
         scope: input.scope ?? "run",
@@ -779,6 +812,7 @@ export function buildFlowGraph(input) {
             runtimeTimelineCount: runtimeTimeline.length,
             upstreamProjectionCount: upstreamProjections.length,
             delegationCount: upstreamContext.delegationNodes.length,
+            runtimeSurface,
             ...(input.metadata ?? {}),
         },
     };

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.248";
+export declare const AGENT_HARNESS_VERSION = "0.0.249";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.248";
+export const AGENT_HARNESS_VERSION = "0.0.249";

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

@@ -47,6 +47,7 @@ export async function dispatchRunListeners(stream, listeners, options) {
                 runId: item.runId,
                 agentId: item.agentId,
                 agentName: item.agentName,
+                surfaceItems: item.surfaceItems,
                 event: item.event,
             });
             continue;

package/dist/runtime/harness/run/inspection.d.ts

@@ -1,4 +1,4 @@
-import type { CompiledAgentBinding, RuntimeSnapshot } from "../../../contracts/types.js";
+import type { CompiledAgentBinding, RuntimeSnapshot, RuntimeSurfaceItem } from "../../../contracts/types.js";
 export declare function buildRunRuntimeSnapshot(binding: CompiledAgentBinding, options?: {
     runId?: string;
 }): RuntimeSnapshot;
@@ -11,3 +11,19 @@ export declare function consumeRunInspectionUpstreamEvent(input: {
     currentAgentId: string;
     delegationChain: string[];
 };
+export declare function projectRuntimeSurfaceFromUpstreamEvents(input: {
+    upstreamEvents: unknown[];
+    binding?: CompiledAgentBinding;
+    initialAgentId: string;
+}): RuntimeSurfaceItem[];
+export declare function projectRuntimeSurfaceFromSingleUpstreamEvent(input: {
+    event: unknown;
+    binding?: CompiledAgentBinding;
+    currentAgentId: string;
+    currentAgentName?: string;
+    sourceEventId: string;
+}): {
+    currentAgentId: string;
+    currentAgentName: string;
+    items: RuntimeSurfaceItem[];
+};

package/dist/runtime/harness/run/inspection.js

@@ -1,4 +1,6 @@
 import { readSkillMetadata } from "../../support/skill-metadata.js";
+import { createUpstreamTimelineReducer } from "../../../upstream-events.js";
+import { formatAgentName } from "../../../utils/agent-display.js";
 import { getBindingMemorySources, getBindingPrimaryModel, getBindingPrimaryTools, getBindingSkills, getBindingSubagents, } from "../../support/compiled-binding.js";
 import { buildRuntimeGovernanceBundles } from "./governance.js";
 function asObject(value) {
@@ -7,6 +9,32 @@ function asObject(value) {
 function readStringArray(value) {
     return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
 }
+function normalizeLabel(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || "item";
+}
+function stripStepPrefix(label) {
+    return 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, "");
+}
+function buildSurfaceId(kind, value) {
+    return `${kind}:${slugify(value)}`;
+}
 function readTracingConfig(binding) {
     const deepAgentTracing = asObject(binding.harnessRuntime?.deepagent?.passthrough)?.tracing;
     const langchainTracing = asObject(binding.harnessRuntime?.langchain?.passthrough)?.tracing;
@@ -158,3 +186,121 @@ export function consumeRunInspectionUpstreamEvent(input) {
         delegationChain: maybeAppendAgent(input.delegationChain, delegatedAgentId),
     };
 }
+function unwrapUpstreamEvent(event) {
+    const typed = asObject(event);
+    if (!typed) {
+        return { event };
+    }
+    const nestedEvent = asObject(typed.event);
+    if (nestedEvent) {
+        return {
+            event: nestedEvent,
+            ...(typeof typed.agentId === "string" ? { agentId: typed.agentId } : {}),
+            ...(typeof typed.agentName === "string" ? { agentName: typed.agentName } : {}),
+        };
+    }
+    return { event };
+}
+function toSurfaceKind(category) {
+    switch (category) {
+        case "llm":
+        case "memory":
+        case "skill":
+        case "tool":
+            return category;
+        default:
+            return null;
+    }
+}
+export function projectRuntimeSurfaceFromUpstreamEvents(input) {
+    const items = [];
+    let currentAgentId = input.initialAgentId;
+    let currentAgentName = formatAgentName(currentAgentId);
+    for (const [index, rawEvent] of input.upstreamEvents.entries()) {
+        const projected = projectRuntimeSurfaceFromSingleUpstreamEvent({
+            event: rawEvent,
+            binding: input.binding,
+            currentAgentId,
+            currentAgentName,
+            sourceEventId: `upstream:${index + 1}`,
+        });
+        currentAgentId = projected.currentAgentId;
+        currentAgentName = projected.currentAgentName;
+        items.push(...projected.items);
+    }
+    return items;
+}
+export function projectRuntimeSurfaceFromSingleUpstreamEvent(input) {
+    const reducer = createUpstreamTimelineReducer();
+    const items = [];
+    let currentAgentId = input.currentAgentId;
+    let currentAgentName = input.currentAgentName ?? formatAgentName(currentAgentId);
+    const unwrapped = unwrapUpstreamEvent(input.event);
+    if (unwrapped.agentId) {
+        if (unwrapped.agentId !== currentAgentId) {
+            const nextAgentName = unwrapped.agentName ?? formatAgentName(unwrapped.agentId);
+            items.push({
+                kind: "agent",
+                id: buildSurfaceId("agent", unwrapped.agentId),
+                name: nextAgentName,
+                label: `Delegate to ${nextAgentName}`,
+                status: "completed",
+                ownerAgentId: currentAgentId,
+                ownerAgentName: currentAgentName,
+                sourceEventId: input.sourceEventId,
+            });
+        }
+        currentAgentId = unwrapped.agentId;
+        currentAgentName = unwrapped.agentName ?? formatAgentName(currentAgentId);
+    }
+    else if (unwrapped.agentName) {
+        currentAgentName = unwrapped.agentName;
+    }
+    const typed = asObject(unwrapped.event);
+    if (typed && input.binding) {
+        const next = consumeRunInspectionUpstreamEvent({
+            event: typed,
+            currentAgentId,
+            delegationChain: [currentAgentId],
+            binding: input.binding,
+        });
+        if (next.currentAgentId !== currentAgentId) {
+            currentAgentId = next.currentAgentId;
+            currentAgentName = formatAgentName(currentAgentId);
+            items.push({
+                kind: "agent",
+                id: buildSurfaceId("agent", currentAgentId),
+                name: currentAgentName,
+                label: `Delegate to ${currentAgentName}`,
+                status: "completed",
+                ownerAgentId: next.delegationChain.at(-2),
+                ownerAgentName: next.delegationChain.at(-2) ? formatAgentName(next.delegationChain.at(-2)) : undefined,
+                sourceEventId: input.sourceEventId,
+            });
+        }
+    }
+    for (const projection of reducer.consume(unwrapped.event)) {
+        if (projection.type !== "step") {
+            continue;
+        }
+        const kind = toSurfaceKind(projection.category);
+        if (!kind) {
+            continue;
+        }
+        items.push({
+            kind,
+            id: buildSurfaceId(kind, stripStepPrefix(projection.step) || projection.step),
+            name: stripStepPrefix(projection.step) || formatAgentName(kind),
+            label: projection.step,
+            status: projection.status,
+            ownerAgentId: currentAgentId,
+            ownerAgentName: currentAgentName,
+            sourceEventId: input.sourceEventId,
+        });
+    }
+    return {
+        currentAgentId,
+        currentAgentName,
+        items,
+    };
+}

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

@@ -2,7 +2,7 @@ import { AGENT_INTERRUPT_SENTINEL_PREFIX, RuntimeOperationTimeoutError } from ".
 import { renderRuntimeFailure, renderToolFailure } from "../../support/harness-support.js";
 import { getBindingPrimaryModel } from "../../support/compiled-binding.js";
 import { createContentBlocksItem, createToolResultKey, } from "../events/streaming.js";
-import { consumeRunInspectionUpstreamEvent } from "./inspection.js";
+import { consumeRunInspectionUpstreamEvent, projectRuntimeSurfaceFromSingleUpstreamEvent } from "./inspection.js";
 import { formatAgentName } from "../../../utils/agent-display.js";
 function normalizeStreamChunk(chunk) {
     if (typeof chunk === "string") {
@@ -48,6 +48,7 @@ export async function* streamHarnessRun(options) {
     let currentAgentId = options.selectedAgentId;
     let currentAgentName = formatAgentName(options.selectedAgentId);
     let delegationChain = [options.selectedAgentId];
+    let upstreamEventOrdinal = 0;
     let syntheticFallback;
     try {
         const [priorHistory, acquiredReleaseRunSlot] = await Promise.all([
@@ -71,6 +72,18 @@ export async function* streamHarnessRun(options) {
             streamActivityObserved = true;
             const normalizedChunk = normalizeStreamChunk(rawChunk);
             if (normalizedChunk.kind === "upstream-event") {
+                upstreamEventOrdinal += 1;
+                const surfaceProjection = projectRuntimeSurfaceFromSingleUpstreamEvent({
+                    event: {
+                        agentId: currentAgentId,
+                        agentName: currentAgentName,
+                        event: normalizedChunk.event,
+                    },
+                    binding: options.binding,
+                    currentAgentId,
+                    currentAgentName,
+                    sourceEventId: `upstream:${upstreamEventOrdinal}`,
+                });
                 const inspection = consumeRunInspectionUpstreamEvent({
                     event: normalizedChunk.event,
                     currentAgentId,
@@ -95,6 +108,7 @@ export async function* streamHarnessRun(options) {
                     runId: options.runId,
                     agentId: currentAgentId,
                     agentName: currentAgentName,
+                    surfaceItems: surfaceProjection.items,
                     event: normalizedChunk.event,
                 };
                 continue;

package/dist/runtime/harness/run/thread-records.js

@@ -1,6 +1,7 @@
 import { isTerminalRunState, toInspectableApprovalRecord } from "./helpers.js";
 import { projectRuntimeTimeline } from "../events/timeline.js";
 import { createUpstreamTimelineReducer } from "../../../upstream-events.js";
+import { projectRuntimeSurfaceFromUpstreamEvents } from "./inspection.js";
 function unwrapPersistedUpstreamEvent(event) {
     if (typeof event !== "object" || event === null || Array.isArray(event)) {
         return event;
@@ -31,6 +32,10 @@ export async function buildRequestInspectionRecord(persistence, request) {
     const inspection = await persistence.getRunInspection(request.threadId, request.runId);
     const runtimeEvents = await persistence.listRunEvents(request.threadId, request.runId);
     const { upstreamEvents, history } = buildRunInspectionProjection(inspection.upstreamEvents);
+    const runtimeSurface = projectRuntimeSurfaceFromUpstreamEvents({
+        upstreamEvents,
+        initialAgentId: request.agentId ?? inspection.currentAgentId ?? "agent",
+    });
     return {
         requestId: request.runId,
         sessionId: request.threadId,
@@ -51,6 +56,7 @@ export async function buildRequestInspectionRecord(persistence, request) {
         runtimeSnapshot: request.runtimeSnapshot,
         upstreamEvents,
         history,
+        runtimeSurface,
         runtimeTimeline: projectRuntimeTimeline(runtimeEvents, {
             threadId: request.threadId,
             runId: request.runId,
@@ -78,6 +84,7 @@ function toRunRecord(request) {
         runtimeSnapshot: request.runtimeSnapshot,
         upstreamEvents: request.upstreamEvents,
         history: request.history,
+        runtimeSurface: request.runtimeSurface,
         runtimeTimeline: request.runtimeTimeline,
     };
 }

package/dist/runtime/harness.js

@@ -1837,6 +1837,7 @@ function toRequestRecord(record) {
         ...toRequestSummary(record),
         upstreamEvents: record.upstreamEvents,
         history: record.history,
+        runtimeSurface: record.runtimeSurface,
         runtimeTimeline: record.runtimeTimeline,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.249",
+  "version": "0.0.250",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",