@botbotgo/agent-harness 0.0.51 → 0.0.52

package/README.md

@@ -6,7 +6,7 @@
 
 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.
 
-The product boundary is simple:
+The boundary is strict:
 
 - LangChain v1 and DeepAgents own agent execution semantics
 - `agent-harness` owns application-level orchestration and lifecycle management
@@ -15,12 +15,13 @@ That means:
 
 - public API stays small
 - complex setup and operating policy live in YAML
+- application-level orchestration and lifecycle management stays in the harness
 - runtime lifecycle stays stable even if backend implementations change
 
 What the runtime provides:
 
 - `createAgentHarness(...)`, `run(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
-- YAML-defined workspace assembly for routing, models, tools, stores, MCP, recovery, and maintenance
+- YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
 - backend-adapted execution with current LangChain v1 and DeepAgents adapters
 - local `resources/tools/` and `resources/skills/` discovery
 - persisted threads, runs, approvals, events, queue state, and recovery metadata
@@ -44,6 +45,7 @@ your-workspace/
     embedding-models.yaml
     vector-stores.yaml
     stores.yaml
+    backends.yaml
     tools.yaml
     mcp.yaml
     agents/
@@ -242,6 +244,7 @@ Core workspace files:
 - `config/embedding-models.yaml`
 - `config/vector-stores.yaml`
 - `config/stores.yaml`
+- `config/backends.yaml`
 - `config/tools.yaml`
 - `config/mcp.yaml`
 - `config/agents/direct.yaml`
@@ -323,6 +326,38 @@ spec:
     checkpointerKind: MemorySaver
 ```
 
+Built-in store kinds today:
+
+- `FileStore`
+- `InMemoryStore`
+
+Built-in checkpointer kinds today:
+
+- `MemorySaver`
+- `FileCheckpointer`
+- `SqliteSaver`
+
+If you need other store or checkpointer implementations, inject them through runtime resolvers instead of treating them as built-in harness features.
+
+### `config/backends.yaml`
+
+Use reusable DeepAgent backend presets so filesystem and long-term memory topology stays in YAML instead of application code:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Backends
+spec:
+  - kind: Backend
+    name: default
+    backendKind: CompositeBackend
+    state:
+      kind: VfsSandbox
+      timeout: 600
+    routes:
+      /memories/:
+        kind: StoreBackend
+```
+
 ### `config/tools.yaml`
 
 Use this file for reusable tool objects.
@@ -390,13 +425,7 @@ spec:
       checkpointer:
         ref: checkpointer/default
       backend:
-        kind: CompositeBackend
-        state:
-          kind: VfsSandbox
-          timeout: 600
-        routes:
-          /memories/:
-            kind: StoreBackend
+        ref: backend/default
 ```
 
 Client-configurable agent fields include:

package/dist/config/agents/orchestra.yaml

@@ -39,27 +39,19 @@ spec:
         ref: checkpointer/default
       # Upstream execution feature: store config passed into the selected backend adapter.
       # In the default deepagent adapter this is the LangGraph store used by `StoreBackend` routes.
-      # Available `kind` options in this harness: `FileStore`, `InMemoryStore`, `RedisStore`, `PostgresStore`.
+      # Built-in kinds in this harness today: `FileStore`, `InMemoryStore`.
+      # Other store kinds should flow through a custom runtime resolver instead of being claimed as built in.
       store:
         ref: store/default
       # Upstream execution feature: backend config passed into the selected backend adapter.
-      # This directly defines the backend topology for this agent:
+      # Prefer a reusable backend preset via `ref` so backend topology stays declarative and reusable in YAML.
+      # The default preset keeps DeepAgent execution semantics upstream-owned:
       # - workspace execution uses a lightweight VFS sandbox
       # - long-term memory under `/memories/*` uses `StoreBackend`
       # - `CompositeBackend` composes those backend instances together
-      # The harness also injects a persistent file-backed store and a file-backed checkpointer so that
-      # `/memories/*` and resumable run state survive restarts in the default setup.
-      # Available top-level `kind` options in this harness: `CompositeBackend`, `StateBackend`, `StoreBackend`.
+      # The harness injects the resolved store/checkpointer instances, but the backend topology itself stays upstream-shaped.
       backend:
-        kind: CompositeBackend
-        state:
-          # Available state backend `kind` options today: `StateBackend`, `LocalShellBackend`, `VfsSandbox`.
-          kind: VfsSandbox
-          timeout: 600
-        routes:
-          /memories/:
-            # Available route backend `kind` options today: `StoreBackend`.
-            kind: StoreBackend
+        ref: backend/default
       # Upstream execution feature: system prompt for the orchestration host.
       # This becomes the top-level instruction block for the selected execution backend and should hold the
       # agent's durable role, priorities, and behavioral guardrails rather than bulky project facts.

package/dist/config/backends.yaml

@@ -0,0 +1,16 @@
+# agent-harness feature: schema version for reusable backend presets.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type for named DeepAgent backend presets.
+kind: Backends
+spec:
+  # upstream deepagents feature: default hybrid backend for workspace execution plus durable /memories storage.
+  - kind: Backend
+    name: default
+    description: Default DeepAgent backend preset with a virtual workspace sandbox and durable /memories storage.
+    backendKind: CompositeBackend
+    state:
+      kind: VfsSandbox
+      timeout: 600
+    routes:
+      /memories/:
+        kind: StoreBackend

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.50";
+export declare const AGENT_HARNESS_VERSION = "0.0.51";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.50";
+export const AGENT_HARNESS_VERSION = "0.0.51";

package/dist/workspace/agent-binding-compiler.js

@@ -127,14 +127,22 @@ function resolveInterruptOn(agent) {
     return (agent.deepAgentConfig?.interruptOn ??
         agent.langchainAgentConfig?.interruptOn);
 }
-function resolveBackendConfig(agent) {
+function resolveBackendConfig(agent, refs) {
     if (agent.executionMode !== "deepagent") {
         return undefined;
     }
     const backendConfig = typeof agent.deepAgentConfig?.backend === "object" && agent.deepAgentConfig.backend
         ? agent.deepAgentConfig.backend
         : undefined;
-    return backendConfig ? { config: backendConfig } : undefined;
+    if (!backendConfig) {
+        return undefined;
+    }
+    if (isRefConfig(backendConfig)) {
+        return {
+            config: materializeWorkspaceObjectConfig(refs, backendConfig.ref, ["backend"], `Agent ${agent.id} backend`),
+        };
+    }
+    return { config: backendConfig };
 }
 function isRefConfig(value) {
     if (typeof value?.ref !== "string" || value.ref.trim().length === 0) {
@@ -161,6 +169,11 @@ function materializeWorkspaceObjectConfig(refs, ref, allowedKinds, ownerLabel) {
         const { checkpointerKind: _checkpointerKind, ...rest } = config;
         return checkpointerKind ? { kind: checkpointerKind, ...rest } : config;
     }
+    if (object.kind === "backend") {
+        const backendKind = typeof config.backendKind === "string" ? config.backendKind : undefined;
+        const { backendKind: _backendKind, ...rest } = config;
+        return backendKind ? { kind: backendKind, ...rest } : config;
+    }
     return config;
 }
 function resolveStoreConfig(agent, refs) {
@@ -208,7 +221,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
     const compiledAgentSkills = compileAgentSkills(workspaceRoot, agent);
     const compiledAgentMemory = compileAgentMemories(workspaceRoot, agent.memorySources);
     const compiledAgentModel = requireModel(models, agent.modelRef || (internalSubagent ? "model/default" : ""), agent.id);
-    const backend = resolveBackendConfig(agent);
+    const backend = resolveBackendConfig(agent, refs);
     const store = resolveStoreConfig(agent, refs);
     const checkpointer = resolveCheckpointerConfig(agent, refs);
     const runRoot = typeof agent.runRoot === "string" && agent.runRoot.trim().length > 0

package/dist/workspace/object-loader.js

@@ -377,11 +377,13 @@ async function objectItemsFromDocument(document, sourcePath) {
         ? normalizeCatalogSpec(document, { defaultKind: "Model" })
         : catalogKind === "Stores"
             ? normalizeCatalogSpec(document)
-            : catalogKind === "Tools"
-                ? normalizeCatalogSpec(document, { defaultKind: "Tool" })
-                : catalogKind === "McpServers"
-                    ? normalizeCatalogSpec(document)
-                    : [];
+            : catalogKind === "Backends"
+                ? normalizeCatalogSpec(document, { defaultKind: "Backend" })
+                : catalogKind === "Tools"
+                    ? normalizeCatalogSpec(document, { defaultKind: "Tool" })
+                    : catalogKind === "McpServers"
+                        ? normalizeCatalogSpec(document)
+                        : [];
     if (catalogItems.length > 0) {
         return catalogItems;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.51",
+  "version": "0.0.52",
   "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/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/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",