@botbotgo/agent-harness 0.0.267 → 0.0.268

package/README.md

@@ -752,6 +752,7 @@ Important fields:
 - `concurrency.maxConcurrentRuns`
 - `routing.defaultAgentId`
 - `routing.rules`
+- `toolModuleDiscovery.scope`
 - `maintenance.checkpoints`
 - `maintenance.records`
 - `recovery.enabled`
@@ -765,6 +766,11 @@ Important fields:
 - `maintenance.checkpoints` trims backend checkpoint state used for resume/recovery
 - `maintenance.records` trims harness-owned terminal session/request records stored in `runtime.sqlite`
 
+`toolModuleDiscovery.scope` controls how local `resources/tools/`-style module discovery walks tool directories:
+
+- `recursive` is the default and keeps scanning nested folders
+- `top-level` limits module discovery to files directly under each tool root while leaving YAML catalogs recursive
+
 When libSQL reports an error against harness runtime persistence, the message is prefixed with the absolute path to `runtime.sqlite`. For constraint-class failures (or whenever you set `AGENT_HARNESS_RUNTIME_SQLITE_DEBUG=1`), the message also includes a truncated copy of the failing SQL so you can tell harness persistence apart from other SQLite databases in the same process.
 
 Example:
@@ -776,6 +782,8 @@ metadata:
   name: default
 spec:
   runRoot: ./.agent
+  toolModuleDiscovery:
+    scope: top-level
   concurrency:
     maxConcurrentRuns: 3
   routing:

package/README.zh.md

@@ -724,6 +724,11 @@ await stop(runtime);
 - `maintenance.checkpoints` 清理后端用于 resume/recovery 的 checkpoint 状态
 - `maintenance.records` 清理 harness 自己保存在 `runtime.sqlite` 中、已结束的 session/request 记录
 
+`toolModuleDiscovery.scope` 用来控制本地 `resources/tools/` 这类 tool module 目录的发现范围：
+
+- `recursive` 是默认值，会继续扫描嵌套目录
+- `top-level` 只发现每个工具根目录下一层文件，同时保留 YAML catalog 的递归发现
+
 当 libSQL 对 harness 运行时持久化报错时，错误信息会带上 `runtime.sqlite` 的绝对路径。对约束类错误（或设置环境变量 `AGENT_HARNESS_RUNTIME_SQLITE_DEBUG=1` 时），信息中还会包含被截断的失败 SQL，便于在同一进程里区分 harness 与其它 SQLite 数据库。
 
 示例：
@@ -735,6 +740,8 @@ metadata:
   name: default
 spec:
   runRoot: ./.agent
+  toolModuleDiscovery:
+    scope: top-level
   concurrency:
     maxConcurrentRuns: 3
   routing:

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.266";
+export declare const AGENT_HARNESS_VERSION = "0.0.267";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.266";
+export const AGENT_HARNESS_VERSION = "0.0.267";

package/dist/workspace/compile.js

@@ -10,7 +10,7 @@ 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 { getRoutingDefaultAgentId, getRuntimeResources, getRoutingRules, resolveRefId, } from "./support/workspace-ref-utils.js";
+import { getRoutingDefaultAgentId, getRuntimeResources, getToolModuleDiscoveryConfig, getRoutingRules, resolveRefId, } from "./support/workspace-ref-utils.js";
 import { hydrateAgentMcpTools, hydrateResourceAndExternalTools } from "./tool-hydration.js";
 import { traceStartupStage } from "../runtime/startup-tracing.js";
 import { shouldSkipScanDirectory } from "../utils/fs.js";
@@ -123,7 +123,7 @@ async function resolveConfiguredResources(entries, workspaceRoot) {
     }
     return resolved;
 }
-async function registerAttachedResourceTools(tools, resourceRoot) {
+async function registerAttachedResourceTools(tools, resourceRoot, toolModuleDiscoveryScope) {
     const toolsRoot = path.join(resourceRoot, "tools");
     for (const { item, sourcePath } of await readYamlItems(toolsRoot, undefined, { recursive: true })) {
         const parsed = parseToolObject({
@@ -134,7 +134,7 @@ async function registerAttachedResourceTools(tools, resourceRoot) {
         });
         tools.set(parsed.id, parsed);
     }
-    for (const { item, sourcePath } of await readToolModuleItems(toolsRoot)) {
+    for (const { item, sourcePath } of await readToolModuleItems(toolsRoot, { scope: toolModuleDiscoveryScope })) {
         const parsed = parseToolObject({
             id: String(item.id),
             kind: "tool",
@@ -221,6 +221,7 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
         loaded.refs.set(`agent/${agent.id}`, agent);
     }
     const { embeddings, mcpServers, models, vectorStores, tools } = collectParsedResources(loaded.refs);
+    const toolModuleDiscoveryConfig = getToolModuleDiscoveryConfig(loaded.refs);
     await traceStartupStage("workspace.hydrate.agentMcpTools", () => hydrateAgentMcpTools(loaded.agents, mcpServers, tools), {
         workspaceRoot,
         agentCount: loaded.agents.length,
@@ -234,7 +235,7 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
         configuredResourceCount: configuredResources.length,
     });
     for (const resource of resolvedConfiguredResources) {
-        await traceStartupStage("workspace.register.attachedResourceTools", () => registerAttachedResourceTools(tools, resource.root), {
+        await traceStartupStage("workspace.register.attachedResourceTools", () => registerAttachedResourceTools(tools, resource.root, toolModuleDiscoveryConfig.scope), {
             workspaceRoot,
             resourceRoot: resource.root,
         });
@@ -259,7 +260,7 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
         workspaceRoot,
         externalResourceCount: externalResources.length,
     });
-    await traceStartupStage("workspace.hydrate.externalTools", () => hydrateResourceAndExternalTools(tools, externalResources, workspaceRoot), {
+    await traceStartupStage("workspace.hydrate.externalTools", () => hydrateResourceAndExternalTools(tools, externalResources, workspaceRoot, toolModuleDiscoveryConfig.scope), {
         workspaceRoot,
         externalResourceCount: externalResources.length,
     });

package/dist/workspace/object-loader.d.ts

@@ -1,4 +1,5 @@
 import type { ParsedAgentObject, WorkspaceLoadOptions, WorkspaceObject } from "../contracts/types.js";
+import type { ToolModuleDiscoveryScope } from "./support/workspace-ref-utils.js";
 export { normalizeYamlItem, readYamlItems } from "./yaml-object-reader.js";
 type RefMap = Map<string, WorkspaceObject | ParsedAgentObject>;
 export type WorkspaceObjects = {
@@ -7,7 +8,9 @@ export type WorkspaceObjects = {
 };
 export declare function conventionalPackageRoots(root: string, relativeDir: "tools" | "skills"): string[];
 export declare function parseAgentItem(item: Record<string, unknown>, sourcePath: string): ParsedAgentObject;
-export declare function readToolModuleItems(root: string): Promise<Array<{
+export declare function readToolModuleItems(root: string, options?: {
+    scope?: ToolModuleDiscoveryScope;
+}): Promise<Array<{
     item: Record<string, unknown>;
     sourcePath: string;
 }>>;

package/dist/workspace/object-loader.js

@@ -613,7 +613,14 @@ async function loadModuleAgentsForRoot(root, mergedAgents) {
         }
     }
 }
-async function loadConventionalObjectsForRoot(root, mergedObjects) {
+function getMergedToolModuleDiscoveryScope(mergedObjects) {
+    const runtimeDefaults = mergedObjects.get("runtime/default")?.item;
+    const toolModuleDiscovery = typeof runtimeDefaults?.toolModuleDiscovery === "object" && runtimeDefaults.toolModuleDiscovery
+        ? runtimeDefaults.toolModuleDiscovery
+        : {};
+    return toolModuleDiscovery.scope === "top-level" ? "top-level" : "recursive";
+}
+async function loadConventionalObjectsForRoot(root, mergedObjects, toolModuleDiscoveryScope) {
     for (const directory of CONVENTIONAL_OBJECT_DIRECTORIES) {
         for (const objectRoot of conventionalDirectoryRoots(root, directory)) {
             for (const { item, sourcePath } of await readYamlItemsIgnoringNodeModules(objectRoot)) {
@@ -623,7 +630,7 @@ async function loadConventionalObjectsForRoot(root, mergedObjects) {
                 }
                 mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
             }
-            for (const { item, sourcePath } of await readToolModuleItems(objectRoot)) {
+            for (const { item, sourcePath } of await readToolModuleItems(objectRoot, { scope: toolModuleDiscoveryScope })) {
                 const workspaceObject = parseWorkspaceObject(item, sourcePath);
                 if (!workspaceObject) {
                     continue;
@@ -785,10 +792,11 @@ async function loadRootObjects(root, mergedObjects) {
 function isAgentKind(kind) {
     return kind === "agent";
 }
-export async function readToolModuleItems(root) {
+export async function readToolModuleItems(root, options = {}) {
     if (!(await fileExists(root))) {
         return [];
     }
+    const scope = options.scope === "top-level" ? "top-level" : "recursive";
     const files = [];
     const pending = [root];
     while (pending.length > 0) {
@@ -798,7 +806,7 @@ export async function readToolModuleItems(root) {
             const entryPath = path.join(current, entry.name);
             const entryType = await resolveScanEntryType(entryPath, entry);
             if (entryType === "directory") {
-                if (shouldSkipScanDirectory(entry.name)) {
+                if (shouldSkipScanDirectory(entry.name) || scope === "top-level") {
                     continue;
                 }
                 pending.push(entryPath);
@@ -886,7 +894,7 @@ export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
         const configRoot = conventionalConfigRoot(root) ?? root;
         await loadConfigYamlForRoot(root, configRoot, mergedAgents, mergedObjects);
         await loadModuleAgentsForRoot(root, mergedAgents);
-        await loadConventionalObjectsForRoot(root, mergedObjects);
+        await loadConventionalObjectsForRoot(root, mergedObjects, getMergedToolModuleDiscoveryScope(mergedObjects));
         await loadModuleObjectsForRoot(root, mergedObjects);
         await loadRootObjects(root, mergedObjects);
     }

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

@@ -31,9 +31,14 @@ export type ProviderRetryConfig = {
 export type ResilienceConfig = {
     providerRetries: ProviderRetryConfig;
 };
+export type ToolModuleDiscoveryScope = "recursive" | "top-level";
+export type ToolModuleDiscoveryConfig = {
+    scope: ToolModuleDiscoveryScope;
+};
 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 getRuntimeResources(refs: Map<string, WorkspaceObject | ParsedAgentObject>): string[];
+export declare function getToolModuleDiscoveryConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): ToolModuleDiscoveryConfig;
 export declare function getRuntimeMemoryDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
 export declare function getRecoveryConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): RecoveryConfig;
 export declare function getConcurrencyConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): ConcurrencyConfig;

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

@@ -35,6 +35,15 @@ export function getRuntimeResources(refs) {
         .filter((value) => typeof value === "string" && value.trim().length > 0)
         .map((value) => value.trim());
 }
+export function getToolModuleDiscoveryConfig(refs) {
+    const runtimeDefaults = getRuntimeDefaults(refs);
+    const toolModuleDiscovery = typeof runtimeDefaults?.toolModuleDiscovery === "object" && runtimeDefaults.toolModuleDiscovery
+        ? runtimeDefaults.toolModuleDiscovery
+        : {};
+    return {
+        scope: toolModuleDiscovery.scope === "top-level" ? "top-level" : "recursive",
+    };
+}
 export function getRuntimeMemoryDefaults(refs) {
     const runtimeMemories = Array.from(refs.values()).filter((object) => !("executionMode" in object) && object.kind === "runtime-memory");
     if (runtimeMemories.length === 0) {

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

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

package/dist/workspace/tool-hydration.js

@@ -144,11 +144,11 @@ function mergeReferencedMcpServer(referencedServer, item, agentId, name, sourceP
         sourcePath,
     };
 }
-async function hydrateExternalToolSource(tools, source, workspaceRoot) {
+async function hydrateExternalToolSource(tools, source, workspaceRoot, toolModuleDiscoveryScope) {
     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"))) {
+    for (const { item, sourcePath } of await readToolModuleItems(path.join(externalRoot, "tools"), { scope: toolModuleDiscoveryScope })) {
         const toolId = typeof item.id === "string" ? item.id : undefined;
         if (!toolId) {
             continue;
@@ -179,10 +179,10 @@ async function hydrateExternalToolSource(tools, source, workspaceRoot) {
         });
     }
 }
-export async function hydrateResourceAndExternalTools(tools, toolSourceRefs, workspaceRoot) {
+export async function hydrateResourceAndExternalTools(tools, toolSourceRefs, workspaceRoot, toolModuleDiscoveryScope = "recursive") {
     for (const source of toolSourceRefs) {
         if (isExternalSourceLocator(source)) {
-            await hydrateExternalToolSource(tools, source, workspaceRoot);
+            await hydrateExternalToolSource(tools, source, workspaceRoot, toolModuleDiscoveryScope);
         }
     }
     for (const resourceTool of await listResourceTools(toolSourceRefs, workspaceRoot)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.267",
+  "version": "0.0.268",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",