@botbotgo/agent-harness 0.0.54 → 0.0.56

package/README.md

@@ -18,7 +18,7 @@ That means:
 - runtime lifecycle stays stable even if backend implementations change
 - backend internals stay behind adapters
 
-What the runtime provides:
+The runtime provides:
 
 - `createAgentHarness(workspaceRoot)`, `run(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
 - YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
@@ -26,6 +26,19 @@ What the runtime provides:
 - local `resources/tools/` and `resources/skills/` discovery
 - persisted threads, runs, approvals, events, queue state, and recovery metadata
 
+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:
+
+- if LangChain v1 or DeepAgents already has the feature, map it in YAML and adapt it internally
+- do not add a new public runtime API unless the problem is truly runtime-owned
+
+Boundary documents live in:
+
+- `docs/upstream-feature-matrix.md`
+- `docs/product-boundary.md`
+- `docs/feature-checklist.md`
+
 ## Quick Start
 
 Install:
@@ -100,7 +113,7 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-`createAgentHarness(...)` loads one workspace, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
+`createAgentHarness(...)` loads the workspace, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
 
 ### Run A Request
 
@@ -124,7 +137,7 @@ const result = await run(runtime, {
 });
 ```
 
-`run(runtime, { ... })` creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and a compact text `output`. Richer upstream results remain available through `outputContent`, `contentBlocks`, and `structuredResponse` without expanding the main facade.
+`run(runtime, { ... })` creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and compact text `output`. Richer upstream result shapes stay available through `outputContent`, `contentBlocks`, and `structuredResponse`.
 
 Use `invocation` as the runtime-facing request envelope:
 
@@ -163,7 +176,7 @@ const result = await run(runtime, {
 });
 ```
 
-`subscribe(...)` is a read-only observer surface over stored lifecycle events.
+`subscribe(...)` is the read-only observer surface over stored lifecycle events.
 
 The runtime event stream includes:
 
@@ -199,9 +212,11 @@ if (approval) {
 }
 ```
 
-These methods return runtime-facing records, not raw persistence or backend checkpoint objects.
+These methods return runtime-facing records, not raw checkpoint or backend objects.
+
+### Expose And Consume MCP
 
-### Bridge MCP Servers Into Agents
+Bridge MCP servers into agents:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -218,9 +233,7 @@ spec:
         args: ["./mcp-browser-server.mjs"]
 ```
 
-The runtime discovers MCP tools, filters them through agent configuration, and exposes them like other tools.
-
-### Expose Runtime Tools As An MCP Server
+Expose harness tools as an MCP server:
 
 ```ts
 import { createToolMcpServer, serveToolsOverStdio } from "@botbotgo/agent-harness";
@@ -242,7 +255,7 @@ await stop(runtime);
 Use Kubernetes-style YAML:
 
 - collection files use `apiVersion`, plural `kind`, and `spec: []`
-- single-object files use `apiVersion`, singular `kind`, `metadata`, and `spec`
+- singleton files use `apiVersion`, singular `kind`, `metadata`, and `spec`
 
 Core workspace files:
 
@@ -260,19 +273,17 @@ Core workspace files:
 - `resources/tools/`
 - `resources/skills/`
 
-There are three configuration layers:
+There are three main configuration layers:
 
 - runtime policy in `config/workspace.yaml`
 - reusable object catalogs in `config/*.yaml`
 - agent assembly in `config/agents/*.yaml`
 
-The repository-owned default config layer is intentionally full-shaped. The shipped YAML keeps explicit default values for the main runtime knobs so teams can start from concrete config instead of reconstructing adapter defaults from code.
-
 ### `config/workspace.yaml`
 
-Use this file for runtime-level policy shared by the whole workspace.
+Use this file for workspace-wide runtime policy.
 
-Primary fields:
+Important fields:
 
 - `runRoot`
 - `concurrency.maxConcurrentRuns`
@@ -285,13 +296,36 @@ Primary fields:
 - `recovery.resumeResumingRunsOnStartup`
 - `recovery.maxRecoveryAttempts`
 
-If `runRoot` is omitted, the runtime defaults to `<workspace-root>/run-data`.
+`recovery.resumeResumingRunsOnStartup` keeps checkpoint resume a runtime-owned lifecycle behavior instead of exposing checkpoint orchestration as public API.
+
+Example:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Runtime
+metadata:
+  name: default
+spec:
+  runRoot: ./.agent
+  concurrency:
+    maxConcurrentRuns: 3
+  routing:
+    defaultAgentId: orchestra
+    modelRouting: false
+  maintenance:
+    checkpoints:
+      enabled: true
+  recovery:
+    enabled: true
+    resumeResumingRunsOnStartup: true
+    maxRecoveryAttempts: 3
+```
 
 ### `config/agent-context.md`
 
-Use this file for shared bootstrap context loaded into agents at construction time.
+Use this file for shared bootstrap memory loaded at agent construction time.
 
-Put stable project context here. Do not use it as mutable long-term memory.
+Keep stable project context here. Treat it as startup context, not mutable long-term memory.
 
 ### `config/models.yaml`
 
@@ -340,7 +374,7 @@ spec:
 
 ### `config/backends.yaml`
 
-Use reusable DeepAgent backend presets so filesystem and long-term memory topology stays in YAML instead of application code:
+Use reusable DeepAgents backend presets so filesystem and `/memories/*` topology stays in YAML:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -363,9 +397,7 @@ spec:
 
 Use this file for reusable tool objects.
 
-Supported tool families in the built-in runtime include function tools, backend tools, MCP tools, provider-native tools, and bundles.
-
-Provider-native tools are declared in YAML and resolved directly to upstream provider tool factories.
+Built-in tool families include function tools, backend tools, MCP tools, bundles, and provider-native tools. Provider-native tools are declared in YAML and resolved directly to upstream factories.
 
 ### `config/mcp.yaml`
 
@@ -373,16 +405,14 @@ Use this file for named MCP server presets.
 
 ### `config/agents/*.yaml`
 
-Agents are always declared with `kind: Agent` and `spec.execution.backend`.
+Agents always use `kind: Agent` plus `spec.execution.backend`.
 
-Use two nested sections inside each agent:
+Use two nested sections:
 
 - `spec.runtime` for harness-owned runtime placement such as `spec.runtime.runRoot`
 - `spec.execution` for upstream execution semantics and adapter-facing config
 
-This keeps the public product model small while letting LangChain v1 and DeepAgents concepts pass through with minimal translation.
-
-Example lightweight host:
+Example direct host:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -406,11 +436,15 @@ spec:
       store:
         ref: store/default
       interruptOn: {}
+      filesystem:
+        rootDir: .
+        virtualMode: true
+        maxFileSizeMb: 10
       middleware: []
       systemPrompt: Answer simple requests directly.
 ```
 
-Example main execution host:
+Example orchestra host:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -439,36 +473,29 @@ spec:
       interruptOn: {}
       middleware: []
       generalPurposeAgent: true
-      taskDescription: Complete delegated sidecar work and return concise results.
+      taskDescription: Complete delegated sidecar work and return concise results without bloating the parent context.
 ```
 
-For backend-specific agent options, prefer the upstream concept directly inside `spec.execution.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
-
-### `resources/`
-
-Use `resources/` for executable local extensions:
-
-- `resources/tools/` for tool modules
-- `resources/skills/` for SKILL packages
-
-Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`, and `resources/tools/*.cjs`.
+For backend-specific options, prefer the upstream concept directly inside `spec.execution.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
 
 ## Design Notes
 
+- `agent-harness` is not a third agent framework
 - public runtime contract stays generic and small
 - application-level orchestration and lifecycle management stays in the harness
 - upstream LangChain v1 and DeepAgents concepts should be expressed as directly as possible in YAML
-- recovery, approvals, threads, runs, and events are runtime concepts, not backend-specific escape hatches
-- backend implementation details should stay internal unless product requirements force exposure
-- new LangChain v1 or DeepAgents public config should land in YAML passthrough and compatibility tests before adding new public runtime APIs
+- when a feature can be expressed in YAML, prefer YAML over expanding the public API
+- recovery, approvals, threads, runs, and events are runtime concepts, not backend escape hatches
+- new LangChain v1 or DeepAgents config should land in YAML mapping and tests before adding public runtime APIs
 
-In short: `agent-harness` is a public runtime contract generic enough to survive backend changes, while the deep execution semantics stay upstream.
+In short, the product model stays stable while the execution semantics remain upstream-owned.
 
 ## API Summary
 
 Primary exports:
 
 - `createAgentHarness`
+- `AgentHarnessRuntime`
 - `run`
 - `resolveApproval`
 - `subscribe`

package/dist/config/agents/direct.yaml

@@ -46,7 +46,25 @@ spec:
         ref: store/default
       # Upstream execution feature: no declarative HITL tool routing by default.
       interruptOn: {}
+      # Upstream execution feature: filesystem middleware settings for LangChain v1 agents.
+      # This only becomes active when `middleware` includes `{ kind: filesystem }`, or when
+      # automatic upstream middleware such as skills or memory need a filesystem backend.
+      # Keep the default root inside the workspace so file-aware middleware stays bounded.
+      filesystem:
+        rootDir: .
+        virtualMode: true
+        maxFileSizeMb: 10
       # Upstream execution feature: no extra declarative middleware beyond the runtime's automatic injections.
+      # Common upstream middleware kinds that this harness can compile directly from YAML:
+      # - `filesystem`
+      # - `patchToolCalls`
+      # - `summarization`
+      # - `dynamicSystemPrompt`
+      # - `humanInTheLoop`
+      # - `todoList`
+      # - `pii`, `piiRedaction`
+      #
+      # Keep the default empty so the lightweight direct host stays minimal.
       middleware: []
       # Upstream execution feature: system prompt for the lightweight direct-response host.
       # This prompt should keep the agent focused on:

package/dist/config/agents/orchestra.yaml

@@ -66,6 +66,16 @@ spec:
       # Upstream execution feature: no extra declarative HITL rules by default.
       interruptOn: {}
       # Upstream execution feature: no extra declarative middleware beyond upstream deepagents defaults by default.
+      # Common upstream middleware kinds that this harness can compile directly from YAML:
+      # - `patchToolCalls`
+      # - `summarization`
+      # - `dynamicSystemPrompt`
+      # - `humanInTheLoop`
+      # - `todoList`
+      # - `pii`, `piiRedaction`
+      #
+      # DeepAgents already includes its own filesystem, planning, subagent, and memory semantics.
+      # Keep this list empty unless you are intentionally adding extra upstream middleware on top.
       middleware: []
       # Upstream execution feature: keep the built-in general-purpose subagent enabled.
       generalPurposeAgent: true

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.53";
+export declare const AGENT_HARNESS_VERSION = "0.0.55";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.53";
+export const AGENT_HARNESS_VERSION = "0.0.55";

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

@@ -525,6 +525,8 @@ export class AgentRuntimeAdapter {
     async resolveMiddleware(binding, interruptOn) {
         const declarativeMiddleware = await resolveDeclaredMiddleware(getBindingMiddlewareConfigs(binding), {
             resolveModel: (model) => this.resolveModel(model),
+            resolveBackend: (resolvedBinding) => this.options.backendResolver?.(resolvedBinding ?? binding),
+            resolveFilesystemBackend: (resolvedBinding) => this.resolveFilesystemBackend(resolvedBinding ?? binding),
             resolveCustom: this.options.declaredMiddlewareResolver,
             binding,
         });
@@ -575,6 +577,14 @@ export class AgentRuntimeAdapter {
             contextSchema: subagent.contextSchema,
             middleware: (await resolveDeclaredMiddleware(subagent.middleware, {
                 resolveModel: (model) => this.resolveModel(model),
+                resolveBackend: (resolvedBinding) => {
+                    const targetBinding = resolvedBinding ?? binding;
+                    return targetBinding ? this.options.backendResolver?.(targetBinding) : undefined;
+                },
+                resolveFilesystemBackend: (resolvedBinding) => {
+                    const targetBinding = resolvedBinding ?? binding;
+                    return targetBinding ? this.resolveFilesystemBackend(targetBinding) : undefined;
+                },
                 resolveCustom: this.options.declaredMiddlewareResolver,
                 binding,
             })),

package/dist/runtime/declared-middleware.d.ts

@@ -3,12 +3,17 @@ type MiddlewareConfig = Record<string, unknown>;
 type MiddlewareFactoryContext = {
     config: MiddlewareConfig;
     resolveModel: (model: CompiledModel) => Promise<unknown>;
+    resolveBackend?: () => unknown;
+    resolveFilesystemBackend?: () => unknown;
+    binding?: CompiledAgentBinding;
 };
 type MiddlewareFactory = (context: MiddlewareFactoryContext) => Promise<unknown | unknown[] | null | undefined>;
 export declare const DECLARATIVE_MIDDLEWARE_REGISTRY: Record<string, MiddlewareFactory>;
 export declare const SUPPORTED_DECLARATIVE_MIDDLEWARE_KINDS: readonly string[];
 export declare function resolveDeclaredMiddleware(middlewareConfigs: unknown[] | undefined, options: {
     resolveModel: (model: CompiledModel) => Promise<unknown>;
+    resolveBackend?: (binding?: CompiledAgentBinding) => unknown;
+    resolveFilesystemBackend?: (binding?: CompiledAgentBinding) => unknown;
     resolveCustom?: (input: {
         kind: string;
         config: Record<string, unknown>;

package/dist/runtime/declared-middleware.js

@@ -1,4 +1,5 @@
-import { anthropicPromptCachingMiddleware, contextEditingMiddleware, humanInTheLoopMiddleware, llmToolSelectorMiddleware, modelCallLimitMiddleware, modelFallbackMiddleware, modelRetryMiddleware, openAIModerationMiddleware, piiMiddleware, summarizationMiddleware, todoListMiddleware, toolCallLimitMiddleware, toolEmulatorMiddleware, toolRetryMiddleware, } from "langchain";
+import { anthropicPromptCachingMiddleware, contextEditingMiddleware, dynamicSystemPromptMiddleware, humanInTheLoopMiddleware, llmToolSelectorMiddleware, modelCallLimitMiddleware, modelFallbackMiddleware, modelRetryMiddleware, openAIModerationMiddleware, piiMiddleware, piiRedactionMiddleware, summarizationMiddleware, todoListMiddleware, toolCallLimitMiddleware, toolEmulatorMiddleware, toolRetryMiddleware, } from "langchain";
+import { createFilesystemMiddleware, createPatchToolCallsMiddleware, createSummarizationMiddleware as createDeepAgentSummarizationMiddleware, } from "deepagents";
 function asMiddlewareConfig(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value) ? { ...value } : null;
 }
@@ -26,6 +27,18 @@ async function resolveReferencedModelList(values, options) {
     return Promise.all(values.map((value) => resolveReferencedModel(value, options)));
 }
 async function createSummarizationMiddleware({ config, resolveModel }) {
+    if (config.provider === "deepagents") {
+        const runtimeConfig = { ...config };
+        runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, { resolveModel });
+        if (runtimeConfig.model === undefined) {
+            throw new Error("deepagents summarization middleware requires model or modelRef");
+        }
+        if (runtimeConfig.backend === undefined) {
+            throw new Error("deepagents summarization middleware requires backend");
+        }
+        delete runtimeConfig.provider;
+        return createDeepAgentSummarizationMiddleware(runtimeConfig);
+    }
     const runtimeConfig = { ...config };
     runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, { resolveModel });
     if (runtimeConfig.model === undefined) {
@@ -33,6 +46,17 @@ async function createSummarizationMiddleware({ config, resolveModel }) {
     }
     return summarizationMiddleware(runtimeConfig);
 }
+async function createBindingAwareSummarizationMiddleware(context) {
+    const runtimeConfig = { ...context.config };
+    if (context.binding?.agent.executionMode === "deepagent") {
+        runtimeConfig.provider = "deepagents";
+        runtimeConfig.backend ??= context.resolveBackend?.() ?? context.resolveFilesystemBackend?.();
+    }
+    return createSummarizationMiddleware({
+        ...context,
+        config: runtimeConfig,
+    });
+}
 async function createLlmToolSelectorMiddleware({ config, resolveModel }) {
     const runtimeConfig = { ...config };
     runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, { resolveModel });
@@ -54,8 +78,15 @@ async function createPiiDeclarativeMiddleware({ config }) {
     const { piiType: _piiType, ...piiOptions } = config;
     return piiMiddleware(piiType, piiOptions);
 }
+async function createFilesystemDeclarativeMiddleware({ config, resolveFilesystemBackend }) {
+    const runtimeConfig = { ...config };
+    runtimeConfig.backend ??= resolveFilesystemBackend?.();
+    return createFilesystemMiddleware(runtimeConfig);
+}
 export const DECLARATIVE_MIDDLEWARE_REGISTRY = {
-    summarization: createSummarizationMiddleware,
+    filesystem: createFilesystemDeclarativeMiddleware,
+    patchToolCalls: async () => createPatchToolCallsMiddleware(),
+    summarization: createBindingAwareSummarizationMiddleware,
     llmToolSelector: createLlmToolSelectorMiddleware,
     modelRetry: async ({ config }) => modelRetryMiddleware(config),
     modelFallback: createModelFallbackDeclarativeMiddleware,
@@ -64,10 +95,12 @@ export const DECLARATIVE_MIDDLEWARE_REGISTRY = {
     modelCallLimit: async ({ config }) => modelCallLimitMiddleware(config),
     todoList: async ({ config }) => todoListMiddleware(config),
     contextEditing: async ({ config }) => contextEditingMiddleware(config),
+    dynamicSystemPrompt: async ({ config }) => dynamicSystemPromptMiddleware(config),
     toolEmulator: async ({ config }) => toolEmulatorMiddleware(config),
     humanInTheLoop: async ({ config }) => humanInTheLoopMiddleware(config),
     openAIModeration: async ({ config }) => openAIModerationMiddleware(config),
     pii: createPiiDeclarativeMiddleware,
+    piiRedaction: async ({ config }) => piiRedactionMiddleware(config),
     anthropicPromptCaching: async ({ config }) => anthropicPromptCachingMiddleware(config),
 };
 export const SUPPORTED_DECLARATIVE_MIDDLEWARE_KINDS = Object.freeze(Object.keys(DECLARATIVE_MIDDLEWARE_REGISTRY).sort());
@@ -85,6 +118,9 @@ export async function resolveDeclaredMiddleware(middlewareConfigs, options) {
             const resolvedBuiltin = await registeredFactory({
                 config: runtimeConfig,
                 resolveModel: options.resolveModel,
+                resolveBackend: () => options.resolveBackend?.(options.binding),
+                resolveFilesystemBackend: () => options.resolveFilesystemBackend?.(options.binding),
+                binding: options.binding,
             });
             if (Array.isArray(resolvedBuiltin)) {
                 resolved.push(...resolvedBuiltin);

package/dist/workspace/validate.js

@@ -41,6 +41,9 @@ function validateMiddlewareConfig(agent) {
         if (kind === "humanInTheLoop" && typeof typed.interruptOn !== "object") {
             throw new Error(`Agent ${agent.id} humanInTheLoop middleware requires interruptOn`);
         }
+        if (kind === "filesystem" && agent.executionMode === "deepagent") {
+            throw new Error(`Agent ${agent.id} cannot use filesystem middleware with DeepAgents; configure filesystem behavior through the deepagent backend instead`);
+        }
         if (kind === "pii" && typeof typed.piiType !== "string") {
             throw new Error(`Agent ${agent.id} pii middleware requires piiType`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.54",
+  "version": "0.0.56",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -50,7 +50,7 @@
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts",
+    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts",
     "test:real-providers": "vitest run test/real-provider-harness.test.ts",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",