@botbotgo/agent-harness 0.0.8 → 0.0.9

package/dist/config/orchestra.yaml

@@ -39,7 +39,7 @@ spec:
     path: store.json
   # DeepAgents aligned feature: backend config passed into `createDeepAgent({ backend })`.
   # This directly defines the backend topology for this agent:
-  # - runtime graph state uses `StateBackend`
+  # - workspace execution uses a lightweight VFS sandbox
   # - long-term memory under `/memories/*` uses `StoreBackend`
   # - `CompositeBackend` composes those backend instances together
   # The harness also injects a persistent file-backed store and a file-backed checkpointer so that
@@ -48,11 +48,9 @@ spec:
   backend:
     kind: CompositeBackend
     state:
-      # Available state backend `kind` options today: `StateBackend`, `LocalShellBackend`.
-      kind: LocalShellBackend
-      inheritEnv: true
+      # Available state backend `kind` options today: `StateBackend`, `LocalShellBackend`, `VfsSandbox`.
+      kind: VfsSandbox
       timeout: 600
-      maxOutputBytes: 200000
     routes:
       /memories/:
         # Available route backend `kind` options today: `StoreBackend`.

package/dist/contracts/types.d.ts

@@ -57,6 +57,7 @@ export type ParsedToolObject = {
     type: string;
     name: string;
     description: string;
+    implementationName?: string;
     config?: Record<string, unknown>;
     inputSchemaRef?: string;
     backendOperation?: string;
@@ -158,7 +159,8 @@ export type CompiledAgentBinding = {
 };
 export type WorkspaceBundle = {
     workspaceRoot: string;
-    builtinSources: string[];
+    resourceSources: string[];
+    builtinSources?: string[];
     refs: Map<string, WorkspaceObject | ParsedAgentObject>;
     models: Map<string, ParsedModelObject>;
     embeddings: Map<string, ParsedEmbeddingModelObject>;
@@ -169,6 +171,7 @@ export type WorkspaceBundle = {
 };
 export type WorkspaceLoadOptions = {
     overlayRoots?: string[];
+    resourceSources?: string[];
     builtinSources?: string[];
 };
 export type ThreadSummary = {

package/dist/extensions.js

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { builtinSkillsRoot } from "./vendor/builtins.js";
-import { isExternalSourceLocator, resolveExternalSourcePath } from "./vendor/sources.js";
+import { defaultResourceSkillsRoot } from "./resource/resource.js";
+import { isExternalSourceLocator, resolveExternalResourcePath } from "./resource/sources.js";
 const toolKindAdapters = new Map();
 const skillSourceResolvers = new Map();
 const skillInheritancePolicies = new Map();
@@ -217,7 +217,7 @@ registerSkillSourceResolver({
         }
         const candidate = String(skill.sourcePathRef);
         if (isExternalSourceLocator(candidate)) {
-            return [resolveExternalSourcePath(candidate, workspaceRoot)];
+            return [resolveExternalResourcePath(candidate, workspaceRoot)];
         }
         return [candidate.startsWith("/") ? candidate : `${workspaceRoot}/${candidate}`];
     },
@@ -225,7 +225,7 @@ registerSkillSourceResolver({
 registerSkillSourceResolver({
     kind: "builtin",
     resolve({ skill }) {
-        return [path.join(builtinSkillsRoot(), skill.sourcePathRef)];
+        return [path.join(defaultResourceSkillsRoot(), skill.sourcePathRef)];
     },
 });
 registerSkillInheritancePolicy({
@@ -244,7 +244,7 @@ registerSkillPackagingConvention({
     resolve({ workspaceRoot, skill }) {
         const candidate = String(skill.sourcePathRef);
         if (isExternalSourceLocator(candidate)) {
-            return [resolveExternalSourcePath(candidate, workspaceRoot)];
+            return [resolveExternalResourcePath(candidate, workspaceRoot)];
         }
         return [candidate.startsWith("/") ? candidate : `${workspaceRoot}/${candidate}`];
     },

package/dist/resource/builtins.d.ts

@@ -0,0 +1 @@
+export { builtinConfigRoot, builtinSkillsRoot, createBuiltinBackendResolver, createBuiltinToolResolver, ensureBuiltinSources, listBuiltinTools, listBuiltinToolsForSource, resolveLocalBuiltinsEntry, } from "./resource.js";

package/dist/resource/builtins.js

@@ -0,0 +1 @@
+export { builtinConfigRoot, builtinSkillsRoot, createBuiltinBackendResolver, createBuiltinToolResolver, ensureBuiltinSources, listBuiltinTools, listBuiltinToolsForSource, resolveLocalBuiltinsEntry, } from "./resource.js";

package/dist/resource/resource-impl.d.ts

@@ -0,0 +1,30 @@
+import type { RuntimeAdapterOptions, WorkspaceBundle } from "../contracts/types.js";
+export declare function resolveLocalBuiltinsEntry(currentResourceDir: string, resolveInstalledEntry?: () => string | null): string;
+export type ResourceToolInfo = {
+    toolPath: string;
+    backendOperation: string;
+    name: string;
+    description: string;
+    hitl?: {
+        enabled: boolean;
+        allow: Array<"approve" | "edit" | "reject">;
+    };
+};
+export declare function ensureResourceSources(sources?: string[], workspaceRoot?: string): Promise<void>;
+export declare function defaultResourceSkillsRoot(): string;
+export declare function defaultResourceConfigRoot(): string;
+export declare function listResourceTools(sources?: string[], workspaceRoot?: string): Promise<ResourceToolInfo[]>;
+export declare function listResourceToolsForSource(source: string, workspaceRoot?: string): Promise<ResourceToolInfo[]>;
+export declare function createResourceBackendResolver(workspace: WorkspaceBundle): NonNullable<RuntimeAdapterOptions["backendResolver"]>;
+export declare function createResourceToolResolver(workspace: WorkspaceBundle, options?: {
+    getStore?: (_binding?: WorkspaceBundle["bindings"] extends Map<any, infer T> ? T : never) => unknown;
+    getEmbeddingModel?: (embeddingModelRef?: string, _binding?: WorkspaceBundle["bindings"] extends Map<any, infer T> ? T : never) => Promise<unknown>;
+    getVectorStore?: (vectorStoreRef?: string, _binding?: WorkspaceBundle["bindings"] extends Map<any, infer T> ? T : never) => Promise<unknown>;
+}): NonNullable<RuntimeAdapterOptions["toolResolver"]>;
+export declare const ensureBuiltinSources: typeof ensureResourceSources;
+export declare const builtinSkillsRoot: typeof defaultResourceSkillsRoot;
+export declare const builtinConfigRoot: typeof defaultResourceConfigRoot;
+export declare const listBuiltinTools: typeof listResourceTools;
+export declare const listBuiltinToolsForSource: typeof listResourceToolsForSource;
+export declare const createBuiltinBackendResolver: typeof createResourceBackendResolver;
+export declare const createBuiltinToolResolver: typeof createResourceToolResolver;

package/dist/resource/resource-impl.js

@@ -0,0 +1,250 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { stat } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ensureExternalResourceSource, ensureExternalSource, isExternalSourceLocator, parseExternalSourceLocator } from "./sources.js";
+const resourceDir = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+function installedBuiltinsEntry() {
+    try {
+        return require.resolve("@botbotgo/agent-harness-builtin");
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveLocalBuiltinsEntry(currentResourceDir, resolveInstalledEntry = installedBuiltinsEntry) {
+    const candidates = [
+        path.resolve(currentResourceDir, "../../../builtins/dist/src/index.js"),
+        path.resolve(currentResourceDir, "../../../agent-harness/packages/builtins/dist/src/index.js"),
+        path.resolve(currentResourceDir, "../../../builtins/src/index.ts"),
+        path.resolve(currentResourceDir, "../../../agent-harness/packages/builtins/src/index.ts"),
+        resolveInstalledEntry(),
+    ].filter((candidate) => typeof candidate === "string" && candidate.length > 0);
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates.at(-1) ?? path.resolve(currentResourceDir, "../../../agent-harness/packages/builtins/dist/src/index.js");
+}
+const builtinsEntry = resolveLocalBuiltinsEntry(resourceDir);
+async function loadLocalResource(entry) {
+    if (!existsSync(entry)) {
+        return null;
+    }
+    const imported = await import(pathToFileURL(entry).href);
+    return (imported.default ?? imported);
+}
+const localResource = await loadLocalResource(builtinsEntry);
+function listProviderTools(provider) {
+    const rawTools = provider?.listResourceTools?.() ?? provider?.listBuiltinTools?.() ?? [];
+    return rawTools.map((tool) => ({
+        ...tool,
+        toolPath: tool.toolPath ?? tool.builtinPath ?? "",
+    }));
+}
+function createProviderToolResolver(provider, workspace, options) {
+    return (provider?.createResourceToolResolver?.(workspace, options) ??
+        provider?.createBuiltinToolResolver?.(workspace, options));
+}
+function createProviderBackendResolver(provider, workspace) {
+    return (provider?.createResourceBackendResolver?.(workspace) ??
+        provider?.createBuiltinBackendResolver?.(workspace));
+}
+function requireLocalResource(feature) {
+    if (localResource) {
+        return localResource;
+    }
+    throw new Error(`agent-harness optional tool bundle support is unavailable for ${feature}. Install the matching provider package or provide a local sibling checkout.`);
+}
+const remoteResourceCache = new Map();
+async function findPackageRoot(startPath) {
+    let current = path.dirname(startPath);
+    for (;;) {
+        try {
+            await stat(path.join(current, "package.json"));
+            return current;
+        }
+        catch { }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.dirname(startPath);
+        }
+        current = parent;
+    }
+}
+const functionToolModuleCache = new Map();
+async function loadFunctionToolModule(tool) {
+    const cacheKey = `${tool.sourcePath}:${tool.implementationName ?? tool.id}`;
+    const cached = functionToolModuleCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const loading = (async () => {
+        const imported = await import(pathToFileURL(tool.sourcePath).href);
+        const implementationName = tool.implementationName ?? tool.id;
+        const invoke = imported[implementationName];
+        const schema = imported[`${implementationName}Schema`];
+        if (typeof invoke !== "function") {
+            throw new Error(`Tool module ${tool.sourcePath} must export function ${implementationName}.`);
+        }
+        if (!schema?.parse) {
+            throw new Error(`Tool module ${tool.sourcePath} must export ${implementationName}Schema as a Zod schema.`);
+        }
+        return { invoke, schema };
+    })();
+    functionToolModuleCache.set(cacheKey, loading);
+    return loading;
+}
+function createFunctionToolResolver(workspace) {
+    const functionTools = new Map(Array.from(workspace.tools.values())
+        .filter((tool) => tool.type === "function" && tool.sourcePath.endsWith(".mjs"))
+        .map((tool) => [tool.id, tool]));
+    return (toolIds) => toolIds.flatMap((toolId) => {
+        const tool = functionTools.get(toolId);
+        if (!tool) {
+            return [];
+        }
+        return [
+            {
+                name: tool.name,
+                description: tool.description,
+                async invoke(input) {
+                    const loaded = await loadFunctionToolModule(tool);
+                    const parsedInput = loaded.schema.parse(input ?? {});
+                    const toolPackageRoot = await findPackageRoot(tool.sourcePath);
+                    return loaded.invoke(parsedInput, {
+                        appRoot: workspace.workspaceRoot,
+                        toolId: tool.id,
+                        toolPath: tool.sourcePath,
+                        toolPackageRoot,
+                    });
+                },
+            },
+        ];
+    });
+}
+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");
+}
+async function loadRemoteResource(source, workspaceRoot) {
+    const cached = remoteResourceCache.get(source);
+    if (cached !== undefined) {
+        return cached;
+    }
+    if (!isExternalSourceLocator(source)) {
+        throw new Error(`Unsupported resource source ${source}. Use npm:, tgz:, or file:.`);
+    }
+    const parsed = parseExternalSourceLocator(source);
+    if (parsed.subpath) {
+        throw new Error(`Resource source ${source} must point at a package root, not a subpath`);
+    }
+    await ensureExternalResourceSource(source, workspaceRoot);
+    const packageRoot = await ensureExternalSource(source, workspaceRoot);
+    const pkg = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+    const entry = resolvePackageEntry(packageRoot, pkg);
+    if (!existsSync(entry)) {
+        remoteResourceCache.set(source, null);
+        return null;
+    }
+    const imported = await import(pathToFileURL(entry).href);
+    const provider = (imported.default ?? imported);
+    if (listProviderTools(provider).length === 0 &&
+        !provider.listResourceTools &&
+        !provider.listBuiltinTools) {
+        remoteResourceCache.set(source, null);
+        return null;
+    }
+    if (!provider.createResourceToolResolver && !provider.createBuiltinToolResolver) {
+        remoteResourceCache.set(source, null);
+        return null;
+    }
+    const typedProvider = provider;
+    remoteResourceCache.set(source, typedProvider);
+    return typedProvider;
+}
+export async function ensureResourceSources(sources = [], workspaceRoot = process.cwd()) {
+    await Promise.all(sources.map((source) => loadRemoteResource(source, workspaceRoot)));
+}
+export function defaultResourceSkillsRoot() {
+    const provider = requireLocalResource("default resource skill resolution");
+    return provider.defaultResourceSkillsRoot?.() ?? provider.builtinSkillsRoot?.() ?? "";
+}
+export function defaultResourceConfigRoot() {
+    const provider = requireLocalResource("default resource config resolution");
+    return provider.defaultResourceConfigRoot?.() ?? provider.builtinConfigRoot?.() ?? provider.builtinDefaultsRoot?.() ?? "";
+}
+export async function listResourceTools(sources = [], workspaceRoot = process.cwd()) {
+    await ensureResourceSources(sources, workspaceRoot);
+    const deduped = new Map();
+    for (const tool of listProviderTools(localResource)) {
+        deduped.set(tool.toolPath, tool);
+    }
+    for (const source of sources) {
+        for (const tool of listProviderTools(remoteResourceCache.get(source) ?? undefined)) {
+            deduped.set(tool.toolPath, tool);
+        }
+    }
+    return Array.from(deduped.values());
+}
+export async function listResourceToolsForSource(source, workspaceRoot = process.cwd()) {
+    await ensureResourceSources([source], workspaceRoot);
+    return listProviderTools(remoteResourceCache.get(source) ?? undefined);
+}
+export function createResourceBackendResolver(workspace) {
+    const localResolver = createProviderBackendResolver(localResource, workspace);
+    return (binding) => localResolver?.(binding) ?? [];
+}
+export function createResourceToolResolver(workspace, options = {}) {
+    const functionResolver = createFunctionToolResolver(workspace);
+    const localResolver = createProviderToolResolver(localResource, workspace, options);
+    const remoteResolvers = (workspace.resourceSources ?? workspace.builtinSources ?? [])
+        .map((source) => remoteResourceCache.get(source))
+        .filter((provider) => Boolean(provider))
+        .map((provider) => createProviderToolResolver(provider, workspace, options))
+        .filter((resolver) => Boolean(resolver));
+    return (toolIds, binding) => {
+        const resolved = [
+            ...functionResolver(toolIds, binding),
+            ...(localResolver?.(toolIds, binding) ?? []),
+            ...remoteResolvers.flatMap((resolver) => resolver(toolIds, binding)),
+        ];
+        const deduped = new Map();
+        for (const tool of resolved) {
+            deduped.set(String(tool.name), tool);
+        }
+        return Array.from(deduped.values());
+    };
+}
+export const ensureBuiltinSources = ensureResourceSources;
+export const builtinSkillsRoot = defaultResourceSkillsRoot;
+export const builtinConfigRoot = defaultResourceConfigRoot;
+export const listBuiltinTools = listResourceTools;
+export const listBuiltinToolsForSource = listResourceToolsForSource;
+export const createBuiltinBackendResolver = createResourceBackendResolver;
+export const createBuiltinToolResolver = createResourceToolResolver;

package/dist/resource/resource.d.ts

@@ -0,0 +1 @@
+export { type ResourceToolInfo, ensureResourceSources, defaultResourceSkillsRoot, defaultResourceConfigRoot, listResourceTools, listResourceToolsForSource, createResourceBackendResolver, createResourceToolResolver, ensureBuiltinSources, builtinSkillsRoot, builtinConfigRoot, listBuiltinTools, listBuiltinToolsForSource, createBuiltinBackendResolver, createBuiltinToolResolver, resolveLocalBuiltinsEntry, } from "./resource-impl.js";

package/dist/resource/resource.js

@@ -0,0 +1 @@
+export { ensureResourceSources, defaultResourceSkillsRoot, defaultResourceConfigRoot, listResourceTools, listResourceToolsForSource, createResourceBackendResolver, createResourceToolResolver, ensureBuiltinSources, builtinSkillsRoot, builtinConfigRoot, listBuiltinTools, listBuiltinToolsForSource, createBuiltinBackendResolver, createBuiltinToolResolver, resolveLocalBuiltinsEntry, } from "./resource-impl.js";

package/dist/{vendor → resource}/sources.d.ts

@@ -3,10 +3,13 @@ type ParsedLocator = {
     spec: string;
     subpath?: string;
 };
+export declare function resolveResourcePackageRoot(root: string): string | null;
 export declare function isExternalSourceLocator(value: unknown): boolean;
 export declare function parseExternalSourceLocator(locator: string): ParsedLocator;
 export declare function ensureExternalSource(locator: string, workspaceRoot: string): Promise<string>;
+export declare function ensureExternalResourceSource(locator: string, workspaceRoot: string): Promise<string>;
 export declare function ensureExternalSources(locators: string[], workspaceRoot: string): Promise<void>;
 export declare function resolveExternalSourcePath(locator: string, workspaceRoot: string): string;
+export declare function resolveExternalResourcePath(locator: string, workspaceRoot: string): string;
 export declare function isDirectoryPath(candidate: string): boolean;
 export {};

package/dist/{vendor → resource}/sources.js

@@ -14,6 +14,23 @@ function sourceCacheDir(locator) {
     const digest = createHash("sha256").update(locator).digest("hex").slice(0, 16);
     return path.join(cacheRoot(), digest);
 }
+export function resolveResourcePackageRoot(root) {
+    const candidates = path.basename(root) === "resources" ? [root] : [path.join(root, "resources")];
+    for (const candidate of candidates) {
+        if (!existsSync(candidate)) {
+            continue;
+        }
+        if (!statSync(candidate).isDirectory()) {
+            continue;
+        }
+        const packageJsonPath = path.join(candidate, "package.json");
+        if (!existsSync(packageJsonPath)) {
+            throw new Error(`Resource package ${candidate} is missing package.json.`);
+        }
+        return candidate;
+    }
+    return null;
+}
 export function isExternalSourceLocator(value) {
     return typeof value === "string" && /^(npm|tgz|file):/.test(value);
 }
@@ -91,6 +108,24 @@ export async function ensureExternalSource(locator, workspaceRoot) {
     sourceCache.set(cacheKey, basePath);
     return parsed.subpath ? path.join(basePath, parsed.subpath) : basePath;
 }
+export async function ensureExternalResourceSource(locator, workspaceRoot) {
+    const parsed = parseExternalSourceLocator(locator);
+    const baseLocator = `${parsed.kind}:${parsed.spec}`;
+    const packageRoot = await ensureExternalSource(baseLocator, workspaceRoot);
+    const resourcesRoot = path.join(packageRoot, "resources");
+    if (!existsSync(resourcesRoot) || !statSync(resourcesRoot).isDirectory()) {
+        throw new Error(`External source ${baseLocator} is missing resources/.`);
+    }
+    const resourcePackageJson = path.join(resourcesRoot, "package.json");
+    if (!existsSync(resourcePackageJson)) {
+        throw new Error(`External source ${baseLocator} is missing resources/package.json.`);
+    }
+    const resourcePackageRoot = resolveResourcePackageRoot(packageRoot);
+    if (!resourcePackageRoot) {
+        throw new Error(`External source ${baseLocator} is missing resources/package.json.`);
+    }
+    return parsed.subpath ? path.join(resourcePackageRoot, parsed.subpath) : resourcePackageRoot;
+}
 export async function ensureExternalSources(locators, workspaceRoot) {
     await Promise.all(Array.from(new Set(locators)).map((locator) => ensureExternalSource(locator, workspaceRoot)));
 }
@@ -110,6 +145,24 @@ export function resolveExternalSourcePath(locator, workspaceRoot) {
     }
     throw new Error(`External source ${locator} must be preloaded before synchronous resolution`);
 }
+export function resolveExternalResourcePath(locator, workspaceRoot) {
+    const parsed = parseExternalSourceLocator(locator);
+    const baseLocator = `${parsed.kind}:${parsed.spec}`;
+    const packageRoot = resolveExternalSourcePath(baseLocator, workspaceRoot);
+    const resourcesRoot = path.join(packageRoot, "resources");
+    if (!existsSync(resourcesRoot) || !statSync(resourcesRoot).isDirectory()) {
+        throw new Error(`External source ${baseLocator} is missing resources/.`);
+    }
+    const resourcePackageJson = path.join(resourcesRoot, "package.json");
+    if (!existsSync(resourcePackageJson)) {
+        throw new Error(`External source ${baseLocator} is missing resources/package.json.`);
+    }
+    const resourcePackageRoot = resolveResourcePackageRoot(packageRoot);
+    if (!resourcePackageRoot) {
+        throw new Error(`External source ${baseLocator} is missing resources/package.json.`);
+    }
+    return parsed.subpath ? path.join(resourcePackageRoot, parsed.subpath) : resourcePackageRoot;
+}
 export function isDirectoryPath(candidate) {
     return existsSync(candidate) && statSync(candidate).isDirectory();
 }

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

@@ -318,7 +318,7 @@ export class AgentRuntimeAdapter {
         if (!params) {
             throw new Error(`Agent ${binding.agent.id} has no runnable params`);
         }
-        return createDeepAgent({
+        const deepAgentConfig = {
             model: (await this.resolveModel(params.model)),
             tools: this.resolveTools(params.tools, binding),
             systemPrompt: params.systemPrompt,
@@ -331,7 +331,8 @@ export class AgentRuntimeAdapter {
             name: params.name,
             memory: params.memory,
             skills: params.skills,
-        });
+        };
+        return createDeepAgent(deepAgentConfig);
     }
     async route(input, primaryBinding, secondaryBinding, options = {}) {
         const routeModelConfig = primaryBinding.langchainAgentParams?.model ??

package/dist/runtime/file-checkpoint-saver.js

@@ -29,6 +29,21 @@ function decodeBinary(value) {
     }
     return value;
 }
+function pruneThreadEntries(record, threadId) {
+    for (const key of Object.keys(record)) {
+        if (key.includes(threadId)) {
+            delete record[key];
+            continue;
+        }
+        const value = record[key];
+        if (typeof value === "object" && value && !Array.isArray(value)) {
+            pruneThreadEntries(value, threadId);
+            if (Object.keys(value).length === 0) {
+                delete record[key];
+            }
+        }
+    }
+}
 export class FileCheckpointSaver extends MemorySaver {
     filePath;
     loaded = false;
@@ -83,9 +98,9 @@ export class FileCheckpointSaver extends MemorySaver {
     }
     async deleteThread(threadId) {
         await this.ensureLoaded();
-        const result = await super.deleteThread(threadId);
+        pruneThreadEntries(this.storage, threadId);
+        pruneThreadEntries(this.writes, threadId);
         await this.persist();
-        return result;
     }
 }
 export { FileCheckpointSaver as FileCheckpointer };

package/dist/runtime/harness.js

@@ -2,7 +2,7 @@ import { AUTO_AGENT_ID } from "../contracts/types.js";
 import { FilePersistence } from "../persistence/file-store.js";
 import { createPersistentId } from "../utils/id.js";
 import { AGENT_INTERRUPT_SENTINEL_PREFIX, AgentRuntimeAdapter } from "./agent-runtime-adapter.js";
-import { createBuiltinBackendResolver, createBuiltinToolResolver } from "../vendor/builtins.js";
+import { createResourceBackendResolver, createResourceToolResolver } from "../resource/resource.js";
 import { EventBus } from "./event-bus.js";
 import { PolicyEngine } from "./policy-engine.js";
 import { getRoutingSystemPrompt } from "../workspace/support/workspace-ref-utils.js";
@@ -115,7 +115,7 @@ export class AgentHarness {
         this.runtimeAdapter = new AgentRuntimeAdapter({
             ...runtimeAdapterOptions,
             toolResolver: runtimeAdapterOptions.toolResolver ??
-                createBuiltinToolResolver(workspace, {
+                createResourceToolResolver(workspace, {
                     getStore: (binding) => this.resolveStore(binding),
                     getEmbeddingModel: (embeddingModelRef) => this.resolveEmbeddingModel(embeddingModelRef),
                     getVectorStore: (vectorStoreRef) => this.resolveVectorStore(vectorStoreRef),
@@ -135,7 +135,7 @@ export class AgentHarness {
             storeResolver: runtimeAdapterOptions.storeResolver ??
                 ((binding) => this.resolveStore(binding)),
             backendResolver: runtimeAdapterOptions.backendResolver ??
-                ((binding) => createBuiltinBackendResolver(workspace)(binding)),
+                ((binding) => createResourceBackendResolver(workspace)(binding)),
         });
         this.routingSystemPrompt = getRoutingSystemPrompt(workspace.refs);
         this.threadMemorySync = new ThreadMemorySync(this.persistence, this.defaultStore);

package/dist/runtime/support/vector-stores.js

@@ -110,7 +110,7 @@ export async function resolveCompiledVectorStore(workspace, vectorStore, options
                 table,
                 column,
             });
-            const rows = await store.similaritySearchWithScore(query, limit);
+            const rows = (await store.similaritySearchWithScore(query, limit));
             return rows.map(([document, score]) => ({
                 pageContent: document.pageContent,
                 metadata: document.metadata,

package/dist/workspace/compile.js

@@ -1,6 +1,8 @@
-import { ensureBuiltinSources, listBuiltinTools, listBuiltinToolsForSource } from "../vendor/builtins.js";
-import { isExternalSourceLocator } from "../vendor/sources.js";
-import { loadWorkspaceObjects } from "./object-loader.js";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { ensureResourceSources, listResourceTools, listResourceToolsForSource } from "../resource/resource.js";
+import { ensureExternalResourceSource, isExternalSourceLocator } from "../resource/sources.js";
+import { loadWorkspaceObjects, readToolModuleItems } from "./object-loader.js";
 import { parseEmbeddingModelObject, parseModelObject, parseToolObject, parseVectorStoreObject, validateEmbeddingModelObject, validateModelObject, validateToolObject, validateVectorStoreObject, } from "./resource-compilers.js";
 import { validateAgent, validateTopology } from "./validate.js";
 import { compileBinding } from "./agent-binding-compiler.js";
@@ -32,34 +34,56 @@ function collectParsedResources(refs) {
     }
     return { embeddings, models, vectorStores, tools };
 }
-async function hydrateBuiltinAndExternalTools(tools, toolSourceRefs, workspaceRoot) {
+async function hydrateResourceAndExternalTools(tools, toolSourceRefs, workspaceRoot) {
     for (const source of toolSourceRefs) {
         if (isExternalSourceLocator(source)) {
-            const sourceTools = await listBuiltinToolsForSource(source, workspaceRoot);
-            if (sourceTools.length > 0) {
+            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 builtin tool bundle loaded from ${source}`,
-                    bundleRefs: sourceTools.map((tool) => tool.builtinPath),
+                    description: `External tool resource loaded from ${source}`,
+                    bundleRefs,
                     sourcePath: source,
                 });
             }
         }
     }
-    for (const builtinTool of await listBuiltinTools(toolSourceRefs, workspaceRoot)) {
-        const existing = tools.get(builtinTool.builtinPath);
-        tools.set(builtinTool.builtinPath, {
-            id: builtinTool.builtinPath,
+    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 || builtinTool.name,
-            description: existing?.description || builtinTool.description,
+            name: existing?.name || resourceTool.name,
+            description: existing?.description || resourceTool.description,
             config: existing?.config,
-            backendOperation: existing?.backendOperation ?? builtinTool.backendOperation,
+            backendOperation: existing?.backendOperation ?? resourceTool.backendOperation,
             bundleRefs: existing?.bundleRefs ?? [],
-            hitl: existing?.hitl ?? builtinTool.hitl,
-            sourcePath: existing?.sourcePath ?? builtinTool.builtinPath,
+            hitl: existing?.hitl ?? resourceTool.hitl,
+            sourcePath: existing?.sourcePath ?? resourceTool.toolPath,
         });
     }
 }
@@ -90,11 +114,12 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
     }
     const { embeddings, models, vectorStores, tools } = collectParsedResources(loaded.refs);
     const toolSourceRefs = collectToolSourceRefs(tools, loaded.agents, options);
-    await ensureBuiltinSources(toolSourceRefs, workspaceRoot);
-    await hydrateBuiltinAndExternalTools(tools, toolSourceRefs, workspaceRoot);
+    await ensureResourceSources(toolSourceRefs, workspaceRoot);
+    await hydrateResourceAndExternalTools(tools, toolSourceRefs, workspaceRoot);
     validateWorkspaceResources(embeddings, models, vectorStores, tools, loaded.agents);
     return {
         workspaceRoot,
+        resourceSources: [...toolSourceRefs],
         builtinSources: [...toolSourceRefs],
         refs: loaded.refs,
         embeddings,

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

@@ -4,6 +4,7 @@ export type WorkspaceObjects = {
     refs: RefMap;
     agents: ParsedAgentObject[];
 };
+export declare function conventionalPackageRoots(root: string, relativeDir: "tools" | "skills"): string[];
 export declare function normalizeYamlItem(item: Record<string, unknown>): Record<string, unknown>;
 export declare function parseAgentItem(item: Record<string, unknown>, sourcePath: string): ParsedAgentObject;
 export declare function readYamlItems(root: string, relativeDir?: string, options?: {
@@ -12,5 +13,9 @@ export declare function readYamlItems(root: string, relativeDir?: string, option
     item: Record<string, unknown>;
     sourcePath: string;
 }>>;
+export declare function readToolModuleItems(root: string): Promise<Array<{
+    item: Record<string, unknown>;
+    sourcePath: string;
+}>>;
 export declare function loadWorkspaceObjects(workspaceRoot: string, options?: WorkspaceLoadOptions): Promise<WorkspaceObjects>;
 export {};

package/dist/workspace/object-loader.js

@@ -1,8 +1,9 @@
 import path from "node:path";
 import { existsSync, statSync } from "node:fs";
-import { readdir } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
+import { readdir, readFile } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { parseAllDocuments } from "yaml";
+import { resolveResourcePackageRoot } from "../resource/sources.js";
 import { fileExists, listFilesRecursive, readYamlOrJson } from "../utils/fs.js";
 const ROOT_AGENT_FILENAMES = [
     "agent.yaml",
@@ -15,21 +16,51 @@ const ROOT_AGENT_FILENAMES = [
     "research.yml",
 ];
 const LEGACY_GLOBAL_AGENT_FILENAMES = ["agent.yaml", "agent.yml"];
-function frameworkConfigRoot() {
-    const resolved = fileURLToPath(new URL("../../config", import.meta.url));
-    const distSegment = `${path.sep}dist${path.sep}config`;
-    if (!resolved.includes(distSegment)) {
+const CONVENTIONAL_OBJECT_DIRECTORIES = ["tools"];
+function conventionalConfigRoot(root) {
+    if (path.basename(root) === "config" && existsSync(root) && statSync(root).isDirectory()) {
+        return root;
+    }
+    const candidate = path.join(root, "config");
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+        return candidate;
+    }
+    return null;
+}
+function conventionalDirectoryRoots(root, relativeDir) {
+    const resourceRoot = resolveResourcePackageRoot(root);
+    const configRoot = conventionalConfigRoot(root);
+    const candidates = relativeDir === "agents"
+        ? [
+            ...(configRoot ? [path.join(configRoot, "agents")] : []),
+            path.join(root, "agents"),
+        ]
+        : [
+            ...(resourceRoot ? [path.join(resourceRoot, relativeDir)] : []),
+            path.join(root, relativeDir),
+        ];
+    return Array.from(new Set(candidates));
+}
+export function conventionalPackageRoots(root, relativeDir) {
+    const resourceRoot = resolveResourcePackageRoot(root);
+    const candidates = resourceRoot ? [path.join(resourceRoot, relativeDir), resourceRoot] : [];
+    return Array.from(new Set(candidates));
+}
+function frameworkWorkspaceRoot() {
+    const resolved = fileURLToPath(new URL("../..", import.meta.url));
+    const distSegment = `${path.sep}dist`;
+    if (!resolved.endsWith(distSegment)) {
         return resolved;
     }
-    const sourceConfigRoot = resolved.replace(distSegment, `${path.sep}config`);
-    if (!existsSync(sourceConfigRoot)) {
+    const sourceRoot = resolved.slice(0, -distSegment.length);
+    if (!existsSync(sourceRoot)) {
         return resolved;
     }
     try {
-        return statSync(sourceConfigRoot).mtimeMs >= statSync(resolved).mtimeMs ? sourceConfigRoot : resolved;
+        return statSync(sourceRoot).mtimeMs >= statSync(resolved).mtimeMs ? sourceRoot : resolved;
     }
     catch {
-        return sourceConfigRoot;
+        return sourceRoot;
     }
 }
 function toArray(value) {
@@ -106,7 +137,7 @@ export function normalizeYamlItem(item) {
         ...(kind ? { kind } : {}),
     };
 }
-function normalizeCatalogItem(item) {
+function normalizeResourceItem(item) {
     if ("metadata" in item || "spec" in item || "path" in item || typeof item.name !== "string") {
         return item;
     }
@@ -215,7 +246,7 @@ async function objectItemsFromDocument(document, sourcePath) {
                 }
                 continue;
             }
-            records.push(normalizeCatalogItem(typedItem));
+            records.push(normalizeResourceItem(typedItem));
         }
         return records;
     }
@@ -292,6 +323,66 @@ async function readNamedYamlItems(root, filenames) {
     }
     return records;
 }
+function isAgentKind(kind) {
+    return kind === "deepagent" || kind === "langchain-agent";
+}
+async function readConfigAgentItems(configRoot) {
+    const records = await readYamlItems(configRoot, undefined, { 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));
+    });
+}
+function discoverAnnotatedFunctionNames(sourceText) {
+    const matches = sourceText.matchAll(/@tool[\s\S]*?export\s+(?:async\s+)?function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/g);
+    return Array.from(matches, (match) => match[1]);
+}
+export async function readToolModuleItems(root) {
+    if (!(await fileExists(root))) {
+        return [];
+    }
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".mjs"))
+        .map((entry) => path.join(root, entry.name))
+        .sort();
+    const records = [];
+    for (const filePath of files) {
+        const sourceText = await readFile(filePath, "utf8");
+        const functionNames = discoverAnnotatedFunctionNames(sourceText);
+        if (functionNames.length === 0) {
+            continue;
+        }
+        const imported = await import(pathToFileURL(filePath).href);
+        for (const functionName of functionNames) {
+            const invoke = imported[functionName];
+            const schema = imported[`${functionName}Schema`];
+            if (typeof invoke !== "function") {
+                throw new Error(`Tool module ${filePath} must export function ${functionName}.`);
+            }
+            if (!schema?.parse) {
+                throw new Error(`Tool module ${filePath} must export ${functionName}Schema as a Zod schema.`);
+            }
+            records.push({
+                item: {
+                    kind: "tool",
+                    id: functionName,
+                    type: "function",
+                    name: functionName,
+                    description: typeof schema.description === "string" ? schema.description : `Auto-discovered tool ${functionName}`,
+                    implementationName: functionName,
+                },
+                sourcePath: filePath,
+            });
+        }
+    }
+    return records;
+}
 function isPrimaryAgentFile(sourcePath) {
     const base = path.basename(sourcePath).toLowerCase();
     return ROOT_AGENT_FILENAMES.includes(base);
@@ -337,35 +428,39 @@ export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
     const refs = new Map();
     const mergedAgents = new Map();
     const mergedObjects = new Map();
-    const roots = [frameworkConfigRoot(), ...(options.overlayRoots ?? []), workspaceRoot];
+    const roots = [frameworkWorkspaceRoot(), ...(options.overlayRoots ?? []), workspaceRoot];
     let sharedAgentDefaults = {};
     let sharedAgentDefaultsByMode = {};
     for (const root of roots) {
-        for (const { item, sourcePath } of await readNamedYamlItems(root, [...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)),
-                    };
+        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 { item, sourcePath } of await readYamlItems(root, "agents", { recursive: true })) {
+        for (const { item, sourcePath } of await readConfigAgentItems(configRoot)) {
             const id = typeof item.id === "string" ? item.id : undefined;
             if (!id) {
                 continue;
@@ -377,7 +472,56 @@ export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
                 sourcePath,
             });
         }
-        for (const { item, sourcePath } of (await readYamlItems(root)).filter(({ sourcePath: fullPath }) => !fullPath.includes(`${path.sep}agents${path.sep}`) && !isPrimaryAgentFile(fullPath))) {
+        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) {
+                        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)) {
+                    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;

package/dist/workspace/resource-compilers.js

@@ -161,6 +161,7 @@ export function parseToolObject(object) {
         type: String(inferredType),
         name: String(value.name ?? "").trim(),
         description: String(value.description ?? "").trim(),
+        implementationName: typeof value.implementationName === "string" ? value.implementationName : undefined,
         config: asObject(value.config),
         inputSchemaRef: typeof asObject(value.inputSchema)?.ref === "string" ? String(asObject(value.inputSchema)?.ref) : undefined,
         backendOperation: typeof backend?.operation === "string"

package/dist/workspace/support/discovery.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
-import { builtinConfigRoot, builtinSkillsRoot } from "../../vendor/builtins.js";
-import { ensureExternalSource, isDirectoryPath, isExternalSourceLocator, resolveExternalSourcePath } from "../../vendor/sources.js";
+import { defaultResourceConfigRoot, defaultResourceSkillsRoot } from "../../resource/resource.js";
+import { ensureExternalResourceSource, isDirectoryPath, isExternalSourceLocator, resolveExternalResourcePath, resolveResourcePackageRoot, } from "../../resource/sources.js";
 import { parseAgentItem, readYamlItems } from "../object-loader.js";
 function resolveBuiltinPath(kind, ref) {
     const normalized = ref.replace(/^builtin:\/\//, "").replace(/^\/+/, "");
@@ -10,7 +10,7 @@ function resolveBuiltinPath(kind, ref) {
             throw new Error(`Unsupported builtin skill discovery path ${ref}`);
         }
         const suffix = normalized.replace(/^skills\/?/, "");
-        const root = builtinSkillsRoot();
+        const root = defaultResourceSkillsRoot();
         if (!suffix) {
             return root;
         }
@@ -18,8 +18,8 @@ function resolveBuiltinPath(kind, ref) {
         if (existsSync(candidate)) {
             return candidate;
         }
-        const sourceFallback = root.includes(`${path.sep}dist${path.sep}skills`)
-            ? path.join(path.resolve(root, "..", ".."), "skills", suffix)
+        const sourceFallback = root.includes(`${path.sep}dist${path.sep}resources${path.sep}skills`)
+            ? path.join(path.resolve(root, "..", "..", ".."), "resources", "skills", suffix)
             : null;
         if (sourceFallback && existsSync(sourceFallback)) {
             return sourceFallback;
@@ -30,7 +30,7 @@ function resolveBuiltinPath(kind, ref) {
         throw new Error(`Unsupported builtin subagent discovery path ${ref}`);
     }
     const suffix = normalized.replace(/^agents\/?/, "");
-    const root = path.join(builtinConfigRoot(), "agents");
+    const root = path.join(defaultResourceConfigRoot(), "agents");
     if (!suffix) {
         return root;
     }
@@ -47,9 +47,14 @@ function resolveBuiltinPath(kind, ref) {
     return candidate;
 }
 function preferPackageConvention(root, kind) {
-    const candidates = kind === "skills"
-        ? [path.join(root, "skills"), root]
-        : [path.join(root, "config", "agents"), path.join(root, "agents"), root];
+    const resourceRoot = resolveResourcePackageRoot(root);
+    const candidates = resourceRoot
+        ? kind === "skills"
+            ? [path.join(root, "config", "skills"), path.join(resourceRoot, "skills"), resourceRoot]
+            : [path.join(root, "config", "agents"), path.join(root, "agents"), path.join(resourceRoot, "agents"), resourceRoot]
+        : kind === "skills"
+            ? [path.join(root, "config", "skills"), path.join(root, "skills"), root]
+            : [path.join(root, "config", "agents"), path.join(root, "agents"), root];
     for (const candidate of candidates) {
         if (isDirectoryPath(candidate)) {
             return candidate;
@@ -60,25 +65,25 @@ function preferPackageConvention(root, kind) {
 export async function ensureDiscoverySources(locators, workspaceRoot) {
     await Promise.all(Array.from(new Set(locators))
         .filter((locator) => isExternalSourceLocator(locator))
-        .map((locator) => ensureExternalSource(locator, workspaceRoot)));
+        .map((locator) => ensureExternalResourceSource(locator, workspaceRoot)));
 }
 export function resolveDiscoveryRoot(ref, workspaceRoot, kind) {
     if (ref.startsWith("builtin://")) {
         return resolveBuiltinPath(kind, ref);
     }
     if (isExternalSourceLocator(ref)) {
-        return preferPackageConvention(resolveExternalSourcePath(ref, workspaceRoot), kind);
+        return preferPackageConvention(resolveExternalResourcePath(ref, workspaceRoot), kind);
     }
-    return path.resolve(workspaceRoot, ref);
+    return preferPackageConvention(path.resolve(workspaceRoot, ref), kind);
 }
 async function resolveDiscoveryRootAsync(ref, workspaceRoot, kind) {
     if (ref.startsWith("builtin://")) {
         return resolveBuiltinPath(kind, ref);
     }
     if (isExternalSourceLocator(ref)) {
-        return preferPackageConvention(await ensureExternalSource(ref, workspaceRoot), kind);
+        return preferPackageConvention(await ensureExternalResourceSource(ref, workspaceRoot), kind);
     }
-    return path.resolve(workspaceRoot, ref);
+    return preferPackageConvention(path.resolve(workspaceRoot, ref), kind);
 }
 export function discoverSkillPaths(rootRefs, workspaceRoot) {
     const discovered = new Map();

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

@@ -1,6 +1,6 @@
-import { isExternalSourceLocator } from "../../vendor/sources.js";
+import { isExternalSourceLocator } from "../../resource/sources.js";
 export function collectToolSourceRefs(tools, agents, options) {
-    const refs = new Set(options.builtinSources ?? []);
+    const refs = new Set(options.resourceSources ?? options.builtinSources ?? []);
     for (const tool of tools.values()) {
         for (const ref of tool.bundleRefs) {
             if (isExternalSourceLocator(ref)) {

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Agent Harness framework package",
   "type": "module",
+  "packageManager": "npm@10.9.2",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,8 +15,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/botbotgo/agent-harness.git",
-    "directory": "packages/framework"
+    "url": "git+https://github.com/botbotgo/agent-harness.git"
   },
   "exports": {
     ".": {
@@ -25,10 +25,32 @@
     }
   },
   "dependencies": {
-    "@botbotgo/agent-harness-builtin": "0.0.8"
+    "@langchain/anthropic": "^1.1.0",
+    "@langchain/community": "^1.1.24",
+    "@langchain/core": "^1.1.33",
+    "@langchain/google": "^0.1.7",
+    "@langchain/langgraph": "^1.2.3",
+    "@langchain/langgraph-checkpoint-sqlite": "^1.0.1",
+    "@langchain/ollama": "^1.2.6",
+    "@langchain/openai": "^1.1.0",
+    "@libsql/client": "^0.17.0",
+    "@llamaindex/ollama": "^0.1.24",
+    "deepagents": "1.8.4",
+    "langchain": "1.2.34",
+    "llamaindex": "^0.12.1",
+    "mustache": "^4.2.0",
+    "yaml": "^2.8.1"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
-    "check": "tsc -p tsconfig.json --noEmit"
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/stock-research-app-load-harness.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts",
+    "release:pack": "npm pack --dry-run",
+    "release:publish": "npm publish --access public --registry https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   }
 }

package/dist/vendor/builtins.d.ts

@@ -1,24 +0,0 @@
-import type { RuntimeAdapterOptions, WorkspaceBundle } from "../contracts/types.js";
-export declare function resolveLocalBuiltinsEntry(currentVendorDir: string, resolveInstalledEntry?: () => string | null): string;
-type BuiltinToolInfo = {
-    builtinPath: string;
-    backendOperation: string;
-    name: string;
-    description: string;
-    hitl?: {
-        enabled: boolean;
-        allow: Array<"approve" | "edit" | "reject">;
-    };
-};
-export declare function ensureBuiltinSources(sources?: string[], workspaceRoot?: string): Promise<void>;
-export declare const builtinSkillsRoot: () => string;
-export declare const builtinConfigRoot: () => string;
-export declare function listBuiltinTools(sources?: string[], workspaceRoot?: string): Promise<BuiltinToolInfo[]>;
-export declare function listBuiltinToolsForSource(source: string, workspaceRoot?: string): Promise<BuiltinToolInfo[]>;
-export declare function createBuiltinBackendResolver(workspace: WorkspaceBundle): NonNullable<RuntimeAdapterOptions["backendResolver"]>;
-export declare function createBuiltinToolResolver(workspace: WorkspaceBundle, options?: {
-    getStore?: (_binding?: WorkspaceBundle["bindings"] extends Map<any, infer T> ? T : never) => unknown;
-    getEmbeddingModel?: (embeddingModelRef?: string, _binding?: WorkspaceBundle["bindings"] extends Map<any, infer T> ? T : never) => Promise<unknown>;
-    getVectorStore?: (vectorStoreRef?: string, _binding?: WorkspaceBundle["bindings"] extends Map<any, infer T> ? T : never) => Promise<unknown>;
-}): NonNullable<RuntimeAdapterOptions["toolResolver"]>;
-export {};

package/dist/vendor/builtins.js

@@ -1,118 +0,0 @@
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import path from "node:path";
-import { readFile } from "node:fs/promises";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { ensureExternalSource, isExternalSourceLocator, parseExternalSourceLocator } from "./sources.js";
-const vendorDir = path.dirname(fileURLToPath(import.meta.url));
-const require = createRequire(import.meta.url);
-function installedBuiltinsEntry() {
-    try {
-        return require.resolve("@botbotgo/agent-harness-builtin");
-    }
-    catch {
-        return null;
-    }
-}
-export function resolveLocalBuiltinsEntry(currentVendorDir, resolveInstalledEntry = installedBuiltinsEntry) {
-    const candidates = [
-        path.resolve(currentVendorDir, "../../../builtins/dist/src/index.js"),
-        resolveInstalledEntry(),
-        path.resolve(currentVendorDir, "../../../builtins/src/index.ts"),
-    ].filter((candidate) => typeof candidate === "string" && candidate.length > 0);
-    for (const candidate of candidates) {
-        if (existsSync(candidate)) {
-            return candidate;
-        }
-    }
-    return candidates.at(-1) ?? path.resolve(currentVendorDir, "../../../builtins/src/index.ts");
-}
-const builtinsEntry = resolveLocalBuiltinsEntry(vendorDir);
-const localBuiltins = await import(pathToFileURL(builtinsEntry).href);
-const remoteProviderCache = new Map();
-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");
-}
-async function loadRemoteProvider(source, workspaceRoot) {
-    const cached = remoteProviderCache.get(source);
-    if (cached) {
-        return cached;
-    }
-    if (!isExternalSourceLocator(source)) {
-        throw new Error(`Unsupported builtin source ${source}. Use npm:, tgz:, or file:.`);
-    }
-    const parsed = parseExternalSourceLocator(source);
-    if (parsed.subpath) {
-        throw new Error(`Builtin source ${source} must point at a package root, not a subpath`);
-    }
-    const packageRoot = await ensureExternalSource(source, workspaceRoot);
-    const pkg = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
-    const entry = resolvePackageEntry(packageRoot, pkg);
-    const imported = await import(pathToFileURL(entry).href);
-    const provider = (imported.default ?? imported);
-    if (typeof provider.listBuiltinTools !== "function" || typeof provider.createBuiltinToolResolver !== "function") {
-        throw new Error(`Remote builtin source ${source} must export listBuiltinTools() and createBuiltinToolResolver().`);
-    }
-    const typedProvider = provider;
-    remoteProviderCache.set(source, typedProvider);
-    return typedProvider;
-}
-export async function ensureBuiltinSources(sources = [], workspaceRoot = process.cwd()) {
-    await Promise.all(sources.map((source) => loadRemoteProvider(source, workspaceRoot)));
-}
-export const builtinSkillsRoot = localBuiltins.builtinSkillsRoot;
-export const builtinConfigRoot = (localBuiltins.builtinConfigRoot ?? localBuiltins.builtinDefaultsRoot);
-export async function listBuiltinTools(sources = [], workspaceRoot = process.cwd()) {
-    await ensureBuiltinSources(sources, workspaceRoot);
-    const deduped = new Map();
-    const local = localBuiltins.listBuiltinTools;
-    for (const tool of local()) {
-        deduped.set(tool.builtinPath, tool);
-    }
-    for (const source of sources) {
-        for (const tool of remoteProviderCache.get(source)?.listBuiltinTools() ?? []) {
-            deduped.set(tool.builtinPath, tool);
-        }
-    }
-    return Array.from(deduped.values());
-}
-export async function listBuiltinToolsForSource(source, workspaceRoot = process.cwd()) {
-    await ensureBuiltinSources([source], workspaceRoot);
-    return remoteProviderCache.get(source)?.listBuiltinTools() ?? [];
-}
-export function createBuiltinBackendResolver(workspace) {
-    return localBuiltins.createBuiltinBackendResolver(workspace);
-}
-export function createBuiltinToolResolver(workspace, options = {}) {
-    const localResolver = localBuiltins.createBuiltinToolResolver(workspace, options);
-    const remoteResolvers = workspace.builtinSources
-        .map((source) => remoteProviderCache.get(source))
-        .filter((provider) => Boolean(provider))
-        .map((provider) => provider.createBuiltinToolResolver(workspace));
-    return (toolIds, binding) => [
-        ...localResolver(toolIds, binding),
-        ...remoteResolvers.flatMap((resolver) => resolver(toolIds, binding)),
-    ];
-}