@botbotgo/agent-harness 0.0.306 → 0.0.308

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/resources/prompts/runtime/procedural-memory-manager.md

@@ -0,0 +1,40 @@
+You are deciding whether a completed run should produce reusable procedural memory.
+
+Focus areas:
+{{focus}}
+
+Session:
+{{sessionId}}
+
+Request:
+{{requestId}}
+
+Candidate:
+{{candidateJson}}
+
+Existing procedural memory:
+{{existingRecords}}
+
+Return exactly one JSON object.
+
+Rules:
+- Store only reusable experience, tactics, workflows, debugging lessons, or failure-prevention guidance.
+- Ignore pure personal facts, profile facts, location changes, and one-off durable knowledge facts unless they imply a reusable procedure.
+- Prefer concise, imperative procedural guidance that can help a future run act better.
+- Avoid duplicating existing procedural memory.
+- Default kind must be "procedural".
+- Use scope "workspace" for repo/workspace habits, "project" for broader project rules, "agent" for agent-specific operating habits, and "user" only when the reusable procedure is clearly personal to the user.
+
+If there is no reusable procedural lesson, return:
+{"store":false}
+
+If there is a reusable lesson, return:
+{
+  "store": true,
+  "summary": "short summary",
+  "content": "clear reusable procedure or lesson",
+  "kind": "procedural",
+  "scope": "workspace",
+  "tags": ["workflow_patterns"],
+  "confidence": 0.78
+}

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/runtime/harness.d.ts

@@ -36,6 +36,12 @@ export declare class AgentHarnessRuntime {
     private readonly knowledgeModule;
     private readonly runtimeMemoryFormationSync;
     private readonly unregisterRuntimeMemoryFormationSync;
+    private readonly proceduralMemoryConfig;
+    private readonly proceduralMemoryStore;
+    private readonly proceduralMemoryManager;
+    private readonly proceduralMemoryModule;
+    private readonly proceduralMemoryFormationSync;
+    private readonly unregisterProceduralMemoryFormationSync;
     private readonly resolvedRuntimeAdapterOptions;
     private readonly scheduleManager;
     private readonly healthMonitor;

package/dist/runtime/harness.js

@@ -35,7 +35,7 @@ import { Mem0IngestionSync, Mem0SemanticRecall, readMem0RuntimeConfig, } from ".
 import { createRuntimeMemoryManager, RuntimeMemoryFormationSync, readRuntimeMemoryFormationConfig, } from "./harness/system/runtime-memory-manager.js";
 import { readRuntimeMemoryMaintenanceConfig, readRuntimeMemoryPolicyConfig, resolveMemoryNamespace, } from "./harness/system/runtime-memory-policy.js";
 import { resolveRuntimeAdapterOptions } from "./support/runtime-adapter-options.js";
-import { resolveKnowledgeStorePath } from "./support/runtime-layout.js";
+import { resolveKnowledgeStorePath, resolveProceduralMemoryStorePath } from "./support/runtime-layout.js";
 import { SystemScheduleManager } from "./scheduling/system-schedule-manager.js";
 import { initializeHarnessRuntime, reclaimExpiredClaimedRequests as reclaimHarnessExpiredClaimedRequests, recoverStartupRequests as recoverHarnessStartupRequests, isStaleRunningRequest as isHarnessStaleRunningRequest, } from "./harness/run/startup-runtime.js";
 import { traceStartupStage } from "./startup-tracing.js";
@@ -44,6 +44,7 @@ import { streamHarnessRun } from "./harness/run/stream-run.js";
 import { defaultRequestedAgentId, prepareRunStart } from "./harness/run/start-run.js";
 import { buildRequestInspectionRecord, buildSessionInspectionRecord, deleteSessionRecord, getPublicApproval, listPublicApprovals, } from "./harness/run/session-records.js";
 import { createKnowledgeModule } from "../knowledge/index.js";
+import { createProceduralMemoryManager, ProceduralMemoryFormationSync, readProceduralMemoryRuntimeConfig, } from "../procedural/index.js";
 const ACTIVE_REQUEST_STATES = [
     "queued",
     "claimed",
@@ -132,6 +133,17 @@ function toPublicHarnessStreamItem(item) {
             return item;
     }
 }
+function mergeMemoryItems(...groups) {
+    const merged = new Map();
+    for (const group of groups) {
+        for (const item of group) {
+            if (!merged.has(item.id)) {
+                merged.set(item.id, item);
+            }
+        }
+    }
+    return Array.from(merged.values());
+}
 function normalizeSessionListText(content, limit) {
     if (!content) {
         return undefined;
@@ -216,6 +228,12 @@ export class AgentHarnessRuntime {
     knowledgeModule;
     runtimeMemoryFormationSync;
     unregisterRuntimeMemoryFormationSync;
+    proceduralMemoryConfig;
+    proceduralMemoryStore;
+    proceduralMemoryManager;
+    proceduralMemoryModule;
+    proceduralMemoryFormationSync;
+    unregisterProceduralMemoryFormationSync;
     resolvedRuntimeAdapterOptions;
     scheduleManager;
     healthMonitor;
@@ -461,6 +479,82 @@ export class AgentHarnessRuntime {
             this.runtimeMemoryFormationSync = null;
             this.unregisterRuntimeMemoryFormationSync = () => { };
         }
+        const proceduralMemoryConfig = readProceduralMemoryRuntimeConfig(this.defaultRuntimeEntryBinding?.harnessRuntime.proceduralMemory);
+        this.proceduralMemoryConfig = proceduralMemoryConfig?.enabled ? proceduralMemoryConfig : null;
+        const proceduralStoreConfig = this.proceduralMemoryConfig?.store && Object.keys(this.proceduralMemoryConfig.store).length > 0
+            ? this.proceduralMemoryConfig.store
+            : {
+                kind: "SqliteStore",
+                path: resolveProceduralMemoryStorePath(runtimeRoot),
+            };
+        this.proceduralMemoryStore = this.proceduralMemoryConfig
+            ? resolveStoreFromConfig(this.stores, proceduralStoreConfig, runtimeRoot) ?? null
+            : null;
+        this.proceduralMemoryManager =
+            this.defaultRuntimeEntryBinding && this.proceduralMemoryConfig
+                ? createProceduralMemoryManager({
+                    workspace: this.workspace,
+                    binding: this.defaultRuntimeEntryBinding,
+                    config: this.proceduralMemoryConfig,
+                    modelResolver: this.resolvedRuntimeAdapterOptions.modelResolver,
+                })
+                : null;
+        this.proceduralMemoryModule =
+            this.proceduralMemoryConfig && this.proceduralMemoryStore
+                ? createKnowledgeModule({
+                    store: this.proceduralMemoryStore,
+                    policy: null,
+                    maintenanceConfig: null,
+                    resolveNamespace: (scope, context) => {
+                        const binding = this.defaultRuntimeEntryBinding;
+                        if (!binding) {
+                            const identifier = scope === "session"
+                                ? context.sessionId
+                                : scope === "agent"
+                                    ? context.agentId
+                                    : scope === "workspace"
+                                        ? context.workspaceId
+                                        : scope === "user"
+                                            ? context.userId ?? "default"
+                                            : context.projectId ?? context.workspaceId;
+                            return ["procedural", `${scope}s`, identifier ?? "default"];
+                        }
+                        return this.resolveMemoryNamespace(scope, binding, {
+                            sessionId: context.sessionId,
+                            agentId: context.agentId,
+                            userId: context.userId,
+                            projectId: context.projectId,
+                        });
+                    },
+                    resolveVectorStore: async () => null,
+                    transformCandidates: this.proceduralMemoryManager && this.defaultRuntimeEntryBinding
+                        ? ({ candidates, context, existingRecords }) => this.proceduralMemoryManager.transform({
+                            candidates,
+                            binding: this.defaultRuntimeEntryBinding,
+                            sessionId: context.sessionId ?? `procedural-api-${context.requestId ?? "unknown"}`,
+                            requestId: context.requestId ?? createPersistentId(new Date(context.recordedAt ?? new Date().toISOString())),
+                            recordedAt: context.recordedAt ?? new Date().toISOString(),
+                            existingRecords,
+                        })
+                        : undefined,
+                })
+                : null;
+        if (this.proceduralMemoryConfig && this.proceduralMemoryModule) {
+            this.proceduralMemoryFormationSync = new ProceduralMemoryFormationSync(this.persistence, this.proceduralMemoryConfig, (input) => this.proceduralMemoryModule.memorizeCandidates(input.candidates, {
+                sessionId: input.sessionId,
+                requestId: input.requestId,
+                agentId: input.agentId,
+                workspaceId: this.getWorkspaceId(this.defaultRuntimeEntryBinding),
+                userId: input.userId,
+                projectId: input.projectId,
+                recordedAt: input.recordedAt,
+            }, { storeCandidateLog: false }).then(() => undefined), runtimeRoot);
+            this.unregisterProceduralMemoryFormationSync = this.eventBus.registerProjection(this.proceduralMemoryFormationSync);
+        }
+        else {
+            this.proceduralMemoryFormationSync = null;
+            this.unregisterProceduralMemoryFormationSync = () => { };
+        }
         this.recoveryConfig = getRecoveryConfig(workspace.refs);
         this.concurrencyConfig = getConcurrencyConfig(workspace.refs);
         const healthConfig = readHealthMonitorConfig(workspace);
@@ -514,6 +608,9 @@ export class AgentHarnessRuntime {
             scheduleBackgroundTask: (task) => this.scheduleBackgroundStartupTask(task),
         });
         this.scheduleBackgroundStartupTask(traceStartupStage("runtime.initialize.startupRecovery", () => this.recoverStartupRequests()));
+        if (this.proceduralMemoryStore) {
+            await this.proceduralMemoryStore.listNamespaces();
+        }
         this.initialized = true;
     }
     subscribe(listener) {
@@ -604,26 +701,44 @@ export class AgentHarnessRuntime {
         if (!binding) {
             throw new Error("recall requires a runtime entry binding.");
         }
-        return this.knowledgeModule.recall(input, {
+        const context = {
             sessionId: input.sessionId,
             agentId: input.agentId ?? binding.agent.id,
             workspaceId: input.workspaceId ?? this.getWorkspaceId(binding),
             userId: input.userId,
             projectId: input.projectId,
-        });
+        };
+        const [knowledge, procedural] = await Promise.all([
+            this.knowledgeModule.recall(input, context),
+            this.proceduralMemoryModule && this.proceduralMemoryConfig?.retrieval?.enabled !== false
+                ? this.proceduralMemoryModule.recall(input, context)
+                : Promise.resolve({ items: [] }),
+        ]);
+        return {
+            items: mergeMemoryItems(knowledge.items, procedural.items),
+        };
     }
     async listMemories(input = {}) {
         const binding = this.defaultRuntimeEntryBinding;
         if (!binding) {
             throw new Error("listMemories requires a runtime entry binding.");
         }
-        return this.knowledgeModule.list(input, {
+        const context = {
             sessionId: input.sessionId,
             agentId: input.agentId,
             workspaceId: input.workspaceId ?? this.getWorkspaceId(binding),
             userId: input.userId,
             projectId: input.projectId,
-        });
+        };
+        const [knowledge, procedural] = await Promise.all([
+            this.knowledgeModule.list(input, context),
+            this.proceduralMemoryModule
+                ? this.proceduralMemoryModule.list(input, context)
+                : Promise.resolve({ items: [] }),
+        ]);
+        return {
+            items: mergeMemoryItems(knowledge.items, procedural.items),
+        };
     }
     async updateMemory(input) {
         const binding = this.defaultRuntimeEntryBinding;
@@ -1029,27 +1144,40 @@ export class AgentHarnessRuntime {
         return path.basename(workspaceRoot) || "default";
     }
     async buildRuntimeMemoryContext(binding, sessionId, input) {
-        if (!this.runtimeMemoryPolicy) {
+        if (!this.runtimeMemoryPolicy && !this.proceduralMemoryModule) {
             return undefined;
         }
         const query = extractMessageText(input ?? "").trim();
         if (!query) {
             return undefined;
         }
-        const promptRecall = await this.knowledgeModule.buildPromptRecall({
-            query,
-            topK: this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? 8,
-        }, {
+        const context = {
             sessionId,
             agentId: binding.agent.id,
             workspaceId: this.getWorkspaceId(binding),
-        });
-        if (!promptRecall.context?.trim()) {
+        };
+        const proceduralTopK = this.proceduralMemoryConfig?.retrieval?.maxPromptItems ?? 4;
+        const [knowledgeRecall, proceduralRecall] = await Promise.all([
+            this.runtimeMemoryPolicy
+                ? this.knowledgeModule.buildPromptRecall({
+                    query,
+                    topK: this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? 8,
+                }, context)
+                : Promise.resolve({ items: [], context: undefined }),
+            this.proceduralMemoryModule && this.proceduralMemoryConfig?.retrieval?.enabled !== false
+                ? this.proceduralMemoryModule.buildPromptRecall({
+                    query,
+                    topK: proceduralTopK,
+                }, context)
+                : Promise.resolve({ items: [], context: undefined }),
+        ]);
+        const promptParts = [knowledgeRecall.context?.trim(), proceduralRecall.context?.trim()].filter((value) => !!value);
+        if (promptParts.length === 0) {
             return undefined;
         }
         return {
-            prompt: promptRecall.context,
-            items: promptRecall.items,
+            prompt: promptParts.join("\n\n"),
+            items: mergeMemoryItems(knowledgeRecall.items, proceduralRecall.items),
         };
     }
     async persistRuntimeMemoryCandidates(binding, sessionId, requestId, value) {
@@ -1374,11 +1502,13 @@ export class AgentHarnessRuntime {
         this.unregisterRuntimeMemorySync();
         this.unregisterMem0IngestionSync();
         this.unregisterRuntimeMemoryFormationSync();
+        this.unregisterProceduralMemoryFormationSync();
         await Promise.allSettled(Array.from(this.backgroundTasks));
         await this.sessionMemorySync?.close();
         await this.runtimeMemorySync?.close();
         await this.mem0IngestionSync?.close();
         await this.runtimeMemoryFormationSync?.close();
+        await this.proceduralMemoryFormationSync?.close();
         await closeMcpClientsForWorkspace(this.workspace);
         this.initialized = false;
     }

package/dist/runtime/support/runtime-prompts.d.ts

@@ -28,3 +28,10 @@ export declare function renderRuntimeMemoryMutationReconciliationPrompt(input: {
     candidate: MemoryCandidate;
     existingRecords: MemoryRecord[];
 }): string;
+export declare function renderProceduralMemoryManagerPrompt(input: {
+    candidate: MemoryCandidate;
+    sessionId: string;
+    requestId: string;
+    focus: string[];
+    existingRecords: MemoryRecord[];
+}): string;

package/dist/runtime/support/runtime-prompts.js

@@ -53,3 +53,17 @@ export function renderRuntimeMemoryMutationReconciliationPrompt(input) {
         existingRecords: existing,
     });
 }
+export function renderProceduralMemoryManagerPrompt(input) {
+    const existing = input.existingRecords.length === 0
+        ? "(none)"
+        : input.existingRecords
+            .map((record) => `- scope=${record.scope}; kind=${record.kind}; status=${record.status}; summary=${record.summary}; content=${record.content.replace(/\s+/g, " ").slice(0, 220)}`)
+            .join("\n");
+    return renderBundledTemplate("prompts/runtime/procedural-memory-manager.md", {
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        focus: input.focus.join(", "),
+        candidateJson: JSON.stringify(input.candidate, null, 2),
+        existingRecords: existing,
+    });
+}

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);