@botbotgo/agent-harness 0.0.123 → 0.0.125

package/README.md

@@ -14,7 +14,7 @@
 # @botbotgo/agent-harness
 
 <p align="center">
-  <strong>The production runtime for multi-agent systems—built to ship, operate, and recover, not just execute.</strong>
+  <strong>The application runtime for multi-agent products with approvals, recovery, and operator control built in.</strong>
 </p>
 
 <p align="center">
@@ -29,9 +29,38 @@
   >
 </p>
 
+## What Problem We Solve
+
+AI makes it much easier to generate agent logic, tool calls, and workflow code. The hard part moves to operations.
+
+Once the demo works, the real software problem changes shape:
+
+- more generated logic creates more execution paths to inspect, interrupt, retry, and recover
+- natural-language entrypoints turn approvals and policy boundaries into runtime requirements
+- backend, prompt, and tool changes happen faster, but product-facing behavior still needs one stable control surface
+- MCP and provider-native tooling expand what agents can reach, which raises the bar for governance
+
+Teams still need answers to the runtime questions that appear after that shift:
+
+- how approvals are resolved and audited
+- how runs, threads, and events stay inspectable
+- how execution recovers after interruption, failure, or restart
+- how routing, concurrency, and maintenance policy stay consistent
+- how backend churn does not leak into the product model
+
+`agent-harness` solves that layer. It keeps agent execution upstream while making the application runtime operable, recoverable, and governable.
+
+Concretely, that means:
+
+- a product-facing approval and operator surface instead of backend-specific middleware state
+- persisted `runs`, `threads`, `approvals`, and `events` as stable runtime records
+- restart-safe recovery and continuation as system-managed behavior
+- YAML-owned routing, concurrency, maintenance, and recovery policy
+- adapter isolation so backend replacement does not redefine the public runtime model
+
 ## Product Overview
 
-`@botbotgo/agent-harness` is a workspace-shaped application runtime for real agent products.
+`@botbotgo/agent-harness` is a workspace-shaped application runtime for real multi-agent products.
 
 It is not a new agent framework. It is the runtime layer around LangChain v1 and DeepAgents that turns one workspace into one operable application runtime.
 
@@ -39,7 +68,7 @@ The point is simple:
 
 - Codex, Claude Code, and Cursor are products for people using agents
 - LangChain v1 and DeepAgents are frameworks for defining agent execution semantics
-- `agent-harness` is the runtime product layer for shipping, operating, recovering, and governing multi-agent applications
+- `agent-harness` is the runtime product layer for operating, recovering, approving, and governing multi-agent applications
 
 The product boundary is strict:
 
@@ -61,6 +90,14 @@ The runtime provides:
 - local `resources/tools/` `tool({...})` modules and `resources/skills/` discovery
 - persisted threads, runs, approvals, events, queue state, and recovery metadata
 
+In practice, the harness exists for the parts that are painful to rebuild inside every agent app:
+
+- approval inboxes and human decision flow
+- persisted runs, threads, and inspectable event history
+- runtime-managed recovery after interrupts, failures, or process restart
+- queueing, concurrency, maintenance, and operational policy
+- stable runtime records that stay usable even if the backend changes
+
 The repository-owned default config layer is intentionally full-shaped. The shipped YAML keeps explicit defaults for the important runtime and agent knobs so teams can start from concrete config instead of reverse-engineering adapter behavior from source.
 
 The default rule is:
@@ -89,7 +126,7 @@ Recommended orchestration shape for long-running flows:
 
 ## Why This Exists
 
-Most agent demos stop at execution.
+Most agent tooling stops at execution.
 
 Real products need a runtime that can answer harder questions:
 
@@ -103,9 +140,10 @@ Real products need a runtime that can answer harder questions:
 
 ## What Makes It Different
 
-- It treats `runs`, `threads`, `approvals`, `events`, and recovery as product concepts
+- It treats `runs`, `threads`, `approvals`, `events`, and recovery as first-class product records
+- It gives operators a runtime control surface instead of exposing raw backend internals
 - It keeps checkpoint resume system-managed instead of promoting checkpoint internals into the primary API
-- It lets YAML own assembly complexity while code keeps a tiny surface
+- It lets YAML own assembly and operating policy while code keeps a tiny surface
 - It goes deep on runtime concerns that upstream libraries do not fully productize
 
 ## Quick Start

package/README.zh.md

@@ -14,7 +14,7 @@
 # @botbotgo/agent-harness
 
 <p align="center">
-  <strong>面向多 agent 生产落地的运行时：为上线、运维与恢复而设计，而不止步于执行。</strong>
+  <strong>面向多 agent 产品的应用运行时：内建审批、恢复与运维控制，而不只是执行。</strong>
 </p>
 
 <p align="center">
@@ -29,9 +29,38 @@
   >
 </p>
 
+## 我们解决什么问题
+
+AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正变难的是运行时运维。
+
+当 demo 跑起来之后，真正的软件问题会换一种形状出现：
+
+- 更多生成式逻辑，意味着更多要观测、打断、重试和恢复的执行路径
+- 自然语言入口让审批与策略边界变成运行时要求，而不是事后补丁
+- backend、prompt 和工具变化更快了，但面向产品的控制面仍然必须稳定
+- MCP 与 provider 原生工具扩展了 agent 的可触达范围，也同步抬高了治理要求
+
+团队仍然要回答这些运行时问题：
+
+- 审批怎么决策、怎么审计
+- runs、threads、events 怎么稳定可查
+- 执行被打断、失败或进程重启后怎么恢复
+- 路由、并发和维护策略怎么保持一致
+- 后端频繁变化时，怎么不让产品模型跟着漂移
+
+`agent-harness` 解决的就是这一层。它把 agent 执行留在上游，同时把应用运行时做成可运维、可恢复、可治理的系统。
+
+具体来说，就是把这些能力沉到运行时里：
+
+- 面向产品的审批与运维控制面，而不是 backend 专属的中间件状态
+- 稳定持久化的 `runs`、`threads`、`approvals` 与 `events` 记录
+- 由系统托管的重启恢复与中断续跑
+- 由 YAML 持有的路由、并发、维护与恢复策略
+- 通过适配器隔离 backend 变化，不让公共运行时模型漂移
+
 ## 产品概览
 
-`@botbotgo/agent-harness` 是面向真实 agent 产品的、工作区形态的应用运行时。
+`@botbotgo/agent-harness` 是面向真实多 agent 产品的、工作区形态的应用运行时。
 
 它不是又一个 agent 框架，而是围绕 LangChain v1 与 DeepAgents 的运行时层：把一个工作区变成一套可运维的应用运行时。
 
@@ -39,7 +68,7 @@
 
 - Codex、Claude Code、Cursor 是「人用 agent」的产品
 - LangChain v1 与 DeepAgents 是定义 agent 执行语义的框架
-- `agent-harness` 是交付、运维、恢复与治理多 agent 应用的运行时产品层
+- `agent-harness` 是负责运维、恢复、审批与治理多 agent 应用的运行时产品层
 
 产品边界是清晰的：
 
@@ -61,6 +90,14 @@
 - 本地 `resources/tools/` 中 `tool({...})` 工具模块与 `resources/skills/` 的发现
 - 持久化的线程、运行、审批、事件、队列状态与恢复元数据
 
+落到实际系统里，harness 主要解决那些每个 agent 应用都不想重复造一遍的运行时难题：
+
+- 审批收件箱与人工决策流
+- 持久化的 runs、threads 与可查询事件历史
+- 中断、失败或进程重启后的运行时托管恢复
+- 队列、并发、维护与运维策略
+- 即使后端变更也保持稳定的运行时记录模型
+
 仓库自带的默认配置刻意做成「形状完整」。随仓库提供的 YAML 对重要的运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
 
 默认原则是：
@@ -89,7 +126,7 @@
 
 ## 为何需要它
 
-多数 agent 演示停在「能跑」。
+多数 agent 工具停在「能跑」。
 
 真实产品需要能回答更难问题的运行时：
 
@@ -103,10 +140,11 @@
 
 ## 有何不同
 
-- 将 `runs`、`threads`、`approvals`、`events` 与恢复视为产品概念
+- 将 `runs`、`threads`、`approvals`、`events` 与恢复视为一等产品记录
+- 给运维侧提供运行时控制面，而不是暴露原始后端内部结构
 - 将 checkpoint 恢复作为系统管理的行为，而不是把 checkpoint 细节抬成主 API
-- 复杂装配交给 YAML，代码面保持极小
-- 在上游库未充分产品化的运行时时，做深做透
+- 复杂装配与运行策略交给 YAML，代码面保持极小
+- 在上游库未充分产品化的运行时问题上做深做透
 
 ## 快速开始
 

package/dist/benchmark/upstream-runtime-ab-benchmark.d.ts

@@ -1,15 +1,23 @@
-export declare const DEFAULT_UPSTREAM_BENCHMARK_PATHS: readonly ["harness", "raw-langchain-v1", "raw-deepagent"];
+export declare const DEFAULT_UPSTREAM_BENCHMARK_PATHS: readonly ["harness", "harness-minimal-upstream", "raw-langchain-v1", "raw-deepagent"];
 export declare const DEFAULT_UPSTREAM_BENCHMARK_WORKLOAD: "tool";
+export declare const DEFAULT_UPSTREAM_BENCHMARK_SCENARIOS: readonly ["normal", "complex", "extreme"];
 export type UpstreamBenchmarkPath = (typeof DEFAULT_UPSTREAM_BENCHMARK_PATHS)[number];
 export type UpstreamBenchmarkWorkload = "tool" | "no-tool";
+export type UpstreamBenchmarkScenario = (typeof DEFAULT_UPSTREAM_BENCHMARK_SCENARIOS)[number];
 export type UpstreamBenchmarkRunSummary = {
     providerLabel: string;
     model: string;
+    scenario: UpstreamBenchmarkScenario;
     path: UpstreamBenchmarkPath;
     runNumber: number;
     status: "completed" | "failed";
     totalMs: number;
     firstTokenMs: number | null;
+    setupMs: number | null;
+    firstToolMs: number | null;
+    lastToolMs: number | null;
+    finalOutputMs: number | null;
+    cleanupMs: number | null;
     outputLength: number;
     normalizedOutputLength: number;
     toolCallCount: number;
@@ -19,6 +27,7 @@ export type UpstreamBenchmarkRunSummary = {
 export type UpstreamBenchmarkAggregateSummary = {
     providerLabel: string;
     model: string;
+    scenario: UpstreamBenchmarkScenario;
     path: UpstreamBenchmarkPath;
     repetitions: number;
     successCount: number;
@@ -31,6 +40,11 @@ export type UpstreamBenchmarkAggregateSummary = {
     trimmedAvgFirstTokenMs: number | null;
     medianFirstTokenMs: number | null;
     p95FirstTokenMs: number | null;
+    avgSetupMs: number | null;
+    avgFirstToolMs: number | null;
+    avgLastToolMs: number | null;
+    avgFinalOutputMs: number | null;
+    avgCleanupMs: number | null;
     avgOutputLength: number | null;
     avgNormalizedOutputLength: number | null;
     avgToolCallCount: number | null;
@@ -44,8 +58,24 @@ export type UpstreamBenchmarkComparison = {
     avgFirstTokenMsDelta: number | null;
     avgFirstTokenMsOverheadPct: number | null;
 };
+export type UpstreamBenchmarkPhaseCheckpoint = {
+    label: string;
+    atMs: number | null;
+};
+export type UpstreamBenchmarkTemperature = "cold" | "warm";
+export type UpstreamBenchmarkDurationSummary = {
+    count: number;
+    totalMs: number;
+    avgMs: number | null;
+    maxMs: number | null;
+};
 export declare function resolveUpstreamBenchmarkPaths(rawValue?: string): readonly UpstreamBenchmarkPath[];
 export declare function resolveUpstreamBenchmarkWorkload(rawValue?: string): UpstreamBenchmarkWorkload;
+export declare function resolveUpstreamBenchmarkScenarios(rawValue?: string): readonly UpstreamBenchmarkScenario[];
 export declare function extractLastMatchingToken(output: string, prefixes: readonly string[]): string;
-export declare function aggregateUpstreamBenchmarkRuns(providerLabel: string, model: string, path: UpstreamBenchmarkPath, runs: UpstreamBenchmarkRunSummary[]): UpstreamBenchmarkAggregateSummary;
+export declare function aggregateUpstreamBenchmarkRuns(providerLabel: string, model: string, scenario: UpstreamBenchmarkScenario, path: UpstreamBenchmarkPath, runs: UpstreamBenchmarkRunSummary[]): UpstreamBenchmarkAggregateSummary;
+export declare function withUpstreamBenchmarkCleanup(summary: UpstreamBenchmarkRunSummary, cleanupMs: number | null): UpstreamBenchmarkRunSummary;
+export declare function summarizeUpstreamBenchmarkPhases(checkpoints: readonly UpstreamBenchmarkPhaseCheckpoint[]): Record<string, number | null>;
+export declare function selectUpstreamBenchmarkRunsByTemperature(runs: readonly UpstreamBenchmarkRunSummary[], temperature: UpstreamBenchmarkTemperature): UpstreamBenchmarkRunSummary[];
+export declare function summarizeUpstreamBenchmarkDurations(values: readonly number[]): UpstreamBenchmarkDurationSummary;
 export declare function compareUpstreamBenchmarkPaths(baseline: UpstreamBenchmarkAggregateSummary, candidate: UpstreamBenchmarkAggregateSummary): UpstreamBenchmarkComparison;

package/dist/benchmark/upstream-runtime-ab-benchmark.js

@@ -1,9 +1,15 @@
 export const DEFAULT_UPSTREAM_BENCHMARK_PATHS = Object.freeze([
     "harness",
+    "harness-minimal-upstream",
     "raw-langchain-v1",
     "raw-deepagent",
 ]);
 export const DEFAULT_UPSTREAM_BENCHMARK_WORKLOAD = "tool";
+export const DEFAULT_UPSTREAM_BENCHMARK_SCENARIOS = Object.freeze([
+    "normal",
+    "complex",
+    "extreme",
+]);
 function average(values) {
     return Number((values.reduce((sum, value) => sum + value, 0) / values.length).toFixed(2));
 }
@@ -47,12 +53,25 @@ export function resolveUpstreamBenchmarkPaths(rawValue) {
     const parsed = rawValue
         .split(",")
         .map((value) => value.trim().toLowerCase())
-        .filter((value) => value === "harness" || value === "raw-langchain-v1" || value === "raw-deepagent");
+        .filter((value) => value === "harness" ||
+        value === "harness-minimal-upstream" ||
+        value === "raw-langchain-v1" ||
+        value === "raw-deepagent");
     return parsed.length > 0 ? parsed : [...DEFAULT_UPSTREAM_BENCHMARK_PATHS];
 }
 export function resolveUpstreamBenchmarkWorkload(rawValue) {
     return rawValue?.trim().toLowerCase() === "no-tool" ? "no-tool" : DEFAULT_UPSTREAM_BENCHMARK_WORKLOAD;
 }
+export function resolveUpstreamBenchmarkScenarios(rawValue) {
+    if (!rawValue) {
+        return [...DEFAULT_UPSTREAM_BENCHMARK_SCENARIOS];
+    }
+    const parsed = rawValue
+        .split(",")
+        .map((value) => value.trim().toLowerCase())
+        .filter((value) => value === "normal" || value === "complex" || value === "extreme");
+    return parsed.length > 0 ? parsed : [...DEFAULT_UPSTREAM_BENCHMARK_SCENARIOS];
+}
 export function extractLastMatchingToken(output, prefixes) {
     const normalized = output.replace(/\s+/g, " ").trim();
     let matched = "";
@@ -69,7 +88,7 @@ export function extractLastMatchingToken(output, prefixes) {
     }
     return matched || normalized;
 }
-export function aggregateUpstreamBenchmarkRuns(providerLabel, model, path, runs) {
+export function aggregateUpstreamBenchmarkRuns(providerLabel, model, scenario, path, runs) {
     const successfulRuns = runs.filter((run) => run.status === "completed");
     const totalValues = successfulRuns.map((run) => run.totalMs);
     const firstTokenValues = successfulRuns
@@ -78,6 +97,7 @@ export function aggregateUpstreamBenchmarkRuns(providerLabel, model, path, runs)
     return {
         providerLabel,
         model,
+        scenario,
         path,
         repetitions: runs.length,
         successCount: successfulRuns.length,
@@ -90,12 +110,48 @@ export function aggregateUpstreamBenchmarkRuns(providerLabel, model, path, runs)
         trimmedAvgFirstTokenMs: trimmedAverageOrNull(firstTokenValues, 0.1),
         medianFirstTokenMs: medianOrNull(firstTokenValues),
         p95FirstTokenMs: percentileOrNull(firstTokenValues, 0.95),
+        avgSetupMs: averageOrNull(successfulRuns.map((run) => run.setupMs).filter((value) => value !== null)),
+        avgFirstToolMs: averageOrNull(successfulRuns.map((run) => run.firstToolMs).filter((value) => value !== null)),
+        avgLastToolMs: averageOrNull(successfulRuns.map((run) => run.lastToolMs).filter((value) => value !== null)),
+        avgFinalOutputMs: averageOrNull(successfulRuns.map((run) => run.finalOutputMs).filter((value) => value !== null)),
+        avgCleanupMs: averageOrNull(successfulRuns.map((run) => run.cleanupMs).filter((value) => value !== null)),
         avgOutputLength: averageOrNull(successfulRuns.map((run) => run.outputLength)),
         avgNormalizedOutputLength: averageOrNull(successfulRuns.map((run) => run.normalizedOutputLength)),
         avgToolCallCount: averageOrNull(successfulRuns.map((run) => run.toolCallCount)),
         exactOutputMatchCount: successfulRuns.filter((run) => run.exactOutputMatch).length,
     };
 }
+export function withUpstreamBenchmarkCleanup(summary, cleanupMs) {
+    return {
+        ...summary,
+        cleanupMs,
+    };
+}
+export function summarizeUpstreamBenchmarkPhases(checkpoints) {
+    let previousAtMs = 0;
+    const durations = {};
+    for (const checkpoint of checkpoints) {
+        const key = `${checkpoint.label}Ms`;
+        if (checkpoint.atMs === null) {
+            durations[key] = null;
+            continue;
+        }
+        durations[key] = Number((checkpoint.atMs - previousAtMs).toFixed(2));
+        previousAtMs = checkpoint.atMs;
+    }
+    return durations;
+}
+export function selectUpstreamBenchmarkRunsByTemperature(runs, temperature) {
+    return runs.filter((run) => (temperature === "cold" ? run.runNumber === 1 : run.runNumber > 1));
+}
+export function summarizeUpstreamBenchmarkDurations(values) {
+    return {
+        count: values.length,
+        totalMs: Number(values.reduce((sum, value) => sum + value, 0).toFixed(2)),
+        avgMs: values.length > 0 ? average(values) : null,
+        maxMs: values.length > 0 ? Number(Math.max(...values).toFixed(2)) : null,
+    };
+}
 function computeOverhead(candidate, baseline) {
     if (candidate === null || baseline === null) {
         return { delta: null, pct: null };

package/dist/contracts/runtime.d.ts

@@ -1,5 +1,10 @@
 import type { RunState } from "./core.js";
 import type { CompiledAgentBinding, CompiledModel, CompiledTool, ParsedAgentObject, ParsedToolObject, WorkspaceBundle } from "./workspace.js";
+/**
+ * Persisted runtime summary for an inspectable conversation thread.
+ * This projects upstream session/thread execution state into a stable runtime
+ * inspection surface.
+ */
 export type ThreadSummary = {
     agentId: string;
     threadId: string;
@@ -11,6 +16,11 @@ export type ThreadSummary = {
 export type SessionRecord = ThreadSummary;
 export type KnownHarnessEventType = "run.created" | "run.queued" | "run.dequeued" | "run.state.changed" | "run.resumed" | "approval.requested" | "approval.resolved" | "artifact.created" | "output.delta" | "runtime.health.changed" | "runtime.synthetic_fallback";
 export type HarnessEventType = KnownHarnessEventType | (string & {});
+/**
+ * Persisted runtime event recorded by the harness runtime.
+ * Event payload semantics should stay aligned with upstream/runtime behavior
+ * rather than introducing a second execution protocol.
+ */
 export type HarnessEvent = {
     eventId: string;
     eventType: HarnessEventType;
@@ -45,6 +55,10 @@ export type RuntimeHealthSymptom = {
     firstSeenAt: string;
     lastSeenAt: string;
 };
+/**
+ * Harness-operated operational state built from persisted records and runtime telemetry.
+ * This is runtime ops state, not an upstream execution semantic.
+ */
 export type RuntimeHealthSnapshot = {
     status: HealthStatus;
     updatedAt: string;
@@ -153,8 +167,15 @@ export type ThreadRunRecord = {
     checkpointRef: string | null;
     resumable: boolean;
 };
+/**
+ * Persisted run summary projected from upstream execution state plus runtime lifecycle metadata.
+ */
 export type RunSummary = ThreadRunRecord;
 export type RunRecord = RunSummary;
+/**
+ * Persisted thread inspection record assembled from runtime records.
+ * This is an inspectable projection, not a second thread semantic model.
+ */
 export type ThreadRecord = {
     threadId: string;
     entryAgentId: string;
@@ -188,6 +209,11 @@ export type RestartConversationOptions = {
     mode: "restart-in-thread" | "restart-new-thread";
     input: string;
 };
+/**
+ * Persisted approval inspection record.
+ * Approval decision semantics should stay aligned with upstream interrupt/approval
+ * behavior even though the record is stored and resolved through harness persistence.
+ */
 export type ApprovalRecord = {
     approvalId: string;
     pendingActionId: string;
@@ -240,6 +266,12 @@ export type RuntimeAdapterOptions = {
     checkpointerResolver?: RuntimeCheckpointerResolver;
     storeResolver?: RuntimeStoreResolver;
     backendResolver?: RuntimeBackendResolver;
+    /**
+     * DeepAgent execution semantics stay upstream-owned.
+     * `minimal` keeps harness runtime persistence/ops active while only attaching
+     * upstream substrate objects when the binding explicitly needs them.
+     */
+    deepAgentUpstreamSubstrateMode?: "full" | "minimal";
 };
 export type ToolKindAdapter = {
     type: string;

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.122";
+export declare const AGENT_HARNESS_VERSION = "0.0.124";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.122";
+export const AGENT_HARNESS_VERSION = "0.0.124";

package/dist/runtime/agent-runtime-adapter.d.ts

@@ -32,9 +32,9 @@ export declare function buildDeepAgentCreateParams(input: {
     resolvedTools: unknown[];
     resolvedMiddleware: unknown[];
     resolvedSubagents: UpstreamSubagentConfig[];
-    resolvedCheckpointer: unknown;
-    resolvedStore: unknown;
-    resolvedBackend: unknown;
+    resolvedCheckpointer?: unknown;
+    resolvedStore?: unknown;
+    resolvedBackend?: unknown;
     resolvedInterruptOn?: Record<string, {
         allowedDecisions: Array<"approve" | "edit" | "reject">;
     }>;

package/dist/runtime/agent-runtime-adapter.js

@@ -18,7 +18,7 @@ export { applyDeepAgentDelegationPromptCompatibility, materializeDeepAgentSkillS
 export { buildAuthOmittingFetch, normalizeOpenAICompatibleInit } from "./adapter/compat/openai-compatible.js";
 export { buildToolNameMapping, createModelFacingToolNameCandidates, createModelFacingToolNameLookupCandidates, resolveModelFacingToolName, sanitizeToolNameForModel, } from "./adapter/tool/tool-name-mapping.js";
 export { computeRemainingTimeoutMs, isRetryableProviderError, resolveBindingTimeout, resolveProviderRetryPolicy, resolveStreamIdleTimeout, resolveTimeoutMs, } from "./adapter/resilience.js";
-import { getBindingAdapterKind, getBindingExecutionKind, getBindingExecutionParams, getBindingFilesystemConfig, getBindingInterruptCompatibilityRules, getBindingPrimaryModel, getBindingSkills, getBindingSubagents, getBindingToolCount, getBindingPrimaryTools, getBindingSystemPrompt, isDeepAgentBinding, isLangChainBinding, } from "./support/compiled-binding.js";
+import { getBindingBackendConfig, getBindingAdapterKind, getBindingExecutionKind, getBindingExecutionParams, getBindingFilesystemConfig, getBindingInterruptCompatibilityRules, getBindingMemorySources, getBindingMiddlewareConfigs, getBindingPrimaryModel, getBindingSkills, getBindingStoreConfig, getBindingSubagents, getBindingToolCount, getBindingPrimaryTools, getBindingSystemPrompt, isDeepAgentBinding, isLangChainBinding, } from "./support/compiled-binding.js";
 const AGENT_INTERRUPT_SENTINEL_PREFIX = "__agent_harness_interrupt__:";
 const UPSTREAM_BUILTIN_MIDDLEWARE_TOOL_NAMES = Object.freeze([
     "write_todos",
@@ -116,13 +116,28 @@ export function buildDeepAgentCreateParams(input) {
         model: input.resolvedModel,
         tools: input.resolvedTools,
         middleware: input.resolvedMiddleware,
-        checkpointer: input.resolvedCheckpointer,
-        store: input.resolvedStore,
         subagents: input.resolvedSubagents,
-        backend: input.resolvedBackend,
         interruptOn: input.resolvedInterruptOn,
+        ...(input.resolvedCheckpointer !== undefined ? { checkpointer: input.resolvedCheckpointer } : {}),
+        ...(input.resolvedStore !== undefined ? { store: input.resolvedStore } : {}),
+        ...(input.resolvedBackend !== undefined ? { backend: input.resolvedBackend } : {}),
     };
 }
+function shouldAttachMinimalDeepAgentCheckpointer(binding, resolvedInterruptOn) {
+    if (binding.harnessRuntime.checkpointer !== undefined) {
+        return true;
+    }
+    return resolvedInterruptOn !== undefined && Object.keys(resolvedInterruptOn).length > 0;
+}
+function shouldAttachMinimalDeepAgentStore(binding) {
+    return getBindingStoreConfig(binding) !== undefined || getBindingMemorySources(binding).length > 0;
+}
+function shouldAttachMinimalDeepAgentBackend(binding) {
+    return (getBindingBackendConfig(binding) !== undefined ||
+        getBindingMemorySources(binding).length > 0 ||
+        getBindingSkills(binding).length > 0 ||
+        (getBindingMiddlewareConfigs(binding)?.length ?? 0) > 0);
+}
 export class AgentRuntimeAdapter {
     options;
     modelCache = new Map();
@@ -351,10 +366,19 @@ export class AgentRuntimeAdapter {
         const resolvedTools = this.resolveTools(primaryTools, binding);
         const resolvedMiddleware = await this.resolveMiddleware(binding);
         const resolvedSubagents = await this.resolveSubagents(getBindingSubagents(binding), binding);
-        const resolvedCheckpointer = resolveRunnableCheckpointer(this.options, binding);
-        const resolvedStore = this.options.storeResolver?.(binding);
-        const resolvedBackend = this.options.backendResolver?.(binding);
         const resolvedInterruptOn = resolveRunnableInterruptOn(binding);
+        const substrateMode = this.options.deepAgentUpstreamSubstrateMode ?? "minimal";
+        const resolvedCheckpointer = substrateMode === "minimal"
+            ? (shouldAttachMinimalDeepAgentCheckpointer(binding, resolvedInterruptOn)
+                ? resolveRunnableCheckpointer(this.options, binding)
+                : undefined)
+            : resolveRunnableCheckpointer(this.options, binding);
+        const resolvedStore = substrateMode === "minimal"
+            ? (shouldAttachMinimalDeepAgentStore(binding) ? this.options.storeResolver?.(binding) : undefined)
+            : this.options.storeResolver?.(binding);
+        const resolvedBackend = substrateMode === "minimal"
+            ? (shouldAttachMinimalDeepAgentBackend(binding) ? this.options.backendResolver?.(binding) : undefined)
+            : this.options.backendResolver?.(binding);
         const resolvedSkills = resolveDeepAgentSkillSourcePaths({
             workspaceRoot: binding.harnessRuntime.workspaceRoot,
             runRoot: binding.harnessRuntime.runRoot,

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

@@ -1,5 +1,5 @@
 import type { ApprovalRecord, HarnessEvent, InternalApprovalRecord, InvocationEnvelope, RunListeners, RunOptions, RunResult, RunStartOptions, MessageContent } from "../../../contracts/types.js";
-export declare function toPublicApprovalRecord(approval: InternalApprovalRecord): ApprovalRecord;
+export declare function toInspectableApprovalRecord(approval: InternalApprovalRecord): ApprovalRecord;
 export declare function normalizeInvocationEnvelope(options: RunStartOptions): {
     context?: Record<string, unknown>;
     state?: Record<string, unknown>;

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

@@ -1,5 +1,5 @@
 import { normalizeMessageContent } from "../../../utils/message-content.js";
-export function toPublicApprovalRecord(approval) {
+export function toInspectableApprovalRecord(approval) {
     const { toolCallId: _toolCallId, checkpointRef: _checkpointRef, eventRefs: _eventRefs, ...publicApproval } = approval;
     return publicApproval;
 }

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

@@ -1,6 +1,6 @@
 import { AGENT_INTERRUPT_SENTINEL_PREFIX, RuntimeOperationTimeoutError } from "../../agent-runtime-adapter.js";
 import { renderRuntimeFailure, renderToolFailure } from "../../support/harness-support.js";
-import { createContentBlocksItem, createToolResultKey, emitOutputDeltaAndCreateItem, } from "../events/streaming.js";
+import { createContentBlocksItem, createToolResultKey, } from "../events/streaming.js";
 function normalizeStreamChunk(chunk) {
     if (typeof chunk === "string") {
         if (chunk.startsWith(AGENT_INTERRUPT_SENTINEL_PREFIX)) {
@@ -33,7 +33,6 @@ export async function* streamHarnessRun(options) {
     let releaseRunSlot = async () => undefined;
     let emitted = false;
     let streamActivityObserved = false;
-    const emitOutputDelta = (content) => emitOutputDeltaAndCreateItem(options.emit, options.threadId, options.runId, options.selectedAgentId, content);
     try {
         const [priorHistory, acquiredReleaseRunSlot] = await Promise.all([
             priorHistoryPromise,
@@ -114,12 +113,10 @@ export async function* streamHarnessRun(options) {
             }
             emitted = true;
             assistantOutput += normalizedChunk.content;
-            yield await emitOutputDelta(normalizedChunk.content);
         }
         if (!assistantOutput && toolErrors.length > 0) {
             assistantOutput = toolErrors.join("\n\n");
             emitted = true;
-            yield await emitOutputDelta(assistantOutput);
         }
         if (!assistantOutput) {
             const actual = await options.invokeWithHistory(options.binding, options.input, options.threadId, options.runId);
@@ -129,7 +126,6 @@ export async function* streamHarnessRun(options) {
             if (actual.output) {
                 assistantOutput = actual.output;
                 emitted = true;
-                yield await emitOutputDelta(actual.output);
             }
         }
         await options.appendAssistantMessage(options.threadId, options.runId, assistantOutput);
@@ -216,9 +212,6 @@ export async function* streamHarnessRun(options) {
             if (Array.isArray(actual.contentBlocks) && actual.contentBlocks.length > 0) {
                 yield createContentBlocksItem(options.threadId, options.runId, options.selectedAgentId, actual.contentBlocks);
             }
-            if (actual.output) {
-                yield await emitOutputDelta(actual.output);
-            }
             yield {
                 type: "result",
                 result: {

package/dist/runtime/harness/run/thread-records.d.ts

@@ -1,6 +1,6 @@
 import type { ApprovalRecord, ThreadRecord, ThreadSummary } from "../../../contracts/types.js";
 import type { RuntimePersistence } from "../../../persistence/types.js";
-export declare function getThreadRecord(input: {
+export declare function buildThreadInspectionRecord(input: {
     persistence: RuntimePersistence;
     getSession: (threadId: string) => Promise<ThreadSummary | null>;
 }, threadId: string): Promise<ThreadRecord | null>;

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

@@ -1,5 +1,10 @@
-import { isTerminalRunState, toPublicApprovalRecord } from "./helpers.js";
-export async function getThreadRecord(input, threadId) {
+import { isTerminalRunState, toInspectableApprovalRecord } from "./helpers.js";
+function selectLatestPendingApproval(approvals) {
+    return approvals
+        .filter((approval) => approval.status === "pending")
+        .sort((left, right) => right.requestedAt.localeCompare(left.requestedAt))[0];
+}
+export async function buildThreadInspectionRecord(input, threadId) {
     const [threadSummary, meta, messages, runs] = await Promise.all([
         input.getSession(threadId),
         input.persistence.getThreadMeta(threadId),
@@ -11,9 +16,7 @@ export async function getThreadRecord(input, threadId) {
     }
     const latestRunId = threadSummary.latestRunId;
     const latestApprovals = await input.persistence.getRunApprovals(threadId, latestRunId);
-    const pendingApproval = latestApprovals
-        .filter((approval) => approval.status === "pending")
-        .sort((left, right) => right.requestedAt.localeCompare(left.requestedAt))[0];
+    const pendingApproval = selectLatestPendingApproval(latestApprovals);
     return {
         threadId,
         entryAgentId: meta.entryAgentId,
@@ -36,11 +39,11 @@ export async function getThreadRecord(input, threadId) {
 }
 export async function listPublicApprovals(input, filter) {
     const approvals = await input.persistence.listApprovals(filter);
-    return approvals.map((approval) => toPublicApprovalRecord(approval));
+    return approvals.map((approval) => toInspectableApprovalRecord(approval));
 }
 export async function getPublicApproval(input, approvalId) {
     const approval = await input.persistence.getApproval(approvalId);
-    return approval ? toPublicApprovalRecord(approval) : null;
+    return approval ? toInspectableApprovalRecord(approval) : null;
 }
 export async function deleteThreadRecord(input, threadId) {
     const thread = await input.getThread(threadId);

package/dist/runtime/harness.js

@@ -29,7 +29,7 @@ import { resolveRuntimeAdapterOptions } from "./support/runtime-adapter-options.
 import { initializeHarnessRuntime, reclaimExpiredClaimedRuns as reclaimHarnessExpiredClaimedRuns, recoverStartupRuns as recoverHarnessStartupRuns, isStaleRunningRun as isHarnessStaleRunningRun, } from "./harness/run/startup-runtime.js";
 import { streamHarnessRun } from "./harness/run/stream-run.js";
 import { defaultRequestedAgentId, prepareRunStart } from "./harness/run/start-run.js";
-import { deleteThreadRecord, getPublicApproval, getThreadRecord, listPublicApprovals, } from "./harness/run/thread-records.js";
+import { buildThreadInspectionRecord, deleteThreadRecord, getPublicApproval, listPublicApprovals, } from "./harness/run/thread-records.js";
 export class AgentHarnessRuntime {
     workspace;
     runtimeAdapterOptions;
@@ -199,7 +199,7 @@ export class AgentHarnessRuntime {
         return this.persistence.getSession(threadId);
     }
     async getThread(threadId) {
-        return getThreadRecord({
+        return buildThreadInspectionRecord({
             persistence: this.persistence,
             getSession: (currentThreadId) => this.getSession(currentThreadId),
         }, threadId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.123",
+  "version": "0.0.125",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",