@botbotgo/agent-harness 0.0.52 → 0.0.53

package/README.md

@@ -258,6 +258,8 @@ There are three configuration layers:
 - 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.
@@ -324,6 +326,10 @@ spec:
   - kind: Checkpointer
     name: default
     checkpointerKind: MemorySaver
+  - kind: Checkpointer
+    name: sqlite
+    checkpointerKind: SqliteSaver
+    path: checkpoints.sqlite
 ```
 
 Built-in store kinds today:
@@ -352,6 +358,8 @@ spec:
     backendKind: CompositeBackend
     state:
       kind: VfsSandbox
+      rootDir: .
+      virtualMode: true
       timeout: 600
     routes:
       /memories/:
@@ -397,12 +405,23 @@ kind: Agent
 metadata:
   name: direct
 spec:
+  runtime:
+    runRoot: ./.agent
   execution:
     backend: langchain-v1
     modelRef: model/default
+    tools: []
+    skills: []
+    memory: []
+    subagents: []
+    mcpServers: []
     config:
       checkpointer:
         ref: checkpointer/default
+      store:
+        ref: store/default
+      interruptOn: {}
+      middleware: []
       systemPrompt: Answer simple requests directly.
 ```
 
@@ -414,11 +433,17 @@ kind: Agent
 metadata:
   name: orchestra
 spec:
+  runtime:
+    runRoot: ./.agent
   execution:
     backend: deepagent
     modelRef: model/default
     memory:
       - path: config/agent-context.md
+    tools: []
+    skills: []
+    subagents: []
+    mcpServers: []
     config:
       store:
         ref: store/default
@@ -426,6 +451,10 @@ spec:
         ref: checkpointer/default
       backend:
         ref: backend/default
+      interruptOn: {}
+      middleware: []
+      generalPurposeAgent: true
+      taskDescription: Complete delegated sidecar work and return concise results.
 ```
 
 Client-configurable agent fields include:
@@ -457,6 +486,8 @@ Client-configurable agent fields include:
 
 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.
 
+Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
+
 ### `resources/`
 
 Use `resources/` for executable local extensions:
@@ -477,6 +508,7 @@ 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
+- new LangChain v1 or DeepAgents public config should land in YAML passthrough and compatibility tests before adding new 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.
 
@@ -495,5 +527,3 @@ Primary exports:
 - `createToolMcpServer`
 - `serveToolsOverStdio`
 - `stop`
-
-`AgentHarnessRuntime` is the concrete runtime class behind the public facade.

package/dist/config/agents/direct.yaml

@@ -9,7 +9,10 @@ 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:
-  runtime: {}
+  runtime:
+    # agent-harness feature: host-level run data placement override.
+    # This matches the workspace default and keeps the default config shape explicit.
+    runRoot: ./.agent
   # =====================
   # Runtime Agent Features
   # =====================
@@ -20,6 +23,16 @@ spec:
     # 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
+    # Upstream execution feature: direct host starts with no attached explicit tools by default.
+    tools: []
+    # Upstream execution feature: direct host starts with no attached local skill packages by default.
+    skills: []
+    # Upstream execution feature: direct host does not bootstrap project memory by default.
+    memory: []
+    # Upstream execution feature: direct host does not predeclare specialist subagents by default.
+    subagents: []
+    # Upstream execution feature: direct host does not attach MCP servers by default.
+    mcpServers: []
     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.
@@ -27,6 +40,14 @@ spec:
       # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
       checkpointer:
         ref: checkpointer/default
+      # Upstream execution feature: LangGraph store available to middleware and runtime context hooks.
+      # The default direct host keeps this enabled so middleware can use the same durable store surface as other hosts.
+      store:
+        ref: store/default
+      # Upstream execution feature: no declarative HITL tool routing by default.
+      interruptOn: {}
+      # Upstream execution feature: no extra declarative middleware beyond the runtime's automatic injections.
+      middleware: []
       # 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

package/dist/config/agents/orchestra.yaml

@@ -9,7 +9,10 @@ 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:
-  runtime: {}
+  runtime:
+    # agent-harness feature: host-level run data placement override.
+    # This matches the workspace default and keeps the default config shape explicit.
+    runRoot: ./.agent
   # =====================
   # Runtime Agent Features
   # =====================
@@ -29,6 +32,14 @@ spec:
       # 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: top-level host starts with no extra direct tool refs beyond discovered workspace tools.
+    tools: []
+    # Upstream execution feature: top-level host starts with no explicit skill package refs in the default workspace.
+    skills: []
+    # Upstream execution feature: specialist topology is empty in the repository default and can be filled in YAML.
+    subagents: []
+    # Upstream execution feature: host-level MCP servers are opt-in and empty by default.
+    mcpServers: []
     config:
       # Runtime execution feature: checkpointer config passed into the selected backend adapter.
       # This persists resumable graph state for this agent.
@@ -52,6 +63,14 @@ spec:
       # The harness injects the resolved store/checkpointer instances, but the backend topology itself stays upstream-shaped.
       backend:
         ref: backend/default
+      # Upstream execution feature: no extra declarative HITL rules by default.
+      interruptOn: {}
+      # Upstream execution feature: no extra declarative middleware beyond upstream deepagents defaults by default.
+      middleware: []
+      # Upstream execution feature: keep the built-in general-purpose subagent enabled.
+      generalPurposeAgent: true
+      # Upstream execution feature: bias the general-purpose subagent toward bounded sidecar work and context isolation.
+      taskDescription: Complete delegated sidecar work and return concise results without bloating the parent context.
       # 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

@@ -10,6 +10,8 @@ spec:
     backendKind: CompositeBackend
     state:
       kind: VfsSandbox
+      rootDir: .
+      virtualMode: true
       timeout: 600
     routes:
       /memories/:

package/dist/config/stores.yaml

@@ -15,3 +15,10 @@ spec:
     name: default
     description: Default in-memory checkpointer preset for lightweight local development.
     checkpointerKind: MemorySaver
+
+  # agent-harness feature: reusable sqlite checkpointer preset for longer-lived local runs.
+  - kind: Checkpointer
+    name: sqlite
+    description: Default sqlite-backed checkpointer preset for durable local graph state and maintenance sweeps.
+    checkpointerKind: SqliteSaver
+    path: checkpoints.sqlite

package/dist/contracts/types.d.ts

@@ -196,7 +196,6 @@ export type CompiledAgentBinding = {
         config: Record<string, unknown>;
     };
     langchainAgentParams?: LangChainAgentParams;
-    directAgentParams?: LangChainAgentParams;
     deepAgentParams?: DeepAgentParams;
     harnessRuntime: {
         runRoot: string;

package/dist/package-version.d.ts

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

package/dist/package-version.js

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

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

@@ -1,4 +1,12 @@
 import type { CompiledAgentBinding, CompiledModel } from "../contracts/types.js";
+type MiddlewareConfig = Record<string, unknown>;
+type MiddlewareFactoryContext = {
+    config: MiddlewareConfig;
+    resolveModel: (model: CompiledModel) => Promise<unknown>;
+};
+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>;
     resolveCustom?: (input: {
@@ -9,3 +17,4 @@ export declare function resolveDeclaredMiddleware(middlewareConfigs: unknown[] |
     }) => unknown | unknown[] | null | undefined | Promise<unknown | unknown[] | null | undefined>;
     binding?: CompiledAgentBinding;
 }): Promise<unknown[]>;
+export {};

package/dist/runtime/declared-middleware.js

@@ -25,6 +25,52 @@ async function resolveReferencedModelList(values, options) {
     }
     return Promise.all(values.map((value) => resolveReferencedModel(value, options)));
 }
+async function createSummarizationMiddleware({ config, resolveModel }) {
+    const runtimeConfig = { ...config };
+    runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, { resolveModel });
+    if (runtimeConfig.model === undefined) {
+        throw new Error("summarization middleware requires model or modelRef");
+    }
+    return summarizationMiddleware(runtimeConfig);
+}
+async function createLlmToolSelectorMiddleware({ config, resolveModel }) {
+    const runtimeConfig = { ...config };
+    runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, { resolveModel });
+    return llmToolSelectorMiddleware(runtimeConfig);
+}
+async function createModelFallbackDeclarativeMiddleware({ config, resolveModel }) {
+    const fallbackModels = (await resolveReferencedModelList(config.fallbackModels, { resolveModel })) ??
+        (await resolveReferencedModelList(config.models, { resolveModel }));
+    if (!fallbackModels || fallbackModels.length === 0) {
+        throw new Error("modelFallback middleware requires fallbackModels or models");
+    }
+    return modelFallbackMiddleware(...fallbackModels);
+}
+async function createPiiDeclarativeMiddleware({ config }) {
+    const piiType = typeof config.piiType === "string" ? config.piiType : undefined;
+    if (!piiType) {
+        throw new Error("pii middleware requires piiType");
+    }
+    const { piiType: _piiType, ...piiOptions } = config;
+    return piiMiddleware(piiType, piiOptions);
+}
+export const DECLARATIVE_MIDDLEWARE_REGISTRY = {
+    summarization: createSummarizationMiddleware,
+    llmToolSelector: createLlmToolSelectorMiddleware,
+    modelRetry: async ({ config }) => modelRetryMiddleware(config),
+    modelFallback: createModelFallbackDeclarativeMiddleware,
+    toolRetry: async ({ config }) => toolRetryMiddleware(config),
+    toolCallLimit: async ({ config }) => toolCallLimitMiddleware(config),
+    modelCallLimit: async ({ config }) => modelCallLimitMiddleware(config),
+    todoList: async ({ config }) => todoListMiddleware(config),
+    contextEditing: async ({ config }) => contextEditingMiddleware(config),
+    toolEmulator: async ({ config }) => toolEmulatorMiddleware(config),
+    humanInTheLoop: async ({ config }) => humanInTheLoopMiddleware(config),
+    openAIModeration: async ({ config }) => openAIModerationMiddleware(config),
+    pii: createPiiDeclarativeMiddleware,
+    anthropicPromptCaching: async ({ config }) => anthropicPromptCachingMiddleware(config),
+};
+export const SUPPORTED_DECLARATIVE_MIDDLEWARE_KINDS = Object.freeze(Object.keys(DECLARATIVE_MIDDLEWARE_REGISTRY).sort());
 export async function resolveDeclaredMiddleware(middlewareConfigs, options) {
     const resolved = [];
     for (const rawConfig of middlewareConfigs ?? []) {
@@ -34,87 +80,38 @@ export async function resolveDeclaredMiddleware(middlewareConfigs, options) {
         }
         const kind = requireKind(config);
         const runtimeConfig = omitKind(config);
-        switch (kind) {
-            case "summarization": {
-                runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, options);
-                if (runtimeConfig.model === undefined) {
-                    throw new Error("summarization middleware requires model or modelRef");
-                }
-                resolved.push(summarizationMiddleware(runtimeConfig));
-                break;
+        const registeredFactory = DECLARATIVE_MIDDLEWARE_REGISTRY[kind];
+        if (registeredFactory) {
+            const resolvedBuiltin = await registeredFactory({
+                config: runtimeConfig,
+                resolveModel: options.resolveModel,
+            });
+            if (Array.isArray(resolvedBuiltin)) {
+                resolved.push(...resolvedBuiltin);
+                continue;
             }
-            case "llmToolSelector":
-                runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, options);
-                resolved.push(llmToolSelectorMiddleware(runtimeConfig));
-                break;
-            case "modelRetry":
-                resolved.push(modelRetryMiddleware(runtimeConfig));
-                break;
-            case "modelFallback": {
-                const fallbackModels = (await resolveReferencedModelList(runtimeConfig.fallbackModels, options)) ??
-                    (await resolveReferencedModelList(runtimeConfig.models, options));
-                if (!fallbackModels || fallbackModels.length === 0) {
-                    throw new Error("modelFallback middleware requires fallbackModels or models");
-                }
-                resolved.push(modelFallbackMiddleware(...fallbackModels));
-                break;
-            }
-            case "toolRetry":
-                resolved.push(toolRetryMiddleware(runtimeConfig));
-                break;
-            case "toolCallLimit":
-                resolved.push(toolCallLimitMiddleware(runtimeConfig));
-                break;
-            case "modelCallLimit":
-                resolved.push(modelCallLimitMiddleware(runtimeConfig));
-                break;
-            case "todoList":
-                resolved.push(todoListMiddleware(runtimeConfig));
-                break;
-            case "contextEditing":
-                resolved.push(contextEditingMiddleware(runtimeConfig));
-                break;
-            case "toolEmulator":
-                resolved.push(toolEmulatorMiddleware(runtimeConfig));
-                break;
-            case "humanInTheLoop":
-                resolved.push(humanInTheLoopMiddleware(runtimeConfig));
-                break;
-            case "openAIModeration":
-                resolved.push(openAIModerationMiddleware(runtimeConfig));
-                break;
-            case "pii": {
-                const piiType = typeof runtimeConfig.piiType === "string" ? runtimeConfig.piiType : undefined;
-                if (!piiType) {
-                    throw new Error("pii middleware requires piiType");
-                }
-                const { piiType: _piiType, ...piiOptions } = runtimeConfig;
-                resolved.push(piiMiddleware(piiType, piiOptions));
-                break;
-            }
-            case "anthropicPromptCaching":
-                resolved.push(anthropicPromptCachingMiddleware(runtimeConfig));
-                break;
-            default: {
-                const customResolved = options.resolveCustom
-                    ? await options.resolveCustom({
-                        kind,
-                        config: runtimeConfig,
-                        binding: options.binding,
-                        resolveModel: options.resolveModel,
-                    })
-                    : undefined;
-                if (Array.isArray(customResolved)) {
-                    resolved.push(...customResolved);
-                    break;
-                }
-                if (customResolved) {
-                    resolved.push(customResolved);
-                    break;
-                }
-                throw new Error(`Unsupported declarative middleware kind ${kind}`);
+            if (resolvedBuiltin) {
+                resolved.push(resolvedBuiltin);
+                continue;
             }
         }
+        const customResolved = options.resolveCustom
+            ? await options.resolveCustom({
+                kind,
+                config: runtimeConfig,
+                binding: options.binding,
+                resolveModel: options.resolveModel,
+            })
+            : undefined;
+        if (Array.isArray(customResolved)) {
+            resolved.push(...customResolved);
+            continue;
+        }
+        if (customResolved) {
+            resolved.push(customResolved);
+            continue;
+        }
+        throw new Error(`Unsupported declarative middleware kind ${kind}`);
     }
     return resolved;
 }

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

@@ -294,7 +294,6 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
                 },
             },
             langchainAgentParams,
-            directAgentParams: langchainAgentParams,
         };
     }
     const deepAgentParams = {

package/dist/workspace/object-loader.js

@@ -242,11 +242,12 @@ function readPassthroughConfig(item, consumedKeys) {
 }
 function resolveExecutionBackend(item, current) {
     const execution = readExecutionConfig(item.execution) ?? readExecutionConfig(current?.execution);
+    if (typeof execution?.mode === "string" && execution.mode.trim().length > 0) {
+        throw new Error("Agent execution.mode is no longer supported; use execution.backend");
+    }
     const backend = typeof execution?.backend === "string"
         ? execution.backend.trim().toLowerCase()
-        : typeof execution?.mode === "string"
-            ? execution.mode.trim().toLowerCase()
-            : undefined;
+        : undefined;
     if (backend === "langchain-v1") {
         return "langchain-v1";
     }

package/package.json

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