@botbotgo/agent-harness 0.0.22 → 0.0.23

package/README.md

@@ -9,7 +9,9 @@ It helps developers:
 - define agents in YAML
 - keep workspace behavior in `config/workspace.yaml`
 - keep shared bootstrap context in `config/agent-context.md`
-- discover tools and skills from `resources/`
+- discover tools and SKILL packages from `resources/`
+- bridge remote MCP servers into agent toolsets
+- expose harness-managed tools as an MCP server
 - run through either LangChain v1 or DeepAgents with one app-facing API
 
 Why it works:
@@ -54,6 +56,8 @@ your-workspace/
     skills/
 ```
 
+Use the standard layout only. Agent entry files must live under `config/agents/`; root-level files such as `agent.yaml`, `orchestra.yaml`, and `direct.yaml` are not loaded.
+
 Minimal usage:
 
 ```ts
@@ -78,7 +82,9 @@ try {
 - One workspace for agents, models, tools, and runtime behavior
 - One API for both LangChain v1 and DeepAgents
 - Built-in routing for direct and orchestration flows
-- Auto-discovered local tools and skills from `resources/tools/` and `resources/skills/`
+- Auto-discovered local tools and SKILL packages from `resources/tools/` and `resources/skills/`
+- MCP bridge support: agent YAML can mount remote or local MCP servers as agent tools
+- MCP server support: expose harness-managed tools over stdio or an in-memory MCP server
 - Built-in thread state, approvals, resumable runs, and long-term memory
 - MCP server helpers plus background checkpoint maintenance
 
@@ -146,6 +152,49 @@ const result = await run(harness, {
 });
 ```
 
+### Use Skills And Local Tools
+
+`agent-harness` treats `resources/skills/` as SKILL packages and `resources/tools/` as executable local tools.
+
+Point agent YAML at both:
+
+```yaml
+spec:
+  skills:
+    - path: resources/skills/reviewer
+  tools:
+    - ref: tool/local-toolset
+```
+
+### Bridge MCP Servers Into Agents
+
+Use `mcpServers:` inside agent YAML to bridge MCP servers into the agent's tool list:
+
+```yaml
+spec:
+  mcpServers:
+    - name: browser
+      command: node
+      args: ["./mcp-browser-server.mjs"]
+    - name: docs
+      transport: http
+      url: https://example.com/mcp
+      token: ${DOCS_MCP_TOKEN}
+```
+
+The harness discovers MCP tools, filters them through the agent config, and exposes them to the runtime like any other tool.
+
+### Expose Harness Tools As An MCP Server
+
+Use the MCP server helpers when another client should connect to the harness as an MCP server:
+
+```ts
+import { createToolMcpServer, serveToolsOverStdio } from "@botbotgo/agent-harness";
+
+const server = await createToolMcpServer(harness, { agentId: "orchestra" });
+await serveToolsOverStdio(harness, { agentId: "orchestra" });
+```
+
 ### Read Back Thread State
 
 ```ts
@@ -221,6 +270,12 @@ Use `config/agents/*.yaml` to configure agents. Common fields include:
 Use `resources/` for executable extensions:
 
 - `resources/tools/` for local tool modules
-- `resources/skills/` for skill packages
+- `resources/skills/` for SKILL packages
 
 Each resource package should include its own `package.json`.
+
+### Skills And MCP
+
+- Use `resources/skills/` for SKILL packages that carry reusable instructions, templates, scripts, and metadata
+- Use `mcpServers:` in `config/agents/*.yaml` when you want the harness to bridge external MCP tools into an agent
+- Use `createToolMcpServer(...)` or `serveToolsOverStdio(...)` when you want the harness itself to act as an MCP server for another client

package/dist/config/models.yaml

@@ -0,0 +1,29 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: object type for named model presets.
+kind: Models
+spec:
+  - name: default
+    # ====================
+    # LangChain v1 Features
+    # ====================
+    # LangChain aligned feature: provider family or integration namespace.
+    # Common options in this harness today include:
+    # - `ollama`
+    # - `openai`
+    # - `openai-compatible`
+    # - `anthropic`
+    # - `google` / `google-genai` / `gemini`
+    # The runtime adapter uses this to select the concrete LangChain chat model implementation.
+    provider: ollama
+    # LangChain aligned feature: concrete model identifier passed to the selected provider integration.
+    # Example values depend on `provider`, such as `gpt-oss:latest` for `ollama`.
+    model: gpt-oss:latest
+    init:
+      # LangChain aligned feature: provider-specific initialization options.
+      # Available keys are provider-specific; common examples include `baseUrl`, `temperature`, and auth/client settings.
+      # `baseUrl` configures the Ollama-compatible endpoint used by the model client.
+      # For `openai-compatible`, `baseUrl` is normalized into the ChatOpenAI `configuration.baseURL` field.
+      baseUrl: https://ollama-rtx-4070.easynet.world/
+      # LangChain aligned feature: provider/model initialization option controlling sampling temperature.
+      temperature: 0.2

package/dist/runtime/harness.d.ts

@@ -44,6 +44,15 @@ export declare class AgentHarness {
         threadId?: string;
     }): Promise<string>;
     private emit;
+    private ensureThreadStarted;
+    private loadPriorHistory;
+    private appendAssistantMessage;
+    private invokeWithHistory;
+    private emitOutputDeltaAndCreateItem;
+    private emitRunCreated;
+    private setRunStateAndEmit;
+    private requestApprovalAndEmit;
+    private emitSyntheticFallback;
     private persistApproval;
     private resolveApprovalRecord;
     private isDecisionRun;

package/dist/runtime/harness.js

@@ -269,6 +269,95 @@ export class AgentHarness {
         this.eventBus.publish(event);
         return event;
     }
+    async ensureThreadStarted(selectedAgentId, binding, input, existingThreadId) {
+        const threadId = existingThreadId ?? createPersistentId();
+        const runId = createPersistentId();
+        const createdAt = new Date().toISOString();
+        if (!existingThreadId) {
+            await this.persistence.createThread({
+                threadId,
+                agentId: selectedAgentId,
+                runId,
+                status: "running",
+                createdAt,
+            });
+        }
+        await this.persistence.appendThreadMessage(threadId, {
+            role: "user",
+            content: input,
+            runId,
+            createdAt,
+        });
+        await this.persistence.createRun({
+            threadId,
+            runId,
+            agentId: binding.agent.id,
+            executionMode: binding.agent.executionMode,
+            createdAt,
+        });
+        return { threadId, runId, createdAt };
+    }
+    async loadPriorHistory(threadId, runId) {
+        const history = await this.persistence.listThreadMessages(threadId);
+        return history.filter((message) => message.runId !== runId);
+    }
+    async appendAssistantMessage(threadId, runId, content) {
+        if (!content) {
+            return;
+        }
+        await this.persistence.appendThreadMessage(threadId, {
+            role: "assistant",
+            content,
+            runId,
+            createdAt: new Date().toISOString(),
+        });
+    }
+    async invokeWithHistory(binding, input, threadId, runId, resumePayload) {
+        const priorHistory = await this.loadPriorHistory(threadId, runId);
+        return this.runtimeAdapter.invoke(binding, input, threadId, runId, resumePayload, priorHistory);
+    }
+    async emitOutputDeltaAndCreateItem(threadId, runId, agentId, content) {
+        await this.emit(threadId, runId, 3, "output.delta", {
+            content,
+        });
+        return {
+            type: "content",
+            threadId,
+            runId,
+            agentId,
+            content,
+        };
+    }
+    async emitRunCreated(threadId, runId, payload) {
+        return this.emit(threadId, runId, 1, "run.created", payload);
+    }
+    async setRunStateAndEmit(threadId, runId, sequence, state, options) {
+        await this.persistence.setRunState(threadId, runId, state, options.checkpointRef ?? null);
+        return this.emit(threadId, runId, sequence, "run.state.changed", {
+            previousState: options.previousState,
+            state,
+            checkpointRef: options.checkpointRef ?? null,
+            ...(options.error ? { error: options.error } : {}),
+        });
+    }
+    async requestApprovalAndEmit(threadId, runId, input, interruptContent, checkpointRef, sequence) {
+        const approval = await this.persistApproval(threadId, runId, checkpointRef, input, interruptContent);
+        const event = await this.emit(threadId, runId, sequence, "approval.requested", {
+            approvalId: approval.approvalId,
+            pendingActionId: approval.pendingActionId,
+            toolName: approval.toolName,
+            toolCallId: approval.toolCallId,
+            allowedDecisions: approval.allowedDecisions,
+            checkpointRef,
+        });
+        return { approval, event };
+    }
+    async emitSyntheticFallback(threadId, runId, selectedAgentId, error, sequence = 3) {
+        await this.emit(threadId, runId, sequence, "runtime.synthetic_fallback", {
+            reason: error instanceof Error ? error.message : String(error),
+            selectedAgentId,
+        });
+    }
     async persistApproval(threadId, runId, checkpointRef, input, interruptContent) {
         const approval = createPendingApproval(threadId, runId, checkpointRef, input, interruptContent);
         await this.persistence.createApproval(approval);
@@ -381,68 +470,25 @@ export class AgentHarness {
         if (!policyDecision.allowed) {
             throw new Error(`Policy evaluation blocked agent ${selectedAgentId}: ${policyDecision.reasons.join(", ")}`);
         }
-        const threadId = options.threadId ?? createPersistentId();
-        const runId = createPersistentId();
-        const createdAt = new Date().toISOString();
-        if (!options.threadId) {
-            await this.persistence.createThread({
-                threadId,
-                agentId: selectedAgentId,
-                runId,
-                status: "running",
-                createdAt,
-            });
-        }
-        await this.persistence.appendThreadMessage(threadId, {
-            role: "user",
-            content: options.input,
-            runId,
-            createdAt,
-        });
-        await this.persistence.createRun({
-            threadId,
-            runId,
-            agentId: binding.agent.id,
-            executionMode: binding.agent.executionMode,
-            createdAt,
-        });
-        await this.emit(threadId, runId, 1, "run.created", {
+        const { threadId, runId } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, options.threadId);
+        await this.emitRunCreated(threadId, runId, {
             agentId: binding.agent.id,
             requestedAgentId: options.agentId ?? AUTO_AGENT_ID,
             selectedAgentId,
             executionMode: binding.agent.executionMode,
         });
         try {
-            const history = await this.persistence.listThreadMessages(threadId);
-            const priorHistory = history.filter((message) => message.runId !== runId);
-            const actual = await this.runtimeAdapter.invoke(binding, options.input, threadId, runId, undefined, priorHistory);
+            const actual = await this.invokeWithHistory(binding, options.input, threadId, runId);
             let approval;
-            if (actual.output) {
-                await this.persistence.appendThreadMessage(threadId, {
-                    role: "assistant",
-                    content: actual.output,
-                    runId,
-                    createdAt: new Date().toISOString(),
-                });
-            }
-            await this.persistence.setRunState(threadId, runId, actual.state, actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null);
-            if (actual.state === "waiting_for_approval") {
-                const checkpointRef = `checkpoints/${threadId}/${runId}/cp-1`;
-                approval = await this.persistApproval(threadId, runId, checkpointRef, options.input, actual.interruptContent);
-                await this.emit(threadId, runId, 4, "approval.requested", {
-                    approvalId: approval.approvalId,
-                    pendingActionId: approval.pendingActionId,
-                    toolName: approval.toolName,
-                    toolCallId: approval.toolCallId,
-                    allowedDecisions: approval.allowedDecisions,
-                    checkpointRef,
-                });
-            }
-            await this.emit(threadId, runId, 3, "run.state.changed", {
+            await this.appendAssistantMessage(threadId, runId, actual.output);
+            const checkpointRef = actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null;
+            await this.setRunStateAndEmit(threadId, runId, 3, actual.state, {
                 previousState: null,
-                state: actual.state,
-                checkpointRef: actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null,
+                checkpointRef,
             });
+            if (actual.state === "waiting_for_approval") {
+                approval = (await this.requestApprovalAndEmit(threadId, runId, options.input, actual.interruptContent, checkpointRef, 4)).approval;
+            }
             return {
                 ...actual,
                 threadId,
@@ -453,15 +499,9 @@ export class AgentHarness {
             };
         }
         catch (error) {
-            await this.emit(threadId, runId, 3, "runtime.synthetic_fallback", {
-                reason: error instanceof Error ? error.message : String(error),
-                selectedAgentId,
-            });
-            await this.persistence.setRunState(threadId, runId, "failed");
-            await this.emit(threadId, runId, 4, "run.state.changed", {
+            await this.emitSyntheticFallback(threadId, runId, selectedAgentId, error);
+            await this.setRunStateAndEmit(threadId, runId, 4, "failed", {
                 previousState: null,
-                state: "failed",
-                checkpointRef: null,
                 error: error instanceof Error ? error.message : String(error),
             });
             return {
@@ -490,32 +530,8 @@ export class AgentHarness {
             return;
         }
         let emitted = false;
-        const threadId = options.threadId ?? createPersistentId();
-        const runId = createPersistentId();
-        const createdAt = new Date().toISOString();
-        if (!options.threadId) {
-            await this.persistence.createThread({
-                threadId,
-                agentId: selectedAgentId,
-                runId,
-                status: "running",
-                createdAt,
-            });
-        }
-        await this.persistence.appendThreadMessage(threadId, {
-            role: "user",
-            content: options.input,
-            runId,
-            createdAt,
-        });
-        await this.persistence.createRun({
-            threadId,
-            runId,
-            agentId: selectedAgentId,
-            executionMode: binding.agent.executionMode,
-            createdAt,
-        });
-        yield { type: "event", event: await this.emit(threadId, runId, 1, "run.created", {
+        const { threadId, runId } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, options.threadId);
+        yield { type: "event", event: await this.emitRunCreated(threadId, runId, {
                 agentId: selectedAgentId,
                 requestedAgentId: options.agentId ?? AUTO_AGENT_ID,
                 selectedAgentId,
@@ -523,8 +539,7 @@ export class AgentHarness {
                 state: "running",
             }) };
         try {
-            const history = await this.persistence.listThreadMessages(threadId);
-            const priorHistory = history.filter((message) => message.runId !== runId);
+            const priorHistory = await this.loadPriorHistory(threadId, runId);
             let assistantOutput = "";
             for await (const chunk of this.runtimeAdapter.stream(binding, options.input, threadId, priorHistory)) {
                 if (chunk) {
@@ -535,26 +550,18 @@ export class AgentHarness {
                         : chunk;
                     if (normalizedChunk.kind === "interrupt") {
                         const checkpointRef = `checkpoints/${threadId}/${runId}/cp-1`;
-                        await this.persistence.setRunState(threadId, runId, "waiting_for_approval", checkpointRef);
-                        const approval = await this.persistApproval(threadId, runId, checkpointRef, options.input, normalizedChunk.content);
+                        const waitingEvent = await this.setRunStateAndEmit(threadId, runId, 4, "waiting_for_approval", {
+                            previousState: null,
+                            checkpointRef,
+                        });
+                        const approvalRequest = await this.requestApprovalAndEmit(threadId, runId, options.input, normalizedChunk.content, checkpointRef, 5);
                         yield {
                             type: "event",
-                            event: await this.emit(threadId, runId, 4, "run.state.changed", {
-                                previousState: null,
-                                state: "waiting_for_approval",
-                                checkpointRef,
-                            }),
+                            event: waitingEvent,
                         };
                         yield {
                             type: "event",
-                            event: await this.emit(threadId, runId, 5, "approval.requested", {
-                                approvalId: approval.approvalId,
-                                pendingActionId: approval.pendingActionId,
-                                toolName: approval.toolName,
-                                toolCallId: approval.toolCallId,
-                                allowedDecisions: approval.allowedDecisions,
-                                checkpointRef,
-                            }),
+                            event: approvalRequest.event,
                         };
                         return;
                     }
@@ -594,98 +601,46 @@ export class AgentHarness {
                     }
                     emitted = true;
                     assistantOutput += normalizedChunk.content;
-                    await this.emit(threadId, runId, 3, "output.delta", {
-                        content: normalizedChunk.content,
-                    });
-                    yield {
-                        type: "content",
-                        threadId,
-                        runId,
-                        agentId: selectedAgentId,
-                        content: normalizedChunk.content,
-                    };
+                    yield await this.emitOutputDeltaAndCreateItem(threadId, runId, selectedAgentId, normalizedChunk.content);
                 }
             }
             if (!assistantOutput) {
-                const actual = await this.runtimeAdapter.invoke(binding, options.input, threadId, runId, undefined, priorHistory);
+                const actual = await this.invokeWithHistory(binding, options.input, threadId, runId);
                 if (actual.output) {
                     assistantOutput = actual.output;
                     emitted = true;
-                    await this.emit(threadId, runId, 3, "output.delta", {
-                        content: actual.output,
-                    });
-                    yield {
-                        type: "content",
-                        threadId,
-                        runId,
-                        agentId: selectedAgentId,
-                        content: actual.output,
-                    };
+                    yield await this.emitOutputDeltaAndCreateItem(threadId, runId, selectedAgentId, actual.output);
                 }
             }
-            if (assistantOutput) {
-                await this.persistence.appendThreadMessage(threadId, {
-                    role: "assistant",
-                    content: assistantOutput,
-                    runId,
-                    createdAt: new Date().toISOString(),
-                });
-            }
-            await this.persistence.setRunState(threadId, runId, "completed");
-            yield { type: "event", event: await this.emit(threadId, runId, 4, "run.state.changed", {
+            await this.appendAssistantMessage(threadId, runId, assistantOutput);
+            yield { type: "event", event: await this.setRunStateAndEmit(threadId, runId, 4, "completed", {
                     previousState: null,
-                    state: "completed",
-                    checkpointRef: null,
                 }) };
             return;
         }
         catch (error) {
             if (emitted) {
-                await this.persistence.setRunState(threadId, runId, "failed");
-                yield { type: "event", event: await this.emit(threadId, runId, 4, "run.state.changed", {
+                yield { type: "event", event: await this.setRunStateAndEmit(threadId, runId, 4, "failed", {
                         previousState: null,
-                        state: "failed",
                         error: error instanceof Error ? error.message : String(error),
                     }) };
                 return;
             }
             try {
-                const history = await this.persistence.listThreadMessages(threadId);
-                const priorHistory = history.filter((message) => message.runId !== runId);
-                const actual = await this.runtimeAdapter.invoke(binding, options.input, threadId, runId, undefined, priorHistory);
+                const actual = await this.invokeWithHistory(binding, options.input, threadId, runId);
+                await this.appendAssistantMessage(threadId, runId, actual.output);
                 if (actual.output) {
-                    await this.persistence.appendThreadMessage(threadId, {
-                        role: "assistant",
-                        content: actual.output,
-                        runId,
-                        createdAt: new Date().toISOString(),
-                    });
-                    yield {
-                        type: "content",
-                        threadId,
-                        runId,
-                        agentId: selectedAgentId,
-                        content: actual.output,
-                    };
+                    yield await this.emitOutputDeltaAndCreateItem(threadId, runId, selectedAgentId, actual.output);
                 }
-                await this.persistence.setRunState(threadId, runId, actual.state);
-                yield { type: "event", event: await this.emit(threadId, runId, 4, "run.state.changed", {
+                yield { type: "event", event: await this.setRunStateAndEmit(threadId, runId, 4, actual.state, {
                         previousState: null,
-                        state: actual.state,
-                        checkpointRef: null,
                     }) };
                 return;
             }
             catch (invokeError) {
-                await this.emit(threadId, runId, 3, "runtime.synthetic_fallback", {
-                    reason: invokeError instanceof Error ? invokeError.message : String(invokeError),
-                    selectedAgentId,
-                });
-                await this.persistence.setRunState(threadId, runId, "failed");
-                yield { type: "event", event: await this.emit(threadId, runId, 4, "run.state.changed", {
+                await this.emitSyntheticFallback(threadId, runId, selectedAgentId, invokeError);
+                yield { type: "event", event: await this.setRunStateAndEmit(threadId, runId, 4, "failed", {
                         previousState: null,
-                        state: "failed",
-                        checkpointRef: null,
                         error: invokeError instanceof Error ? invokeError.message : String(invokeError),
                     }) };
                 yield {
@@ -737,14 +692,7 @@ export class AgentHarness {
             ? { decision: "edit", editedInput: options.editedInput }
             : (options.decision ?? "approve");
         const actual = await this.runtimeAdapter.invoke(binding, "", threadId, runId, resumeDecision, priorHistory);
-        if (actual.output) {
-            await this.persistence.appendThreadMessage(threadId, {
-                role: "assistant",
-                content: actual.output,
-                runId,
-                createdAt: new Date().toISOString(),
-            });
-        }
+        await this.appendAssistantMessage(threadId, runId, actual.output);
         await this.persistence.setRunState(threadId, runId, actual.state, actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null);
         await this.emit(threadId, runId, 7, "run.state.changed", {
             previousState: "resuming",

package/dist/workspace/compile.js

@@ -1,15 +1,12 @@
-import path from "node:path";
-import { createHash } from "node:crypto";
-import { ensureResourceSources, listResourceTools, listResourceToolsForSource } from "../resource/resource.js";
-import { listRemoteMcpTools } from "../resource/resource-impl.js";
-import { ensureExternalResourceSource, isExternalSourceLocator } from "../resource/sources.js";
-import { loadWorkspaceObjects, readToolModuleItems } from "./object-loader.js";
+import { ensureResourceSources } from "../resource/resource.js";
+import { loadWorkspaceObjects } from "./object-loader.js";
 import { parseEmbeddingModelObject, parseMcpServerObject, parseModelObject, parseToolObject, parseVectorStoreObject, validateEmbeddingModelObject, validateMcpServerObject, validateModelObject, validateToolObject, validateVectorStoreObject, } from "./resource-compilers.js";
 import { validateAgent, validateTopology } from "./validate.js";
 import { compileBinding } from "./agent-binding-compiler.js";
 import { discoverSubagents, ensureDiscoverySources } from "./support/discovery.js";
 import { collectAgentDiscoverySourceRefs, collectToolSourceRefs } from "./support/source-collectors.js";
 import { resolveRefId } from "./support/workspace-ref-utils.js";
+import { hydrateAgentMcpTools, hydrateResourceAndExternalTools } from "./tool-hydration.js";
 function collectParsedResources(refs) {
     const embeddings = new Map();
     const mcpServers = new Map();
@@ -39,154 +36,6 @@ function collectParsedResources(refs) {
     }
     return { embeddings, mcpServers, models, vectorStores, tools };
 }
-async function hydrateResourceAndExternalTools(tools, toolSourceRefs, workspaceRoot) {
-    for (const source of toolSourceRefs) {
-        if (isExternalSourceLocator(source)) {
-            const externalRoot = await ensureExternalResourceSource(source, workspaceRoot);
-            const discoveredToolRefs = [];
-            const sourcePrefix = `external.${createHash("sha256").update(source).digest("hex").slice(0, 12)}`;
-            for (const { item, sourcePath } of await readToolModuleItems(path.join(externalRoot, "tools"))) {
-                const toolId = typeof item.id === "string" ? item.id : undefined;
-                if (!toolId) {
-                    continue;
-                }
-                const namespacedId = `${sourcePrefix}.${toolId}`;
-                const parsed = parseToolObject({
-                    id: namespacedId,
-                    kind: "tool",
-                    sourcePath,
-                    value: {
-                        ...item,
-                        id: namespacedId,
-                    },
-                });
-                tools.set(parsed.id, parsed);
-                discoveredToolRefs.push(`tool/${parsed.id}`);
-            }
-            const sourceTools = await listResourceToolsForSource(source, workspaceRoot);
-            const bundleRefs = [...sourceTools.map((tool) => tool.toolPath), ...discoveredToolRefs];
-            if (bundleRefs.length > 0) {
-                tools.set(source, {
-                    id: source,
-                    type: "bundle",
-                    name: source,
-                    description: `External tool resource loaded from ${source}`,
-                    bundleRefs,
-                    sourcePath: source,
-                });
-            }
-        }
-    }
-    for (const resourceTool of await listResourceTools(toolSourceRefs, workspaceRoot)) {
-        const existing = tools.get(resourceTool.toolPath);
-        tools.set(resourceTool.toolPath, {
-            id: resourceTool.toolPath,
-            type: existing?.type ?? "backend",
-            name: existing?.name || resourceTool.name,
-            description: existing?.description || resourceTool.description,
-            config: existing?.config,
-            backendOperation: existing?.backendOperation ?? resourceTool.backendOperation,
-            bundleRefs: existing?.bundleRefs ?? [],
-            hitl: existing?.hitl ?? resourceTool.hitl,
-            sourcePath: existing?.sourcePath ?? resourceTool.toolPath,
-        });
-    }
-}
-function toMcpServerConfig(server) {
-    return {
-        transport: server.transport,
-        command: server.command,
-        args: server.args,
-        env: server.env,
-        cwd: server.cwd,
-        url: server.url,
-        token: server.token,
-        headers: server.headers,
-    };
-}
-function readStringArray(value) {
-    return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
-}
-function compileRegexList(value, label) {
-    return readStringArray(value).map((pattern) => {
-        try {
-            return new RegExp(pattern);
-        }
-        catch (error) {
-            throw new Error(`${label} contains invalid regex ${JSON.stringify(pattern)}: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    });
-}
-function compileMcpToolFilter(serverItem) {
-    return {
-        includeNames: new Set(readStringArray(serverItem.tools)),
-        excludeNames: new Set(readStringArray(serverItem.excludeTools)),
-        includePatterns: compileRegexList(serverItem.toolFilters ?? serverItem.toolFilter, "toolFilter"),
-        excludePatterns: compileRegexList(serverItem.excludeToolFilters ?? serverItem.excludeToolFilter, "excludeToolFilter"),
-    };
-}
-function shouldIncludeRemoteMcpTool(filter, toolName) {
-    const { includeNames, excludeNames, includePatterns, excludePatterns } = filter;
-    const includedByName = includeNames.size === 0 || includeNames.has(toolName);
-    const includedByPattern = includePatterns.length === 0 || includePatterns.some((pattern) => pattern.test(toolName));
-    if (!includedByName || !includedByPattern) {
-        return false;
-    }
-    if (excludeNames.has(toolName)) {
-        return false;
-    }
-    if (excludePatterns.some((pattern) => pattern.test(toolName))) {
-        return false;
-    }
-    return true;
-}
-async function hydrateAgentMcpTools(agents, mcpServers, tools) {
-    for (const agent of agents) {
-        const discoveredRefs = new Set(agent.toolRefs);
-        for (const item of agent.mcpServers ?? []) {
-            const name = typeof item.name === "string" && item.name.trim()
-                ? item.name.trim()
-                : typeof item.id === "string" && item.id.trim()
-                    ? item.id.trim()
-                    : "";
-            if (!name) {
-                throw new Error(`Agent ${agent.id} has an MCP server entry without a name`);
-            }
-            const serverId = `${agent.id}.${name}`;
-            const parsedServer = parseMcpServerObject({
-                id: serverId,
-                kind: "mcp",
-                sourcePath: agent.sourcePath,
-                value: item,
-            });
-            const filter = compileMcpToolFilter(item);
-            mcpServers.set(serverId, parsedServer);
-            const remoteTools = await listRemoteMcpTools(toMcpServerConfig(parsedServer));
-            for (const remoteTool of remoteTools) {
-                if (!shouldIncludeRemoteMcpTool(filter, remoteTool.name)) {
-                    continue;
-                }
-                const toolId = `mcp.${agent.id}.${name}.${remoteTool.name}`;
-                tools.set(toolId, {
-                    id: toolId,
-                    type: "mcp",
-                    name: remoteTool.name,
-                    description: remoteTool.description ?? remoteTool.name,
-                    config: {
-                        mcp: {
-                            serverRef: `mcp/${serverId}`,
-                        },
-                    },
-                    mcpRef: remoteTool.name,
-                    bundleRefs: [],
-                    sourcePath: agent.sourcePath,
-                });
-                discoveredRefs.add(`tool/${toolId}`);
-            }
-        }
-        agent.toolRefs = Array.from(discoveredRefs);
-    }
-}
 function validateWorkspaceResources(embeddings, mcpServers, models, vectorStores, tools, agents) {
     embeddings.forEach((embedding) => validateEmbeddingModelObject(embedding));
     mcpServers.forEach((server) => validateMcpServerObject(server));

package/dist/workspace/object-loader.js

@@ -7,18 +7,7 @@ import { resolveIsolatedResourceModulePath } from "../resource/isolation.js";
 import { resolveResourcePackageRoot } from "../resource/sources.js";
 import { discoverToolModuleDefinitions, isSupportedToolModulePath } from "../tool-modules.js";
 import { fileExists, listFilesRecursive, readYamlOrJson } from "../utils/fs.js";
-const ROOT_AGENT_FILENAMES = [
-    "agent.yaml",
-    "agent.yml",
-    "orchestra.yaml",
-    "orchestra.yml",
-    "direct.yaml",
-    "direct.yml",
-    "research.yaml",
-    "research.yml",
-];
 const MODEL_FILENAMES = ["models.yaml", "models.yml"];
-const LEGACY_GLOBAL_AGENT_FILENAMES = ["agent.yaml", "agent.yml"];
 const CONVENTIONAL_OBJECT_DIRECTORIES = ["tools"];
 function conventionalConfigRoot(root) {
     if (path.basename(root) === "config" && existsSync(root) && statSync(root).isDirectory()) {
@@ -220,6 +209,27 @@ function readObjectArray(items) {
         .map((item) => ({ ...item }));
     return records.length > 0 ? records : undefined;
 }
+function readSharedAgentConfig(item) {
+    const middleware = readMiddlewareArray(item.middleware);
+    return {
+        ...(typeof item.systemPrompt === "string" ? { systemPrompt: item.systemPrompt } : {}),
+        ...(typeof item.checkpointer === "object" && item.checkpointer ? { checkpointer: item.checkpointer } : {}),
+        ...(typeof item.interruptOn === "object" && item.interruptOn ? { interruptOn: item.interruptOn } : {}),
+        ...(item.responseFormat !== undefined ? { responseFormat: item.responseFormat } : {}),
+        ...(item.contextSchema !== undefined ? { contextSchema: item.contextSchema } : {}),
+        ...(middleware ? { middleware } : {}),
+    };
+}
+function readLangchainAgentConfig(item) {
+    return readSharedAgentConfig(item);
+}
+function readDeepAgentConfig(item) {
+    return {
+        ...readSharedAgentConfig(item),
+        ...(typeof item.backend === "object" && item.backend ? { backend: item.backend } : {}),
+        ...(typeof item.store === "object" && item.store ? { store: item.store } : {}),
+    };
+}
 export function parseAgentItem(item, sourcePath) {
     const subagentRefs = readRefArray(item.subagents);
     const subagentPathRefs = readPathArray(item.subagents);
@@ -239,44 +249,8 @@ export function parseAgentItem(item, sourcePath) {
         memorySources: readPathArray(item.memory),
         subagentRefs,
         subagentPathRefs,
-        langchainAgentConfig: {
-            ...(typeof item.systemPrompt === "string" ||
-                typeof item.interruptOn === "object" ||
-                typeof item.checkpointer === "object" ||
-                item.responseFormat !== undefined ||
-                item.contextSchema !== undefined ||
-                item.middleware !== undefined
-                ? {
-                    ...(typeof item.systemPrompt === "string" ? { systemPrompt: item.systemPrompt } : {}),
-                    ...(typeof item.interruptOn === "object" && item.interruptOn ? { interruptOn: item.interruptOn } : {}),
-                    ...(typeof item.checkpointer === "object" && item.checkpointer ? { checkpointer: item.checkpointer } : {}),
-                    ...(item.responseFormat !== undefined ? { responseFormat: item.responseFormat } : {}),
-                    ...(item.contextSchema !== undefined ? { contextSchema: item.contextSchema } : {}),
-                    ...(readMiddlewareArray(item.middleware) ? { middleware: readMiddlewareArray(item.middleware) } : {}),
-                }
-                : {}),
-        },
-        deepAgentConfig: {
-            ...(typeof item.systemPrompt === "string" ||
-                typeof item.backend === "object" ||
-                typeof item.store === "object" ||
-                typeof item.checkpointer === "object" ||
-                typeof item.interruptOn === "object" ||
-                item.responseFormat !== undefined ||
-                item.contextSchema !== undefined ||
-                item.middleware !== undefined
-                ? {
-                    ...(typeof item.systemPrompt === "string" ? { systemPrompt: item.systemPrompt } : {}),
-                    ...(typeof item.backend === "object" && item.backend ? { backend: item.backend } : {}),
-                    ...(typeof item.store === "object" && item.store ? { store: item.store } : {}),
-                    ...(typeof item.checkpointer === "object" && item.checkpointer ? { checkpointer: item.checkpointer } : {}),
-                    ...(typeof item.interruptOn === "object" && item.interruptOn ? { interruptOn: item.interruptOn } : {}),
-                    ...(item.responseFormat !== undefined ? { responseFormat: item.responseFormat } : {}),
-                    ...(item.contextSchema !== undefined ? { contextSchema: item.contextSchema } : {}),
-                    ...(readMiddlewareArray(item.middleware) ? { middleware: readMiddlewareArray(item.middleware) } : {}),
-                }
-                : {}),
-        },
+        langchainAgentConfig: readLangchainAgentConfig(item),
+        deepAgentConfig: readDeepAgentConfig(item),
         sourcePath,
     };
 }
@@ -346,6 +320,89 @@ function mergeValues(base, override) {
     }
     return override;
 }
+function mergeRawItemRecord(records, key, item, sourcePath) {
+    const current = records.get(key);
+    const mergedRecord = {
+        item: current ? mergeValues(current.item, item) : item,
+        sourcePath,
+    };
+    records.set(key, mergedRecord);
+    return mergedRecord;
+}
+function mergeAgentRecord(records, item, sourcePath) {
+    const id = typeof item.id === "string" ? item.id : undefined;
+    if (!id) {
+        return null;
+    }
+    return mergeRawItemRecord(records, id, item, sourcePath);
+}
+function mergeWorkspaceObjectRecord(records, workspaceObject, item, sourcePath) {
+    mergeRawItemRecord(records, `${workspaceObject.kind}/${workspaceObject.id}`, item, sourcePath);
+}
+async function loadNamedModelsForRoot(configRoot, mergedObjects) {
+    for (const { item, sourcePath } of await readNamedModelItems(configRoot)) {
+        const workspaceObject = parseWorkspaceObject(item, sourcePath);
+        if (!workspaceObject || workspaceObject.kind !== "model") {
+            continue;
+        }
+        mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
+    }
+}
+async function loadConfigAgentsForRoot(configRoot, mergedAgents) {
+    for (const { item, sourcePath } of await readConfigAgentItems(configRoot)) {
+        mergeAgentRecord(mergedAgents, item, sourcePath);
+    }
+}
+async function loadConventionalObjectsForRoot(root, mergedObjects) {
+    for (const directory of CONVENTIONAL_OBJECT_DIRECTORIES) {
+        for (const objectRoot of conventionalDirectoryRoots(root, directory)) {
+            for (const { item, sourcePath } of await readYamlItems(objectRoot, undefined, { recursive: true })) {
+                const workspaceObject = parseWorkspaceObject(item, sourcePath);
+                if (!workspaceObject || workspaceObject.kind === "tool") {
+                    continue;
+                }
+                mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
+            }
+            for (const { item, sourcePath } of await readToolModuleItems(objectRoot)) {
+                const workspaceObject = parseWorkspaceObject(item, sourcePath);
+                if (!workspaceObject) {
+                    continue;
+                }
+                mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
+            }
+        }
+    }
+}
+async function loadConfigObjectsForRoot(root, configRoot, mergedObjects) {
+    if (!conventionalConfigRoot(root)) {
+        return;
+    }
+    for (const { item, sourcePath } of await readYamlItems(configRoot, undefined, { recursive: true })) {
+        const workspaceObject = parseWorkspaceObject(item, sourcePath);
+        if (!workspaceObject) {
+            continue;
+        }
+        if (isAgentKind(workspaceObject.kind) || workspaceObject.kind === "model") {
+            continue;
+        }
+        mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
+    }
+}
+async function loadRootObjects(root, mergedObjects) {
+    for (const { item, sourcePath } of (await readYamlItems(root)).filter(({ sourcePath: fullPath }) => !fullPath.includes(`${path.sep}config${path.sep}`) &&
+        !fullPath.includes(`${path.sep}resources${path.sep}`) &&
+        !fullPath.includes(`${path.sep}agents${path.sep}`) &&
+        !CONVENTIONAL_OBJECT_DIRECTORIES.some((directory) => fullPath.includes(`${path.sep}${directory}${path.sep}`)))) {
+        const workspaceObject = parseWorkspaceObject(item, sourcePath);
+        if (!workspaceObject) {
+            continue;
+        }
+        if (workspaceObject.kind === "tool" || workspaceObject.kind === "mcp" || workspaceObject.kind === "model") {
+            continue;
+        }
+        mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
+    }
+}
 export async function readYamlItems(root, relativeDir, options = {}) {
     const targetRoot = relativeDir ? path.join(root, relativeDir) : root;
     if (!(await fileExists(targetRoot))) {
@@ -405,15 +462,13 @@ function isAgentKind(kind) {
     return kind === "deepagent" || kind === "langchain-agent";
 }
 async function readConfigAgentItems(configRoot) {
-    const records = await readYamlItems(configRoot, undefined, { recursive: true });
+    const records = await readYamlItems(configRoot, "agents", { recursive: true });
     return records.filter(({ item, sourcePath }) => {
         const kind = typeof item.kind === "string" ? item.kind : undefined;
         if (!isAgentKind(kind)) {
             return false;
         }
-        const parentDir = path.dirname(sourcePath);
-        const filename = path.basename(sourcePath).toLowerCase();
-        return !(parentDir === configRoot && ROOT_AGENT_FILENAMES.includes(filename));
+        return sourcePath.includes(`${path.sep}agents${path.sep}`);
     });
 }
 export async function readToolModuleItems(root) {
@@ -451,10 +506,6 @@ export async function readToolModuleItems(root) {
     }
     return records;
 }
-function isPrimaryAgentFile(sourcePath) {
-    const base = path.basename(sourcePath).toLowerCase();
-    return ROOT_AGENT_FILENAMES.includes(base);
-}
 function inferExecutionMode(item, current) {
     const kind = typeof item.kind === "string" ? item.kind : typeof current?.kind === "string" ? current.kind : undefined;
     if (kind === "langchain-agent") {
@@ -465,160 +516,18 @@ function inferExecutionMode(item, current) {
     }
     return undefined;
 }
-function extractSharedAgentDefaults(item) {
-    const defaults = {};
-    for (const key of ["modelRef", "runRoot", "checkpointer", "interruptOn"]) {
-        if (key in item) {
-            defaults[key] = item[key];
-        }
-    }
-    return defaults;
-}
-function applySharedAgentDefaults(globalDefaults, defaultsByMode, item, current) {
-    const executionMode = inferExecutionMode(item, current);
-    const defaults = {
-        ...globalDefaults,
-        ...(executionMode ? defaultsByMode[executionMode] : {}),
-    };
-    const merged = { ...item };
-    for (const [key, value] of Object.entries(defaults)) {
-        if (key in merged) {
-            continue;
-        }
-        if (current && key in current) {
-            continue;
-        }
-        merged[key] = value;
-    }
-    return merged;
-}
 export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
     const refs = new Map();
     const mergedAgents = new Map();
     const mergedObjects = new Map();
     const roots = [frameworkWorkspaceRoot(), ...(options.overlayRoots ?? []), workspaceRoot];
-    let sharedAgentDefaults = {};
-    let sharedAgentDefaultsByMode = {};
     for (const root of roots) {
         const configRoot = conventionalConfigRoot(root) ?? root;
-        const namedAgentRoots = Array.from(new Set([root, configRoot]));
-        for (const namedAgentRoot of namedAgentRoots) {
-            for (const { item, sourcePath } of await readNamedYamlItems(namedAgentRoot, [...ROOT_AGENT_FILENAMES])) {
-                const id = typeof item.id === "string" ? item.id : undefined;
-                if (!id) {
-                    continue;
-                }
-                const current = mergedAgents.get(id);
-                mergedAgents.set(id, {
-                    item: current ? mergeValues(current.item, item) : item,
-                    sourcePath,
-                });
-                const filename = path.basename(sourcePath).toLowerCase();
-                if (LEGACY_GLOBAL_AGENT_FILENAMES.includes(filename)) {
-                    sharedAgentDefaults = mergeValues(sharedAgentDefaults, extractSharedAgentDefaults(item));
-                }
-                else {
-                    const executionMode = inferExecutionMode(item, current?.item);
-                    if (executionMode) {
-                        sharedAgentDefaultsByMode = {
-                            ...sharedAgentDefaultsByMode,
-                            [executionMode]: mergeValues(sharedAgentDefaultsByMode[executionMode] ?? {}, extractSharedAgentDefaults(item)),
-                        };
-                    }
-                }
-            }
-        }
-        for (const modelRoot of Array.from(new Set([configRoot]))) {
-            for (const { item, sourcePath } of await readNamedModelItems(modelRoot)) {
-                const workspaceObject = parseWorkspaceObject(item, sourcePath);
-                if (!workspaceObject || workspaceObject.kind !== "model") {
-                    continue;
-                }
-                const ref = `${workspaceObject.kind}/${workspaceObject.id}`;
-                const current = mergedObjects.get(ref);
-                mergedObjects.set(ref, {
-                    item: current ? mergeValues(current.item, item) : item,
-                    sourcePath,
-                });
-            }
-        }
-        for (const { item, sourcePath } of await readConfigAgentItems(configRoot)) {
-            const id = typeof item.id === "string" ? item.id : undefined;
-            if (!id) {
-                continue;
-            }
-            const current = mergedAgents.get(id);
-            const itemWithDefaults = applySharedAgentDefaults(sharedAgentDefaults, sharedAgentDefaultsByMode, item, current?.item);
-            mergedAgents.set(id, {
-                item: current ? mergeValues(current.item, itemWithDefaults) : itemWithDefaults,
-                sourcePath,
-            });
-        }
-        for (const directory of CONVENTIONAL_OBJECT_DIRECTORIES) {
-            for (const objectRoot of conventionalDirectoryRoots(root, directory)) {
-                for (const { item, sourcePath } of await readYamlItems(objectRoot, undefined, { recursive: true })) {
-                    const workspaceObject = parseWorkspaceObject(item, sourcePath);
-                    if (!workspaceObject || workspaceObject.kind === "tool") {
-                        continue;
-                    }
-                    const ref = `${workspaceObject.kind}/${workspaceObject.id}`;
-                    const current = mergedObjects.get(ref);
-                    mergedObjects.set(ref, {
-                        item: current ? mergeValues(current.item, item) : item,
-                        sourcePath,
-                    });
-                }
-                for (const { item, sourcePath } of await readToolModuleItems(objectRoot)) {
-                    const workspaceObject = parseWorkspaceObject(item, sourcePath);
-                    if (!workspaceObject) {
-                        continue;
-                    }
-                    const ref = `${workspaceObject.kind}/${workspaceObject.id}`;
-                    const current = mergedObjects.get(ref);
-                    mergedObjects.set(ref, {
-                        item: current ? mergeValues(current.item, item) : item,
-                        sourcePath,
-                    });
-                }
-            }
-        }
-        if (conventionalConfigRoot(root)) {
-            for (const { item, sourcePath } of await readYamlItems(configRoot, undefined, { recursive: true })) {
-                const workspaceObject = parseWorkspaceObject(item, sourcePath);
-                if (!workspaceObject) {
-                    continue;
-                }
-                if (isAgentKind(workspaceObject.kind) ||
-                    workspaceObject.kind === "model") {
-                    continue;
-                }
-                const ref = `${workspaceObject.kind}/${workspaceObject.id}`;
-                const current = mergedObjects.get(ref);
-                mergedObjects.set(ref, {
-                    item: current ? mergeValues(current.item, item) : item,
-                    sourcePath,
-                });
-            }
-        }
-        for (const { item, sourcePath } of (await readYamlItems(root)).filter(({ sourcePath: fullPath }) => !fullPath.includes(`${path.sep}config${path.sep}`) &&
-            !fullPath.includes(`${path.sep}resources${path.sep}`) &&
-            !fullPath.includes(`${path.sep}agents${path.sep}`) &&
-            !CONVENTIONAL_OBJECT_DIRECTORIES.some((directory) => fullPath.includes(`${path.sep}${directory}${path.sep}`)) &&
-            !isPrimaryAgentFile(fullPath))) {
-            const workspaceObject = parseWorkspaceObject(item, sourcePath);
-            if (!workspaceObject) {
-                continue;
-            }
-            if (workspaceObject.kind === "tool" || workspaceObject.kind === "mcp" || workspaceObject.kind === "model") {
-                continue;
-            }
-            const ref = `${workspaceObject.kind}/${workspaceObject.id}`;
-            const current = mergedObjects.get(ref);
-            mergedObjects.set(ref, {
-                item: current ? mergeValues(current.item, item) : item,
-                sourcePath,
-            });
-        }
+        await loadNamedModelsForRoot(configRoot, mergedObjects);
+        await loadConfigAgentsForRoot(configRoot, mergedAgents);
+        await loadConventionalObjectsForRoot(root, mergedObjects);
+        await loadConfigObjectsForRoot(root, configRoot, mergedObjects);
+        await loadRootObjects(root, mergedObjects);
     }
     const agents = Array.from(mergedAgents.values()).map(({ item, sourcePath }) => parseAgentItem(item, sourcePath));
     for (const [ref, { item, sourcePath }] of mergedObjects) {

package/dist/workspace/tool-hydration.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedAgentObject, ParsedMcpServerObject, ParsedToolObject } from "../contracts/types.js";
+export declare function hydrateResourceAndExternalTools(tools: Map<string, ParsedToolObject>, toolSourceRefs: string[], workspaceRoot: string): Promise<void>;
+export declare function hydrateAgentMcpTools(agents: ParsedAgentObject[], mcpServers: Map<string, ParsedMcpServerObject>, tools: Map<string, ParsedToolObject>): Promise<void>;

package/dist/workspace/tool-hydration.js

@@ -0,0 +1,158 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { listRemoteMcpTools } from "../resource/resource-impl.js";
+import { ensureExternalResourceSource, isExternalSourceLocator } from "../resource/sources.js";
+import { listResourceTools, listResourceToolsForSource } from "../resource/resource.js";
+import { readToolModuleItems } from "./object-loader.js";
+import { parseMcpServerObject, parseToolObject } from "./resource-compilers.js";
+function toMcpServerConfig(server) {
+    return {
+        transport: server.transport,
+        command: server.command,
+        args: server.args,
+        env: server.env,
+        cwd: server.cwd,
+        url: server.url,
+        token: server.token,
+        headers: server.headers,
+    };
+}
+function readStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
+}
+function compileRegexList(value, label) {
+    return readStringArray(value).map((pattern) => {
+        try {
+            return new RegExp(pattern);
+        }
+        catch (error) {
+            throw new Error(`${label} contains invalid regex ${JSON.stringify(pattern)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+function compileMcpToolFilter(serverItem) {
+    return {
+        includeNames: new Set(readStringArray(serverItem.tools)),
+        excludeNames: new Set(readStringArray(serverItem.excludeTools)),
+        includePatterns: compileRegexList(serverItem.toolFilters ?? serverItem.toolFilter, "toolFilter"),
+        excludePatterns: compileRegexList(serverItem.excludeToolFilters ?? serverItem.excludeToolFilter, "excludeToolFilter"),
+    };
+}
+function shouldIncludeRemoteMcpTool(filter, toolName) {
+    const { includeNames, excludeNames, includePatterns, excludePatterns } = filter;
+    const includedByName = includeNames.size === 0 || includeNames.has(toolName);
+    const includedByPattern = includePatterns.length === 0 || includePatterns.some((pattern) => pattern.test(toolName));
+    if (!includedByName || !includedByPattern) {
+        return false;
+    }
+    if (excludeNames.has(toolName)) {
+        return false;
+    }
+    if (excludePatterns.some((pattern) => pattern.test(toolName))) {
+        return false;
+    }
+    return true;
+}
+async function hydrateExternalToolSource(tools, source, workspaceRoot) {
+    const externalRoot = await ensureExternalResourceSource(source, workspaceRoot);
+    const discoveredToolRefs = [];
+    const sourcePrefix = `external.${createHash("sha256").update(source).digest("hex").slice(0, 12)}`;
+    for (const { item, sourcePath } of await readToolModuleItems(path.join(externalRoot, "tools"))) {
+        const toolId = typeof item.id === "string" ? item.id : undefined;
+        if (!toolId) {
+            continue;
+        }
+        const namespacedId = `${sourcePrefix}.${toolId}`;
+        const parsed = parseToolObject({
+            id: namespacedId,
+            kind: "tool",
+            sourcePath,
+            value: {
+                ...item,
+                id: namespacedId,
+            },
+        });
+        tools.set(parsed.id, parsed);
+        discoveredToolRefs.push(`tool/${parsed.id}`);
+    }
+    const sourceTools = await listResourceToolsForSource(source, workspaceRoot);
+    const bundleRefs = [...sourceTools.map((tool) => tool.toolPath), ...discoveredToolRefs];
+    if (bundleRefs.length > 0) {
+        tools.set(source, {
+            id: source,
+            type: "bundle",
+            name: source,
+            description: `External tool resource loaded from ${source}`,
+            bundleRefs,
+            sourcePath: source,
+        });
+    }
+}
+export async function hydrateResourceAndExternalTools(tools, toolSourceRefs, workspaceRoot) {
+    for (const source of toolSourceRefs) {
+        if (isExternalSourceLocator(source)) {
+            await hydrateExternalToolSource(tools, source, workspaceRoot);
+        }
+    }
+    for (const resourceTool of await listResourceTools(toolSourceRefs, workspaceRoot)) {
+        const existing = tools.get(resourceTool.toolPath);
+        tools.set(resourceTool.toolPath, {
+            id: resourceTool.toolPath,
+            type: existing?.type ?? "backend",
+            name: existing?.name || resourceTool.name,
+            description: existing?.description || resourceTool.description,
+            config: existing?.config,
+            backendOperation: existing?.backendOperation ?? resourceTool.backendOperation,
+            bundleRefs: existing?.bundleRefs ?? [],
+            hitl: existing?.hitl ?? resourceTool.hitl,
+            sourcePath: existing?.sourcePath ?? resourceTool.toolPath,
+        });
+    }
+}
+export async function hydrateAgentMcpTools(agents, mcpServers, tools) {
+    for (const agent of agents) {
+        const discoveredRefs = new Set(agent.toolRefs);
+        for (const item of agent.mcpServers ?? []) {
+            const name = typeof item.name === "string" && item.name.trim()
+                ? item.name.trim()
+                : typeof item.id === "string" && item.id.trim()
+                    ? item.id.trim()
+                    : "";
+            if (!name) {
+                throw new Error(`Agent ${agent.id} has an MCP server entry without a name`);
+            }
+            const serverId = `${agent.id}.${name}`;
+            const parsedServer = parseMcpServerObject({
+                id: serverId,
+                kind: "mcp",
+                sourcePath: agent.sourcePath,
+                value: item,
+            });
+            const filter = compileMcpToolFilter(item);
+            mcpServers.set(serverId, parsedServer);
+            const remoteTools = await listRemoteMcpTools(toMcpServerConfig(parsedServer));
+            for (const remoteTool of remoteTools) {
+                if (!shouldIncludeRemoteMcpTool(filter, remoteTool.name)) {
+                    continue;
+                }
+                const toolId = `mcp.${agent.id}.${name}.${remoteTool.name}`;
+                tools.set(toolId, {
+                    id: toolId,
+                    type: "mcp",
+                    name: remoteTool.name,
+                    description: remoteTool.description ?? remoteTool.name,
+                    config: {
+                        mcp: {
+                            serverRef: `mcp/${serverId}`,
+                        },
+                    },
+                    mcpRef: remoteTool.name,
+                    bundleRefs: [],
+                    sourcePath: agent.sourcePath,
+                });
+                discoveredRefs.add(`tool/${toolId}`);
+            }
+        }
+        agent.toolRefs = Array.from(discoveredRefs);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "Agent Harness framework package",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/dist/config/model.yaml

@@ -1,44 +0,0 @@
-# agent-harness feature: schema version for this declarative config object.
-apiVersion: agent-harness/v1alpha1
-# agent-harness feature: object type for a named model preset.
-# Available options today: `Model`.
-# The harness resolves this object into LangChain model construction parameters.
-kind: Model
-metadata:
-  # agent-harness feature: stable model object id used by refs such as `model/default`.
-  name: default
-spec:
-  # ====================
-  # LangChain v1 Features
-  # ====================
-  # LangChain aligned feature: provider family or integration namespace.
-  # Common options in this harness today include:
-  # - `ollama`
-  # - `openai`
-  # - `openai-compatible`
-  # - `anthropic`
-  # - `google` / `google-genai` / `gemini`
-  # The runtime adapter uses this to select the concrete LangChain chat model implementation.
-  provider: ollama
-  # LangChain aligned feature: concrete model identifier passed to the selected provider integration.
-  # Example values depend on `provider`, such as `gpt-oss:latest` for `ollama`.
-  model: gpt-oss:latest
-  init:
-    # LangChain aligned feature: provider-specific initialization options.
-    # Available keys are provider-specific; common examples include `baseUrl`, `temperature`, and auth/client settings.
-    # `baseUrl` configures the Ollama-compatible endpoint used by the model client.
-    # For `openai-compatible`, `baseUrl` is normalized into the ChatOpenAI `configuration.baseURL` field.
-    baseUrl: https://ollama-rtx-4070.easynet.world/
-    # LangChain aligned feature: provider/model initialization option controlling sampling temperature.
-    temperature: 0.2
-  # ===================
-  # DeepAgents Features
-  # ===================
-  # DeepAgents uses the same model object shape indirectly through `createDeepAgent({ model })`.
-  # There is no separate DeepAgents-only field here; DeepAgent bindings consume the same compiled model.
-
-  # ======================
-  # agent-harness Features
-  # ======================
-  # This object is packaged and referenced through `modelRef` fields in harness config, but the actual
-  # model arguments above map directly onto the upstream LangChain model layer.