@botbotgo/agent-harness 0.0.95 → 0.0.97

package/dist/runtime/harness.js

@@ -2,24 +2,30 @@ import { AUTO_AGENT_ID } from "../contracts/types.js";
 import { SqlitePersistence } from "../persistence/sqlite-store.js";
 import { createPersistentId } from "../utils/id.js";
 import { AGENT_INTERRUPT_SENTINEL_PREFIX, AgentRuntimeAdapter, RuntimeOperationTimeoutError } from "./agent-runtime-adapter.js";
+import { normalizeUpstreamRuntimeEvent } from "./parsing/stream-event-parsing.js";
 import { createResourceBackendResolver, createResourceToolResolver } from "../resource/resource.js";
-import { EventBus } from "./event-bus.js";
-import { PolicyEngine } from "./policy-engine.js";
+import { EventBus } from "./harness/events/event-bus.js";
+import { PolicyEngine } from "./harness/system/policy-engine.js";
 import { getConcurrencyConfig, getRecoveryConfig, getRoutingDefaultAgentId, getRoutingRules, getRoutingSystemPrompt, isModelRoutingEnabled, matchRoutingRule, } from "../workspace/support/workspace-ref-utils.js";
-import { createHarnessEvent, createPendingApproval, heuristicRoute, inferRoutingBindings, renderRuntimeFailure, renderToolFailure, } from "./support/harness-support.js";
-import { createCheckpointerForConfig, createStoreForConfig } from "./support/runtime-factories.js";
-import { resolveCompiledEmbeddingModel, resolveCompiledEmbeddingModelRef } from "./support/embedding-models.js";
-import { resolveCompiledVectorStore, resolveCompiledVectorStoreRef } from "./support/vector-stores.js";
-import { ThreadMemorySync } from "./thread-memory-sync.js";
-import { FileBackedStore } from "./store.js";
+import { createHarnessEvent, inferRoutingBindings, renderRuntimeFailure, renderToolFailure, } from "./support/harness-support.js";
+import { ThreadMemorySync } from "./harness/system/thread-memory-sync.js";
+import { FileBackedStore } from "./harness/system/store.js";
 import { CheckpointMaintenanceLoop, discoverCheckpointMaintenanceTargets, readCheckpointMaintenanceConfig, } from "./checkpoint-maintenance.js";
-import { RuntimeRecordMaintenanceLoop, discoverRuntimeRecordMaintenanceTargets, readRuntimeRecordMaintenanceConfig, } from "./runtime-record-maintenance.js";
-import { HealthMonitor } from "./health-monitor.js";
+import { RuntimeRecordMaintenanceLoop, discoverRuntimeRecordMaintenanceTargets, readRuntimeRecordMaintenanceConfig, } from "./maintenance/runtime-record-maintenance.js";
+import { HealthMonitor } from "./harness/system/health-monitor.js";
 import { extractMessageText, normalizeMessageContent } from "../utils/message-content.js";
+import { buildPersistedRunRequest, isTerminalRunState, normalizeInvocationEnvelope, normalizeRunPriority, resolveRunListeners, toPublicApprovalRecord, } from "./harness/run/helpers.js";
+import { emitHarnessEvent, emitRunCreatedEvent, emitSyntheticFallbackEvent, persistApproval, requestApprovalAndEmitEvent, setRunStateAndEmitEvent, } from "./harness/events/events.js";
+import { appendAssistantMessage as appendLifecycleAssistantMessage, checkpointRefForState as getCheckpointRefForRunState, expirePendingApprovals as expireLifecyclePendingApprovals, finalizeCancelledRun as finalizeLifecycleCancelledRun, finalizeContinuedRun as finalizeLifecycleContinuedRun, reviewCompletedRun as reviewLifecycleCompletedRun, synthesizeCompletedRun as synthesizeLifecycleCompletedRun, } from "./harness/run/run-lifecycle.js";
+import { createContentBlocksItem as createStreamingContentBlocksItem, createToolResultKey as createStreamingToolResultKey, dispatchRunListeners as dispatchStreamingRunListeners, emitOutputDeltaAndCreateItem as emitStreamingOutputDeltaAndCreateItem, } from "./harness/events/streaming.js";
+import { buildResumePayload as buildHarnessResumePayload, resolveApprovalRecord as resolveHarnessApprovalRecord, } from "./harness/run/resume.js";
+import { dropPendingRunSlot, enqueuePendingRunSlot, shiftNextPendingRunSlot } from "./harness/run/run-queue.js";
+import { buildRoutingInput, getDefaultHostAgentId, heuristicHostRoute, resolveSelectedAgentId } from "./harness/run/routing.js";
+import { resolveCheckpointer, resolveEmbeddingModel, resolveStore, resolveStoreFromConfig, resolveVectorStore, } from "./harness/run/resources.js";
 import { createToolMcpServerFromTools, serveToolsOverStdioFromHarness } from "../mcp.js";
-import { getBindingAdapterKind, getBindingPrimaryTools, getBindingStoreConfig, isDeepAgentBinding } from "./support/compiled-binding.js";
+import { getBindingAdapterKind, getBindingPrimaryTools, getBindingStoreConfig } from "./support/compiled-binding.js";
 import { isRuntimeEntryBinding } from "./support/runtime-entry.js";
-import { describeWorkspaceInventory, listAgentSkills as listWorkspaceAgentSkills, } from "./inventory.js";
+import { describeWorkspaceInventory, listAgentSkills as listWorkspaceAgentSkills, } from "./harness/system/inventory.js";
 export class AgentHarnessRuntime {
     workspace;
     runtimeAdapterOptions;
@@ -59,22 +65,6 @@ export class AgentHarnessRuntime {
     pendingRunInsertionOrder = 0;
     pendingRunSlots = [];
     runtimeEventSequence = 0;
-    toPublicApprovalRecord(approval) {
-        const { toolCallId: _toolCallId, checkpointRef: _checkpointRef, eventRefs: _eventRefs, ...publicApproval } = approval;
-        return publicApproval;
-    }
-    normalizeInvocationEnvelope(options) {
-        const invocation = options.invocation;
-        return {
-            context: invocation?.context,
-            state: invocation?.inputs,
-            files: invocation?.attachments,
-            invocation,
-        };
-    }
-    isTerminalRunState(state) {
-        return state === "completed" || state === "failed";
-    }
     listHostBindings() {
         return inferRoutingBindings(this.workspace).hostBindings;
     }
@@ -83,90 +73,36 @@ export class AgentHarnessRuntime {
             `${this.workspace.workspaceRoot}/run-data`);
     }
     heuristicRoute(input) {
-        const { primaryBinding, secondaryBinding } = inferRoutingBindings(this.workspace);
-        return heuristicRoute(extractMessageText(input), primaryBinding, secondaryBinding);
+        return heuristicHostRoute(this.workspace, input);
     }
     getDefaultHostAgentId() {
-        const orchestraBinding = this.workspace.bindings.get(AgentHarnessRuntime.DEFAULT_HOST_AGENT_ID);
-        if (orchestraBinding && isRuntimeEntryBinding(orchestraBinding)) {
-            return orchestraBinding.agent.id;
-        }
-        return this.heuristicRoute("");
+        return getDefaultHostAgentId(this.workspace, AgentHarnessRuntime.DEFAULT_HOST_AGENT_ID);
     }
     async buildRoutingInput(input, threadId) {
-        const inputText = extractMessageText(input);
-        if (!threadId) {
-            return inputText;
-        }
-        const history = await this.persistence.listThreadMessages(threadId);
-        const priorHistory = history.filter((message) => extractMessageText(message.content).trim());
-        if (priorHistory.length === 0) {
-            return inputText;
-        }
-        const recentTurns = priorHistory.slice(-6).map((message) => {
-            const role = message.role === "assistant" ? "assistant" : "user";
-            const compact = extractMessageText(message.content).replace(/\s+/g, " ").trim();
-            return `${role}: ${compact.slice(0, 240)}`;
-        });
-        return [
-            "Recent conversation context:",
-            ...recentTurns,
-            "",
-            `Current user request: ${inputText}`,
-        ].join("\n");
+        const history = threadId ? await this.persistence.listThreadMessages(threadId) : [];
+        return buildRoutingInput(input, history);
     }
     async resolveSelectedAgentId(input, requestedAgentId, threadId) {
-        if (!requestedAgentId || requestedAgentId === AUTO_AGENT_ID) {
-            if (threadId) {
-                const thread = await this.getSession(threadId);
-                const threadBinding = thread ? this.workspace.bindings.get(thread.agentId) : undefined;
-                if (thread?.agentId && threadBinding && isRuntimeEntryBinding(threadBinding)) {
-                    return thread.agentId;
-                }
-            }
-            return this.getDefaultHostAgentId();
-        }
-        return requestedAgentId;
+        return resolveSelectedAgentId({
+            workspace: this.workspace,
+            input,
+            requestedAgentId,
+            threadId,
+            preferredHostAgentId: AgentHarnessRuntime.DEFAULT_HOST_AGENT_ID,
+            getThreadSummary: (currentThreadId) => this.getSession(currentThreadId),
+        });
     }
     resolveStore(binding) {
-        const storeConfig = binding ? getBindingStoreConfig(binding) : undefined;
-        return this.resolveStoreFromConfig(storeConfig, binding?.harnessRuntime.runRoot ?? this.defaultRunRoot()) ?? this.defaultStore;
+        return resolveStore(this.stores, this.defaultStore, this.defaultRunRoot(), (currentBinding) => currentBinding ? getBindingStoreConfig(currentBinding) : undefined, binding);
     }
     resolveStoreFromConfig(storeConfig, runRoot) {
-        const cacheKey = storeConfig ? JSON.stringify(storeConfig) : undefined;
-        if (!storeConfig || !cacheKey) {
-            return undefined;
-        }
-        const existing = this.stores.get(cacheKey);
-        if (existing) {
-            return existing;
-        }
-        const created = createStoreForConfig(storeConfig, runRoot);
-        this.stores.set(cacheKey, created);
-        return created;
+        return resolveStoreFromConfig(this.stores, storeConfig, runRoot);
     }
     async resolveEmbeddingModel(embeddingModelRef) {
-        const compiled = resolveCompiledEmbeddingModelRef(this.workspace, embeddingModelRef);
-        const existing = this.embeddingModels.get(compiled.id);
-        if (existing) {
-            return existing;
-        }
-        const resolved = await resolveCompiledEmbeddingModel(compiled, this.runtimeAdapterOptions.embeddingModelResolver);
-        this.embeddingModels.set(compiled.id, resolved);
-        return resolved;
+        return resolveEmbeddingModel(this.workspace, this.embeddingModels, embeddingModelRef, this.runtimeAdapterOptions);
     }
     async resolveVectorStore(vectorStoreRef) {
-        const compiled = resolveCompiledVectorStoreRef(this.workspace, vectorStoreRef);
-        const existing = this.vectorStores.get(compiled.id);
-        if (existing) {
-            return existing;
-        }
-        const resolved = await resolveCompiledVectorStore(this.workspace, compiled, {
-            embeddingModelResolver: this.runtimeAdapterOptions.embeddingModelResolver,
-            vectorStoreResolver: this.runtimeAdapterOptions.vectorStoreResolver,
-        });
-        this.vectorStores.set(compiled.id, resolved);
-        return resolved;
+        return resolveVectorStore(this.workspace, this.vectorStores, vectorStoreRef, this.runtimeAdapterOptions);
     }
     constructor(workspace, runtimeAdapterOptions = {}) {
         this.workspace = workspace;
@@ -189,21 +125,7 @@ export class AgentHarnessRuntime {
                     getVectorStore: (vectorStoreRef) => this.resolveVectorStore(vectorStoreRef),
                 }),
             checkpointerResolver: runtimeAdapterOptions.checkpointerResolver ??
-                ((binding) => {
-                    const key = `${binding.harnessRuntime.runRoot}:${JSON.stringify(binding.harnessRuntime.checkpointer ?? { kind: "FileCheckpointer", path: "checkpoints.json" })}`;
-                    const existing = this.checkpointers.get(key);
-                    if (existing) {
-                        return existing;
-                    }
-                    const resolvedConfig = binding.harnessRuntime.checkpointer ?? { kind: "FileCheckpointer", path: "checkpoints.json" };
-                    if (typeof resolvedConfig === "boolean") {
-                        this.checkpointers.set(key, resolvedConfig);
-                        return resolvedConfig;
-                    }
-                    const saver = createCheckpointerForConfig(resolvedConfig, binding.harnessRuntime.runRoot);
-                    this.checkpointers.set(key, saver);
-                    return saver;
-                }),
+                ((binding) => resolveCheckpointer(this.checkpointers, binding)),
             storeResolver: runtimeAdapterOptions.storeResolver ??
                 ((binding) => this.resolveStore(binding)),
             backendResolver: runtimeAdapterOptions.backendResolver ??
@@ -327,11 +249,11 @@ export class AgentHarnessRuntime {
     }
     async listApprovals(filter) {
         const approvals = await this.persistence.listApprovals(filter);
-        return approvals.map((approval) => this.toPublicApprovalRecord(approval));
+        return approvals.map((approval) => toPublicApprovalRecord(approval));
     }
     async getApproval(approvalId) {
         const approval = await this.persistence.getApproval(approvalId);
-        return approval ? this.toPublicApprovalRecord(approval) : null;
+        return approval ? toPublicApprovalRecord(approval) : null;
     }
     listAgentSkills(agentId, options = {}) {
         return listWorkspaceAgentSkills(this.workspace, agentId, options);
@@ -362,7 +284,7 @@ export class AgentHarnessRuntime {
         if (!thread) {
             return false;
         }
-        const activeRun = thread.runs.find((run) => !this.isTerminalRunState(run.state));
+        const activeRun = thread.runs.find((run) => !isTerminalRunState(run.state));
         if (activeRun) {
             throw new Error(`Cannot delete thread ${threadId} while run ${activeRun.runId} is ${activeRun.state}`);
         }
@@ -389,7 +311,8 @@ export class AgentHarnessRuntime {
         return serveToolsOverStdioFromHarness(tools, options);
     }
     async routeAgent(input, options = {}) {
-        const routingInput = await this.buildRoutingInput(input, options.threadId);
+        const routingHistory = options.threadId ? await this.persistence.listThreadMessages(options.threadId) : [];
+        const routingInput = buildRoutingInput(input, routingHistory);
         const rawInput = extractMessageText(input);
         const { primaryBinding, secondaryBinding } = inferRoutingBindings(this.workspace);
         const configuredRule = this.routingRules.find((rule) => matchRoutingRule(rawInput, rule, options));
@@ -408,7 +331,7 @@ export class AgentHarnessRuntime {
             }
         }
         if (!primaryBinding || !secondaryBinding) {
-            return heuristicRoute(rawInput, primaryBinding, secondaryBinding);
+            return heuristicHostRoute(this.workspace, rawInput);
         }
         try {
             return await this.runtimeAdapter.route(routingInput, primaryBinding, secondaryBinding, {
@@ -416,21 +339,16 @@ export class AgentHarnessRuntime {
             });
         }
         catch {
-            return heuristicRoute(rawInput, primaryBinding, secondaryBinding);
+            return heuristicHostRoute(this.workspace, rawInput);
         }
     }
     async emit(threadId, runId, sequence, eventType, payload, source = "runtime") {
-        const event = createHarnessEvent(threadId, runId, sequence, eventType, payload, source);
-        if (AgentHarnessRuntime.BACKGROUND_EVENT_TYPES.has(event.eventType)) {
-            this.trackBackgroundTask(this.persistence.appendEvent(event).catch(() => {
-                // Fail open for telemetry-style event persistence.
-            }));
-        }
-        else {
-            await this.persistence.appendEvent(event);
-        }
-        this.eventBus.publish(event);
-        return event;
+        return emitHarnessEvent({
+            persistence: this.persistence,
+            publishEvent: (event) => this.eventBus.publish(event),
+            trackBackgroundTask: (task) => this.trackBackgroundTask(task),
+            backgroundEventTypes: AgentHarnessRuntime.BACKGROUND_EVENT_TYPES,
+        }, threadId, runId, sequence, eventType, payload, source);
     }
     trackBackgroundTask(task) {
         this.backgroundTasks.add(task);
@@ -498,15 +416,7 @@ export class AgentHarnessRuntime {
         return userTurn?.content ?? "";
     }
     async appendAssistantMessage(threadId, runId, content) {
-        if (!content) {
-            return;
-        }
-        await this.persistence.appendThreadMessage(threadId, {
-            role: "assistant",
-            content,
-            runId,
-            createdAt: new Date().toISOString(),
-        });
+        return appendLifecycleAssistantMessage(this.persistence, threadId, runId, content);
     }
     async getRunCancellation(runId) {
         const control = await this.persistence.getRunControl(runId);
@@ -516,37 +426,17 @@ export class AgentHarnessRuntime {
         };
     }
     async expirePendingApprovals(threadId, runId) {
-        const approvals = await this.persistence.getRunApprovals(threadId, runId);
-        for (const approval of approvals) {
-            if (approval.status !== "pending") {
-                continue;
-            }
-            await this.persistence.resolveApproval(threadId, runId, approval.approvalId, "expired");
-            await this.emit(threadId, runId, 6, "approval.resolved", {
-                approvalId: approval.approvalId,
-                pendingActionId: approval.pendingActionId,
-                decision: "cancel",
-                toolName: approval.toolName,
-            });
-        }
+        return expireLifecyclePendingApprovals({
+            persistence: this.persistence,
+            emit: (currentThreadId, currentRunId, sequence, eventType, payload, source) => this.emit(currentThreadId, currentRunId, sequence, eventType, payload, source),
+        }, threadId, runId);
     }
     async finalizeCancelledRun(threadId, runId, previousState, reason) {
-        await this.expirePendingApprovals(threadId, runId);
-        await this.persistence.releaseRunClaim(runId);
-        await this.persistence.clearRunCancel(runId);
-        await this.persistence.clearRunRequest(threadId, runId);
-        await this.setRunStateAndEmit(threadId, runId, 104, "cancelled", {
-            previousState,
-            ...(reason ? { error: reason } : {}),
-        });
-        const runMeta = await this.persistence.getRunMeta(threadId, runId);
-        return {
-            threadId,
-            runId,
-            agentId: runMeta.agentId,
-            state: "cancelled",
-            output: reason ? `cancelled: ${reason}` : "cancelled",
-        };
+        return finalizeLifecycleCancelledRun({
+            persistence: this.persistence,
+            emit: (currentThreadId, currentRunId, sequence, eventType, payload, source) => this.emit(currentThreadId, currentRunId, sequence, eventType, payload, source),
+            setRunStateAndEmit: (currentThreadId, currentRunId, sequence, state, options) => this.setRunStateAndEmit(currentThreadId, currentRunId, sequence, state, options),
+        }, threadId, runId, previousState, reason);
     }
     async invokeWithHistory(binding, input, threadId, runId, resumePayload, priorHistory, options = {}) {
         const history = priorHistory ?? await this.loadPriorHistory(threadId, runId);
@@ -561,67 +451,12 @@ export class AgentHarnessRuntime {
             throw error;
         }
     }
-    buildPersistedRunRequest(input, invocation, priority) {
-        const envelope = invocation.invocation ?? {
-            ...(invocation.context ? { context: invocation.context } : {}),
-            ...(invocation.state ? { inputs: invocation.state } : {}),
-            ...(invocation.files ? { attachments: invocation.files } : {}),
-        };
-        return {
-            input: normalizeMessageContent(input),
-            priority: Number.isFinite(priority) ? Math.trunc(priority) : undefined,
-            invocation: envelope && Object.keys(envelope).length > 0
-                ? {
-                    ...(envelope.context ? { context: envelope.context } : {}),
-                    ...(envelope.inputs ? { inputs: envelope.inputs } : {}),
-                    ...(envelope.attachments ? { attachments: envelope.attachments } : {}),
-                    ...(envelope.capabilities ? { capabilities: envelope.capabilities } : {}),
-                }
-                : undefined,
-            savedAt: new Date().toISOString(),
-        };
-    }
-    normalizeRunPriority(priority) {
-        if (!Number.isFinite(priority)) {
-            return 0;
-        }
-        return Math.trunc(priority);
-    }
     async resolvePersistedRunPriority(threadId, runId) {
         const persisted = await this.persistence.getRunRequest(threadId, runId);
-        return this.normalizeRunPriority(persisted?.priority);
+        return normalizeRunPriority(persisted?.priority);
     }
     enqueuePendingRunSlot(entry) {
-        const previousPositions = new Map(this.pendingRunSlots
-            .filter((candidate) => Boolean(candidate.threadId && candidate.runId))
-            .map((candidate, index) => [candidate.runId, index + 1]));
-        const queuedEntry = {
-            ...entry,
-            insertionOrder: this.pendingRunInsertionOrder++,
-        };
-        this.pendingRunSlots.push(queuedEntry);
-        this.pendingRunSlots.sort((left, right) => {
-            if (right.priority !== left.priority) {
-                return right.priority - left.priority;
-            }
-            return left.insertionOrder - right.insertionOrder;
-        });
-        return this.pendingRunSlots.flatMap((candidate, index) => {
-            if (!candidate.threadId || !candidate.runId) {
-                return [];
-            }
-            const previousPosition = previousPositions.get(candidate.runId);
-            const queuePosition = index + 1;
-            if (previousPosition === undefined || previousPosition === queuePosition) {
-                return [];
-            }
-            return [{
-                    threadId: candidate.threadId,
-                    runId: candidate.runId,
-                    priority: candidate.priority,
-                    queuePosition,
-                }];
-        });
+        return enqueuePendingRunSlot(this.pendingRunSlots, entry, this.pendingRunInsertionOrder++);
     }
     async executeQueuedRun(binding, input, threadId, runId, agentId, options = {}) {
         const previousState = options.previousState ?? "running";
@@ -689,164 +524,80 @@ export class AgentHarnessRuntime {
         }
     }
     checkpointRefForState(threadId, runId, state) {
-        return state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null;
+        return getCheckpointRefForRunState(threadId, runId, state);
     }
     async finalizeContinuedRun(binding, threadId, runId, input, actual, options) {
-        let approval;
-        const finalizedActual = actual.state === "completed"
-            ? await this.synthesizeCompletedRun(binding, input, actual)
-            : actual;
-        await this.appendAssistantMessage(threadId, runId, finalizedActual.output);
-        const checkpointRef = this.checkpointRefForState(threadId, runId, actual.state);
-        await this.setRunStateAndEmit(threadId, runId, options.stateSequence, finalizedActual.state, {
-            previousState: options.previousState,
-            checkpointRef,
-        });
-        if (finalizedActual.state === "waiting_for_approval" && options.approvalSequence) {
-            approval = (await this.requestApprovalAndEmit(threadId, runId, input, finalizedActual.interruptContent, checkpointRef, options.approvalSequence)).approval;
-        }
-        if (finalizedActual.state === "completed") {
-            await this.reviewCompletedRun(binding, threadId, runId, input, finalizedActual);
-        }
-        return {
-            ...finalizedActual,
-            threadId,
-            runId,
-            approvalId: approval?.approvalId ?? finalizedActual.approvalId,
-            pendingActionId: approval?.pendingActionId ?? finalizedActual.pendingActionId,
-        };
+        return finalizeLifecycleContinuedRun({
+            persistence: this.persistence,
+            emit: (currentThreadId, currentRunId, sequence, eventType, payload, source) => this.emit(currentThreadId, currentRunId, sequence, eventType, payload, source),
+            setRunStateAndEmit: (currentThreadId, currentRunId, sequence, state, lifecycleOptions) => this.setRunStateAndEmit(currentThreadId, currentRunId, sequence, state, lifecycleOptions),
+            requestApprovalAndEmit: (currentThreadId, currentRunId, lifecycleInput, interruptContent, checkpointRef, sequence) => this.requestApprovalAndEmit(currentThreadId, currentRunId, lifecycleInput, interruptContent, checkpointRef, sequence),
+            synthesizeFinalResult: (currentBinding, lifecycleInput, lifecycleActual) => this.runtimeAdapter.synthesizeFinalResult(currentBinding, lifecycleInput, lifecycleActual),
+            reviewRunResult: (currentBinding, lifecycleInput, lifecycleActual) => this.runtimeAdapter.reviewRunResult(currentBinding, lifecycleInput, lifecycleActual),
+        }, binding, threadId, runId, input, actual, options);
     }
     async synthesizeCompletedRun(binding, input, actual) {
-        try {
-            const synthesized = await this.runtimeAdapter.synthesizeFinalResult(binding, input, actual);
-            if (!synthesized) {
-                return actual;
-            }
-            return {
-                ...actual,
-                output: synthesized.output,
-                finalMessageText: synthesized.finalMessageText,
-                metadata: {
-                    ...(typeof actual.metadata === "object" && actual.metadata ? actual.metadata : {}),
-                    finalSynthesis: {
-                        modelId: synthesized.modelId,
-                    },
-                },
-            };
-        }
-        catch {
-            return actual;
-        }
+        return synthesizeLifecycleCompletedRun({
+            synthesizeFinalResult: (currentBinding, lifecycleInput, lifecycleActual) => this.runtimeAdapter.synthesizeFinalResult(currentBinding, lifecycleInput, lifecycleActual),
+        }, binding, input, actual);
     }
     async reviewCompletedRun(binding, threadId, runId, input, actual) {
-        try {
-            const review = await this.runtimeAdapter.reviewRunResult(binding, input, actual);
-            if (!review) {
-                return;
-            }
-            await this.emit(threadId, runId, 7, "run.reviewed", {
-                modelId: review.modelId,
-                assessment: review.assessment,
-            });
-        }
-        catch {
-            // Review is advisory; do not fail the completed run if the review pass fails.
-        }
+        return reviewLifecycleCompletedRun({
+            reviewRunResult: (currentBinding, lifecycleInput, lifecycleActual) => this.runtimeAdapter.reviewRunResult(currentBinding, lifecycleInput, lifecycleActual),
+            emit: (currentThreadId, currentRunId, sequence, eventType, payload, source) => this.emit(currentThreadId, currentRunId, sequence, eventType, payload, source),
+        }, binding, threadId, runId, input, actual);
     }
     async emitOutputDeltaAndCreateItem(threadId, runId, agentId, content) {
-        await this.emit(threadId, runId, 3, "output.delta", {
-            content,
-        });
-        return {
-            type: "content",
-            threadId,
-            runId,
-            agentId,
-            content,
-        };
+        return emitStreamingOutputDeltaAndCreateItem((currentThreadId, currentRunId, sequence, eventType, payload) => this.emit(currentThreadId, currentRunId, sequence, eventType, payload), threadId, runId, agentId, content);
     }
     createContentBlocksItem(threadId, runId, agentId, contentBlocks) {
-        return {
-            type: "content-blocks",
-            threadId,
-            runId,
-            agentId,
-            contentBlocks,
-        };
+        return createStreamingContentBlocksItem(threadId, runId, agentId, contentBlocks);
     }
     createToolResultKey(toolName, output, isError) {
-        let serializedOutput = "";
-        try {
-            serializedOutput = JSON.stringify(output);
-        }
-        catch {
-            serializedOutput = String(output);
-        }
-        return JSON.stringify([toolName, serializedOutput, isError === true]);
+        return createStreamingToolResultKey(toolName, output, isError);
     }
     async emitRunCreated(threadId, runId, payload) {
-        return this.emit(threadId, runId, 1, "run.created", payload);
+        return emitRunCreatedEvent({
+            persistence: this.persistence,
+            publishEvent: (event) => this.eventBus.publish(event),
+            trackBackgroundTask: (task) => this.trackBackgroundTask(task),
+            backgroundEventTypes: AgentHarnessRuntime.BACKGROUND_EVENT_TYPES,
+        }, threadId, runId, payload);
     }
     async setRunStateAndEmit(threadId, runId, sequence, state, options) {
-        await this.persistence.setRunState(threadId, runId, state, options.checkpointRef ?? null);
-        return this.emit(threadId, runId, sequence, "run.state.changed", {
-            previousState: options.previousState,
-            state,
-            checkpointRef: options.checkpointRef ?? null,
-            ...(options.error ? { error: options.error } : {}),
-        });
+        return setRunStateAndEmitEvent({
+            persistence: this.persistence,
+            publishEvent: (event) => this.eventBus.publish(event),
+            trackBackgroundTask: (task) => this.trackBackgroundTask(task),
+            backgroundEventTypes: AgentHarnessRuntime.BACKGROUND_EVENT_TYPES,
+        }, threadId, runId, sequence, state, options);
     }
     async requestApprovalAndEmit(threadId, runId, input, interruptContent, checkpointRef, sequence) {
-        const approval = await this.persistApproval(threadId, runId, checkpointRef, input, interruptContent);
-        const event = await this.emit(threadId, runId, sequence, "approval.requested", {
-            approvalId: approval.approvalId,
-            pendingActionId: approval.pendingActionId,
-            toolName: approval.toolName,
-            toolCallId: approval.toolCallId,
-            allowedDecisions: approval.allowedDecisions,
-            checkpointRef,
-        });
-        return { approval, event };
+        return requestApprovalAndEmitEvent({
+            persistence: this.persistence,
+            publishEvent: (event) => this.eventBus.publish(event),
+            trackBackgroundTask: (task) => this.trackBackgroundTask(task),
+            backgroundEventTypes: AgentHarnessRuntime.BACKGROUND_EVENT_TYPES,
+        }, threadId, runId, input, interruptContent, checkpointRef, sequence);
     }
     async emitSyntheticFallback(threadId, runId, selectedAgentId, error, sequence = 3) {
-        await this.emit(threadId, runId, sequence, "runtime.synthetic_fallback", {
-            reason: error instanceof Error ? error.message : String(error),
-            selectedAgentId,
-        });
+        await emitSyntheticFallbackEvent({
+            persistence: this.persistence,
+            publishEvent: (event) => this.eventBus.publish(event),
+            trackBackgroundTask: (task) => this.trackBackgroundTask(task),
+            backgroundEventTypes: AgentHarnessRuntime.BACKGROUND_EVENT_TYPES,
+        }, threadId, runId, selectedAgentId, error, sequence);
     }
     async persistApproval(threadId, runId, checkpointRef, input, interruptContent) {
-        const approval = createPendingApproval(threadId, runId, checkpointRef, extractMessageText(input), interruptContent);
-        await this.persistence.createApproval(approval);
-        const artifact = await this.persistence.createArtifact(threadId, runId, {
-            artifactId: `artifact-approval-${runId}`,
-            kind: "approval-packet",
-            path: `artifacts/approval-${runId}.json`,
-            createdAt: approval.requestedAt,
-        }, approval);
-        await this.emit(threadId, runId, 5, "artifact.created", {
-            artifactId: artifact.artifactId,
-            kind: artifact.kind,
-            path: artifact.path,
-        });
-        return approval;
+        return persistApproval({
+            persistence: this.persistence,
+            publishEvent: (event) => this.eventBus.publish(event),
+            trackBackgroundTask: (task) => this.trackBackgroundTask(task),
+            backgroundEventTypes: AgentHarnessRuntime.BACKGROUND_EVENT_TYPES,
+        }, threadId, runId, checkpointRef, input, interruptContent);
     }
     async resolveApprovalRecord(options, thread) {
-        if (options.approvalId) {
-            const approval = await this.persistence.getApproval(options.approvalId);
-            if (!approval) {
-                throw new Error(`Unknown approval ${options.approvalId}`);
-            }
-            return approval;
-        }
-        const runId = options.runId ?? thread.latestRunId;
-        const approvals = await this.persistence.getRunApprovals(options.threadId ?? thread.threadId, runId);
-        const approval = approvals
-            .filter((candidate) => candidate.status === "pending")
-            .sort((left, right) => right.requestedAt.localeCompare(left.requestedAt))[0];
-        if (!approval) {
-            throw new Error(`No pending approval for run ${runId}`);
-        }
-        return approval;
+        return resolveHarnessApprovalRecord(this.persistence, options, thread);
     }
     isDecisionRun(options) {
         return "decision" in options;
@@ -926,7 +677,7 @@ export class AgentHarnessRuntime {
                 released = true;
                 await releaseLease();
                 this.activeRunSlots = Math.max(0, this.activeRunSlots - 1);
-                const next = this.pendingRunSlots.shift();
+                const next = shiftNextPendingRunSlot(this.pendingRunSlots);
                 void next?.activate();
             };
         }
@@ -1008,81 +759,18 @@ export class AgentHarnessRuntime {
             released = true;
             await releaseLease();
             this.activeRunSlots = Math.max(0, this.activeRunSlots - 1);
-            const next = this.pendingRunSlots.shift();
+            const next = shiftNextPendingRunSlot(this.pendingRunSlots);
             void next?.activate();
         };
     }
     dropPendingRunSlot(runId) {
-        const index = this.pendingRunSlots.findIndex((entry) => entry.runId === runId);
-        if (index < 0) {
-            return false;
-        }
-        const [entry] = this.pendingRunSlots.splice(index, 1);
-        entry?.abort();
-        return true;
+        return dropPendingRunSlot(this.pendingRunSlots, runId);
     }
     async dispatchRunListeners(stream, listeners) {
-        let latestEvent;
-        let latestResult;
-        let output = "";
-        for await (const item of stream) {
-            if (item.type === "event") {
-                latestEvent = item.event;
-                await this.notifyListener(listeners.onEvent, item.event);
-                continue;
-            }
-            if (item.type === "result") {
-                latestResult = item.result;
-                continue;
-            }
-            if (item.type === "content") {
-                output += item.content;
-                await this.notifyListener(listeners.onChunk, item.content);
-                continue;
-            }
-            if (item.type === "content-blocks") {
-                await this.notifyListener(listeners.onContentBlocks, item.contentBlocks);
-                continue;
-            }
-            if (item.type === "reasoning") {
-                await this.notifyListener(listeners.onReasoning, item.content);
-                continue;
-            }
-            if (item.type === "step") {
-                await this.notifyListener(listeners.onStep, item.content);
-                continue;
-            }
-            if (item.type === "tool-result") {
-                await this.notifyListener(listeners.onToolResult, {
-                    toolName: item.toolName,
-                    output: item.output,
-                    isError: item.isError,
-                });
-            }
-        }
-        if (!latestEvent) {
-            throw new Error("run did not emit any events");
-        }
-        if (latestResult) {
-            return {
-                ...latestResult,
-                output: latestResult.output || output,
-                finalMessageText: latestResult.finalMessageText ?? latestResult.output ?? output,
-            };
-        }
-        const thread = await this.getThread(latestEvent.threadId);
-        if (!thread) {
-            throw new Error(`Unknown thread ${latestEvent.threadId}`);
-        }
-        return {
-            threadId: thread.threadId,
-            runId: thread.latestRunId,
-            agentId: thread.runs[0]?.agentId ?? thread.entryAgentId,
-            state: thread.currentState,
-            output,
-            approvalId: thread.pendingDecision?.approvalId,
-            pendingActionId: thread.pendingDecision?.pendingActionId,
-        };
+        return dispatchStreamingRunListeners(stream, listeners, {
+            notifyListener: (listener, value) => this.notifyListener(listener, value),
+            getThread: (threadId) => this.getThread(threadId),
+        });
     }
     async run(options) {
         if (this.isDecisionRun(options)) {
@@ -1095,11 +783,19 @@ export class AgentHarnessRuntime {
             };
             return this.resume(resumeOptions);
         }
-        if (options.listeners) {
-            return this.dispatchRunListeners(this.streamEvents(options), options.listeners);
+        const resolvedListeners = resolveRunListeners(options);
+        if (resolvedListeners) {
+            return this.dispatchRunListeners(this.streamEvents(options), resolvedListeners);
         }
-        const invocation = this.normalizeInvocationEnvelope(options);
-        const selectedAgentId = await this.resolveSelectedAgentId(options.input, options.agentId, options.threadId);
+        const invocation = normalizeInvocationEnvelope(options);
+        const selectedAgentId = await resolveSelectedAgentId({
+            workspace: this.workspace,
+            input: options.input,
+            requestedAgentId: options.agentId,
+            threadId: options.threadId,
+            preferredHostAgentId: AgentHarnessRuntime.DEFAULT_HOST_AGENT_ID,
+            getThreadSummary: (threadId) => this.getSession(threadId),
+        });
         const binding = this.workspace.bindings.get(selectedAgentId);
         if (!binding) {
             throw new Error(`Unknown agent ${selectedAgentId}`);
@@ -1108,8 +804,8 @@ export class AgentHarnessRuntime {
         if (!policyDecision.allowed) {
             throw new Error(`Policy evaluation blocked agent ${selectedAgentId}: ${policyDecision.reasons.join(", ")}`);
         }
-        const priority = this.normalizeRunPriority(options.priority);
-        const runRequest = this.buildPersistedRunRequest(options.input, invocation, priority);
+        const priority = normalizeRunPriority(options.priority);
+        const runRequest = buildPersistedRunRequest(options.input, invocation, priority);
         const { threadId, runId, isNewThread } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, runRequest, options.threadId);
         const runCreatedEventPromise = this.emitRunCreated(threadId, runId, {
             agentId: binding.agent.id,
@@ -1136,8 +832,15 @@ export class AgentHarnessRuntime {
         }
     }
     async *streamEvents(options) {
-        const invocation = this.normalizeInvocationEnvelope(options);
-        const selectedAgentId = await this.resolveSelectedAgentId(options.input, options.agentId, options.threadId);
+        const invocation = normalizeInvocationEnvelope(options);
+        const selectedAgentId = await resolveSelectedAgentId({
+            workspace: this.workspace,
+            input: options.input,
+            requestedAgentId: options.agentId,
+            threadId: options.threadId,
+            preferredHostAgentId: AgentHarnessRuntime.DEFAULT_HOST_AGENT_ID,
+            getThreadSummary: (threadId) => this.getSession(threadId),
+        });
         const binding = this.workspace.bindings.get(selectedAgentId);
         if (!binding) {
             const result = await this.run(options);
@@ -1154,8 +857,8 @@ export class AgentHarnessRuntime {
         }
         let emitted = false;
         let streamActivityObserved = false;
-        const priority = this.normalizeRunPriority(options.priority);
-        const runRequest = this.buildPersistedRunRequest(options.input, invocation, priority);
+        const priority = normalizeRunPriority(options.priority);
+        const runRequest = buildPersistedRunRequest(options.input, invocation, priority);
         const { threadId, runId, isNewThread } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, runRequest, options.threadId);
         const priorHistoryPromise = Promise.resolve(isNewThread ? [] : undefined).then((historyHint) => historyHint ?? this.loadPriorHistory(threadId, runId));
         const runCreatedEventPromise = this.emitRunCreated(threadId, runId, {
@@ -1191,6 +894,18 @@ export class AgentHarnessRuntime {
                                 ? { kind: "interrupt", content: chunk.slice(AGENT_INTERRUPT_SENTINEL_PREFIX.length) }
                                 : { kind: "content", content: chunk }
                             : chunk;
+                        if (normalizedChunk.kind === "upstream-event") {
+                            yield {
+                                type: "upstream-event",
+                                threadId,
+                                runId,
+                                agentId: selectedAgentId,
+                                event: normalizedChunk.event.format === "langgraph-v2"
+                                    ? normalizedChunk.event
+                                    : normalizeUpstreamRuntimeEvent(normalizedChunk.event.raw ?? normalizedChunk.event),
+                            };
+                            continue;
+                        }
                         if (normalizedChunk.kind === "interrupt") {
                             const checkpointRef = `checkpoints/${threadId}/${runId}/cp-1`;
                             const waitingEvent = await this.setRunStateAndEmit(threadId, runId, 6, "waiting_for_approval", {
@@ -1490,41 +1205,7 @@ export class AgentHarnessRuntime {
         }
     }
     buildResumePayload(binding, approval, options) {
-        if (!isDeepAgentBinding(binding)) {
-            return options.decision === "edit" && options.editedInput
-                ? { decision: "edit", editedInput: options.editedInput }
-                : (options.decision ?? "approve");
-        }
-        const decisionType = options.decision ?? "approve";
-        if (decisionType === "edit" && options.editedInput) {
-            return {
-                decisions: [
-                    {
-                        type: "edit",
-                        editedAction: {
-                            name: approval.toolName,
-                            args: options.editedInput,
-                        },
-                    },
-                ],
-            };
-        }
-        if (decisionType === "reject") {
-            return {
-                decisions: [
-                    {
-                        type: "reject",
-                    },
-                ],
-            };
-        }
-        return {
-            decisions: [
-                {
-                    type: "approve",
-                },
-            ],
-        };
+        return buildHarnessResumePayload(binding, approval, options);
     }
     async restartConversation(options) {
         const thread = await this.getSession(options.threadId);
@@ -1567,7 +1248,7 @@ export class AgentHarnessRuntime {
         if (!run) {
             throw new Error(`Unknown run ${options.runId}`);
         }
-        if (this.isTerminalRunState(run.state)) {
+        if (isTerminalRunState(run.state)) {
             return {
                 threadId: run.threadId,
                 runId: run.runId,
@@ -1616,7 +1297,7 @@ export class AgentHarnessRuntime {
                     });
                     continue;
                 }
-                const releaseRunSlot = await this.acquireRunSlot(thread.threadId, thread.latestRunId, "running", this.normalizeRunPriority(request.priority));
+                const releaseRunSlot = await this.acquireRunSlot(thread.threadId, thread.latestRunId, "running", normalizeRunPriority(request.priority));
                 try {
                     await this.executeQueuedRun(binding, request.input, thread.threadId, thread.latestRunId, runMeta.agentId, {
                         context: request.invocation?.context,
@@ -1659,7 +1340,7 @@ export class AgentHarnessRuntime {
                     await this.persistence.releaseRunClaim(thread.latestRunId);
                     continue;
                 }
-                const releaseRunSlot = await this.acquireRunSlot(thread.threadId, thread.latestRunId, "running", this.normalizeRunPriority(request.priority));
+                const releaseRunSlot = await this.acquireRunSlot(thread.threadId, thread.latestRunId, "running", normalizeRunPriority(request.priority));
                 try {
                     await this.emit(thread.threadId, thread.latestRunId, 100, "run.resumed", {
                         resumeKind: "startup-running-recovery",