@botbotgo/agent-harness 0.0.307 → 0.0.308

package/README.md

@@ -469,9 +469,9 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-`createAgentHarness(...)` loads the workspace, resolves `resources/`, initializes persistence under `runtimeRoot`, and starts runtime maintenance.
+`createAgentHarness(...)` loads the workspace, resolves workspace sources, initializes persistence under `runtimeRoot`, and starts runtime maintenance.
 
-`runtime.spec.resources` may attach multiple extra resource packages. Each entry may point either to a package root that contains `resources/`, or directly to a resource folder that contains its own `package.json`.
+`runtime.spec.sources` is the primary public discovery surface for local tools, package tools, and skill packages.
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -479,11 +479,29 @@ kind: Runtime
 metadata:
   name: default
 spec:
-  resources:
-    - ../shared-tools
-    - file:../shared-skills
+  sources:
+    tools:
+      - file://./resources/tools
+      - file://../shared-tools
+      - npm://@acme/agent-tools
+    skills:
+      - file://./resources/skills
+      - https://example.com/skills/review/SKILL.md
 ```
 
+Tool-source rules:
+
+- `file://...` scans only the configured folder
+- `npm://...` resolves one package, auto-installs it when missing, and discovers exported `tool({...})` definitions from the package entry
+- tool discovery never traverses `node_modules/**`
+
+Skill-source rules:
+
+- `file://...` accepts a skill collection folder, a single skill root, or a direct `SKILL.md` path
+- `http://...` and `https://...` currently accept a single remote `SKILL.md`
+
+`runtime.spec.resources` remains supported as a compatibility path for attached resource packages.
+
 `createAgentHarness(..., { load })` accepts workspace loading controls.
 
 Merge order is deterministic:
@@ -739,8 +757,10 @@ Discovery rules:
 
 - every YAML document under `config/**` is discovered recursively; filenames and subfolders are organizational only
 - YAML object semantics come from `kind`, `metadata.name` or `id`, and object content rather than the file path
-- local tools are auto-discovered from `resources/tools/**/*.js|*.mjs|*.cjs` when they export `tool({...})`
-- skills are auto-discovered from `resources/skills/**/SKILL.md`
+- `Runtime.spec.sources.tools` defaults to `file://./resources/tools`
+- `Runtime.spec.sources.skills` defaults to `file://./resources/skills`
+- local file-based tools are auto-discovered from each configured tool folder when modules export `tool({...})`
+- file-based skills are auto-discovered from each configured skill source
 - a minimal workspace can start with only `config/models.yaml`; the repository defaults provide the `Runtime`, the default `orchestra` host, and runtime-managed durable memory with `enabled: true`
 - when you do not override runtime placement, harness-owned generated state is written under `./.botbotgo/`
 
@@ -768,7 +788,9 @@ For DeepAgents-backed agents, the runtime still keeps an internal compatibility
 
 Default wiring guidance:
 
-- let workspace startup scan local and attached `resources` packages into one registry
+- let `Runtime.spec.sources` declare the tool and skill roots the workspace owns
+- let workspace startup scan only those declared sources into one registry
+- let workspace startup scan local and attached `resources` packages into one registry when compatibility paths are still in use
 - let agents whitelist tools and skills by name
 - keep `config/catalogs/tools.yaml` for reusable shared tools
 - keep `config/catalogs/mcp.yaml` for shared MCP server definitions
@@ -810,6 +832,8 @@ Important fields:
 
 - `runtimeRoot`
 - `concurrency.maxConcurrentRequests`
+- `sources.tools`
+- `sources.skills`
 - `routing.defaultAgentId`
 - `routing.rules`
 - `toolModuleDiscovery.scope`
@@ -826,7 +850,17 @@ 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:
+`sources.tools` controls which tool roots or packages participate in workspace discovery:
+
+- `file://...` for folder scanning
+- `npm://...` for package-entry discovery and auto-install when missing
+
+`sources.skills` controls which skill folders or skill documents participate in workspace discovery:
+
+- `file://...` for local folders, skill roots, or direct `SKILL.md`
+- `http://...` / `https://...` for one remote `SKILL.md`
+
+`toolModuleDiscovery.scope` controls how local `resources/tools/`-style file 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

package/README.zh.md

@@ -464,9 +464,9 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-`createAgentHarness(...)` 会加载工作区、解析 `resources/`、在 `runtimeRoot` 下初始化持久化，并启动运行时维护任务。
+`createAgentHarness(...)` 会加载工作区、解析工作区 source、在 `runtimeRoot` 下初始化持久化，并启动运行时维护任务。
 
-`runtime.spec.resources` 可以挂载多个额外资源包。每个条目既可以指向“包根目录下带有 `resources/` 的目录”，也可以直接指向“自身带有 `package.json` 的资源目录”。
+`runtime.spec.sources` 现在是本地工具、npm 工具包与 skill package 的主公开发现入口。
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -474,11 +474,29 @@ kind: Runtime
 metadata:
   name: default
 spec:
-  resources:
-    - ../shared-tools
-    - file:../shared-skills
+  sources:
+    tools:
+      - file://./resources/tools
+      - file://../shared-tools
+      - npm://@acme/agent-tools
+    skills:
+      - file://./resources/skills
+      - https://example.com/skills/review/SKILL.md
 ```
 
+tool source 规则：
+
+- `file://...` 只扫描显式配置的目录
+- `npm://...` 只解析单个包；本地缺失时会自动安装，再从包入口发现导出的 `tool({...})`
+- tool 发现永远不会遍历 `node_modules/**`
+
+skill source 规则：
+
+- `file://...` 可以指向 skill 集合目录、单个 skill root，或直接指向 `SKILL.md`
+- `http://...` 与 `https://...` 当前只支持一个远程 `SKILL.md`
+
+`runtime.spec.resources` 仍保留为兼容旧 attached resource package 的路径。
+
 `createAgentHarness(..., { load })` 支持工作区加载控制。
 
 合并顺序是确定性的：
@@ -710,8 +728,10 @@ await stop(runtime);
 
 - `config/**` 下的所有 YAML 文档都会被递归发现；文件名与子目录只用于组织，不参与语义
 - YAML 对象语义由 `kind`、`metadata.name` 或 `id` 以及对象内容决定，而不是由文件路径决定
-- 本地工具会从 `resources/tools/**/*.js|*.mjs|*.cjs` 中自动发现，前提是模块导出 `tool({...})`
-- skills 会从 `resources/skills/**/SKILL.md` 自动发现
+- `Runtime.spec.sources.tools` 默认值是 `file://./resources/tools`
+- `Runtime.spec.sources.skills` 默认值是 `file://./resources/skills`
+- file-based 工具会从每个声明的 tool source 自动发现，前提是模块导出 `tool({...})`
+- file-based skills 会从每个声明的 skill source 自动发现
 - 一个最小工作区只放 `config/models.yaml` 也可以启动；仓库默认值会补上 `Runtime`、默认 `orchestra` host，以及默认开启的 runtime-managed durable memory
 - 如果不显式覆盖 runtime 放置位置，harness 生成的数据默认写到 `./.botbotgo/`
 
@@ -740,7 +760,9 @@ await stop(runtime);
 
 配置大致分这几层（由下至上叠加）：
 
-- workspace 启动时扫描本地与附加的 `resources` 包，建立统一 registry
+- 先由 `Runtime.spec.sources` 声明工作区实际拥有的 tool / skill 来源
+- workspace 启动时只扫描这些显式声明的 source，并建立统一 registry
+- workspace 启动时扫描本地与附加的 `resources` 包，建立统一 registry；这条兼容路径仍可继续工作
 - 各 agent 再按名称白名单选用 tools 与 skills
 - `config/runtime/workspace.yaml` 承载运行时策略
 - `config/catalogs/*.yaml` 承载可复用对象目录
@@ -776,6 +798,8 @@ await stop(runtime);
 
 - `runtimeRoot`
 - `concurrency.maxConcurrentRequests`
+- `sources.tools`
+- `sources.skills`
 - `routing.defaultAgentId`
 - `routing.rules`
 - `routing.systemPrompt`
@@ -793,7 +817,17 @@ await stop(runtime);
 - `maintenance.checkpoints` 清理后端用于 resume/recovery 的 checkpoint 状态
 - `maintenance.records` 清理 harness 自己保存在 `runtime.sqlite` 中、已结束的 session/request 记录
 
-`toolModuleDiscovery.scope` 用来控制本地 `resources/tools/` 这类 tool module 目录的发现范围：
+`sources.tools` 用来声明哪些 tool root 或 package 参与工作区发现：
+
+- `file://...` 用于目录扫描
+- `npm://...` 用于包入口发现；本地缺失时自动安装
+
+`sources.skills` 用来声明哪些 skill 目录或 skill 文档参与工作区发现：
+
+- `file://...` 用于本地目录、skill root 或直接 `SKILL.md`
+- `http://...` / `https://...` 用于单个远程 `SKILL.md`
+
+`toolModuleDiscovery.scope` 用来控制本地 `resources/tools/` 风格 file source 的发现范围：
 
 - `recursive` 是默认值，会继续扫描嵌套目录
 - `top-level` 只发现每个工具根目录下一层文件，同时保留 YAML catalog 的递归发现

package/dist/config/runtime/workspace.yaml

@@ -29,6 +29,22 @@ spec:
   # agent-harness feature: stable runtime profile identifier for this data folder.
   profile: default
 
+  # agent-harness feature: explicit tool and skill discovery sources.
+  # The default local workspace contract stays:
+  # - tools from ./resources/tools
+  # - skills from ./resources/skills
+  #
+  # Supported source forms today:
+  # - tools: file://<folder>, npm://<package-or-spec>
+  # - skills: file://<folder-or-SKILL.md>, http(s)://.../SKILL.md
+  #
+  # Discovery never traverses node_modules directories.
+  sources:
+    tools:
+      - file://./resources/tools
+    skills:
+      - file://./resources/skills
+
   # agent-harness feature: runtime-level task queue and maximum number of concurrent requests.
   # Additional requests wait in the harness queue until a slot becomes available.
   concurrency:

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.306";
+export declare const AGENT_HARNESS_VERSION = "0.0.307";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.306";
+export const AGENT_HARNESS_VERSION = "0.0.307";

package/dist/resource/isolation.js

@@ -93,7 +93,9 @@ async function linkHarnessPackage(isolatedRoot) {
 }
 async function buildIsolatedResourceRoot(packageRoot) {
     const packageJsonPath = path.join(packageRoot, "package.json");
-    const manifest = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    const manifest = existsSync(packageJsonPath)
+        ? JSON.parse(await readFile(packageJsonPath, "utf8"))
+        : {};
     const isolatedRoot = createIsolatedSnapshotDir(packageRoot);
     await mkdir(path.dirname(isolatedRoot), { recursive: true });
     await cp(packageRoot, isolatedRoot, {
@@ -101,6 +103,9 @@ async function buildIsolatedResourceRoot(packageRoot) {
         force: true,
         filter: (source) => path.basename(source) !== "node_modules",
     });
+    if (!existsSync(path.join(isolatedRoot, "package.json"))) {
+        await cp(path.join(HARNESS_PACKAGE_ROOT, "resources", "package.json"), path.join(isolatedRoot, "package.json"));
+    }
     await mkdir(path.join(isolatedRoot, "node_modules"), { recursive: true });
     await linkDeclaredDependencies(isolatedRoot, packageRoot, manifest);
     await linkHarnessPackage(isolatedRoot);

package/dist/runtime/adapter/model/invocation-request.d.ts

@@ -2,6 +2,7 @@ import type { CompiledAgentBinding, MessageContent, TranscriptMessage } from "..
 export declare function buildAgentMessages(history: TranscriptMessage[], input: MessageContent, options?: {
     suppressExplicitResourceTurns?: boolean;
     suppressAssistantTurns?: boolean;
+    suppressHistoryTurns?: boolean;
 }): Array<{
     role: string;
     content: MessageContent;

package/dist/runtime/adapter/model/invocation-request.js

@@ -84,6 +84,9 @@ function selectRelevantHistoryTurns(groupedHistory, inputText, options = {}) {
 }
 export function buildAgentMessages(history, input, options = {}) {
     const inputText = extractMessageText(input).trim();
+    if (options.suppressHistoryTurns) {
+        return [{ role: "user", content: normalizeMessageContent(input) }];
+    }
     const groupedHistory = history.reduce((groups, item) => {
         const current = groups.at(-1);
         if (current && current[0]?.requestId === item.requestId) {
@@ -156,6 +159,7 @@ export function buildInvocationRequest(binding, history, input, options = {}) {
     const messages = buildAgentMessages(history, input, {
         suppressExplicitResourceTurns: Boolean(memoryInstruction) && !hasExplicitResourceReference(inputText),
         suppressAssistantTurns: Boolean(memoryInstruction) && !hasExplicitResourceReference(inputText),
+        suppressHistoryTurns: Boolean(memoryInstruction) && !hasExplicitResourceReference(inputText),
     });
     const contextualFollowUpInstruction = buildContextualFollowUpInstruction(inputText, Boolean(memoryInstruction));
     const conversationLanguage = resolveConversationLanguage(history, inputText);

package/dist/workspace/compile.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
 import { ensureResourceSources } from "../resource/resource.js";
 import { ensureExternalResourceSource, isExternalSourceLocator, resolveResourcePackageRoot } from "../resource/sources.js";
 import { loadWorkspaceObjects, readToolModuleItems, readYamlItems } from "./object-loader.js";
@@ -10,10 +11,30 @@ 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, getRuntimeStorageRoots, getToolModuleDiscoveryConfig, getRoutingRules, resolveRefId, } from "./support/workspace-ref-utils.js";
+import { getRoutingDefaultAgentId, getRuntimeSources, getRuntimeResources, getRuntimeStorageRoots, 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";
+import { ensureRemoteSkillSource, ensureToolPackageSource, isFileSourceUri, isHttpSourceUri, isNpmSourceUri, resolveFileSourcePath, } from "./support/source-protocols.js";
+import { discoverToolModuleDefinitions } from "../tool-modules.js";
+function mergeObjectValues(base, override) {
+    if (override === undefined) {
+        return base;
+    }
+    if (typeof base === "object" &&
+        base &&
+        typeof override === "object" &&
+        override &&
+        !Array.isArray(base) &&
+        !Array.isArray(override)) {
+        const merged = { ...base };
+        for (const [key, value] of Object.entries(override)) {
+            merged[key] = key in merged ? mergeObjectValues(merged[key], value) : value;
+        }
+        return merged;
+    }
+    return override;
+}
 function collectParsedResources(refs) {
     const embeddings = new Map();
     const mcpServers = new Map();
@@ -132,7 +153,7 @@ async function registerAttachedResourceTools(tools, resourceRoot, toolModuleDisc
             sourcePath,
             value: item,
         });
-        tools.set(parsed.id, parsed);
+        tools.set(parsed.id, mergeParsedToolObject(tools.get(parsed.id), parsed));
     }
     for (const { item, sourcePath } of await readToolModuleItems(toolsRoot, { scope: toolModuleDiscoveryScope })) {
         const parsed = parseToolObject({
@@ -141,7 +162,7 @@ async function registerAttachedResourceTools(tools, resourceRoot, toolModuleDisc
             sourcePath,
             value: item,
         });
-        tools.set(parsed.id, parsed);
+        tools.set(parsed.id, mergeParsedToolObject(tools.get(parsed.id), parsed));
     }
 }
 async function collectSkillRoots(root) {
@@ -160,6 +181,90 @@ async function collectSkillRoots(root) {
         return [];
     }
 }
+async function resolveConfiguredSkillSourceRoots(sources, workspaceRoot) {
+    const resolved = [];
+    for (const source of sources) {
+        if (isFileSourceUri(source)) {
+            const resolvedPath = resolveFileSourcePath(source, workspaceRoot);
+            resolved.push(resolvedPath.endsWith(`${path.sep}SKILL.md`) || resolvedPath.endsWith("/SKILL.md")
+                ? path.dirname(resolvedPath)
+                : resolvedPath);
+            continue;
+        }
+        if (isHttpSourceUri(source)) {
+            resolved.push(await ensureRemoteSkillSource(source));
+            continue;
+        }
+        throw new Error(`Unsupported skill source ${source}. Use file:// or https://.`);
+    }
+    return resolved;
+}
+async function registerToolFolderSource(tools, folderRoot, toolModuleDiscoveryScope) {
+    for (const { item, sourcePath } of await readYamlItems(folderRoot, undefined, { recursive: true })) {
+        const parsed = parseToolObject({
+            id: typeof item.id === "string" ? item.id : path.basename(sourcePath).replace(/\.(yaml|yml|json)$/i, ""),
+            kind: "tool",
+            sourcePath,
+            value: item,
+        });
+        tools.set(parsed.id, mergeParsedToolObject(tools.get(parsed.id), parsed));
+    }
+    for (const { item, sourcePath } of await readToolModuleItems(folderRoot, { scope: toolModuleDiscoveryScope })) {
+        const parsed = parseToolObject({
+            id: String(item.id),
+            kind: "tool",
+            sourcePath,
+            value: item,
+        });
+        tools.set(parsed.id, mergeParsedToolObject(tools.get(parsed.id), parsed));
+    }
+}
+async function registerToolPackageSource(tools, source, workspaceRoot) {
+    const installed = await ensureToolPackageSource(source, workspaceRoot);
+    const imported = await import(pathToFileURL(installed.entryPath).href);
+    const definitions = discoverToolModuleDefinitions("", imported);
+    for (const definition of definitions) {
+        const parsed = parseToolObject({
+            id: definition.implementationName,
+            kind: "tool",
+            sourcePath: installed.entryPath,
+            value: {
+                kind: "tool",
+                id: definition.implementationName,
+                type: "function",
+                name: definition.implementationName,
+                description: definition.description,
+                implementationName: definition.implementationName,
+                hasModuleSchema: definition.hasModuleSchema,
+                ...(definition.modelSchema ? { modelSchema: definition.modelSchema } : {}),
+                ...(definition.retryable !== undefined ? { retryable: definition.retryable } : {}),
+                ...(definition.memory ? { config: { memory: definition.memory } } : {}),
+            },
+        });
+        tools.set(parsed.id, mergeParsedToolObject(tools.get(parsed.id), parsed));
+    }
+}
+function mergeParsedToolObject(current, incoming) {
+    if (!current) {
+        return incoming;
+    }
+    return {
+        ...current,
+        ...incoming,
+        config: mergeObjectValues(current.config, incoming.config),
+        subprocess: incoming.subprocess ?? current.subprocess,
+        inputSchemaRef: incoming.inputSchemaRef ?? current.inputSchemaRef,
+        hasModuleSchema: incoming.hasModuleSchema ?? current.hasModuleSchema,
+        modelSchema: incoming.modelSchema ?? current.modelSchema,
+        embeddingModelRef: incoming.embeddingModelRef ?? current.embeddingModelRef,
+        backendOperation: incoming.backendOperation ?? current.backendOperation,
+        mcpRef: incoming.mcpRef ?? current.mcpRef,
+        bundleRefs: incoming.bundleRefs.length > 0 ? incoming.bundleRefs : current.bundleRefs,
+        hitl: incoming.hitl ?? current.hitl,
+        retryable: incoming.retryable ?? current.retryable,
+        sourcePath: incoming.sourcePath,
+    };
+}
 async function registerWorkspaceSkillRegistry(skillCollectionRoots) {
     const registry = new Map();
     for (const skillsRoot of skillCollectionRoots) {
@@ -227,10 +332,29 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
     }
     const { embeddings, mcpServers, models, vectorStores, tools } = collectParsedResources(loaded.refs);
     const toolModuleDiscoveryConfig = getToolModuleDiscoveryConfig(loaded.refs);
+    const runtimeSources = getRuntimeSources(loaded.refs);
     await traceStartupStage("workspace.hydrate.agentMcpTools", () => hydrateAgentMcpTools(loaded.agents, mcpServers, tools), {
         workspaceRoot,
         agentCount: loaded.agents.length,
     });
+    for (const source of runtimeSources.tools) {
+        if (isFileSourceUri(source)) {
+            const folderRoot = resolveFileSourcePath(source, workspaceRoot);
+            await traceStartupStage("workspace.register.toolFolderSource", () => registerToolFolderSource(tools, folderRoot, toolModuleDiscoveryConfig.scope), {
+                workspaceRoot,
+                source,
+            });
+            continue;
+        }
+        if (isNpmSourceUri(source)) {
+            await traceStartupStage("workspace.register.toolPackageSource", () => registerToolPackageSource(tools, source, workspaceRoot), {
+                workspaceRoot,
+                source,
+            });
+            continue;
+        }
+        throw new Error(`Unsupported tool source ${source}. Use file:// or npm://.`);
+    }
     const configuredResources = Array.from(new Set([
         ...getRuntimeResources(loaded.refs),
         ...(options.resources ?? []),
@@ -246,11 +370,16 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
         });
     }
     const localResourceRoot = resolveResourcePackageRoot(workspaceRoot);
-    const skillCollectionRoots = [
+    const configuredSkillSourceRoots = await traceStartupStage("workspace.resolve.skillSources", () => resolveConfiguredSkillSourceRoots(runtimeSources.skills, workspaceRoot), {
+        workspaceRoot,
+        skillSourceCount: runtimeSources.skills.length,
+    });
+    const skillCollectionRoots = Array.from(new Set([
         path.join(workspaceRoot, "modules", "skills"),
         ...(localResourceRoot ? [path.join(localResourceRoot, "skills")] : []),
+        ...configuredSkillSourceRoots,
         ...resolvedConfiguredResources.map((resource) => path.join(resource.root, "skills")),
-    ];
+    ]));
     const skillRegistry = await traceStartupStage("workspace.register.skillRegistry", () => registerWorkspaceSkillRegistry(skillCollectionRoots), {
         workspaceRoot,
         skillCollectionRootCount: skillCollectionRoots.length,
@@ -272,6 +401,7 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
     validateToolNameConflicts(tools);
     const resources = Array.from(new Set([
         ...(localResourceRoot ? [localResourceRoot] : []),
+        ...runtimeSources.tools.filter((source) => isNpmSourceUri(source)),
         ...collectedResources,
     ]));
     await traceStartupStage("workspace.validate.resources", async () => {

package/dist/workspace/object-loader.js

@@ -6,6 +6,7 @@ import { resolveIsolatedResourceModulePath } from "../resource/isolation.js";
 import { isExternalSourceLocator, resolveResourcePackageRoot } from "../resource/sources.js";
 import { discoverToolModuleDefinitions, isSupportedToolModulePath, loadToolModuleDefinition } from "../tool-modules.js";
 import { fileExists, shouldSkipScanDirectory } from "../utils/fs.js";
+import { isFileSourceUri, readRuntimeSources, resolveFileSourcePath } from "./support/source-protocols.js";
 import { readNamedYamlItems, readYamlItems, } from "./yaml-object-reader.js";
 export { normalizeYamlItem, readYamlItems } from "./yaml-object-reader.js";
 const CONVENTIONAL_OBJECT_DIRECTORIES = ["tools"];
@@ -682,23 +683,32 @@ function getMergedToolModuleDiscoveryScope(mergedObjects) {
         : {};
     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)) {
-                const workspaceObject = parseWorkspaceObject(item, sourcePath);
-                if (!workspaceObject) {
-                    continue;
-                }
-                mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
+async function loadConventionalObjectsForRoot(root, runtimeRoot, mergedObjects, toolModuleDiscoveryScope) {
+    const runtimeDefaults = mergedObjects.get("runtime/default")?.item;
+    const configuredToolRoots = readRuntimeSources(runtimeDefaults).tools
+        .filter((source) => isFileSourceUri(source))
+        .map((source) => resolveFileSourcePath(source, runtimeRoot));
+    const conventionalToolRoots = CONVENTIONAL_OBJECT_DIRECTORIES.flatMap((directory) => conventionalDirectoryRoots(root, directory));
+    const objectRoots = root === runtimeRoot
+        ? Array.from(new Set([
+            ...conventionalToolRoots,
+            ...configuredToolRoots,
+        ]))
+        : conventionalToolRoots;
+    for (const objectRoot of objectRoots) {
+        for (const { item, sourcePath } of await readYamlItemsIgnoringNodeModules(objectRoot)) {
+            const workspaceObject = parseWorkspaceObject(item, sourcePath);
+            if (!workspaceObject) {
+                continue;
             }
-            for (const { item, sourcePath } of await readToolModuleItems(objectRoot, { scope: toolModuleDiscoveryScope })) {
-                const workspaceObject = parseWorkspaceObject(item, sourcePath);
-                if (!workspaceObject) {
-                    continue;
-                }
-                mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
+            mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
+        }
+        for (const { item, sourcePath } of await readToolModuleItems(objectRoot, { scope: toolModuleDiscoveryScope })) {
+            const workspaceObject = parseWorkspaceObject(item, sourcePath);
+            if (!workspaceObject) {
+                continue;
             }
+            mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
         }
     }
 }
@@ -882,7 +892,7 @@ export async function readToolModuleItems(root, options = {}) {
     const records = [];
     for (const filePath of files) {
         const sourceText = await readFile(filePath, "utf8");
-        const packageRoot = path.dirname(root);
+        const packageRoot = findToolPackageRoot(filePath);
         const isolatedSourcePath = await resolveIsolatedResourceModulePath(packageRoot, filePath);
         const imported = await import(pathToFileURL(isolatedSourcePath).href);
         const definitions = discoverToolModuleDefinitions(sourceText, imported);
@@ -958,7 +968,7 @@ export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
         await loadConfigYamlForRoot(root, configRoot, mergedAgents, mergedObjects);
         await loadModuleAgentsForRoot(root, mergedAgents);
         if (root !== defaultRoot) {
-            await loadConventionalObjectsForRoot(root, mergedObjects, getMergedToolModuleDiscoveryScope(mergedObjects));
+            await loadConventionalObjectsForRoot(root, workspaceRoot, mergedObjects, getMergedToolModuleDiscoveryScope(mergedObjects));
         }
         await loadModuleObjectsForRoot(root, mergedObjects);
         await loadRootObjects(root, mergedObjects);

package/dist/workspace/resource-compilers.js

@@ -302,9 +302,9 @@ export function parseToolObject(object) {
                 ...(mcpServerConfig && Object.keys(mcpServerConfig).length > 0 ? { mcpServer: mcpServerConfig } : {}),
             }
             : undefined),
-        subprocess: value.subprocess === true,
+        subprocess: value.subprocess === true ? true : undefined,
         inputSchemaRef: typeof asObject(value.inputSchema)?.ref === "string" ? String(asObject(value.inputSchema)?.ref) : undefined,
-        hasModuleSchema: value.hasModuleSchema === true,
+        hasModuleSchema: value.hasModuleSchema === true ? true : undefined,
         modelSchema: asObject(value.modelSchema),
         embeddingModelRef: typeof value.embeddingModelRef === "string"
             ? value.embeddingModelRef
@@ -325,7 +325,7 @@ export function parseToolObject(object) {
                 : undefined,
         bundleRefs,
         hitl: parseHitlPolicy(value.hitl),
-        retryable: value.retryable === true,
+        retryable: value.retryable === true ? true : undefined,
         sourcePath: object.sourcePath,
     };
 }

package/dist/workspace/support/source-protocols.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_TOOL_SOURCE_URIS: string[];
+export declare const DEFAULT_SKILL_SOURCE_URIS: string[];
+export type RuntimeSourceConfig = {
+    tools: string[];
+    skills: string[];
+};
+type ToolPackageInstallation = {
+    entryPath: string;
+    packageRoot: string;
+    packageName: string;
+};
+export declare function readRuntimeSources(runtimeDefaults: Record<string, unknown> | undefined): RuntimeSourceConfig;
+export declare function isFileSourceUri(value: string): boolean;
+export declare function isNpmSourceUri(value: string): boolean;
+export declare function isHttpSourceUri(value: string): boolean;
+export declare function resolveFileSourcePath(uri: string, workspaceRoot: string): string;
+export declare function ensureToolPackageSource(uri: string, workspaceRoot: string): Promise<ToolPackageInstallation>;
+export declare function ensureRemoteSkillSource(uri: string): Promise<string>;
+export {};

package/dist/workspace/support/source-protocols.js

@@ -0,0 +1,192 @@
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { parse as parseYaml } from "yaml";
+const execFileAsync = promisify(execFile);
+export const DEFAULT_TOOL_SOURCE_URIS = ["file://./resources/tools"];
+export const DEFAULT_SKILL_SOURCE_URIS = ["file://./resources/skills"];
+const require = createRequire(import.meta.url);
+function normalizeSourceList(value, fallback) {
+    if (!Array.isArray(value)) {
+        return [...fallback];
+    }
+    return value
+        .filter((item) => typeof item === "string" && item.trim().length > 0)
+        .map((item) => item.trim());
+}
+export function readRuntimeSources(runtimeDefaults) {
+    const rawSources = typeof runtimeDefaults?.sources === "object" && runtimeDefaults.sources && !Array.isArray(runtimeDefaults.sources)
+        ? runtimeDefaults.sources
+        : {};
+    return {
+        tools: normalizeSourceList(rawSources.tools, DEFAULT_TOOL_SOURCE_URIS),
+        skills: normalizeSourceList(rawSources.skills, DEFAULT_SKILL_SOURCE_URIS),
+    };
+}
+export function isFileSourceUri(value) {
+    return value.startsWith("file://");
+}
+export function isNpmSourceUri(value) {
+    return value.startsWith("npm://");
+}
+export function isHttpSourceUri(value) {
+    return value.startsWith("http://") || value.startsWith("https://");
+}
+export function resolveFileSourcePath(uri, workspaceRoot) {
+    if (!isFileSourceUri(uri)) {
+        throw new Error(`Unsupported file source URI ${uri}`);
+    }
+    const rawPath = uri.slice("file://".length).trim();
+    if (!rawPath) {
+        throw new Error(`File source URI ${uri} must include a path`);
+    }
+    return path.isAbsolute(rawPath) ? rawPath : path.resolve(workspaceRoot, rawPath);
+}
+function parseToolPackageName(spec, workspaceRoot) {
+    if (spec.startsWith("file:")) {
+        const localPath = spec.slice("file:".length);
+        const resolvedPath = path.isAbsolute(localPath) ? localPath : path.resolve(workspaceRoot, localPath);
+        const packageJsonPath = path.join(resolvedPath, "package.json");
+        if (!existsSync(packageJsonPath)) {
+            throw new Error(`Package tool source ${spec} is missing package.json`);
+        }
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        if (typeof packageJson.name !== "string" || packageJson.name.trim().length === 0) {
+            throw new Error(`Package tool source ${spec} must define a package.json name`);
+        }
+        return packageJson.name.trim();
+    }
+    const match = spec.match(/^(@[^/]+\/[^@/]+|[^@/]+)(?:@.+)?$/);
+    if (!match?.[1]) {
+        throw new Error(`Unsupported package tool source ${spec}. Use npm://<package-name> or npm://<package-name>@<version>.`);
+    }
+    return match[1];
+}
+function packageInstallCacheRoot(spec) {
+    const digest = createHash("sha256").update(spec).digest("hex").slice(0, 16);
+    return path.join(os.tmpdir(), "agent-harness-package-tools", digest);
+}
+function resolvePackageEntry(packageRoot, pkg) {
+    const exportsField = pkg.exports;
+    if (typeof exportsField === "string") {
+        return path.resolve(packageRoot, exportsField);
+    }
+    if (exportsField && typeof exportsField === "object" && "." in exportsField) {
+        const rootExport = exportsField["."];
+        if (typeof rootExport === "string") {
+            return path.resolve(packageRoot, rootExport);
+        }
+        if (rootExport && typeof rootExport === "object") {
+            const importEntry = rootExport.import ?? rootExport.default;
+            if (typeof importEntry === "string") {
+                return path.resolve(packageRoot, importEntry);
+            }
+        }
+    }
+    if (typeof pkg.module === "string") {
+        return path.resolve(packageRoot, pkg.module);
+    }
+    if (typeof pkg.main === "string") {
+        return path.resolve(packageRoot, pkg.main);
+    }
+    return path.resolve(packageRoot, "index.js");
+}
+function resolveInstalledPackageRoot(packageName, workspaceRoot) {
+    const packageJsonRef = `${packageName}/package.json`;
+    const directNodeModulesPath = path.join(workspaceRoot, "node_modules", ...packageName.split("/"), "package.json");
+    if (existsSync(directNodeModulesPath)) {
+        return path.dirname(directNodeModulesPath);
+    }
+    for (const candidateRoot of [workspaceRoot, process.cwd()]) {
+        try {
+            const candidateRequire = createRequire(path.join(candidateRoot, "__agent_harness_package_resolve__.cjs"));
+            return path.dirname(candidateRequire.resolve(packageJsonRef));
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function installPackageToolSource(spec, workspaceRoot) {
+    const packageName = parseToolPackageName(spec, workspaceRoot);
+    const installRoot = packageInstallCacheRoot(spec);
+    const packageJsonPath = path.join(installRoot, "package.json");
+    await mkdir(installRoot, { recursive: true });
+    if (!existsSync(packageJsonPath)) {
+        await writeFile(packageJsonPath, `${JSON.stringify({ name: "agent-harness-package-tool-cache", private: true }, null, 2)}\n`, "utf8");
+    }
+    const installedRoot = path.join(installRoot, "node_modules", ...packageName.split("/"));
+    if (!existsSync(path.join(installedRoot, "package.json"))) {
+        await execFileAsync("npm", ["install", "--no-save", spec], {
+            cwd: installRoot,
+            maxBuffer: 1024 * 1024 * 20,
+            env: process.env,
+        });
+    }
+    const packageJson = JSON.parse(await readFile(path.join(installedRoot, "package.json"), "utf8"));
+    return {
+        packageName,
+        packageRoot: installedRoot,
+        entryPath: resolvePackageEntry(installedRoot, packageJson),
+    };
+}
+export async function ensureToolPackageSource(uri, workspaceRoot) {
+    if (!isNpmSourceUri(uri)) {
+        throw new Error(`Unsupported package source URI ${uri}`);
+    }
+    const spec = uri.slice("npm://".length).trim();
+    if (!spec) {
+        throw new Error(`Package source URI ${uri} must include a package name`);
+    }
+    const packageName = parseToolPackageName(spec, workspaceRoot);
+    const installedRoot = resolveInstalledPackageRoot(packageName, workspaceRoot);
+    if (installedRoot && !spec.startsWith("file:") && !spec.includes("@", packageName.startsWith("@") ? packageName.length : 0)) {
+        const packageJson = JSON.parse(await readFile(path.join(installedRoot, "package.json"), "utf8"));
+        return {
+            packageName,
+            packageRoot: installedRoot,
+            entryPath: resolvePackageEntry(installedRoot, packageJson),
+        };
+    }
+    return installPackageToolSource(spec, workspaceRoot);
+}
+function parseSkillFrontmatterName(document) {
+    const match = document.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
+    if (!match?.[1]) {
+        return undefined;
+    }
+    const parsed = parseYaml(match[1]);
+    return typeof parsed?.name === "string" && parsed.name.trim().length > 0 ? parsed.name.trim() : undefined;
+}
+function sanitizeSkillDirName(input) {
+    const normalized = input.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    return normalized || "remote-skill";
+}
+function remoteSkillCacheRoot(uri) {
+    const digest = createHash("sha256").update(uri).digest("hex").slice(0, 16);
+    return path.join(os.tmpdir(), "agent-harness-remote-skills", digest);
+}
+export async function ensureRemoteSkillSource(uri) {
+    if (!isHttpSourceUri(uri)) {
+        throw new Error(`Unsupported remote skill source ${uri}`);
+    }
+    const response = await fetch(uri);
+    if (!response.ok) {
+        throw new Error(`Remote skill source ${uri} returned ${response.status}`);
+    }
+    const document = await response.text();
+    const skillName = sanitizeSkillDirName(parseSkillFrontmatterName(document)
+        ?? path.basename(new URL(uri).pathname).replace(/\.md$/i, "")
+        ?? "remote-skill");
+    const cacheRoot = remoteSkillCacheRoot(uri);
+    const skillRoot = path.join(cacheRoot, skillName);
+    await mkdir(skillRoot, { recursive: true });
+    await writeFile(path.join(skillRoot, "SKILL.md"), document, "utf8");
+    return skillRoot;
+}

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

@@ -44,6 +44,10 @@ export type RuntimeStorageRoots = {
 };
 export declare function getRuntimeStorageRoots(refs: Map<string, WorkspaceObject | ParsedAgentObject>, workspaceRoot: string): RuntimeStorageRoots;
 export declare function getRuntimeResources(refs: Map<string, WorkspaceObject | ParsedAgentObject>): string[];
+export declare function getRuntimeSources(refs: Map<string, WorkspaceObject | ParsedAgentObject>): {
+    tools: string[];
+    skills: 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 getProceduralMemoryDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;

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

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { readRuntimeSources } from "./source-protocols.js";
 function getRoutingObject(refs) {
     const runtimeDefaults = getRuntimeDefaults(refs);
     return typeof runtimeDefaults?.routing === "object" && runtimeDefaults.routing
@@ -60,6 +61,9 @@ export function getRuntimeResources(refs) {
         .filter((value) => typeof value === "string" && value.trim().length > 0)
         .map((value) => value.trim());
 }
+export function getRuntimeSources(refs) {
+    return readRuntimeSources(getRuntimeDefaults(refs));
+}
 export function getToolModuleDiscoveryConfig(refs) {
     const runtimeDefaults = getRuntimeDefaults(refs);
     const toolModuleDiscovery = typeof runtimeDefaults?.toolModuleDiscovery === "object" && runtimeDefaults.toolModuleDiscovery

package/package.json

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