@botbotgo/agent-harness 0.0.50 → 0.0.52

package/README.md

@@ -6,21 +6,22 @@
 
 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:
+The boundary is strict:
 
 - LangChain v1 and DeepAgents own agent execution semantics
-- `agent-harness` owns application runtime semantics
+- `agent-harness` owns application-level orchestration and lifecycle management
 
 That means:
 
 - public API stays small
-- complex assembly and policy live in YAML
-- runtime lifecycle stays stable even if the backend implementation changes
+- 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/
@@ -201,11 +203,11 @@ metadata:
 spec:
   execution:
     backend: deepagent
-  modelRef: model/default
-  mcpServers:
-    - name: browser
-      command: node
-      args: ["./mcp-browser-server.mjs"]
+    modelRef: model/default
+    mcpServers:
+      - name: browser
+        command: node
+        args: ["./mcp-browser-server.mjs"]
 ```
 
 The runtime discovers MCP tools, filters them through agent configuration, and exposes them like other tools.
@@ -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.
@@ -347,6 +382,13 @@ Use this file for named MCP server presets.
 
 Agents are always declared with `kind: Agent` and `spec.execution.backend`.
 
+Use two nested sections inside each agent:
+
+- `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:
 
 ```yaml
@@ -357,10 +399,11 @@ metadata:
 spec:
   execution:
     backend: langchain-v1
-  modelRef: model/default
-  checkpointer:
-    ref: checkpointer/default
-  systemPrompt: Answer simple requests directly.
+    modelRef: model/default
+    config:
+      checkpointer:
+        ref: checkpointer/default
+      systemPrompt: Answer simple requests directly.
 ```
 
 Example main execution host:
@@ -373,21 +416,16 @@ metadata:
 spec:
   execution:
     backend: deepagent
-  modelRef: model/default
-  memory:
-    - path: config/agent-context.md
-  store:
-    ref: store/default
-  checkpointer:
-    ref: checkpointer/default
-  backend:
-    kind: CompositeBackend
-    state:
-      kind: VfsSandbox
-      timeout: 600
-    routes:
-      /memories/:
-        kind: StoreBackend
+    modelRef: model/default
+    memory:
+      - path: config/agent-context.md
+    config:
+      store:
+        ref: store/default
+      checkpointer:
+        ref: checkpointer/default
+      backend:
+        ref: backend/default
 ```
 
 Client-configurable agent fields include:
@@ -395,21 +433,29 @@ Client-configurable agent fields include:
 - `metadata.name`
 - `metadata.description`
 - `spec.execution.backend`
-- `spec.modelRef`
-- `spec.systemPrompt`
-- `spec.tools`
-- `spec.skills`
-- `spec.memory`
-- `spec.checkpointer`
-- `spec.store`
-- `spec.backend`
-- `spec.middleware`
-- `spec.subagents`
-- `spec.mcpServers`
-- `spec.responseFormat`
-- `spec.contextSchema`
-
-For backend-specific agent options, prefer passing the upstream concept directly in YAML. The loader keeps a small stable product shape, but it also preserves agent-level passthrough fields so new LangChain v1 or DeepAgents parameters can flow into adapters without expanding the public API surface.
+- `spec.runtime.runRoot`
+- `spec.execution.modelRef`
+- `spec.execution.tools`
+- `spec.execution.skills`
+- `spec.execution.memory`
+- `spec.execution.subagents`
+- `spec.execution.mcpServers`
+- `spec.execution.config.systemPrompt`
+- `spec.execution.config.checkpointer`
+- `spec.execution.config.store`
+- `spec.execution.config.backend`
+- `spec.execution.config.middleware`
+- `spec.execution.config.responseFormat`
+- `spec.execution.config.contextSchema`
+- `spec.execution.config.stateSchema`
+- `spec.execution.config.interruptOn`
+- `spec.execution.config.filesystem`
+- `spec.execution.config.taskDescription`
+- `spec.execution.config.generalPurposeAgent`
+- `spec.execution.config.includeAgentName`
+- `spec.execution.config.version`
+
+For backend-specific agent options, prefer passing the upstream concept directly inside `spec.execution.config`. The loader keeps a small stable product shape, but it also preserves adapter-facing passthrough fields so new LangChain v1 or DeepAgents parameters can flow into adapters without expanding the public API surface.
 
 ### `resources/`
 
@@ -431,7 +477,6 @@ SKILL packages are discovered from `resources/skills/` and attached to agents th
 - 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
-- application-level orchestration and lifecycle management stays in the harness
 
 In short: `agent-harness` is a public runtime contract generic enough to survive backend changes, while the deep execution semantics stay upstream.
 

package/dist/config/agents/direct.yaml

@@ -9,41 +9,43 @@ metadata:
   # agent-harness feature: human-readable summary for inventory and UI.
   description: Manual low-latency host for direct answers and lightweight inventory lookup. Do not use it as the default executor for tool-heavy or specialist-shaped tasks.
 spec:
-  execution:
-    # Current backend adapter for this host profile.
-    backend: langchain-v1
+  runtime: {}
   # =====================
   # Runtime Agent Features
   # =====================
-  # Upstream execution feature: model ref for the underlying LLM used by the direct-response agent.
-  # This should point at a cheap, fast, general-purpose chat model, because `direct` is intended
-  # to be the low-latency path for simple requests.
-  modelRef: model/default
-  # Runtime execution feature: checkpointer config passed into the selected backend adapter.
-  # Even the lightweight direct path can benefit from resumable state during interactive use.
-  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
-  # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
-  checkpointer:
-    ref: checkpointer/default
-  # Upstream execution feature: system prompt for the lightweight direct-response host.
-  # This prompt should keep the agent focused on:
-  # - answering simple requests in one turn
-  # - staying lightweight instead of planning or orchestrating
-  # - avoiding specialist-style decomposition unless the caller explicitly switches agents
-  #
-  # The direct host is intentionally narrower than the orchestra host:
-  # - `direct` is optimized for latency and straightforward completion
-  # - `orchestra` is optimized for multi-step work, tools, delegation, and specialist use
-  #
-  # Keep this prompt biased toward concise, self-contained answers. If richer routing policy is
-  # needed for choosing between host agents, configure that separately via `Runtime.spec.routing`
-  # rather than overloading the direct host prompt with classifier behavior.
-  systemPrompt: |-
-    You are the direct agent.
+  execution:
+    # Current backend adapter for this host profile.
+    backend: langchain-v1
+    # Upstream execution feature: model ref for the underlying LLM used by the direct-response agent.
+    # This should point at a cheap, fast, general-purpose chat model, because `direct` is intended
+    # to be the low-latency path for simple requests.
+    modelRef: model/default
+    config:
+      # Runtime execution feature: checkpointer config passed into the selected backend adapter.
+      # Even the lightweight direct path can benefit from resumable state during interactive use.
+      # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
+      # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
+      checkpointer:
+        ref: checkpointer/default
+      # Upstream execution feature: system prompt for the lightweight direct-response host.
+      # This prompt should keep the agent focused on:
+      # - answering simple requests in one turn
+      # - staying lightweight instead of planning or orchestrating
+      # - avoiding specialist-style decomposition unless the caller explicitly switches agents
+      #
+      # The direct host is intentionally narrower than the orchestra host:
+      # - `direct` is optimized for latency and straightforward completion
+      # - `orchestra` is optimized for multi-step work, tools, delegation, and specialist use
+      #
+      # Keep this prompt biased toward concise, self-contained answers. If richer routing policy is
+      # needed for choosing between host agents, configure that separately via `Runtime.spec.routing`
+      # rather than overloading the direct host prompt with classifier behavior.
+      systemPrompt: |-
+        You are the direct agent.
 
-    This is a manual low-latency host.
-    Answer simple requests directly.
-    Keep the path lightweight.
-    Do not delegate.
-    Do not perform broad multi-step execution.
-    Do not behave like the default execution host.
+        This is a manual low-latency host.
+        Answer simple requests directly.
+        Keep the path lightweight.
+        Do not delegate.
+        Do not perform broad multi-step execution.
+        Do not behave like the default execution host.

package/dist/config/agents/orchestra.yaml

@@ -9,86 +9,80 @@ metadata:
   # agent-harness feature: human-readable summary for inventory and UI.
   description: Default execution host. Answer directly when possible, use local tools and skills first, and delegate only when a specialist is a better fit. Not a reflex delegation-only planner.
 spec:
-  execution:
-    # Current backend adapter for this host profile.
-    backend: deepagent
+  runtime: {}
   # =====================
   # Runtime Agent Features
   # =====================
-  # Upstream execution feature: model ref for the underlying LLM used by this execution host.
-  modelRef: model/default
-  # Runtime execution feature: checkpointer config passed into the selected backend adapter.
-  # This persists resumable graph state for this agent.
-  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
-  # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
-  checkpointer:
-    # ref: checkpointer/sqlite
-    ref: checkpointer/default
-  memory:
-    # Upstream execution feature: bootstrap memory sources supplied to the selected backend at construction time.
-    # These paths resolve relative to the workspace root unless they are already absolute.
-    # Treat this as agent-owned startup context, not as a dynamic long-term memory sink:
-    # - keep `systemPrompt` for stable role, boundaries, and hard behavioral rules
-    # - use `memory:` for stable project knowledge, operating conventions, and shared or agent-specific context files
-    # - use `/memories/*` via the backend/store below for durable knowledge learned from prior runs
-    # - use the harness checkpointer for resumable graph state for an in-flight run
-    # Updating these files changes future agent constructions, but they are still bootstrap inputs rather than
-    # self-updating runtime memory.
-    - path: config/agent-context.md
-  # 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`.
-  store:
-    ref: store/default
-  # Upstream execution feature: backend config passed into the selected backend adapter.
-  # This directly defines the backend topology for this agent:
-  # - 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`.
-  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
-  # 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.
-  systemPrompt: |-
-    You are the orchestra agent.
+  execution:
+    # Current backend adapter for this host profile.
+    backend: deepagent
+    # Upstream execution feature: model ref for the underlying LLM used by this execution host.
+    modelRef: model/default
+    memory:
+      # Upstream execution feature: bootstrap memory sources supplied to the selected backend at construction time.
+      # These paths resolve relative to the workspace root unless they are already absolute.
+      # Treat this as agent-owned startup context, not as a dynamic long-term memory sink:
+      # - keep `systemPrompt` for stable role, boundaries, and hard behavioral rules
+      # - use `memory:` for stable project knowledge, operating conventions, and shared or agent-specific context files
+      # - use `/memories/*` via the backend/store below for durable knowledge learned from prior runs
+      # - use the harness checkpointer for resumable graph state for an in-flight run
+      # Updating these files changes future agent constructions, but they are still bootstrap inputs rather than
+      # self-updating runtime memory.
+      - path: config/agent-context.md
+    config:
+      # Runtime execution feature: checkpointer config passed into the selected backend adapter.
+      # This persists resumable graph state for this agent.
+      # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
+      # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
+      checkpointer:
+        # ref: checkpointer/sqlite
+        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.
+      # 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.
+      # 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 injects the resolved store/checkpointer instances, but the backend topology itself stays upstream-shaped.
+      backend:
+        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.
+      systemPrompt: |-
+        You are the orchestra agent.
 
-    You are the default execution host.
-    Try to finish the request yourself before delegating.
-    Use your own tools first when they are sufficient.
-    Use your own skills first when they are sufficient.
-    Delegate only when a specialist is a clearly better fit or when your own tools and skills are not enough.
-    If neither you nor any suitable specialist can do the work, say so plainly.
+        You are the default execution host.
+        Try to finish the request yourself before delegating.
+        Use your own tools first when they are sufficient.
+        Use your own skills first when they are sufficient.
+        Delegate only when a specialist is a clearly better fit or when your own tools and skills are not enough.
+        If neither you nor any suitable specialist can do the work, say so plainly.
 
-    Do not delegate by reflex.
-    Do not delegate just because a task has multiple steps.
-    Do not delegate when a direct answer or a short local tool pass is enough.
-    Keep the critical path local when immediate progress depends on it; otherwise delegate bounded sidecar work to
-    the most appropriate specialist.
+        Do not delegate by reflex.
+        Do not delegate just because a task has multiple steps.
+        Do not delegate when a direct answer or a short local tool pass is enough.
+        Keep the critical path local when immediate progress depends on it; otherwise delegate bounded sidecar work to
+        the most appropriate specialist.
 
-    Use your own tools for lightweight discovery, inventory, and context gathering.
-    Prefer the structured checkout, indexing, retrieval, and inventory tools that are already attached to you over
-    ad hoc shell work when those tools are sufficient.
-    Use the attached specialist descriptions as the source of truth for what each specialist is for.
-    Do not delegate to a specialist whose description does not clearly match the task.
-    Integrate specialist results into one coherent answer and do not claim checks or evidence you did not obtain.
+        Use your own tools for lightweight discovery, inventory, and context gathering.
+        Prefer the structured checkout, indexing, retrieval, and inventory tools that are already attached to you over
+        ad hoc shell work when those tools are sufficient.
+        Use the attached specialist descriptions as the source of truth for what each specialist is for.
+        Do not delegate to a specialist whose description does not clearly match the task.
+        Integrate specialist results into one coherent answer and do not claim checks or evidence you did not obtain.
 
-    When the user asks about available tools, skills, or agents, use the attached inventory tools instead of
-    inferring from memory.
+        When the user asks about available tools, skills, or agents, use the attached inventory tools instead of
+        inferring from memory.
 
-    Write to `/memories/*` only when the information is durable, reusable across future runs or threads, and likely
-    to matter again: user preferences, project conventions, confirmed decisions, reusable summaries, and stable
-    ownership facts are good candidates.
-    Do not store transient reasoning, temporary plans, scratch work, one-off search results, or intermediate
-    outputs that can be cheaply recomputed.
+        Write to `/memories/*` only when the information is durable, reusable across future runs or threads, and likely
+        to matter again: user preferences, project conventions, confirmed decisions, reusable summaries, and stable
+        ownership facts are good candidates.
+        Do not store transient reasoning, temporary plans, scratch work, one-off search results, or intermediate
+        outputs that can be cheaply recomputed.

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/contracts/types.d.ts

@@ -95,6 +95,7 @@ export type LangChainAgentParams = {
     stateSchema?: unknown;
     responseFormat?: unknown;
     contextSchema?: unknown;
+    filesystem?: Record<string, unknown>;
     middleware?: Array<Record<string, unknown>>;
     passthrough?: Record<string, unknown>;
     subagents?: CompiledSubAgent[];

package/dist/package-version.d.ts

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

package/dist/package-version.js

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

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

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { Command, MemorySaver } from "@langchain/langgraph";
 import { tool as createLangChainTool } from "@langchain/core/tools";
 import { createDeepAgent, createMemoryMiddleware, createSkillsMiddleware, createSubAgentMiddleware, FilesystemBackend, } from "deepagents";
@@ -475,10 +476,20 @@ export class AgentRuntimeAdapter {
         return this.compileInterruptOn(getBindingPrimaryTools(binding), getBindingInterruptCompatibilityRules(binding));
     }
     resolveFilesystemBackend(binding) {
+        const filesystemConfig = getBindingLangChainParams(binding)?.filesystem;
+        const configuredRootDir = typeof filesystemConfig?.rootDir === "string" && filesystemConfig.rootDir.trim().length > 0
+            ? filesystemConfig.rootDir
+            : undefined;
+        const workspaceRoot = binding.harnessRuntime.workspaceRoot;
+        const rootDir = configuredRootDir
+            ? (path.isAbsolute(configuredRootDir) ? configuredRootDir : path.resolve(workspaceRoot ?? process.cwd(), configuredRootDir))
+            : workspaceRoot ?? process.cwd();
         return new FilesystemBackend({
-            rootDir: "/",
-            virtualMode: false,
-            maxFileSizeMb: 10,
+            rootDir,
+            virtualMode: filesystemConfig?.virtualMode === true,
+            maxFileSizeMb: typeof filesystemConfig?.maxFileSizeMb === "number" && Number.isFinite(filesystemConfig.maxFileSizeMb)
+                ? filesystemConfig.maxFileSizeMb
+                : 10,
         });
     }
     async resolveLangChainAutomaticMiddleware(binding) {

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
@@ -245,6 +258,9 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             stateSchema: agent.langchainAgentConfig?.stateSchema,
             responseFormat: agent.langchainAgentConfig?.responseFormat,
             contextSchema: agent.langchainAgentConfig?.contextSchema,
+            filesystem: typeof agent.langchainAgentConfig?.filesystem === "object" && agent.langchainAgentConfig.filesystem
+                ? { ...agent.langchainAgentConfig.filesystem }
+                : undefined,
             middleware: compileMiddlewareConfigs(agent.langchainAgentConfig?.middleware, models, agent.id),
             passthrough: typeof agent.langchainAgentConfig?.passthrough === "object" && agent.langchainAgentConfig.passthrough
                 ? { ...agent.langchainAgentConfig.passthrough }

package/dist/workspace/object-loader.js

@@ -61,6 +61,11 @@ function toArray(value) {
 function asObject(value) {
     return typeof value === "object" && value ? value : undefined;
 }
+function asMutableObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? { ...value }
+        : undefined;
+}
 function normalizeCatalogSpec(document, options = {}) {
     const typed = asObject(document);
     const spec = typed?.spec;
@@ -211,9 +216,14 @@ function readCapabilities(value) {
     return Object.keys(capabilities).length > 0 ? capabilities : undefined;
 }
 function readExecutionConfig(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? { ...value }
-        : undefined;
+    return asMutableObject(value);
+}
+function readExecutionAgentConfig(item) {
+    const execution = readExecutionConfig(item.execution);
+    return asMutableObject(execution?.config) ?? {};
+}
+function readRuntimeConfig(item) {
+    return asMutableObject(item.runtime);
 }
 function cloneConfigValue(value) {
     if (Array.isArray(value)) {
@@ -245,21 +255,42 @@ function resolveExecutionBackend(item, current) {
     }
     return undefined;
 }
-function readSharedAgentConfig(item) {
-    const middleware = readMiddlewareArray(item.middleware);
-    const passthrough = readPassthroughConfig(item, [
-        "id",
-        "kind",
-        "description",
-        "modelRef",
-        "runRoot",
-        "tools",
-        "mcpServers",
-        "skills",
-        "memory",
-        "subagents",
-        "execution",
-        "capabilities",
+function readExecutionSingleRef(item, key) {
+    const execution = readExecutionConfig(item.execution);
+    return readSingleRef(execution?.[key]);
+}
+function readExecutionRefArray(item, key) {
+    const execution = readExecutionConfig(item.execution);
+    return readRefArray(execution?.[key]);
+}
+function readExecutionPathArray(item, key) {
+    const execution = readExecutionConfig(item.execution);
+    return readPathArray(execution?.[key]);
+}
+function readExecutionObjectArray(item, key) {
+    const execution = readExecutionConfig(item.execution);
+    return readObjectArray(execution?.[key]);
+}
+function readSharedAgentConfig(config) {
+    const middleware = readMiddlewareArray(config.middleware);
+    return {
+        ...(typeof config.systemPrompt === "string" ? { systemPrompt: config.systemPrompt } : {}),
+        ...((typeof config.checkpointer === "object" && config.checkpointer) || typeof config.checkpointer === "boolean"
+            ? { checkpointer: config.checkpointer }
+            : {}),
+        ...(typeof config.interruptOn === "object" && config.interruptOn ? { interruptOn: config.interruptOn } : {}),
+        ...(config.stateSchema !== undefined ? { stateSchema: config.stateSchema } : {}),
+        ...(config.responseFormat !== undefined ? { responseFormat: config.responseFormat } : {}),
+        ...(config.contextSchema !== undefined ? { contextSchema: config.contextSchema } : {}),
+        ...(config.includeAgentName === "inline" ? { includeAgentName: "inline" } : {}),
+        ...(config.version === "v1" || config.version === "v2" ? { version: config.version } : {}),
+        ...(typeof config.filesystem === "object" && config.filesystem ? { filesystem: config.filesystem } : {}),
+        ...(middleware ? { middleware } : {}),
+    };
+}
+function readLangchainAgentConfig(item) {
+    const config = readExecutionAgentConfig(item);
+    const passthrough = readPassthroughConfig(config, [
         "systemPrompt",
         "checkpointer",
         "interruptOn",
@@ -273,43 +304,48 @@ function readSharedAgentConfig(item) {
         "store",
         "taskDescription",
         "generalPurposeAgent",
+        "filesystem",
     ]);
     return {
-        ...(typeof item.systemPrompt === "string" ? { systemPrompt: item.systemPrompt } : {}),
-        ...((typeof item.checkpointer === "object" && item.checkpointer) || typeof item.checkpointer === "boolean"
-            ? { checkpointer: item.checkpointer }
-            : {}),
-        ...(typeof item.interruptOn === "object" && item.interruptOn ? { interruptOn: item.interruptOn } : {}),
-        ...(item.stateSchema !== undefined ? { stateSchema: item.stateSchema } : {}),
-        ...(item.responseFormat !== undefined ? { responseFormat: item.responseFormat } : {}),
-        ...(item.contextSchema !== undefined ? { contextSchema: item.contextSchema } : {}),
-        ...(item.includeAgentName === "inline" ? { includeAgentName: "inline" } : {}),
-        ...(item.version === "v1" || item.version === "v2" ? { version: item.version } : {}),
-        ...(middleware ? { middleware } : {}),
+        ...readSharedAgentConfig(config),
+        ...(typeof config.store === "object" && config.store ? { store: config.store } : {}),
+        ...(typeof config.taskDescription === "string" && config.taskDescription.trim() ? { taskDescription: config.taskDescription } : {}),
+        ...(typeof config.generalPurposeAgent === "boolean" ? { generalPurposeAgent: config.generalPurposeAgent } : {}),
         ...(passthrough ? { passthrough } : {}),
     };
 }
-function readLangchainAgentConfig(item) {
-    return {
-        ...readSharedAgentConfig(item),
-        ...(typeof item.store === "object" && item.store ? { store: item.store } : {}),
-        ...(typeof item.taskDescription === "string" && item.taskDescription.trim() ? { taskDescription: item.taskDescription } : {}),
-        ...(typeof item.generalPurposeAgent === "boolean" ? { generalPurposeAgent: item.generalPurposeAgent } : {}),
-    };
-}
 function readDeepAgentConfig(item) {
+    const config = readExecutionAgentConfig(item);
+    const passthrough = readPassthroughConfig(config, [
+        "systemPrompt",
+        "checkpointer",
+        "interruptOn",
+        "stateSchema",
+        "responseFormat",
+        "contextSchema",
+        "includeAgentName",
+        "version",
+        "middleware",
+        "backend",
+        "store",
+        "taskDescription",
+        "generalPurposeAgent",
+        "filesystem",
+    ]);
     return {
-        ...readSharedAgentConfig(item),
-        ...(typeof item.backend === "object" && item.backend ? { backend: item.backend } : {}),
-        ...(typeof item.store === "object" && item.store ? { store: item.store } : {}),
-        ...(typeof item.taskDescription === "string" && item.taskDescription.trim() ? { taskDescription: item.taskDescription } : {}),
-        ...(typeof item.generalPurposeAgent === "boolean" ? { generalPurposeAgent: item.generalPurposeAgent } : {}),
+        ...readSharedAgentConfig(config),
+        ...(typeof config.backend === "object" && config.backend ? { backend: config.backend } : {}),
+        ...(typeof config.store === "object" && config.store ? { store: config.store } : {}),
+        ...(typeof config.taskDescription === "string" && config.taskDescription.trim() ? { taskDescription: config.taskDescription } : {}),
+        ...(typeof config.generalPurposeAgent === "boolean" ? { generalPurposeAgent: config.generalPurposeAgent } : {}),
+        ...(passthrough ? { passthrough } : {}),
     };
 }
 export function parseAgentItem(item, sourcePath) {
-    const subagentRefs = readRefArray(item.subagents);
-    const subagentPathRefs = readPathArray(item.subagents);
+    const subagentRefs = readExecutionRefArray(item, "subagents");
+    const subagentPathRefs = readExecutionPathArray(item, "subagents");
     const executionMode = String(resolveExecutionBackend(item) ?? "deepagent");
+    const runtime = readRuntimeConfig(item);
     return {
         id: String(item.id),
         executionMode: executionMode,
@@ -317,12 +353,12 @@ export function parseAgentItem(item, sourcePath) {
             ? { delegation: true, memory: true }
             : { delegation: true, memory: true }),
         description: String(item.description ?? ""),
-        modelRef: readSingleRef(item.modelRef) ?? "",
-        runRoot: typeof item.runRoot === "string" ? item.runRoot : undefined,
-        toolRefs: readRefArray(item.tools),
-        mcpServers: readObjectArray(item.mcpServers),
-        skillPathRefs: readPathArray(item.skills),
-        memorySources: readPathArray(item.memory),
+        modelRef: readExecutionSingleRef(item, "modelRef") ?? "",
+        runRoot: typeof runtime?.runRoot === "string" ? runtime.runRoot : undefined,
+        toolRefs: readExecutionRefArray(item, "tools"),
+        mcpServers: readExecutionObjectArray(item, "mcpServers"),
+        skillPathRefs: readExecutionPathArray(item, "skills"),
+        memorySources: readExecutionPathArray(item, "memory"),
         subagentRefs,
         subagentPathRefs,
         langchainAgentConfig: readLangchainAgentConfig(item),
@@ -341,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.50",
+  "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",