@botbotgo/agent-harness 0.0.248 → 0.0.250

package/dist/api.d.ts

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

package/dist/api.js

@@ -65,6 +65,8 @@ function toPublicRunListeners(listeners) {
                 sessionId: item.threadId,
                 requestId: item.runId,
                 agentId: item.agentId,
+                agentName: item.agentName,
+                surfaceItems: item.surfaceItems,
                 event: item.event,
             })
             : undefined,
@@ -142,6 +144,7 @@ function toPublicRequestSummary(run) {
         requestId: run.runId,
         sessionId: run.threadId,
         agentId: run.agentId,
+        parentRunId: run.parentRunId,
         executionMode: run.executionMode,
         adapterKind: run.adapterKind,
         createdAt: run.createdAt,

package/dist/contracts/runtime.d.ts

@@ -98,6 +98,21 @@ 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;
+};
 export type RuntimeQueueDiagnostics = {
     status: HealthStatus;
     activeRunSlots: number;
@@ -414,6 +429,8 @@ export type UpstreamRuntimeEventItem = {
     threadId: string;
     runId: string;
     agentId: string;
+    agentName?: string;
+    surfaceItems?: RuntimeSurfaceItem[];
     event: UpstreamRuntimeEvent;
 };
 export type RuntimeListeners = {
@@ -461,6 +478,8 @@ export type HarnessStreamItem = {
     threadId: string;
     runId: string;
     agentId: string;
+    agentName?: string;
+    surfaceItems?: RuntimeSurfaceItem[];
     event: UpstreamRuntimeEvent;
 } | {
     type: "result";
@@ -476,6 +495,7 @@ export type ThreadRunRecord = {
     runId: string;
     threadId: string;
     agentId: string;
+    parentRunId?: string;
     executionMode: string;
     adapterKind?: string;
     createdAt: string;
@@ -500,6 +520,7 @@ export type RequestSummary = Omit<ThreadRunRecord, "threadId" | "runId"> & {
 };
 export type RequestRecord = RequestSummary & {
     history?: RuntimeHistoryItem[];
+    runtimeSurface?: RuntimeSurfaceItem[];
     upstreamEvents?: unknown[];
     runtimeTimeline?: RuntimeTimelineItem[];
 };
@@ -512,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

@@ -1,5 +1,6 @@
 import { projectRuntimeTimeline } from "../runtime/harness/events/timeline.js";
 import { createUpstreamTimelineReducer } from "../upstream-events.js";
+import { formatAgentName } from "../utils/agent-display.js";
 function asObject(value) {
     return typeof value === "object" && value !== null ? value : null;
 }
@@ -17,7 +18,8 @@ function extractUpstreamEventEnvelope(value) {
         ? nestedEvent
         : value;
     const agentId = readString(typed?.agentId);
-    return { event, agentId: agentId ?? undefined };
+    const agentName = readString(typed?.agentName);
+    return { event, agentId: agentId ?? undefined, agentName: agentName ?? undefined };
 }
 function collectNestedAgentNames(value, names = new Set()) {
     if (Array.isArray(value)) {
@@ -48,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, " ")
@@ -352,6 +357,9 @@ function deriveInitialAgentId(input, runtimeTimeline) {
     }
     return "agent";
 }
+function deriveAgentName(agentId, explicitName) {
+    return explicitName && explicitName.trim().length > 0 ? explicitName.trim() : formatAgentName(agentId);
+}
 function extractDelegatedAgentId(event) {
     const typed = asObject(event);
     if (!typed) {
@@ -389,15 +397,21 @@ function convertUpstreamEventsWithAgents(upstreamEvents, initialAgentId) {
     const projections = [];
     const delegationNodes = [];
     let currentAgentId = initialAgentId;
+    let currentAgentName = deriveAgentName(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;
+            currentAgentName = deriveAgentName(currentAgentId, envelope.agentName);
+        }
+        else if (envelope.agentName) {
+            currentAgentName = deriveAgentName(currentAgentId, envelope.agentName);
         }
         const nestedAgentId = extractAgentFromNestedMessages(envelope.event, currentAgentId);
         if (nestedAgentId && nestedAgentId !== currentAgentId) {
+            const nestedAgentName = deriveAgentName(nestedAgentId);
             ordinal += 1;
             delegationNodes.push({
                 id: `delegate:${slugify(currentAgentId)}:${slugify(nestedAgentId)}:${ordinal}`,
@@ -410,19 +424,24 @@ function convertUpstreamEventsWithAgents(upstreamEvents, initialAgentId) {
                 threadId: "",
                 runId: "",
                 agentId: nestedAgentId,
+                agentName: nestedAgentName,
                 sourceEventIds: [sourceEventId],
                 detail: {
                     fromAgentId: currentAgentId,
+                    fromAgentName: currentAgentName,
                     toAgentId: nestedAgentId,
+                    toAgentName: nestedAgentName,
                 },
             });
             currentAgentId = nestedAgentId;
+            currentAgentName = nestedAgentName;
         }
         const emitted = reducer.consume(envelope.event);
         for (const projection of emitted) {
             projections.push({
                 projection,
                 agentId: currentAgentId,
+                agentName: currentAgentName,
                 sourceEventId,
             });
         }
@@ -430,6 +449,7 @@ function convertUpstreamEventsWithAgents(upstreamEvents, initialAgentId) {
         if (!delegatedAgentId || delegatedAgentId === currentAgentId) {
             return;
         }
+        const delegatedAgentName = deriveAgentName(delegatedAgentId);
         ordinal += 1;
         delegationNodes.push({
             id: `delegate:${slugify(initialAgentId)}:${slugify(delegatedAgentId)}:${ordinal}`,
@@ -442,13 +462,17 @@ function convertUpstreamEventsWithAgents(upstreamEvents, initialAgentId) {
             threadId: "",
             runId: "",
             agentId: delegatedAgentId,
+            agentName: delegatedAgentName,
             sourceEventIds: [sourceEventId],
             detail: {
                 fromAgentId: currentAgentId,
+                fromAgentName: currentAgentName,
                 toAgentId: delegatedAgentId,
+                toAgentName: delegatedAgentName,
             },
         });
         currentAgentId = delegatedAgentId;
+        currentAgentName = delegatedAgentName;
     });
     return { projections, delegationNodes };
 }
@@ -479,7 +503,7 @@ function buildAttempts(projectionRecords, delegationNodes, runtimeGroups, thread
             currentGroup = segmentGroups[nextSegmentIndex] ?? currentGroup;
         }
     }
-    function createAttempt(kind, label, projection, agentId) {
+    function createAttempt(kind, label, projection, agentId, agentName) {
         ordinal += 1;
         const attempt = {
             id: `attempt:${runId}:${slugify(kind)}:${slugify(label)}:${ordinal}`,
@@ -487,6 +511,7 @@ function buildAttempts(projectionRecords, delegationNodes, runtimeGroups, thread
             label,
             status: deriveStatusFromProjection(projection),
             agentId,
+            agentName,
             groupId: currentGroup?.id,
             sourceEventIds: [],
             attemptKey: buildAttemptKey(kind, label, currentGroup?.id),
@@ -589,7 +614,7 @@ function buildAttempts(projectionRecords, delegationNodes, runtimeGroups, thread
         const attemptKey = buildAttemptKey(kind, label, currentGroup?.id);
         let attempt;
         if (projection.type === "step" && projection.status === "started") {
-            attempt = createAttempt(kind, label, projection, record.agentId);
+            attempt = createAttempt(kind, label, projection, record.agentId, record.agentName);
             activeAttemptsByKey.set(attemptKey, attempt);
         }
         else if (projection.type === "tool-result") {
@@ -597,16 +622,17 @@ function buildAttempts(projectionRecords, delegationNodes, runtimeGroups, thread
             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);
+                attempt = createAttempt("tool", `Calling tool ${titleCase(toolName)}`, projection, record.agentId, record.agentName);
             }
         }
         else {
             attempt = activeAttemptsByKey.get(attemptKey);
             if (!attempt) {
-                attempt = createAttempt(kind, label, projection, record.agentId);
+                attempt = createAttempt(kind, label, projection, record.agentId, record.agentName);
             }
         }
         attempt.agentId = attempt.agentId ?? record.agentId;
+        attempt.agentName = attempt.agentName ?? record.agentName;
         attempt.projectionKeys.push(projection.key);
         attempt.sourceEventIds.push(record.sourceEventId);
         if (projection.type === "step") {
@@ -684,6 +710,7 @@ function buildAttempts(projectionRecords, delegationNodes, runtimeGroups, thread
             threadId,
             runId,
             agentId: attempt.agentId,
+            agentName: attempt.agentName,
             groupId: attempt.groupId,
             sequenceStart: attempt.sequenceStart,
             sequenceEnd: attempt.sequenceEnd,
@@ -730,15 +757,47 @@ export function buildFlowGraph(input) {
     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;
+        node.agentName = deriveAgentName(node.agentId);
     }
     const projectionRecords = input.upstreamProjections
         ? input.upstreamProjections.map((projection, index) => ({
             projection,
             agentId: initialAgentId,
+            agentName: deriveAgentName(initialAgentId),
             sourceEventId: "key" in projection ? projection.key : `projection:${index + 1}`,
         }))
         : 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",
@@ -753,6 +812,7 @@ export function buildFlowGraph(input) {
             runtimeTimelineCount: runtimeTimeline.length,
             upstreamProjectionCount: upstreamProjections.length,
             delegationCount: upstreamContext.delegationNodes.length,
+            runtimeSurface,
             ...(input.metadata ?? {}),
         },
     };

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

@@ -5,6 +5,13 @@ function sanitizeAlias(value) {
 function escapeLabel(value) {
     return value.replace(/"/g, '\\"');
 }
+function formatAgentParticipantLabel(node) {
+    const agentId = node.agentId ?? "agent";
+    if (node.agentName && node.agentName !== agentId) {
+        return `Agent:${agentId} (${node.agentName})`;
+    }
+    return `Agent:${agentId}`;
+}
 function selectNodes(graph, options) {
     const includedKinds = options.includeKinds
         ? new Set(options.includeKinds)
@@ -33,7 +40,7 @@ function getParticipantsForNode(node) {
     const agentParticipant = {
         id: `agent:${node.agentId ?? "agent"}`,
         alias: sanitizeAlias(`Agent_${node.agentId ?? "agent"}`),
-        label: `Agent${node.agentId ? `:${node.agentId}` : ""}`,
+        label: formatAgentParticipantLabel(node),
     };
     if (node.kind === "run") {
         return [
@@ -48,7 +55,9 @@ function getParticipantsForNode(node) {
             {
                 id: `agent:${fromAgentId}`,
                 alias: sanitizeAlias(`Agent_${fromAgentId}`),
-                label: `Agent:${fromAgentId}`,
+                label: typeof node.detail.fromAgentName === "string" && node.detail.fromAgentName !== fromAgentId
+                    ? `Agent:${fromAgentId} (${node.detail.fromAgentName})`
+                    : `Agent:${fromAgentId}`,
             },
             agentParticipant,
         ];

package/dist/flow/types.d.ts

@@ -16,6 +16,7 @@ export type FlowNode = {
     threadId: string;
     runId: string;
     agentId?: string;
+    agentName?: string;
     startedAt?: string;
     endedAt?: string;
     sequenceStart?: number;

package/dist/package-version.d.ts

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

package/dist/package-version.js

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

package/dist/persistence/file-store.js

@@ -67,10 +67,12 @@ export class FilePersistence {
         const runDir = this.runDir(input.threadId, input.runId);
         await ensureDir(path.join(runDir, "events"));
         await ensureDir(path.join(runDir, "approvals"));
+        const threadMeta = await this.getThreadMeta(input.threadId);
         const meta = {
             runId: input.runId,
             threadId: input.threadId,
             agentId: input.agentId,
+            parentRunId: threadMeta?.latestRunId ?? null,
             executionMode: input.executionMode,
             adapterKind: input.adapterKind ?? input.executionMode,
             createdAt: input.createdAt,
@@ -266,6 +268,7 @@ export class FilePersistence {
             runId: meta.runId,
             threadId: meta.threadId,
             agentId: meta.agentId,
+            ...(meta.parentRunId ? { parentRunId: meta.parentRunId } : {}),
             executionMode: meta.executionMode,
             adapterKind: meta.adapterKind ?? meta.executionMode,
             createdAt: meta.createdAt,

package/dist/persistence/sqlite-store.js

@@ -4,7 +4,7 @@ import { createClient } from "@libsql/client";
 import { fileExists, readJson, writeJson } from "../utils/fs.js";
 import { SqliteRunContextStore } from "./sqlite-run-context-store.js";
 import { SqliteRunQueueStore } from "./sqlite-run-queue-store.js";
-const RUNTIME_SQLITE_SCHEMA_VERSION = 4;
+const RUNTIME_SQLITE_SCHEMA_VERSION = 5;
 const RUNTIME_SQLITE_SCHEMA_FAMILY = "agent-harness-runtime";
 function asRow(value) {
     return value;
@@ -168,6 +168,7 @@ export class SqlitePersistence {
           run_id TEXT PRIMARY KEY,
           thread_id TEXT NOT NULL,
           agent_id TEXT NOT NULL,
+          parent_run_id TEXT,
           execution_mode TEXT NOT NULL,
           adapter_kind TEXT,
           created_at TEXT NOT NULL,
@@ -403,6 +404,7 @@ export class SqlitePersistence {
             runId: asString(row.run_id),
             threadId: asString(row.thread_id),
             agentId: asString(row.agent_id),
+            ...(asNullableString(row.parent_run_id) ? { parentRunId: asNullableString(row.parent_run_id) } : {}),
             executionMode: asString(row.execution_mode),
             adapterKind: asNullableString(row.adapter_kind) ?? undefined,
             createdAt: asString(row.created_at),
@@ -473,12 +475,19 @@ export class SqlitePersistence {
         SELECT run_id, thread_id, created_at, NULL, updated_at, agent_id, json_array(agent_id), NULL, '[]'
         FROM runs
       `);
+            await this.rawExecute("ALTER TABLE runs ADD COLUMN parent_run_id TEXT");
             await this.rawExecute("INSERT OR REPLACE INTO runtime_metadata (key, value) VALUES (?, ?)", ["schema_version", String(RUNTIME_SQLITE_SCHEMA_VERSION)]);
             return;
         }
         if (version === "3") {
             await this.rawExecute("ALTER TABLE run_inspection ADD COLUMN upstream_events_json TEXT NOT NULL DEFAULT '[]'");
             await this.rawExecute("UPDATE run_inspection SET upstream_events_json = '[]' WHERE upstream_events_json IS NULL");
+            await this.rawExecute("ALTER TABLE runs ADD COLUMN parent_run_id TEXT");
+            await this.rawExecute("INSERT OR REPLACE INTO runtime_metadata (key, value) VALUES (?, ?)", ["schema_version", String(RUNTIME_SQLITE_SCHEMA_VERSION)]);
+            return;
+        }
+        if (version === "4") {
+            await this.rawExecute("ALTER TABLE runs ADD COLUMN parent_run_id TEXT");
             await this.rawExecute("INSERT OR REPLACE INTO runtime_metadata (key, value) VALUES (?, ?)", ["schema_version", String(RUNTIME_SQLITE_SCHEMA_VERSION)]);
             return;
         }
@@ -493,6 +502,7 @@ export class SqlitePersistence {
        VALUES (?, ?, ?, ?, ?, ?, ?)`, [input.threadId, "default", input.agentId, input.status, input.runId, input.createdAt, input.createdAt]);
     }
     async bootstrapRun(input) {
+        const parentRunId = input.createThread ? null : (await this.getThreadMeta(input.threadId))?.latestRunId ?? null;
         await mkdir(this.threadDir(input.threadId), { recursive: true });
         await mkdir(path.join(this.runDir(input.threadId, input.runId), "events"), { recursive: true });
         const steps = [];
@@ -506,12 +516,13 @@ export class SqlitePersistence {
         }
         steps.push({
             sql: `INSERT OR REPLACE INTO runs
-       (run_id, thread_id, agent_id, execution_mode, adapter_kind, created_at, updated_at, state, previous_state, state_entered_at, last_transition_at, resumable, checkpoint_ref)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+       (run_id, thread_id, agent_id, parent_run_id, execution_mode, adapter_kind, created_at, updated_at, state, previous_state, state_entered_at, last_transition_at, resumable, checkpoint_ref)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
             args: [
                 input.runId,
                 input.threadId,
                 input.agentId,
+                parentRunId,
                 input.executionMode,
                 input.adapterKind ?? input.executionMode ?? null,
                 input.createdAt,
@@ -562,13 +573,15 @@ export class SqlitePersistence {
         await this.executeTransaction(steps);
     }
     async createRun(input) {
+        const parentRunId = (await this.getThreadMeta(input.threadId))?.latestRunId ?? null;
         await mkdir(path.join(this.runDir(input.threadId, input.runId), "events"), { recursive: true });
         await this.execute(`INSERT OR REPLACE INTO runs
-       (run_id, thread_id, agent_id, execution_mode, adapter_kind, created_at, updated_at, state, previous_state, state_entered_at, last_transition_at, resumable, checkpoint_ref)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+       (run_id, thread_id, agent_id, parent_run_id, execution_mode, adapter_kind, created_at, updated_at, state, previous_state, state_entered_at, last_transition_at, resumable, checkpoint_ref)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
             input.runId,
             input.threadId,
             input.agentId,
+            parentRunId,
             input.executionMode,
             input.adapterKind ?? input.executionMode ?? null,
             input.createdAt,
@@ -698,7 +711,7 @@ export class SqlitePersistence {
             ["runs.thread_id = ?", filter.threadId],
             ["runs.state = ?", filter.state],
         ]);
-        const rows = await this.selectAll(`SELECT runs.run_id, runs.thread_id, runs.agent_id, runs.execution_mode, runs.adapter_kind, runs.created_at, runs.updated_at, runs.state, runs.checkpoint_ref, runs.resumable,
+        const rows = await this.selectAll(`SELECT runs.run_id, runs.thread_id, runs.agent_id, runs.parent_run_id, runs.execution_mode, runs.adapter_kind, runs.created_at, runs.updated_at, runs.state, runs.checkpoint_ref, runs.resumable,
               run_inspection.started_at, run_inspection.ended_at, run_inspection.last_activity_at, run_inspection.current_agent_id, run_inspection.delegation_chain_json, run_inspection.runtime_snapshot_json
        FROM runs
        LEFT JOIN run_inspection ON run_inspection.run_id = runs.run_id
@@ -707,7 +720,7 @@ export class SqlitePersistence {
         return rows.map((row) => this.mapRunSummary(row));
     }
     async getRun(runId) {
-        const row = await this.selectOne(`SELECT runs.run_id, runs.thread_id, runs.agent_id, runs.execution_mode, runs.adapter_kind, runs.created_at, runs.updated_at, runs.state, runs.checkpoint_ref, runs.resumable,
+        const row = await this.selectOne(`SELECT runs.run_id, runs.thread_id, runs.agent_id, runs.parent_run_id, runs.execution_mode, runs.adapter_kind, runs.created_at, runs.updated_at, runs.state, runs.checkpoint_ref, runs.resumable,
               run_inspection.started_at, run_inspection.ended_at, run_inspection.last_activity_at, run_inspection.current_agent_id, run_inspection.delegation_chain_json, run_inspection.runtime_snapshot_json
        FROM runs
        LEFT JOIN run_inspection ON run_inspection.run_id = runs.run_id
@@ -737,7 +750,7 @@ export class SqlitePersistence {
         };
     }
     async listThreadRuns(threadId) {
-        const rows = await this.selectAll(`SELECT runs.run_id, runs.thread_id, runs.agent_id, runs.execution_mode, runs.adapter_kind, runs.created_at, runs.updated_at, runs.state, runs.checkpoint_ref, runs.resumable,
+        const rows = await this.selectAll(`SELECT runs.run_id, runs.thread_id, runs.agent_id, runs.parent_run_id, runs.execution_mode, runs.adapter_kind, runs.created_at, runs.updated_at, runs.state, runs.checkpoint_ref, runs.resumable,
               run_inspection.started_at, run_inspection.ended_at, run_inspection.last_activity_at, run_inspection.current_agent_id, run_inspection.delegation_chain_json, run_inspection.runtime_snapshot_json
        FROM runs
        LEFT JOIN run_inspection ON run_inspection.run_id = runs.run_id
@@ -770,7 +783,7 @@ export class SqlitePersistence {
         return rows.map((row) => this.mapApproval(row));
     }
     async getRunMeta(threadId, runId) {
-        const row = await this.selectOne(`SELECT run_id, thread_id, agent_id, execution_mode, adapter_kind, created_at, updated_at
+        const row = await this.selectOne(`SELECT run_id, thread_id, agent_id, parent_run_id, execution_mode, adapter_kind, created_at, updated_at
        FROM runs
        WHERE thread_id = ? AND run_id = ?`, [threadId, runId]);
         if (!row) {
@@ -780,6 +793,7 @@ export class SqlitePersistence {
             runId: asString(row.run_id),
             threadId: asString(row.thread_id),
             agentId: asString(row.agent_id),
+            parentRunId: asNullableString(row.parent_run_id),
             executionMode: asString(row.execution_mode),
             adapterKind: asNullableString(row.adapter_kind) ?? undefined,
             createdAt: asString(row.created_at),

package/dist/persistence/types.d.ts

@@ -12,6 +12,7 @@ export type PersistenceRunMeta = {
     runId: string;
     threadId: string;
     agentId: string;
+    parentRunId: string | null;
     executionMode: string;
     adapterKind?: string;
     createdAt: string;

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

@@ -46,6 +46,8 @@ export async function dispatchRunListeners(stream, listeners, options) {
                 threadId: item.threadId,
                 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,8 @@ 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") {
         if (chunk.startsWith(AGENT_INTERRUPT_SENTINEL_PREFIX)) {
@@ -45,7 +46,9 @@ export async function* streamHarnessRun(options) {
     let streamActivityObserved = false;
     let nonUpstreamStreamActivityObserved = false;
     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([
@@ -69,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,
@@ -76,17 +91,24 @@ export async function* streamHarnessRun(options) {
                     binding: options.binding,
                 });
                 currentAgentId = inspection.currentAgentId;
+                currentAgentName = formatAgentName(currentAgentId);
                 delegationChain = inspection.delegationChain;
                 await options.updateRunInspection(options.threadId, options.runId, {
                     currentAgentId,
                     delegationChain,
-                    appendUpstreamEvent: normalizedChunk.event,
+                    appendUpstreamEvent: {
+                        agentId: currentAgentId,
+                        agentName: currentAgentName,
+                        event: normalizedChunk.event,
+                    },
                 });
                 yield {
                     type: "upstream-event",
                     threadId: options.threadId,
                     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,20 @@
 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;
+    }
+    const typed = event;
+    if (Object.prototype.hasOwnProperty.call(typed, "event")
+        && typeof typed.event === "object"
+        && typed.event !== null
+        && !Array.isArray(typed.event)) {
+        return typed.event;
+    }
+    return event;
+}
 function selectLatestPendingApproval(approvals) {
     return approvals
         .filter((approval) => approval.status === "pending")
@@ -8,7 +22,7 @@ function selectLatestPendingApproval(approvals) {
 }
 function buildRunInspectionProjection(upstreamEvents) {
     const reducer = createUpstreamTimelineReducer();
-    const history = upstreamEvents.flatMap((event) => reducer.consume(event));
+    const history = upstreamEvents.flatMap((event) => reducer.consume(unwrapPersistedUpstreamEvent(event)));
     return {
         upstreamEvents,
         history,
@@ -18,10 +32,15 @@ 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,
         agentId: request.agentId,
+        parentRunId: request.parentRunId,
         executionMode: request.executionMode,
         adapterKind: request.adapterKind,
         createdAt: request.createdAt,
@@ -37,6 +56,7 @@ export async function buildRequestInspectionRecord(persistence, request) {
         runtimeSnapshot: request.runtimeSnapshot,
         upstreamEvents,
         history,
+        runtimeSurface,
         runtimeTimeline: projectRuntimeTimeline(runtimeEvents, {
             threadId: request.threadId,
             runId: request.runId,
@@ -48,6 +68,7 @@ function toRunRecord(request) {
         runId: request.requestId,
         threadId: request.sessionId,
         agentId: request.agentId,
+        parentRunId: request.parentRunId,
         executionMode: request.executionMode,
         adapterKind: request.adapterKind,
         createdAt: request.createdAt,
@@ -63,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

@@ -385,6 +385,7 @@ export class AgentHarnessRuntime {
             requestId: request.runId,
             sessionId: request.threadId,
             agentId: request.agentId,
+            parentRunId: request.parentRunId,
             executionMode: request.executionMode,
             adapterKind: request.adapterKind,
             createdAt: request.createdAt,
@@ -410,6 +411,7 @@ export class AgentHarnessRuntime {
             runId: request.requestId,
             threadId: request.sessionId,
             agentId: request.agentId,
+            parentRunId: request.parentRunId,
             executionMode: request.executionMode,
             adapterKind: request.adapterKind,
             createdAt: request.createdAt,
@@ -1800,6 +1802,7 @@ function toRequestSummary(summary) {
         requestId: summary.runId,
         sessionId: summary.threadId,
         agentId: summary.agentId,
+        parentRunId: summary.parentRunId,
         executionMode: summary.executionMode,
         adapterKind: summary.adapterKind,
         createdAt: summary.createdAt,
@@ -1834,6 +1837,7 @@ function toRequestRecord(record) {
         ...toRequestSummary(record),
         upstreamEvents: record.upstreamEvents,
         history: record.history,
+        runtimeSurface: record.runtimeSurface,
         runtimeTimeline: record.runtimeTimeline,
     };
 }

package/dist/utils/agent-display.d.ts

@@ -0,0 +1 @@
+export declare function formatAgentName(agentId: string): string;

package/dist/utils/agent-display.js

@@ -0,0 +1,18 @@
+function normalizeSegment(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function formatAgentName(agentId) {
+    const normalized = normalizeSegment(agentId);
+    if (!normalized) {
+        return "Agent";
+    }
+    return normalized
+        .split(" ")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}

package/package.json

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