@botbotgo/agent-harness 0.0.250 → 0.0.252

package/dist/persistence/file-store.js

@@ -1,6 +1,5 @@
 import path from "node:path";
-import { rm } from "node:fs/promises";
-import { readdir } from "node:fs/promises";
+import { appendFile, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { ensureDir, fileExists, readJson, writeJson } from "../utils/fs.js";
 function nowIso() {
     return new Date(Date.now()).toISOString();
@@ -25,6 +24,9 @@ export class FilePersistence {
     runControlPath(runId) {
         return path.join(this.runRoot, "indexes", "run-control", `${runId}.json`);
     }
+    traceItemsPath(threadId, runId) {
+        return path.join(this.runDir(threadId, runId), "trace-items.ndjson");
+    }
     async initialize() {
         await Promise.all([
             "indexes/threads",
@@ -93,12 +95,13 @@ export class FilePersistence {
             currentAgentId: input.currentAgentId ?? input.agentId,
             delegationChain: input.delegationChain ?? [input.currentAgentId ?? input.agentId],
             runtimeSnapshot: input.runtimeSnapshot ?? null,
-            upstreamEvents: [],
+            traceItems: [],
         };
         await Promise.all([
             writeJson(path.join(runDir, "meta.json"), meta),
             writeJson(path.join(runDir, "lifecycle.json"), lifecycle),
             writeJson(path.join(runDir, "inspection.json"), inspection),
+            writeFile(this.traceItemsPath(input.threadId, input.runId), "", "utf8"),
             writeJson(path.join(runDir, "checkpoint-ref.json"), {
                 threadId: input.threadId,
                 runId: input.runId,
@@ -401,14 +404,17 @@ export class FilePersistence {
         const inspection = await readJson(path.join(this.runDir(threadId, runId), "inspection.json"));
         return {
             ...inspection,
-            upstreamEvents: Array.isArray(inspection.upstreamEvents) ? inspection.upstreamEvents : [],
+            traceItems: (await this.listRunTraceItems(threadId, runId))
+                ?? (Array.isArray(inspection.traceItems)
+                    ? inspection.traceItems
+                    : Array.isArray(inspection.upstreamEvents)
+                        ? inspection.upstreamEvents
+                        : []),
         };
     }
     async updateRunInspection(threadId, runId, patch) {
         const inspectionPath = path.join(this.runDir(threadId, runId), "inspection.json");
-        const current = await this.getRunInspection(threadId, runId);
-        const nextUpstreamEvents = patch.upstreamEvents
-            ?? (patch.appendUpstreamEvent === undefined ? current.upstreamEvents : [...current.upstreamEvents, patch.appendUpstreamEvent]);
+        const current = await readJson(inspectionPath);
         await writeJson(inspectionPath, {
             ...current,
             ...(patch.endedAt !== undefined ? { endedAt: patch.endedAt } : {}),
@@ -416,9 +422,29 @@ export class FilePersistence {
             ...(patch.currentAgentId !== undefined ? { currentAgentId: patch.currentAgentId } : {}),
             ...(patch.delegationChain ? { delegationChain: patch.delegationChain } : {}),
             ...(patch.runtimeSnapshot !== undefined ? { runtimeSnapshot: patch.runtimeSnapshot } : {}),
-            upstreamEvents: nextUpstreamEvents,
+            traceItems: Array.isArray(current.traceItems) ? current.traceItems : [],
         });
     }
+    async appendRunTraceItem(threadId, runId, item) {
+        await appendFile(this.traceItemsPath(threadId, runId), `${JSON.stringify(item)}\n`, "utf8");
+    }
+    async listRunTraceItems(threadId, runId) {
+        const traceItemsPath = this.traceItemsPath(threadId, runId);
+        if (await fileExists(traceItemsPath)) {
+            const contents = await readFile(traceItemsPath, "utf8");
+            return contents
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0)
+                .map((line) => JSON.parse(line));
+        }
+        const inspection = await readJson(path.join(this.runDir(threadId, runId), "inspection.json"));
+        return Array.isArray(inspection.traceItems)
+            ? inspection.traceItems
+            : Array.isArray(inspection.upstreamEvents)
+                ? inspection.upstreamEvents
+                : [];
+    }
     async deleteThread(threadId) {
         const threadDir = this.threadDir(threadId);
         const threadIndexPath = this.threadIndexPath(threadId);

package/dist/persistence/sqlite-store.d.ts

@@ -82,9 +82,9 @@ export declare class SqlitePersistence implements RuntimePersistence {
         currentAgentId?: string | null;
         delegationChain?: string[];
         runtimeSnapshot?: RunSummary["runtimeSnapshot"] | null;
-        upstreamEvents?: unknown[];
-        appendUpstreamEvent?: unknown;
     }): Promise<void>;
+    appendRunTraceItem(threadId: string, runId: string, item: unknown): Promise<void>;
+    listRunTraceItems(threadId: string, runId: string): Promise<unknown[]>;
     deleteThread(threadId: string): Promise<boolean>;
     saveRunRequest(threadId: string, runId: string, request: PersistedRunRequest): Promise<void>;
     getRunRequest(threadId: string, runId: string): Promise<PersistedRunRequest | null>;

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 = 5;
+const RUNTIME_SQLITE_SCHEMA_VERSION = 6;
 const RUNTIME_SQLITE_SCHEMA_FAMILY = "agent-harness-runtime";
 function asRow(value) {
     return value;
@@ -196,11 +196,24 @@ export class SqlitePersistence {
           FOREIGN KEY (thread_id) REFERENCES threads(thread_id),
           FOREIGN KEY (run_id) REFERENCES runs(run_id)
         )
+      `);
+            await this.rawExecute(`
+        CREATE TABLE IF NOT EXISTS run_trace_items (
+          trace_id INTEGER PRIMARY KEY AUTOINCREMENT,
+          run_id TEXT NOT NULL,
+          thread_id TEXT NOT NULL,
+          item_json TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          FOREIGN KEY (thread_id) REFERENCES threads(thread_id),
+          FOREIGN KEY (run_id) REFERENCES runs(run_id)
+        )
       `);
             await this.rawExecute("CREATE INDEX IF NOT EXISTS runs_thread_updated_idx ON runs(thread_id, updated_at DESC)");
+            await this.rawExecute("CREATE INDEX IF NOT EXISTS runs_thread_created_idx ON runs(thread_id, created_at DESC)");
             await this.rawExecute("CREATE INDEX IF NOT EXISTS runs_state_updated_idx ON runs(state, updated_at DESC)");
             await this.rawExecute("CREATE INDEX IF NOT EXISTS runs_agent_updated_idx ON runs(agent_id, updated_at DESC)");
             await this.rawExecute("CREATE INDEX IF NOT EXISTS run_inspection_thread_activity_idx ON run_inspection(thread_id, last_activity_at DESC)");
+            await this.rawExecute("CREATE INDEX IF NOT EXISTS run_trace_items_thread_run_trace_idx ON run_trace_items(thread_id, run_id, trace_id)");
             await this.rawExecute(`
         CREATE TABLE IF NOT EXISTS thread_messages (
           id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -491,6 +504,23 @@ export class SqlitePersistence {
             await this.rawExecute("INSERT OR REPLACE INTO runtime_metadata (key, value) VALUES (?, ?)", ["schema_version", String(RUNTIME_SQLITE_SCHEMA_VERSION)]);
             return;
         }
+        if (version === "5") {
+            await this.rawExecute(`
+        CREATE TABLE IF NOT EXISTS run_trace_items (
+          trace_id INTEGER PRIMARY KEY AUTOINCREMENT,
+          run_id TEXT NOT NULL,
+          thread_id TEXT NOT NULL,
+          item_json TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          FOREIGN KEY (thread_id) REFERENCES threads(thread_id),
+          FOREIGN KEY (run_id) REFERENCES runs(run_id)
+        )
+      `);
+            await this.rawExecute("CREATE INDEX IF NOT EXISTS runs_thread_created_idx ON runs(thread_id, created_at DESC)");
+            await this.rawExecute("CREATE INDEX IF NOT EXISTS run_trace_items_thread_run_trace_idx ON run_trace_items(thread_id, run_id, trace_id)");
+            await this.rawExecute("INSERT OR REPLACE INTO runtime_metadata (key, value) VALUES (?, ?)", ["schema_version", String(RUNTIME_SQLITE_SCHEMA_VERSION)]);
+            return;
+        }
         if (version !== String(RUNTIME_SQLITE_SCHEMA_VERSION)) {
             throw new Error(`Unsupported runtime sqlite schema version ${JSON.stringify(version)} in ${this.dbPath}. Expected ${RUNTIME_SQLITE_SCHEMA_VERSION}.`);
         }
@@ -830,26 +860,48 @@ export class SqlitePersistence {
             currentAgentId: asNullableString(row.current_agent_id),
             delegationChain: parseJson(row.delegation_chain_json),
             runtimeSnapshot: row.runtime_snapshot_json ? parseJson(row.runtime_snapshot_json) : null,
-            upstreamEvents: row.upstream_events_json ? parseJson(row.upstream_events_json) : [],
+            traceItems: await this.listRunTraceItems(threadId, runId),
         };
     }
     async updateRunInspection(threadId, runId, patch) {
-        const current = await this.getRunInspection(threadId, runId);
-        const nextUpstreamEvents = patch.upstreamEvents
-            ?? (patch.appendUpstreamEvent === undefined ? current.upstreamEvents : [...current.upstreamEvents, patch.appendUpstreamEvent]);
+        const row = await this.selectOne(`SELECT ended_at, last_activity_at, current_agent_id, delegation_chain_json, runtime_snapshot_json
+       FROM run_inspection
+       WHERE run_id = ? AND thread_id = ?`, [runId, threadId]);
+        if (!row) {
+            throw new Error(`Missing run inspection ${runId} for thread ${threadId}`);
+        }
         await this.execute(`UPDATE run_inspection
        SET ended_at = ?, last_activity_at = ?, current_agent_id = ?, delegation_chain_json = ?, runtime_snapshot_json = ?, upstream_events_json = ?
        WHERE run_id = ? AND thread_id = ?`, [
-            patch.endedAt === undefined ? current.endedAt : patch.endedAt,
-            patch.lastActivityAt ?? current.lastActivityAt,
-            patch.currentAgentId === undefined ? current.currentAgentId : patch.currentAgentId,
-            JSON.stringify(patch.delegationChain ?? current.delegationChain),
-            JSON.stringify(patch.runtimeSnapshot === undefined ? current.runtimeSnapshot : patch.runtimeSnapshot),
-            JSON.stringify(nextUpstreamEvents),
+            patch.endedAt === undefined ? asNullableString(row.ended_at) : patch.endedAt,
+            patch.lastActivityAt ?? asString(row.last_activity_at),
+            patch.currentAgentId === undefined ? asNullableString(row.current_agent_id) : patch.currentAgentId,
+            JSON.stringify(patch.delegationChain ?? parseJson(row.delegation_chain_json)),
+            JSON.stringify(patch.runtimeSnapshot === undefined
+                ? (row.runtime_snapshot_json ? parseJson(row.runtime_snapshot_json) : null)
+                : patch.runtimeSnapshot),
+            "[]",
             runId,
             threadId,
         ]);
     }
+    async appendRunTraceItem(threadId, runId, item) {
+        await this.execute(`INSERT INTO run_trace_items (run_id, thread_id, item_json, created_at)
+       VALUES (?, ?, ?, ?)`, [runId, threadId, JSON.stringify(item), nowIso()]);
+    }
+    async listRunTraceItems(threadId, runId) {
+        const rows = await this.selectAll(`SELECT item_json
+       FROM run_trace_items
+       WHERE thread_id = ? AND run_id = ?
+       ORDER BY trace_id ASC`, [threadId, runId]);
+        if (rows.length > 0) {
+            return rows.map((row) => parseJson(row.item_json));
+        }
+        const row = await this.selectOne(`SELECT upstream_events_json
+       FROM run_inspection
+       WHERE thread_id = ? AND run_id = ?`, [threadId, runId]);
+        return row?.upstream_events_json ? parseJson(row.upstream_events_json) : [];
+    }
     async deleteThread(threadId) {
         const exists = await this.getSession(threadId);
         if (!exists) {
@@ -858,6 +910,7 @@ export class SqlitePersistence {
         await this.execute("DELETE FROM artifacts WHERE thread_id = ?", [threadId]);
         await this.execute("DELETE FROM approvals WHERE thread_id = ?", [threadId]);
         await this.execute("DELETE FROM events WHERE thread_id = ?", [threadId]);
+        await this.execute("DELETE FROM run_trace_items WHERE thread_id = ?", [threadId]);
         await this.execute("DELETE FROM run_inspection WHERE thread_id = ?", [threadId]);
         await this.execute("DELETE FROM run_queue WHERE thread_id = ?", [threadId]);
         await this.execute("DELETE FROM run_requests WHERE thread_id = ?", [threadId]);

package/dist/persistence/types.d.ts

@@ -33,7 +33,7 @@ export type PersistedRunInspection = {
     currentAgentId: string | null;
     delegationChain: string[];
     runtimeSnapshot: RuntimeSnapshot | null;
-    upstreamEvents: unknown[];
+    traceItems: unknown[];
 };
 export type PersistedRunRequest = {
     input: MessageContent;
@@ -142,15 +142,15 @@ export interface RuntimePersistence {
     getRunMeta(threadId: string, runId: string): Promise<PersistenceRunMeta>;
     getRunLifecycle(threadId: string, runId: string): Promise<PersistenceLifecycle>;
     getRunInspection(threadId: string, runId: string): Promise<PersistedRunInspection>;
+    listRunTraceItems(threadId: string, runId: string): Promise<unknown[]>;
     updateRunInspection(threadId: string, runId: string, patch: {
         endedAt?: string | null;
         lastActivityAt?: string;
         currentAgentId?: string | null;
         delegationChain?: string[];
         runtimeSnapshot?: RuntimeSnapshot | null;
-        upstreamEvents?: unknown[];
-        appendUpstreamEvent?: unknown;
     }): Promise<void>;
+    appendRunTraceItem(threadId: string, runId: string, item: unknown): Promise<void>;
     deleteThread(threadId: string): Promise<boolean>;
     saveRunRequest(threadId: string, runId: string, request: PersistedRunRequest): Promise<void>;
     getRunRequest(threadId: string, runId: string): Promise<PersistedRunRequest | null>;

package/dist/protocol/a2a/http.js

@@ -382,8 +382,7 @@ function toSessionRecord(session) {
             currentAgentId: run.currentAgentId,
             delegationChain: run.delegationChain,
             runtimeSnapshot: run.runtimeSnapshot,
-            upstreamEvents: run.upstreamEvents,
-            history: run.history,
+            traceItems: run.traceItems,
             runtimeTimeline: run.runtimeTimeline,
         })),
         pendingDecision: session.pendingDecision,
@@ -410,8 +409,7 @@ function toRequestRecord(request) {
         currentAgentId: request.currentAgentId,
         delegationChain: request.delegationChain,
         runtimeSnapshot: request.runtimeSnapshot,
-        upstreamEvents: request.upstreamEvents,
-        history: request.history,
+        traceItems: request.traceItems,
         runtimeTimeline: request.runtimeTimeline,
     };
 }

package/dist/resource/isolation.js

@@ -29,11 +29,39 @@ function dependencyLinkPath(isolatedRoot, dependencyName) {
 function dependencyPackageRoot(packageJsonPath) {
     return path.dirname(packageJsonPath);
 }
-function resolveDeclaredDependency(packageRoot, dependencyName) {
+function declaredDependencySpec(manifest, dependencyName) {
+    return manifest.dependencies?.[dependencyName]
+        ?? manifest.optionalDependencies?.[dependencyName]
+        ?? manifest.peerDependencies?.[dependencyName]
+        ?? null;
+}
+function resolveDeclaredFileDependency(packageRoot, spec) {
+    if (!spec.startsWith("file:")) {
+        return null;
+    }
+    const relativePath = spec.slice("file:".length).trim();
+    if (!relativePath) {
+        return null;
+    }
+    const resolvedPath = path.resolve(packageRoot, relativePath);
+    const packageJsonPath = resolvedPath.endsWith("package.json")
+        ? resolvedPath
+        : path.join(resolvedPath, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        return null;
+    }
+    return dependencyPackageRoot(packageJsonPath);
+}
+function resolveDeclaredDependency(packageRoot, manifest, dependencyName) {
     const localPath = path.join(packageRoot, "node_modules", ...dependencyName.split("/"), "package.json");
     if (existsSync(localPath)) {
         return dependencyPackageRoot(localPath);
     }
+    const declaredSpec = declaredDependencySpec(manifest, dependencyName);
+    const localFileDependency = declaredSpec ? resolveDeclaredFileDependency(packageRoot, declaredSpec) : null;
+    if (localFileDependency) {
+        return localFileDependency;
+    }
     try {
         const requireFromPackage = createRequire(path.join(packageRoot, "package.json"));
         return dependencyPackageRoot(requireFromPackage.resolve(`${dependencyName}/package.json`));
@@ -44,7 +72,7 @@ function resolveDeclaredDependency(packageRoot, dependencyName) {
 }
 async function linkDeclaredDependencies(isolatedRoot, packageRoot, manifest) {
     for (const dependencyName of declaredDependencyNames(manifest)) {
-        const resolved = resolveDeclaredDependency(packageRoot, dependencyName);
+        const resolved = resolveDeclaredDependency(packageRoot, manifest, dependencyName);
         if (!resolved) {
             continue;
         }

package/dist/resource/resource-impl.js

@@ -418,10 +418,7 @@ async function runFunctionToolInSubprocess(config, input, context) {
     return await new Promise((resolve, reject) => {
         const child = spawn(config.command, config.args, {
             cwd: config.cwd,
-            env: {
-                ...process.env,
-                ...(config.env ?? {}),
-            },
+            env: createRuntimeEnv(config.env, process.env),
             stdio: ["pipe", "pipe", "pipe"],
         });
         let stdout = "";

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

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

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

@@ -21,9 +21,11 @@ export declare function projectRuntimeSurfaceFromSingleUpstreamEvent(input: {
     binding?: CompiledAgentBinding;
     currentAgentId: string;
     currentAgentName?: string;
+    delegationChain?: string[];
     sourceEventId: string;
 }): {
     currentAgentId: string;
     currentAgentName: string;
+    delegationChain: string[];
     items: RuntimeSurfaceItem[];
 };

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

@@ -3,37 +3,19 @@ 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";
+import { buildSurfaceId, resolveSurfaceAction, resolveSurfaceDisplayName, } from "./surface-semantics.js";
 function asObject(value) {
     return typeof value === "object" && value !== null ? value : null;
 }
 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 isTaskDelegationCompletionEvent(event) {
+    const eventName = typeof event.event === "string" ? event.event : "";
+    const name = typeof event.name === "string" ? event.name : "";
+    const runType = typeof event.run_type === "string" ? event.run_type : "";
+    return ((eventName === "on_tool_end" && name === "task")
+        || (eventName === "on_chain_end" && runType === "tool" && name === "task"));
 }
 function readTracingConfig(binding) {
     const deepAgentTracing = asObject(binding.harnessRuntime?.deepagent?.passthrough)?.tracing;
@@ -216,16 +198,19 @@ export function projectRuntimeSurfaceFromUpstreamEvents(input) {
     const items = [];
     let currentAgentId = input.initialAgentId;
     let currentAgentName = formatAgentName(currentAgentId);
+    let delegationChain = [input.initialAgentId];
     for (const [index, rawEvent] of input.upstreamEvents.entries()) {
         const projected = projectRuntimeSurfaceFromSingleUpstreamEvent({
             event: rawEvent,
             binding: input.binding,
             currentAgentId,
             currentAgentName,
+            delegationChain,
             sourceEventId: `upstream:${index + 1}`,
         });
         currentAgentId = projected.currentAgentId;
         currentAgentName = projected.currentAgentName;
+        delegationChain = projected.delegationChain;
         items.push(...projected.items);
     }
     return items;
@@ -235,49 +220,93 @@ export function projectRuntimeSurfaceFromSingleUpstreamEvent(input) {
     const items = [];
     let currentAgentId = input.currentAgentId;
     let currentAgentName = input.currentAgentName ?? formatAgentName(currentAgentId);
+    let delegationChain = input.delegationChain ?? [input.currentAgentId];
     const unwrapped = unwrapUpstreamEvent(input.event);
     if (unwrapped.agentId) {
-        if (unwrapped.agentId !== currentAgentId) {
-            const nextAgentName = unwrapped.agentName ?? formatAgentName(unwrapped.agentId);
+        currentAgentId = unwrapped.agentId;
+        currentAgentName = unwrapped.agentName ?? formatAgentName(currentAgentId);
+        if (unwrapped.agentId !== input.currentAgentId) {
             items.push({
                 kind: "agent",
                 id: buildSurfaceId("agent", unwrapped.agentId),
-                name: nextAgentName,
-                label: `Delegate to ${nextAgentName}`,
-                status: "completed",
-                ownerAgentId: currentAgentId,
-                ownerAgentName: currentAgentName,
+                name: currentAgentName,
+                action: "handoff",
+                status: "started",
+                agentId: unwrapped.agentId,
+                agentName: currentAgentName,
+                ownerAgentId: input.currentAgentId,
+                ownerAgentName: input.currentAgentName ?? formatAgentName(input.currentAgentId),
                 sourceEventId: input.sourceEventId,
+                detail: {
+                    fromAgentId: input.currentAgentId,
+                    fromAgentName: input.currentAgentName ?? formatAgentName(input.currentAgentId),
+                    toAgentId: unwrapped.agentId,
+                    toAgentName: currentAgentName,
+                },
             });
         }
-        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 previousAgentId = currentAgentId;
+        const previousDelegationChain = delegationChain;
         const next = consumeRunInspectionUpstreamEvent({
             event: typed,
             currentAgentId,
-            delegationChain: [currentAgentId],
+            delegationChain,
             binding: input.binding,
         });
-        if (next.currentAgentId !== currentAgentId) {
-            currentAgentId = next.currentAgentId;
-            currentAgentName = formatAgentName(currentAgentId);
+        if (next.delegationChain.length > previousDelegationChain.length) {
+            const delegatedAgentName = formatAgentName(next.currentAgentId);
+            const ownerAgentId = previousDelegationChain.at(-1) ?? previousAgentId;
             items.push({
                 kind: "agent",
-                id: buildSurfaceId("agent", currentAgentId),
-                name: currentAgentName,
-                label: `Delegate to ${currentAgentName}`,
+                id: buildSurfaceId("agent", next.currentAgentId),
+                name: delegatedAgentName,
+                action: "handoff",
+                status: "started",
+                agentId: next.currentAgentId,
+                agentName: delegatedAgentName,
+                ownerAgentId,
+                ownerAgentName: formatAgentName(ownerAgentId),
+                sourceEventId: input.sourceEventId,
+                detail: {
+                    fromAgentId: ownerAgentId,
+                    fromAgentName: formatAgentName(ownerAgentId),
+                    toAgentId: next.currentAgentId,
+                    toAgentName: delegatedAgentName,
+                },
+            });
+        }
+        if (isTaskDelegationCompletionEvent(typed) && previousDelegationChain.length > 1) {
+            const delegatedAgentId = previousDelegationChain.at(-1);
+            const ownerAgentId = previousDelegationChain.at(-2);
+            const delegatedAgentName = formatAgentName(delegatedAgentId);
+            items.push({
+                kind: "agent",
+                id: buildSurfaceId("agent", delegatedAgentId),
+                name: delegatedAgentName,
+                action: "handoff",
                 status: "completed",
-                ownerAgentId: next.delegationChain.at(-2),
-                ownerAgentName: next.delegationChain.at(-2) ? formatAgentName(next.delegationChain.at(-2)) : undefined,
+                agentId: delegatedAgentId,
+                agentName: delegatedAgentName,
+                ...(ownerAgentId ? { ownerAgentId, ownerAgentName: formatAgentName(ownerAgentId) } : {}),
                 sourceEventId: input.sourceEventId,
+                detail: {
+                    ...(ownerAgentId
+                        ? { fromAgentId: ownerAgentId, fromAgentName: formatAgentName(ownerAgentId) }
+                        : {}),
+                    toAgentId: delegatedAgentId,
+                    toAgentName: delegatedAgentName,
+                },
             });
         }
+        currentAgentId = next.currentAgentId;
+        currentAgentName = formatAgentName(currentAgentId);
+        delegationChain = next.delegationChain;
     }
     for (const projection of reducer.consume(unwrapped.event)) {
         if (projection.type !== "step") {
@@ -287,20 +316,36 @@ export function projectRuntimeSurfaceFromSingleUpstreamEvent(input) {
         if (!kind) {
             continue;
         }
+        const displayName = resolveSurfaceDisplayName({
+            kind,
+            step: projection.step,
+            binding: input.binding,
+        });
         items.push({
             kind,
-            id: buildSurfaceId(kind, stripStepPrefix(projection.step) || projection.step),
-            name: stripStepPrefix(projection.step) || formatAgentName(kind),
-            label: projection.step,
+            id: buildSurfaceId(kind, displayName || projection.step),
+            name: displayName,
+            action: resolveSurfaceAction({
+                kind,
+                step: projection.step,
+                event: unwrapped.event,
+            }),
             status: projection.status,
+            agentId: currentAgentId,
+            agentName: currentAgentName,
             ownerAgentId: currentAgentId,
             ownerAgentName: currentAgentName,
             sourceEventId: input.sourceEventId,
+            detail: {
+                step: projection.step,
+                category: projection.category,
+            },
         });
     }
     return {
         currentAgentId,
         currentAgentName,
+        delegationChain,
         items,
     };
 }

package/dist/runtime/harness/run/stream-run.d.ts

@@ -10,6 +10,7 @@ type RuntimeStreamChunk = string | {
 };
 type StreamRunOptions = {
     binding: CompiledAgentBinding;
+    getBinding: (agentId: string) => CompiledAgentBinding | undefined;
     input: MessageContent;
     invocation: {
         context?: Record<string, unknown>;
@@ -53,9 +54,8 @@ type StreamRunOptions = {
         currentAgentId?: string | null;
         delegationChain?: string[];
         runtimeSnapshot?: RuntimeSnapshot | null;
-        upstreamEvents?: unknown[];
-        appendUpstreamEvent?: unknown;
     }) => Promise<void>;
+    appendRunTraceItem: (threadId: string, runId: string, item: unknown) => Promise<void>;
     emitSyntheticFallback: (threadId: string, runId: string, selectedAgentId: string, error: unknown) => Promise<void>;
 };
 export declare function streamHarnessRun(options: StreamRunOptions): AsyncGenerator<InternalHarnessStreamItem>;