@botbotgo/agent-harness 0.0.48 → 0.0.49

package/README.md

@@ -4,20 +4,26 @@
 
 `@botbotgo/agent-harness` is a workspace-shaped application runtime for real agent products.
 
-It is not a new agent framework. It is the layer that sits around LangChain v1 and DeepAgents so an application can be assembled, configured, operated, and recovered as one runtime.
+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 package is built for the gap between:
+The product boundary is:
 
-- agent execution semantics owned by LangChain v1 and DeepAgents
-- application runtime concerns such as persisted threads, approvals, recovery, routing, maintenance, and local resource loading
+- LangChain v1 and DeepAgents own agent execution semantics
+- `agent-harness` owns application runtime semantics
 
-What it provides:
+That means:
 
-- a small runtime API centered on `createAgentHarness(...)`, `run(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
-- YAML-defined runtime assembly for hosts, models, routing, recovery, concurrency, MCP, and maintenance policy
-- backend-adapted execution with a generic runtime contract and current LangChain v1 / DeepAgents adapters
-- local `resources/tools/` and `resources/skills/` loading
-- persisted runs, threads, approvals, events, queued tasks, and resumable checkpoints
+- public API stays small
+- complex assembly and policy live in YAML
+- runtime lifecycle stays stable even if the backend implementation changes
+
+What the runtime provides:
+
+- `createAgentHarness(...)`, `run(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
+- YAML-defined workspace assembly for routing, models, tools, stores, 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
 
 ## Quick Start
 
@@ -32,8 +38,8 @@ Workspace layout:
 ```text
 your-workspace/
   config/
-    agent-context.md
     workspace.yaml
+    agent-context.md
     models.yaml
     embedding-models.yaml
     vector-stores.yaml
@@ -71,15 +77,14 @@ try {
 ## Feature List
 
 - Workspace runtime for multi-agent applications
-- Generic runtime contract with backend-adapted execution
-- YAML-defined host routing
+- Small public runtime contract
+- YAML-defined host routing and runtime policy
+- LangChain v1 and DeepAgents backend adaptation
 - Auto-discovered local tools and SKILL packages
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
-- Persisted threads, runs, approvals, and lifecycle events
-- Recovery policy and resumable checkpoints
-- Background checkpoint maintenance
-- Runtime-level concurrency control and queued-run persistence
+- Persisted threads, runs, approvals, lifecycle events, and queued runs
+- Runtime-managed recovery and checkpoint maintenance
 
 ## How To Use
 
@@ -91,8 +96,6 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-You can also create a runtime from a precompiled `WorkspaceBundle`.
-
 `createAgentHarness(...)` loads one workspace, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
 
 ### Run A Request
@@ -103,25 +106,28 @@ import { run } from "@botbotgo/agent-harness";
 const result = await run(runtime, {
   agentId: "orchestra",
   input: "Summarize the runtime design.",
-  context: {
-    requestId: "req-123",
-  },
-  state: {
-    visitCount: 1,
+  invocation: {
+    context: {
+      requestId: "req-123",
+    },
+    inputs: {
+      visitCount: 1,
+    },
+    attachments: {
+      "/tmp/spec.md": { content: "draft" },
+    },
   },
 });
 ```
 
 Each run creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and the final user-facing output text.
 
-The preferred runtime-facing way to pass execution metadata is `invocation`:
+Use `invocation` as the runtime-facing request envelope:
 
-- `invocation.context` for request-scoped context
+- `invocation.context` for request-scoped execution context
 - `invocation.inputs` for additional structured runtime inputs
 - `invocation.attachments` for attachment-like payloads that the active backend can interpret
 
-For compatibility, `context`, `state`, and `files` are still accepted as existing aliases and are normalized into the same runtime invocation envelope.
-
 ### Let The Runtime Route
 
 ```ts
@@ -152,7 +158,7 @@ const result = await run(runtime, {
 
 `subscribe(...)` is a read-only observer surface over stored lifecycle events.
 
-The event stream includes:
+The runtime event stream includes:
 
 - `run.created`
 - `run.queued`
@@ -183,14 +189,18 @@ These methods return runtime-facing records, not raw persistence or backend chec
 ### Bridge MCP Servers Into Agents
 
 ```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: orchestra
 spec:
+  execution:
+    backend: deepagent
+  modelRef: model/default
   mcpServers:
     - name: browser
       command: node
       args: ["./mcp-browser-server.mjs"]
-    - name: docs
-      transport: http
-      url: https://example.com/mcp
 ```
 
 The runtime discovers MCP tools, filters them through agent configuration, and exposes them like other tools.
@@ -214,6 +224,11 @@ await stop(runtime);
 
 ## How To Configure
 
+Use Kubernetes-style YAML:
+
+- collection files use `apiVersion`, plural `kind`, and `spec: []`
+- single-object files use `apiVersion`, singular `kind`, `metadata`, and `spec`
+
 Core workspace files:
 
 - `config/workspace.yaml`
@@ -226,24 +241,14 @@ Core workspace files:
 - `config/mcp.yaml`
 - `config/agents/direct.yaml`
 - `config/agents/orchestra.yaml`
-- `resources/package.json`
 - `resources/tools/`
 - `resources/skills/`
 
-Use Kubernetes-style YAML:
-
-- collection files use `apiVersion`, plural `kind`, and `spec: []`
-- single-object files use `apiVersion`, singular `kind`, `metadata`, and `spec`
-
-Use distinct names for named objects such as models, stores, checkpointers, tools, and MCP servers.
-
 ### Client-Configurable YAML Reference
 
-This section is the client-facing explanation of what can be configured in YAML today and what each field changes at runtime.
+There are three configuration layers:
 
-There are three layers of client configuration:
-
-- runtime-level policy in `config/workspace.yaml`
+- runtime policy in `config/workspace.yaml`
 - reusable object catalogs in `config/*.yaml`
 - agent assembly in `config/agents/*.yaml`
 
@@ -253,92 +258,30 @@ Use this file for runtime-level policy shared by the whole workspace.
 
 Primary fields:
 
-- `runRoot`: root directory where the runtime stores thread indexes, runs, approvals, artifacts, queued requests, and default local persistence
-- `routing.defaultAgentId`: default host selected when no explicit routing rule matches
-- `routing.rules`: ordered YAML routing rules evaluated before backend routing
-- `routing.systemPrompt`: optional model-classifier prompt used only when model routing is enabled
-- `routing.modelRouting`: opt in to model-driven host classification fallback
-- `concurrency.maxConcurrentRuns`: maximum number of active runs; extra runs enter the persistent queue
-- `recovery.enabled`: enables runtime-managed startup recovery
-- `recovery.resumeOnStartup`: compatibility alias for resuming interrupted approval-driven runs on startup
-- `recovery.resumeResumingRunsOnStartup`: explicit control for resuming interrupted approval-driven runs on startup
-- `recovery.maxRecoveryAttempts`: upper bound for startup recovery retries
-- `maintenance.checkpoints.enabled`: turns on background checkpoint cleanup
-- `maintenance.checkpoints.schedule.intervalSeconds`: maintenance loop interval
-- `maintenance.checkpoints.schedule.runOnStartup`: run checkpoint cleanup during startup
-- `maintenance.checkpoints.policies.maxAgeSeconds`: age-based checkpoint cleanup
-- `maintenance.checkpoints.policies.maxBytes`: size-based checkpoint cleanup
-- `maintenance.checkpoints.sqlite.sweepBatchSize`: batch size for SQLite cleanup scans
-- `maintenance.checkpoints.sqlite.vacuum`: vacuum SQLite after deletions
+- `runRoot`
+- `concurrency.maxConcurrentRuns`
+- `routing.defaultAgentId`
+- `routing.rules`
+- `routing.systemPrompt`
+- `routing.modelRouting`
+- `maintenance.checkpoints`
+- `recovery.enabled`
+- `recovery.resumeResumingRunsOnStartup`
+- `recovery.maxRecoveryAttempts`
 
 If `runRoot` is omitted, the runtime defaults to `<workspace-root>/run-data`.
 
-Example:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Runtime
-metadata:
-  name: default
-spec:
-  runRoot: ./.agent
-  concurrency:
-    maxConcurrentRuns: 3
-  routing:
-    defaultAgentId: orchestra
-    modelRouting: false
-    rules:
-      - agentId: orchestra
-        contains: ["latest", "recent", "today", "news"]
-      - agentId: orchestra
-        regex:
-          - "\\b(create|build|implement|fix|debug|review|inspect)\\b"
-  maintenance:
-    checkpoints:
-      enabled: true
-      schedule:
-        intervalSeconds: 3600
-        runOnStartup: true
-      policies:
-        maxAgeSeconds: 604800
-      sqlite:
-        sweepBatchSize: 200
-        vacuum: false
-  recovery:
-    enabled: true
-    resumeResumingRunsOnStartup: true
-    maxRecoveryAttempts: 3
-```
-
-Notes:
-
-- `routing.rules` only choose the starting host agent; they do not replace backend planning semantics
-- queued runs are persisted under `runRoot` and continue after process restart
-- `running` runs are only replayed on startup when the bound tools are retryable
+Queued runs are persisted under `runRoot` and continue after process restart. `running` runs are only replayed on startup when the bound tools are retryable.
 
 ### `config/agent-context.md`
 
-Use this file for shared startup context loaded into agents at construction time.
+Use this file for shared bootstrap context loaded into agents at construction time.
 
 Put stable project context here. Do not use it as mutable long-term memory.
 
-Good uses:
-
-- product positioning
-- codebase conventions
-- stable domain vocabulary
-- organization-specific rules
-
-Bad uses:
-
-- transient scratch notes
-- per-run execution state
-- approval packets
-- long-term memory that should live in the store
-
 ### `config/models.yaml`
 
-Use one file for multiple named models:
+Use named chat-model presets:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -348,80 +291,21 @@ spec:
     provider: openai
     model: gpt-4.1
     temperature: 0.2
-  - name: planner
-    provider: openai
-    model: gpt-4.1-mini
 ```
 
-These load as `model/default` and `model/planner`.
-
-Client-configurable model fields:
-
-- `name`: catalog name referenced by `model/<name>`
-- `provider`: provider family such as `openai`, `openai-compatible`, `ollama`, `anthropic`, or `google`
-- `model`: provider model id
-- top-level provider init fields such as `temperature`, `baseUrl`, API-specific settings, and client options
-- `clientRef`: optional external client reference
-- `fallbacks`: optional fallback model refs
-- `metadata`: optional model metadata
+These load as `model/<name>`.
 
 ### `config/embedding-models.yaml`
 
-Use this file for named embedding model presets used by retrieval-oriented tools.
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: EmbeddingModels
-spec:
-  - name: default
-    provider: ollama
-    model: nomic-embed-text
-    baseUrl: http://localhost:11434
-```
-
-Client-configurable embedding fields:
-
-- `name`
-- `provider`
-- `model`
-- top-level provider init fields such as `baseUrl`
-- `clientRef`
-- `metadata`
-
-These load as `embedding-model/default`.
+Use named embedding-model presets for retrieval-oriented tools.
 
 ### `config/vector-stores.yaml`
 
-Use this file for named vector store presets referenced by retrieval tools.
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: VectorStores
-spec:
-  - name: default
-    storeKind: LibSQLVectorStore
-    url: file:.agent/vector-store.db
-    table: rag_chunks
-    column: embedding
-    embeddingModelRef: embedding-model/default
-```
-
-Client-configurable vector store fields:
-
-- `name`
-- `storeKind`
-- `url`
-- `authToken`
-- `table`
-- `column`
-- `embeddingModelRef`
-- `metadata`
-
-These load as `vector-store/default`.
+Use named vector-store presets referenced by retrieval tools.
 
 ### `config/stores.yaml`
 
-Use one file for named persistence presets:
+Use reusable store and checkpointer presets:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -436,119 +320,31 @@ spec:
     checkpointerKind: MemorySaver
 ```
 
-These load as `store/default` and `checkpointer/default`.
-
-Client-configurable store fields:
-
-- `kind: Store` for backend stores
-- `kind: Checkpointer` for resumable execution state
-- `name` for refs
-- `storeKind` such as `FileStore`, `InMemoryStore`, `RedisStore`, `PostgresStore`
-- `checkpointerKind` such as `MemorySaver`, `FileCheckpointer`, `SqliteSaver`
-- storage-specific fields such as `path`, connection strings, auth, and provider options
-
 ### `config/tools.yaml`
 
-Use this file for reusable tool presets and tool bundles.
-
-Minimal collection form:
+Use this file for reusable tool objects.
 
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Tools
-spec:
-  - kind: Tool
-    name: fetch_docs
-    type: function
-    description: Fetch a documentation page.
-```
+Supported tool families in the built-in runtime include:
 
-Client-configurable tool fields:
+- function tools
+- backend tools
+- MCP tools
+- provider-native tools
+- bundles
 
-- `name`
-- `type`: `function`, `backend`, `mcp`, or `bundle`
-- `description`
-- `implementationName` for local JS tool modules
-- `inputSchema.ref`
-- `backend.operation`
-- `mcp.ref` or `mcp.tool`
-- `refs` for bundle composition
-- `hitl.enabled` and `hitl.allow` for approval-gated tools
-- `retryable: true` for tools that are safe to replay during startup recovery
-- `config` for tool-specific options
+Provider-native tools are declared in YAML and resolved directly to upstream provider tool factories such as OpenAI and Anthropic tool objects.
 
 Use `retryable` carefully. Mark a tool retryable only when repeated execution is safe or intentionally idempotent.
 
 ### `config/mcp.yaml`
 
-Use this file for reusable MCP server definitions and MCP-backed tool presets.
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: McpServers
-spec:
-  - name: docs
-    transport: http
-    url: https://example.com/mcp
-  - name: local-browser
-    transport: stdio
-    command: node
-    args: ["./mcp-browser-server.mjs"]
-```
-
-Client-configurable MCP fields:
-
-- `name`
-- `transport`: `stdio`, `http`, `sse`, or `websocket`
-- `command`, `args`, `env`, `cwd` for stdio servers
-- `url`, `token`, `headers` for network servers
-
-These load as `mcp/<name>`.
+Use this file for named MCP server presets.
 
 ### `config/agents/*.yaml`
 
-Prefer the generic agent form and declare the current execution backend explicitly:
-
-```yaml
-apiVersion: agent-harness/v1alpha1
-kind: Agent
-metadata:
-  name: orchestra
-spec:
-  modelRef: model/default
-  execution:
-    backend: deepagent
-  systemPrompt: Coordinate the request.
-```
-
-Only `kind: Agent` is supported for agent objects. Select the concrete backend with `spec.execution.backend`.
-
-Common client-configurable agent fields:
-
-- `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`
-
-Typical patterns:
+Agents are always declared with `kind: Agent` and `spec.execution.backend`.
 
-- use `direct` as a lightweight host for simple one-turn requests
-- use `orchestra` as the main execution host for tools, multi-step work, and delegation
-- keep routing policy in `config/workspace.yaml`, not buried in prompts
-
-Example direct agent:
+Example lightweight host:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -561,12 +357,10 @@ spec:
   modelRef: model/default
   checkpointer:
     ref: checkpointer/default
-  systemPrompt: |-
-    You are the direct agent.
-    Answer simple requests directly.
+  systemPrompt: Answer simple requests directly.
 ```
 
-Example orchestra agent:
+Example main execution host:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -593,6 +387,25 @@ spec:
         kind: StoreBackend
 ```
 
+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`
+
 ### `resources/`
 
 Use `resources/` for executable local extensions:
@@ -604,43 +417,32 @@ Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`
 
 The preferred tool module format is exporting `tool({...})`.
 
-Example:
-
-```js
-import { z } from "zod";
-import { tool } from "@botbotgo/agent-harness/tools";
-
-export const local_lookup = tool({
-  description: "Lookup a ticker from a local tool module.",
-  retryable: true,
-  schema: {
-    ticker: z.string().min(1),
-  },
-  async invoke(input) {
-    return input.ticker.toUpperCase();
-  },
-});
-```
-
-Keep runtime extension source under `resources/`. Keep tests outside the published source tree, for example under repository `test/`.
+SKILL packages are discovered from `resources/skills/` and attached to agents through YAML.
 
 ## Design Notes
 
-- `agent-harness` should keep the public runtime contract generic while mapping cleanly onto current backend capabilities
-- agent-level execution behavior stays upstream
+- public runtime contract stays generic and small
 - application-level orchestration and lifecycle management stays in the harness
-- checkpoint resume is treated as a system-managed runtime behavior, not a primary public abstraction
-- public runtime contract generic does not mean backend-agnostic implementation internals; it means client-facing semantics stay stable even when adapters change
+- 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
+
+In short: `agent-harness` is a public runtime contract generic enough to survive backend changes, while the deep execution semantics stay upstream.
 
 ## API Summary
 
-- `createAgentHarness(...)`
-- `run(runtime, {...})`
-- `subscribe(...)`
-- `listThreads(...)`
-- `getThread(...)`
-- `listApprovals(...)`
-- `getApproval(...)`
-- `createToolMcpServer(...)`
-- `serveToolsOverStdio(...)`
-- `stop(...)`
+Primary exports:
+
+- `createAgentHarness`
+- `run`
+- `subscribe`
+- `listThreads`
+- `getThread`
+- `deleteThread`
+- `listApprovals`
+- `getApproval`
+- `createToolMcpServer`
+- `serveToolsOverStdio`
+- `stop`
+
+`AgentHarnessRuntime` is the concrete runtime class behind the public facade.

package/dist/contracts/types.d.ts

@@ -96,6 +96,11 @@ export type LangChainAgentParams = {
     responseFormat?: unknown;
     contextSchema?: unknown;
     middleware?: Array<Record<string, unknown>>;
+    subagents?: CompiledSubAgent[];
+    memory?: string[];
+    skills?: string[];
+    generalPurposeAgent?: boolean;
+    taskDescription?: string;
     includeAgentName?: "inline";
     version?: "v1" | "v2";
     name?: string;
@@ -290,9 +295,6 @@ export type RunStartOptions = {
     input: MessageContent;
     threadId?: string;
     invocation?: InvocationEnvelope;
-    context?: Record<string, unknown>;
-    state?: Record<string, unknown>;
-    files?: Record<string, unknown>;
     listeners?: RunListeners;
 };
 export type RunDecisionOptions = {

package/dist/extensions.js

@@ -198,6 +198,44 @@ registerToolKind({
         ];
     },
 });
+registerToolKind({
+    type: "provider",
+    validate(tool) {
+        if (!tool.name || !tool.description) {
+            throw new Error(`Tool ${tool.id} provider tool requires name and description`);
+        }
+        const providerTool = typeof tool.config?.providerTool === "object" && tool.config.providerTool
+            ? tool.config.providerTool
+            : undefined;
+        if (typeof providerTool?.provider !== "string" || !providerTool.provider.trim()) {
+            throw new Error(`Tool ${tool.id} provider tool must define providerTool.provider`);
+        }
+        if (typeof providerTool?.tool !== "string" || !providerTool.tool.trim()) {
+            throw new Error(`Tool ${tool.id} provider tool must define providerTool.tool`);
+        }
+    },
+    compile(tool) {
+        return [
+            {
+                id: tool.id,
+                type: "provider",
+                name: tool.name,
+                description: tool.description,
+                config: tool.config,
+                inputSchemaRef: tool.inputSchemaRef,
+                bundleRefs: [],
+                hitl: tool.hitl
+                    ? {
+                        enabled: tool.hitl.enabled,
+                        allow: tool.hitl.allow ?? ["approve", "edit", "reject"],
+                    }
+                    : undefined,
+                retryable: tool.retryable,
+                runtimeValue: { name: tool.name, description: tool.description, type: "provider" },
+            },
+        ];
+    },
+});
 registerToolKind({
     type: "bundle",
     validate(tool, tools) {

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.47";
+export declare const AGENT_HARNESS_VERSION = "0.0.48";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.47";
+export const AGENT_HARNESS_VERSION = "0.0.48";

package/dist/resource/resource-impl.js

@@ -20,12 +20,6 @@ function installedResourceProviderEntry() {
     try {
         return require.resolve("@botbotgo/agent-harness-resource");
     }
-    catch {
-        // Fall through to the legacy package name for backward compatibility only.
-    }
-    try {
-        return require.resolve("@botbotgo/agent-harness-builtin");
-    }
     catch {
         return null;
     }

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

@@ -33,6 +33,8 @@ export declare class AgentRuntimeAdapter {
     private normalizeInterruptPolicy;
     private compileInterruptOn;
     private resolveInterruptOn;
+    private resolveFilesystemBackend;
+    private resolveLangChainAutomaticMiddleware;
     private resolveMiddleware;
     private resolveCheckpointer;
     private buildRouteSystemPrompt;

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

@@ -1,10 +1,12 @@
 import { Command, MemorySaver } from "@langchain/langgraph";
 import { tool as createLangChainTool } from "@langchain/core/tools";
-import { createDeepAgent } from "deepagents";
+import { createDeepAgent, createMemoryMiddleware, createSkillsMiddleware, createSubAgentMiddleware, FilesystemBackend, } from "deepagents";
 import { ChatAnthropic } from "@langchain/anthropic";
+import { tools as anthropicProviderTools } from "@langchain/anthropic";
 import { ChatGoogle } from "@langchain/google";
 import { ChatOllama } from "@langchain/ollama";
 import { ChatOpenAI } from "@langchain/openai";
+import { tools as openAIProviderTools } from "@langchain/openai";
 import { createAgent, humanInTheLoopMiddleware, initChatModel } from "langchain";
 import { z } from "zod";
 import { extractEmptyAssistantMessageFailure, extractReasoningText, extractToolFallbackContext, extractVisibleOutput, isLikelyToolArgsObject, isToolCallParseFailure, STRICT_TOOL_JSON_INSTRUCTION, sanitizeVisibleText, tryParseJson, wrapResolvedModel, } from "./parsing/output-parsing.js";
@@ -112,6 +114,35 @@ function buildToolNameMapping(tools) {
     }
     return { originalToModelFacing, modelFacingToOriginal };
 }
+function hasConfiguredSubagentSupport(binding) {
+    const params = getBindingLangChainParams(binding);
+    if (!params) {
+        return false;
+    }
+    return (params.subagents?.length ?? 0) > 0 || params.generalPurposeAgent === true || Boolean(params.taskDescription?.trim());
+}
+function instantiateProviderTool(compiledTool) {
+    const providerTool = asRecord(compiledTool.config?.providerTool);
+    const provider = typeof providerTool?.provider === "string" ? providerTool.provider.trim().toLowerCase() : "";
+    const toolName = typeof providerTool?.tool === "string" ? providerTool.tool.trim() : "";
+    const args = asRecord(providerTool?.args) ?? {};
+    if (!provider || !toolName) {
+        throw new Error(`Provider tool ${compiledTool.id} must define providerTool.provider and providerTool.tool`);
+    }
+    const registry = provider === "openai"
+        ? openAIProviderTools
+        : provider === "anthropic"
+            ? anthropicProviderTools
+            : undefined;
+    if (!registry) {
+        throw new Error(`Provider tool ${compiledTool.id} uses unsupported provider ${provider}`);
+    }
+    const factory = registry[toolName];
+    if (typeof factory !== "function") {
+        throw new Error(`Provider tool ${compiledTool.id} references unknown ${provider} tool ${toolName}`);
+    }
+    return factory(args);
+}
 function wrapResolvedToolWithModelFacingName(resolvedTool, modelFacingName) {
     if (typeof resolvedTool !== "object" || resolvedTool === null) {
         return resolvedTool;
@@ -393,10 +424,10 @@ export class AgentRuntimeAdapter {
     resolveTools(tools, binding) {
         const resolved = this.options.toolResolver ? this.options.toolResolver(tools.map((tool) => tool.id), binding) : [];
         const toolNameMapping = this.buildToolNameMapping(tools);
-        return resolved.map((resolvedTool, index) => {
-            const compiledTool = tools[index];
-            if (!compiledTool) {
-                return resolvedTool;
+        return tools.flatMap((compiledTool, index) => {
+            const resolvedTool = resolved[index] ?? (compiledTool.type === "provider" ? instantiateProviderTool(compiledTool) : undefined);
+            if (resolvedTool === undefined) {
+                return [];
             }
             const wrappedTool = wrapToolForExecution(resolvedTool, compiledTool, binding);
             const modelFacingName = toolNameMapping.originalToModelFacing.get(compiledTool.name) ?? compiledTool.name;
@@ -443,14 +474,55 @@ export class AgentRuntimeAdapter {
     resolveInterruptOn(binding) {
         return this.compileInterruptOn(getBindingPrimaryTools(binding), getBindingInterruptCompatibilityRules(binding));
     }
+    resolveFilesystemBackend(binding) {
+        return new FilesystemBackend({
+            rootDir: "/",
+            virtualMode: false,
+            maxFileSizeMb: 10,
+        });
+    }
+    async resolveLangChainAutomaticMiddleware(binding) {
+        const params = getBindingLangChainParams(binding);
+        if (!params) {
+            return [];
+        }
+        const automaticMiddleware = [];
+        if ((params.skills?.length ?? 0) > 0) {
+            automaticMiddleware.push(createSkillsMiddleware({
+                backend: this.resolveFilesystemBackend(binding),
+                sources: params.skills,
+            }));
+        }
+        if ((params.memory?.length ?? 0) > 0) {
+            automaticMiddleware.push(createMemoryMiddleware({
+                backend: this.resolveFilesystemBackend(binding),
+                sources: params.memory,
+            }));
+        }
+        if (hasConfiguredSubagentSupport(binding)) {
+            automaticMiddleware.push(createSubAgentMiddleware({
+                defaultModel: (await this.resolveModel(params.model)),
+                defaultTools: this.resolveTools(params.tools, binding),
+                defaultInterruptOn: getBindingInterruptCompatibilityRules(binding),
+                subagents: (await this.resolveSubagents(params.subagents ?? [], binding)),
+                generalPurposeAgent: params.generalPurposeAgent,
+                taskDescription: params.taskDescription ?? null,
+            }));
+        }
+        return automaticMiddleware;
+    }
     async resolveMiddleware(binding, interruptOn) {
         const declarativeMiddleware = await resolveDeclaredMiddleware(getBindingMiddlewareConfigs(binding), {
             resolveModel: (model) => this.resolveModel(model),
             resolveCustom: this.options.declaredMiddlewareResolver,
             binding,
         });
+        const automaticMiddleware = isLangChainBinding(binding)
+            ? await this.resolveLangChainAutomaticMiddleware(binding)
+            : [];
         const middleware = [
             ...declarativeMiddleware,
+            ...automaticMiddleware,
             ...(this.options.middlewareResolver ? this.options.middlewareResolver(binding) : []),
         ];
         if (interruptOn && Object.keys(interruptOn).length > 0) {

package/dist/runtime/declared-middleware.js

@@ -1,4 +1,4 @@
-import { anthropicPromptCachingMiddleware, contextEditingMiddleware, llmToolSelectorMiddleware, modelCallLimitMiddleware, modelFallbackMiddleware, modelRetryMiddleware, openAIModerationMiddleware, summarizationMiddleware, todoListMiddleware, toolCallLimitMiddleware, toolEmulatorMiddleware, toolRetryMiddleware, } from "langchain";
+import { anthropicPromptCachingMiddleware, contextEditingMiddleware, llmToolSelectorMiddleware, modelCallLimitMiddleware, modelFallbackMiddleware, modelRetryMiddleware, openAIModerationMiddleware, piiMiddleware, piiRedactionMiddleware, summarizationMiddleware, todoListMiddleware, toolCallLimitMiddleware, toolEmulatorMiddleware, toolRetryMiddleware, } from "langchain";
 function asMiddlewareConfig(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value) ? { ...value } : null;
 }
@@ -80,6 +80,18 @@ export async function resolveDeclaredMiddleware(middlewareConfigs, options) {
             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 "piiRedaction":
+                resolved.push(piiRedactionMiddleware(runtimeConfig));
+                break;
             case "anthropicPromptCaching":
                 resolved.push(anthropicPromptCachingMiddleware(runtimeConfig));
                 break;

package/dist/runtime/harness.js

@@ -47,9 +47,9 @@ export class AgentHarnessRuntime {
     normalizeInvocationEnvelope(options) {
         const invocation = options.invocation;
         return {
-            context: invocation?.context ?? options.context,
-            state: invocation?.inputs ?? options.state,
-            files: invocation?.attachments ?? options.files,
+            context: invocation?.context,
+            state: invocation?.inputs,
+            files: invocation?.attachments,
             invocation,
         };
     }

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

@@ -243,6 +243,19 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             responseFormat: agent.langchainAgentConfig?.responseFormat,
             contextSchema: agent.langchainAgentConfig?.contextSchema,
             middleware: compileMiddlewareConfigs(agent.langchainAgentConfig?.middleware, models, agent.id),
+            subagents: agent.subagentRefs.map((ref) => {
+                const subagent = agents.get(resolveRefId(ref));
+                if (!subagent) {
+                    throw new Error(`Missing subagent ${ref} for agent ${agent.id}`);
+                }
+                return buildSubagent(subagent, workspaceRoot, models, tools, compiledAgentSkills, compiledAgentModel, compiledAgentMemory);
+            }),
+            memory: compiledAgentMemory,
+            skills: compiledAgentSkills,
+            generalPurposeAgent: typeof agent.langchainAgentConfig?.generalPurposeAgent === "boolean" ? agent.langchainAgentConfig.generalPurposeAgent : undefined,
+            taskDescription: typeof agent.langchainAgentConfig?.taskDescription === "string" && agent.langchainAgentConfig.taskDescription.trim()
+                ? agent.langchainAgentConfig.taskDescription
+                : undefined,
             includeAgentName: agent.langchainAgentConfig?.includeAgentName === "inline" ? "inline" : undefined,
             version: agent.langchainAgentConfig?.version === "v1" || agent.langchainAgentConfig?.version === "v2"
                 ? agent.langchainAgentConfig.version

package/dist/workspace/object-loader.js

@@ -222,10 +222,10 @@ function resolveExecutionBackend(item, current) {
         : typeof execution?.mode === "string"
             ? execution.mode.trim().toLowerCase()
             : undefined;
-    if (backend === "langchain-v1" || backend === "langchain" || backend === "langchain-agent") {
+    if (backend === "langchain-v1") {
         return "langchain-v1";
     }
-    if (backend === "deepagent" || backend === "deepagents") {
+    if (backend === "deepagent") {
         return "deepagent";
     }
     return undefined;
@@ -250,6 +250,8 @@ 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) {
@@ -264,17 +266,13 @@ function readDeepAgentConfig(item) {
 export function parseAgentItem(item, sourcePath) {
     const subagentRefs = readRefArray(item.subagents);
     const subagentPathRefs = readPathArray(item.subagents);
-    const kind = typeof item.kind === "string" ? item.kind : "agent";
-    const executionMode = String(resolveExecutionBackend(item) ??
-        (kind === "langchain-agent" ? "langchain-v1" : undefined) ??
-        (kind === "deepagent" ? "deepagent" : undefined) ??
-        "deepagent");
+    const executionMode = String(resolveExecutionBackend(item) ?? "deepagent");
     return {
         id: String(item.id),
         executionMode: executionMode,
         capabilities: readCapabilities(item.capabilities) ?? (executionMode === "deepagent"
             ? { delegation: true, memory: true }
-            : { delegation: false, memory: false }),
+            : { delegation: true, memory: true }),
         description: String(item.description ?? ""),
         modelRef: readSingleRef(item.modelRef) ?? "",
         runRoot: typeof item.runRoot === "string" ? item.runRoot : undefined,
@@ -487,7 +485,7 @@ async function readNamedModelItems(root) {
     return records;
 }
 function isAgentKind(kind) {
-    return kind === "deepagent" || kind === "langchain-agent" || kind === "agent";
+    return kind === "agent";
 }
 async function readConfigAgentItems(configRoot) {
     const records = await readYamlItems(configRoot, "agents", { recursive: true });
@@ -536,18 +534,7 @@ export async function readToolModuleItems(root) {
     return records;
 }
 function inferExecutionMode(item, current) {
-    const explicitExecution = resolveExecutionBackend(item, current);
-    if (explicitExecution) {
-        return explicitExecution;
-    }
-    const kind = typeof item.kind === "string" ? item.kind : typeof current?.kind === "string" ? current.kind : undefined;
-    if (kind === "langchain-agent") {
-        return "langchain-v1";
-    }
-    if (kind === "deepagent") {
-        return "deepagent";
-    }
-    return undefined;
+    return resolveExecutionBackend(item, current);
 }
 export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
     const refs = new Map();

package/dist/workspace/resource-compilers.js

@@ -207,6 +207,7 @@ export function parseToolObject(object) {
     const value = object.value;
     const backend = asObject(value.backend);
     const mcp = asObject(value.mcp);
+    const providerTool = asObject(value.providerTool) ?? asObject(value.provider);
     const mcpReferenceConfig = mcp
         ? {
             ...(typeof mcp.serverRef === "string"
@@ -226,16 +227,22 @@ export function parseToolObject(object) {
             ? "bundle"
             : mcp
                 ? "mcp"
-                : backend
-                    ? "backend"
-                    : "function";
+                : providerTool
+                    ? "provider"
+                    : backend
+                        ? "backend"
+                        : "function";
     return {
         id: object.id,
         type: String(inferredType),
         name: String(value.name ?? "").trim(),
         description: String(value.description ?? "").trim(),
         implementationName: typeof value.implementationName === "string" ? value.implementationName : undefined,
-        config: mergeObjects(asObject(value.config), (mcpReferenceConfig && Object.keys(mcpReferenceConfig).length > 0) || (mcpServerConfig && Object.keys(mcpServerConfig).length > 0)
+        config: mergeObjects(mergeObjects(asObject(value.config), providerTool
+            ? {
+                providerTool,
+            }
+            : undefined), (mcpReferenceConfig && Object.keys(mcpReferenceConfig).length > 0) || (mcpServerConfig && Object.keys(mcpServerConfig).length > 0)
             ? {
                 mcp: mcpReferenceConfig,
                 ...(mcpServerConfig && Object.keys(mcpServerConfig).length > 0 ? { mcpServer: mcpServerConfig } : {}),

package/dist/workspace/support/agent-capabilities.js

@@ -9,8 +9,8 @@ export function inferAgentCapabilities(agent) {
         return normalizeCapabilities(agent.capabilities);
     }
     return {
-        delegation: agent.executionMode === "deepagent",
-        memory: agent.executionMode === "deepagent",
+        delegation: agent.executionMode === "deepagent" || agent.executionMode === "langchain-v1",
+        memory: agent.executionMode === "deepagent" || agent.executionMode === "langchain-v1",
     };
 }
 export function inferBindingCapabilities(binding) {

package/dist/workspace/support/workspace-ref-utils.d.ts

@@ -12,10 +12,6 @@ export type RoutingRule = {
     hasThreadId?: boolean;
     caseSensitive?: boolean;
 };
-export type RuntimeRecoveryConfig = {
-    enabled: boolean;
-    resumeOnStartup: boolean;
-};
 export type RecoveryConfig = {
     enabled: boolean;
     resumeResumingRunsOnStartup: boolean;
@@ -26,7 +22,6 @@ export type ConcurrencyConfig = {
 };
 export declare function getWorkspaceObject(refs: Map<string, WorkspaceObject | ParsedAgentObject>, ref: string | undefined): WorkspaceObject | undefined;
 export declare function getRuntimeDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
-export declare function getRuntimeRecoveryConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): RuntimeRecoveryConfig;
 export declare function getRecoveryConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): RecoveryConfig;
 export declare function getConcurrencyConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): ConcurrencyConfig;
 export declare function getRoutingSystemPrompt(refs: Map<string, WorkspaceObject | ParsedAgentObject>): string | undefined;

package/dist/workspace/support/workspace-ref-utils.js

@@ -25,16 +25,6 @@ export function getRuntimeDefaults(refs) {
     }
     return runtimes[0].value;
 }
-export function getRuntimeRecoveryConfig(refs) {
-    const runtimeDefaults = getRuntimeDefaults(refs);
-    const recovery = typeof runtimeDefaults?.recovery === "object" && runtimeDefaults.recovery
-        ? runtimeDefaults.recovery
-        : undefined;
-    return {
-        enabled: recovery?.enabled !== false,
-        resumeOnStartup: recovery?.resumeOnStartup !== false,
-    };
-}
 export function getRecoveryConfig(refs) {
     const runtimeDefaults = getRuntimeDefaults(refs);
     const recovery = typeof runtimeDefaults?.recovery === "object" && runtimeDefaults.recovery
@@ -49,7 +39,7 @@ export function getRecoveryConfig(refs) {
         enabled: recovery.enabled !== false,
         resumeResumingRunsOnStartup: typeof recovery.resumeResumingRunsOnStartup === "boolean"
             ? recovery.resumeResumingRunsOnStartup
-            : recovery.resumeOnStartup !== false,
+            : true,
         maxRecoveryAttempts,
     };
 }

package/dist/workspace/validate.js

@@ -38,6 +38,9 @@ function validateMiddlewareConfig(agent) {
         if (kind === "modelFallback" && !Array.isArray(typed.fallbackModels) && !Array.isArray(typed.models)) {
             throw new Error(`Agent ${agent.id} modelFallback middleware requires fallbackModels or models`);
         }
+        if (kind === "pii" && typeof typed.piiType !== "string") {
+            throw new Error(`Agent ${agent.id} pii middleware requires piiType`);
+        }
     }
 }
 export function validateAgent(agent) {

package/package.json

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