@botbotgo/agent-harness 0.0.17 → 0.0.19

package/dist/config/{runtime.yaml → workspace.yaml}

@@ -45,3 +45,26 @@ spec:
       codebase, choose {{secondaryAgentId}}.
 
       When uncertain, prefer {{secondaryAgentId}}.
+
+  # agent-harness feature: optional workspace-level background maintenance policies.
+  # This is the framework-owned place to configure periodic housekeeping that should run without
+  # coupling cleanup to user-triggered checkpoint reads or writes.
+  #
+  # Current support:
+  # - checkpoint cleanup for `SqliteSaver` checkpointers only
+  # - oldest-first deletion by time policy and/or size policy
+  # - background scheduling inside the harness lifecycle
+  #
+  # Example:
+  # maintenance:
+  #   checkpoints:
+  #     enabled: true
+  #     schedule:
+  #       intervalSeconds: 3600
+  #       runOnStartup: true
+  #     policies:
+  #       maxAgeSeconds: 604800
+  #       maxBytes: 1073741824
+  #     sqlite:
+  #       sweepBatchSize: 200
+  #       vacuum: false

package/dist/contracts/types.d.ts

@@ -8,6 +8,7 @@ export type ParsedAgentObject = {
     modelRef: string;
     runRoot?: string;
     toolRefs: string[];
+    mcpServers?: Array<Record<string, unknown>>;
     skillPathRefs: string[];
     memorySources: string[];
     subagentRefs: string[];
@@ -52,6 +53,18 @@ export type ParsedVectorStoreObject = {
     metadata?: Record<string, unknown>;
     sourcePath: string;
 };
+export type ParsedMcpServerObject = {
+    id: string;
+    transport: "stdio" | "http" | "sse" | "websocket";
+    url?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    token?: string;
+    headers?: Record<string, string>;
+    sourcePath: string;
+};
 export type ParsedToolObject = {
     id: string;
     type: string;
@@ -174,6 +187,7 @@ export type WorkspaceBundle = {
     models: Map<string, ParsedModelObject>;
     embeddings: Map<string, ParsedEmbeddingModelObject>;
     vectorStores: Map<string, ParsedVectorStoreObject>;
+    mcpServers: Map<string, ParsedMcpServerObject>;
     tools: Map<string, ParsedToolObject>;
     agents: Map<string, ParsedAgentObject>;
     bindings: Map<string, CompiledAgentBinding>;

package/dist/index.d.ts

@@ -1 +1,3 @@
-export { createAgentHarness, getThread, run, subscribe, stop } from "./api.js";
+export { createAgentHarness, createToolMcpServer, getThread, run, serveToolsOverStdio, subscribe, stop } from "./api.js";
+export type { ToolMcpServerOptions } from "./mcp.js";
+export { tool } from "./tools.js";

package/dist/index.js

@@ -1 +1,2 @@
-export { createAgentHarness, getThread, run, subscribe, stop } from "./api.js";
+export { createAgentHarness, createToolMcpServer, getThread, run, serveToolsOverStdio, subscribe, stop } from "./api.js";
+export { tool } from "./tools.js";

package/dist/mcp.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AgentHarness } from "./runtime/harness.js";
+export type ToolMcpServerOptions = {
+    agentId: string;
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    includeToolNames?: string[];
+};
+export declare function createToolMcpServerFromHarness(harness: AgentHarness, options: ToolMcpServerOptions): Promise<McpServer>;
+export declare function serveToolsOverStdioFromHarness(harness: AgentHarness, options: ToolMcpServerOptions): Promise<McpServer>;

package/dist/mcp.js

@@ -0,0 +1,112 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { loadToolModuleDefinition } from "./tool-modules.js";
+function asResolvedTool(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}
+async function buildRawShapeForTool(harness, toolId, resolvedTool) {
+    const tool = harness.getWorkspace().tools.get(toolId);
+    if (!tool) {
+        return undefined;
+    }
+    if (tool.type === "function") {
+        const imported = await import(pathToFileURL(tool.sourcePath).href);
+        const definition = loadToolModuleDefinition(imported, tool.implementationName ?? tool.id);
+        return typeof definition.schema.shape === "object" && definition.schema.shape !== null
+            ? definition.schema.shape
+            : undefined;
+    }
+    const typedResolvedTool = asResolvedTool(resolvedTool);
+    if (!typedResolvedTool?.inputSchemaPromise) {
+        return undefined;
+    }
+    return jsonSchemaObjectToRawShape(await typedResolvedTool.inputSchemaPromise);
+}
+async function invokeResolvedTool(resolvedTool, input) {
+    const typed = asResolvedTool(resolvedTool);
+    if (!typed) {
+        throw new Error("Resolved tool is not invokable.");
+    }
+    if (typeof typed.invoke === "function") {
+        return typed.invoke(input);
+    }
+    if (typeof typed.call === "function") {
+        return typed.call(input);
+    }
+    if (typeof typed.func === "function") {
+        return typed.func(input);
+    }
+    throw new Error("Resolved tool does not expose invoke, call, or func.");
+}
+function renderToolOutput(output) {
+    if (typeof output === "string") {
+        return output;
+    }
+    return JSON.stringify(output, null, 2);
+}
+function jsonSchemaObjectToRawShape(schema) {
+    if (!schema || schema.type !== "object") {
+        return undefined;
+    }
+    const properties = typeof schema.properties === "object" && schema.properties
+        ? schema.properties
+        : {};
+    const required = Array.isArray(schema.required)
+        ? new Set(schema.required.filter((item) => typeof item === "string"))
+        : new Set();
+    const shape = {};
+    for (const [key, propertySchema] of Object.entries(properties)) {
+        const built = jsonSchemaToZod(propertySchema);
+        shape[key] = required.has(key) ? built : built.optional();
+    }
+    return shape;
+}
+function jsonSchemaToZod(schema) {
+    switch (schema?.type) {
+        case "string":
+            return z.string();
+        case "number":
+            return z.number();
+        case "integer":
+            return z.number().int();
+        case "boolean":
+            return z.boolean();
+        case "array":
+            return z.array(jsonSchemaToZod(typeof schema.items === "object" && schema.items ? schema.items : undefined));
+        case "object": {
+            const shape = jsonSchemaObjectToRawShape(schema);
+            return z.object(shape ?? {}).passthrough();
+        }
+        default:
+            return z.any();
+    }
+}
+export async function createToolMcpServerFromHarness(harness, options) {
+    const server = new McpServer({
+        name: options.serverInfo?.name ?? `agent-harness-${options.agentId}`,
+        version: options.serverInfo?.version ?? "0.0.16",
+    });
+    const allowedNames = options.includeToolNames ? new Set(options.includeToolNames) : null;
+    for (const { compiledTool, resolvedTool } of harness.resolveAgentTools(options.agentId)) {
+        if (allowedNames && !allowedNames.has(compiledTool.name)) {
+            continue;
+        }
+        const rawShape = await buildRawShapeForTool(harness, compiledTool.id, resolvedTool);
+        server.tool(compiledTool.name, compiledTool.description, rawShape ?? {}, async (input) => ({
+            content: [
+                {
+                    type: "text",
+                    text: renderToolOutput(await invokeResolvedTool(resolvedTool, input)),
+                },
+            ],
+        }));
+    }
+    return server;
+}
+export async function serveToolsOverStdioFromHarness(harness, options) {
+    const server = await createToolMcpServerFromHarness(harness, options);
+    await server.connect(new StdioServerTransport());
+    return server;
+}

package/dist/resource/isolation.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureIsolatedResourcePackageRoot(packageRoot: string): Promise<string>;
+export declare function resolveIsolatedResourceModulePath(packageRoot: string, sourcePath: string): Promise<string>;

package/dist/resource/isolation.js

@@ -0,0 +1,79 @@
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, rm, symlink } from "node:fs/promises";
+const isolatedResourceRootCache = new Map();
+function isolationCacheRoot() {
+    return path.join(os.tmpdir(), "agent-harness-resource-isolation");
+}
+function isolationDir(packageRoot) {
+    const digest = createHash("sha256").update(packageRoot).digest("hex").slice(0, 16);
+    return path.join(isolationCacheRoot(), `${path.basename(packageRoot)}-${digest}`);
+}
+function declaredDependencyNames(manifest) {
+    return Array.from(new Set([
+        ...Object.keys(manifest.dependencies ?? {}),
+        ...Object.keys(manifest.optionalDependencies ?? {}),
+        ...Object.keys(manifest.peerDependencies ?? {}),
+    ])).sort();
+}
+function dependencyLinkPath(isolatedRoot, dependencyName) {
+    return path.join(isolatedRoot, "node_modules", ...dependencyName.split("/"));
+}
+function dependencyPackageRoot(packageJsonPath) {
+    return path.dirname(packageJsonPath);
+}
+function resolveDeclaredDependency(packageRoot, dependencyName) {
+    const localPath = path.join(packageRoot, "node_modules", ...dependencyName.split("/"), "package.json");
+    if (existsSync(localPath)) {
+        return dependencyPackageRoot(localPath);
+    }
+    try {
+        const requireFromPackage = createRequire(path.join(packageRoot, "package.json"));
+        return dependencyPackageRoot(requireFromPackage.resolve(`${dependencyName}/package.json`));
+    }
+    catch {
+        return null;
+    }
+}
+async function linkDeclaredDependencies(isolatedRoot, packageRoot, manifest) {
+    for (const dependencyName of declaredDependencyNames(manifest)) {
+        const resolved = resolveDeclaredDependency(packageRoot, dependencyName);
+        if (!resolved) {
+            continue;
+        }
+        const targetPath = dependencyLinkPath(isolatedRoot, dependencyName);
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await symlink(resolved, targetPath, "junction");
+    }
+}
+async function buildIsolatedResourceRoot(packageRoot) {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    const manifest = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    const isolatedRoot = isolationDir(packageRoot);
+    await rm(isolatedRoot, { recursive: true, force: true });
+    await mkdir(path.dirname(isolatedRoot), { recursive: true });
+    await cp(packageRoot, isolatedRoot, {
+        recursive: true,
+        force: true,
+        filter: (source) => path.basename(source) !== "node_modules",
+    });
+    await mkdir(path.join(isolatedRoot, "node_modules"), { recursive: true });
+    await linkDeclaredDependencies(isolatedRoot, packageRoot, manifest);
+    return isolatedRoot;
+}
+export async function ensureIsolatedResourcePackageRoot(packageRoot) {
+    const cached = isolatedResourceRootCache.get(packageRoot);
+    if (cached) {
+        return cached;
+    }
+    const loading = buildIsolatedResourceRoot(packageRoot);
+    isolatedResourceRootCache.set(packageRoot, loading);
+    return loading;
+}
+export async function resolveIsolatedResourceModulePath(packageRoot, sourcePath) {
+    const isolatedRoot = await ensureIsolatedResourcePackageRoot(packageRoot);
+    return path.join(isolatedRoot, path.relative(packageRoot, sourcePath));
+}

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

@@ -1,3 +1,4 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { RuntimeAdapterOptions, WorkspaceBundle } from "../contracts/types.js";
 export declare function resolveLocalBuiltinsEntry(currentResourceDir: string, resolveInstalledEntry?: () => string | null): string;
 export type ResourceToolInfo = {
@@ -10,6 +11,23 @@ export type ResourceToolInfo = {
         allow: Array<"approve" | "edit" | "reject">;
     };
 };
+export type McpServerConfig = {
+    transport?: "stdio" | "http" | "sse" | "websocket";
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    token?: string;
+    headers?: Record<string, string>;
+};
+export type McpToolDescriptor = {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+};
+export declare function getOrCreateMcpClient(config: McpServerConfig): Promise<Client>;
+export declare function listRemoteMcpTools(config: McpServerConfig): Promise<McpToolDescriptor[]>;
 export declare function ensureResourceSources(sources?: string[], workspaceRoot?: string): Promise<void>;
 export declare function defaultResourceSkillsRoot(): string;
 export declare function defaultResourceConfigRoot(): string;

package/dist/resource/resource-impl.js

@@ -4,6 +4,13 @@ import path from "node:path";
 import { stat } from "node:fs/promises";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
+import { isSupportedToolModulePath, loadToolModuleDefinition } from "../tool-modules.js";
+import { resolveIsolatedResourceModulePath } from "./isolation.js";
 import { ensureExternalResourceSource, ensureExternalSource, isExternalSourceLocator, parseExternalSourceLocator } from "./sources.js";
 const resourceDir = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -77,6 +84,7 @@ async function findPackageRoot(startPath) {
     }
 }
 const functionToolModuleCache = new Map();
+const mcpClientCache = new Map();
 async function loadFunctionToolModule(tool) {
     const cacheKey = `${tool.sourcePath}:${tool.implementationName ?? tool.id}`;
     const cached = functionToolModuleCache.get(cacheKey);
@@ -84,24 +92,145 @@ async function loadFunctionToolModule(tool) {
         return cached;
     }
     const loading = (async () => {
-        const imported = await import(pathToFileURL(tool.sourcePath).href);
+        const packageRoot = await findPackageRoot(tool.sourcePath);
+        const isolatedSourcePath = await resolveIsolatedResourceModulePath(packageRoot, tool.sourcePath);
+        const imported = await import(pathToFileURL(isolatedSourcePath).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 };
+        const loaded = loadToolModuleDefinition(imported, implementationName);
+        return { invoke: loaded.invoke, schema: loaded.schema, description: loaded.description };
     })();
     functionToolModuleCache.set(cacheKey, loading);
     return loading;
 }
+function normalizeMcpTransport(value) {
+    if (value === "stdio" || value === "http" || value === "sse" || value === "websocket") {
+        return value;
+    }
+    return undefined;
+}
+function readMcpServerConfig(workspace, tool) {
+    const mcpConfig = typeof tool.config?.mcp === "object" && tool.config?.mcp
+        ? tool.config.mcp
+        : undefined;
+    const serverRef = typeof mcpConfig?.serverRef === "string" ? mcpConfig.serverRef : undefined;
+    if (serverRef) {
+        const serverId = serverRef.startsWith("mcp/") ? serverRef.slice(4) : serverRef;
+        const server = workspace.mcpServers.get(serverId);
+        if (!server) {
+            throw new Error(`MCP tool ${tool.id} references missing MCP server ${serverRef}`);
+        }
+        return {
+            transport: server.transport,
+            command: server.command,
+            args: server.args,
+            env: server.env,
+            cwd: server.cwd,
+            url: server.url,
+            token: server.token,
+            headers: server.headers,
+        };
+    }
+    const config = typeof tool.config === "object" && tool.config
+        ? tool.config
+        : undefined;
+    const mcpServer = typeof config?.mcpServer === "object" && config.mcpServer
+        ? config.mcpServer
+        : config;
+    if (!mcpServer) {
+        return null;
+    }
+    const envRecord = typeof mcpServer.env === "object" && mcpServer.env
+        ? Object.fromEntries(Object.entries(mcpServer.env).filter((entry) => typeof entry[1] === "string"))
+        : undefined;
+    return {
+        transport: normalizeMcpTransport(mcpServer.transport) ?? ((typeof mcpServer.url === "string" && mcpServer.url.trim()) ? "http" : "stdio"),
+        command: typeof mcpServer.command === "string" ? mcpServer.command.trim() : undefined,
+        args: Array.isArray(mcpServer.args) ? mcpServer.args.filter((item) => typeof item === "string") : undefined,
+        env: envRecord,
+        cwd: typeof mcpServer.cwd === "string" ? mcpServer.cwd : undefined,
+        url: typeof mcpServer.url === "string" ? mcpServer.url.trim() : undefined,
+        token: typeof mcpServer.token === "string" ? mcpServer.token : undefined,
+        headers: typeof mcpServer.headers === "object" && mcpServer.headers
+            ? Object.fromEntries(Object.entries(mcpServer.headers).filter((entry) => typeof entry[1] === "string"))
+            : undefined,
+    };
+}
+function createMcpCacheKey(config) {
+    return JSON.stringify({
+        transport: config.transport ?? "stdio",
+        command: config.command,
+        args: config.args ?? [],
+        env: config.env ?? {},
+        cwd: config.cwd ?? "",
+        url: config.url ?? "",
+        token: config.token ?? "",
+        headers: config.headers ?? {},
+    });
+}
+export async function getOrCreateMcpClient(config) {
+    const cacheKey = createMcpCacheKey(config);
+    const cached = mcpClientCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const loading = (async () => {
+        const client = new Client({
+            name: "agent-harness",
+            version: "0.0.16",
+        });
+        const headers = {
+            ...(config.headers ?? {}),
+            ...(config.token ? { Authorization: `Bearer ${config.token}` } : {}),
+        };
+        const transport = config.transport === "http"
+            ? new StreamableHTTPClientTransport(new URL(config.url ?? ""), {
+                requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
+            })
+            : config.transport === "sse"
+                ? new SSEClientTransport(new URL(config.url ?? ""), {
+                    requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
+                })
+                : config.transport === "websocket"
+                    ? new WebSocketClientTransport(new URL(config.url ?? ""))
+                    : new StdioClientTransport({
+                        command: config.command ?? "",
+                        args: config.args,
+                        env: config.env,
+                        cwd: config.cwd,
+                    });
+        await client.connect(transport);
+        return client;
+    })();
+    mcpClientCache.set(cacheKey, loading);
+    return loading;
+}
+async function getRemoteMcpToolDescriptor(config, remoteToolName) {
+    const client = await getOrCreateMcpClient(config);
+    const result = await client.listTools();
+    const tool = result.tools.find((item) => typeof item.name === "string" && item.name === remoteToolName);
+    if (!tool || typeof tool.name !== "string") {
+        return null;
+    }
+    return {
+        name: tool.name,
+        description: typeof tool.description === "string" ? tool.description : undefined,
+        inputSchema: typeof tool.inputSchema === "object" && tool.inputSchema ? tool.inputSchema : undefined,
+    };
+}
+export async function listRemoteMcpTools(config) {
+    const client = await getOrCreateMcpClient(config);
+    const result = await client.listTools();
+    return result.tools
+        .filter((tool) => typeof tool.name === "string")
+        .map((tool) => ({
+        name: tool.name,
+        description: typeof tool.description === "string" ? tool.description : undefined,
+        inputSchema: typeof tool.inputSchema === "object" && tool.inputSchema ? tool.inputSchema : undefined,
+    }));
+}
 function createFunctionToolResolver(workspace) {
     const functionTools = new Map(Array.from(workspace.tools.values())
-        .filter((tool) => tool.type === "function" && tool.sourcePath.endsWith(".mjs"))
+        .filter((tool) => tool.type === "function" && isSupportedToolModulePath(tool.sourcePath))
         .map((tool) => [tool.id, tool]));
     return (toolIds) => toolIds.flatMap((toolId) => {
         const tool = functionTools.get(toolId);
@@ -127,6 +256,43 @@ function createFunctionToolResolver(workspace) {
         ];
     });
 }
+function createMcpToolResolver(workspace) {
+    const mcpTools = new Map(Array.from(workspace.tools.values())
+        .filter((tool) => tool.type === "mcp")
+        .map((tool) => [tool.id, tool]));
+    return (toolIds) => toolIds.flatMap((toolId) => {
+        const tool = mcpTools.get(toolId);
+        if (!tool) {
+            return [];
+        }
+        const serverConfig = readMcpServerConfig(workspace, tool);
+        if (!serverConfig) {
+            throw new Error(`MCP tool ${tool.id} must define mcp.serverRef or inline MCP server config.`);
+        }
+        const remoteToolName = tool.mcpRef ?? tool.name;
+        const descriptorPromise = getRemoteMcpToolDescriptor(serverConfig, remoteToolName);
+        return [
+            {
+                name: tool.name,
+                description: tool.description,
+                inputSchemaPromise: descriptorPromise.then((descriptor) => descriptor?.inputSchema),
+                async invoke(input) {
+                    const client = await getOrCreateMcpClient(serverConfig);
+                    const result = await client.callTool({
+                        name: remoteToolName,
+                        arguments: typeof input === "object" && input !== null ? input : {},
+                    });
+                    const textParts = Array.isArray(result.content)
+                        ? result.content
+                            .filter((item) => typeof item === "object" && item !== null && "type" in item)
+                            .flatMap((item) => item.type === "text" && typeof item.text === "string" ? [item.text] : [])
+                        : [];
+                    return textParts.length > 0 ? textParts.join("\n\n") : JSON.stringify(result);
+                },
+            },
+        ];
+    });
+}
 function resolvePackageEntry(packageRoot, pkg) {
     const exportsField = pkg.exports;
     if (typeof exportsField === "string") {
@@ -222,6 +388,7 @@ export function createResourceBackendResolver(workspace) {
 }
 export function createResourceToolResolver(workspace, options = {}) {
     const functionResolver = createFunctionToolResolver(workspace);
+    const mcpResolver = createMcpToolResolver(workspace);
     const localResolver = createProviderToolResolver(localResource, workspace, options);
     const remoteResolvers = (workspace.resourceSources ?? workspace.builtinSources ?? [])
         .map((source) => remoteResourceCache.get(source))
@@ -231,6 +398,7 @@ export function createResourceToolResolver(workspace, options = {}) {
     return (toolIds, binding) => {
         const resolved = [
             ...functionResolver(toolIds, binding),
+            ...mcpResolver(toolIds, binding),
             ...(localResolver?.(toolIds, binding) ?? []),
             ...remoteResolvers.flatMap((resolver) => resolver(toolIds, binding)),
         ];

package/dist/resource/sources.d.ts

@@ -2,6 +2,9 @@ type ParsedLocator = {
     kind: "npm" | "tgz" | "file";
     spec: string;
     subpath?: string;
+    integrity?: string;
+    signature?: string;
+    publicKey?: string;
 };
 export declare function resolveResourcePackageRoot(root: string): string | null;
 export declare function isExternalSourceLocator(value: unknown): boolean;