@botbotgo/agent-harness 0.0.69 → 0.0.71

package/README.md

@@ -53,7 +53,7 @@ The runtime provides:
 - `createAgentHarness(workspaceRoot)`, `run(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
 - YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
 - backend-adapted execution with current LangChain v1 and DeepAgents adapters
-- local `resources/tools/` and `resources/skills/` discovery
+- local `resources/tools/` `tool({...})` modules and `resources/skills/` discovery
 - persisted threads, runs, approvals, events, queue state, and recovery metadata
 
 The repository-owned default config layer is intentionally full-shaped. The shipped YAML keeps explicit defaults for the important runtime and agent knobs so teams can start from concrete config instead of reverse-engineering adapter behavior from source.
@@ -157,7 +157,7 @@ If you want the shortest possible mental model:
 - Small public runtime contract
 - YAML-defined host routing and runtime policy
 - LangChain v1 and DeepAgents backend adaptation
-- Auto-discovered local tools and SKILL packages
+- Auto-discovered local `tool({...})` tools and SKILL packages
 - provider-native tools, MCP tools, and workspace-local tool modules
 - persisted threads, runs, approvals, lifecycle events, and queued runs
 - runtime-managed recovery and checkpoint maintenance
@@ -184,6 +184,26 @@ const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to
 
 `createAgentHarness(...)` loads the workspace, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
 
+`createAgentHarness(..., { load })` accepts workspace loading controls.
+
+Merge order is deterministic:
+
+- framework defaults
+- each `overlayRoots` entry in order
+- workspace root
+
+Later values always override earlier values. Arrays are replaced, while plain objects are deep-merged.
+
+```ts
+import { createAgentHarness } from "@botbotgo/agent-harness";
+
+const runtime = await createAgentHarness("/path/to/workspace", {
+  load: {
+    overlayRoots: ["/path/to/framework-defaults", "/path/to/product-overrides"],
+  },
+});
+```
+
 ### Run A Request
 
 ```ts
@@ -345,6 +365,9 @@ Core workspace files:
 - `resources/tools/`
 - `resources/skills/`
 
+Workspace-local tool modules in `resources/tools/` should be exported with `tool({...})`.
+Any other local module shape is not supported, and unsupported shapes are rejected at load time.
+
 There are three main configuration layers:
 
 - runtime policy in `config/workspace.yaml`
@@ -379,12 +402,18 @@ Important fields:
 - `routing.systemPrompt`
 - `routing.modelRouting`
 - `maintenance.checkpoints`
+- `maintenance.records`
 - `recovery.enabled`
 - `recovery.resumeResumingRunsOnStartup`
 - `recovery.maxRecoveryAttempts`
 
 `recovery.resumeResumingRunsOnStartup` keeps checkpoint resume a runtime-owned lifecycle behavior instead of exposing checkpoint orchestration as public API.
 
+`maintenance.checkpoints` and `maintenance.records` are separate retention layers:
+
+- `maintenance.checkpoints` trims backend checkpoint state used for resume/recovery
+- `maintenance.records` trims harness-owned terminal thread/run records stored in `runtime.sqlite`
+
 Example:
 
 ```yaml
@@ -402,6 +431,8 @@ spec:
   maintenance:
     checkpoints:
       enabled: true
+    records:
+      enabled: false
   recovery:
     enabled: true
     resumeResumingRunsOnStartup: true

package/README.zh.md

@@ -53,7 +53,7 @@
 - `createAgentHarness(workspaceRoot)`、`run(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
 - 以 YAML 描述的工作区装配：路由、模型、工具、存储、后端、MCP、恢复与维护等
 - 通过适配器对接当前的 LangChain v1 与 DeepAgents 执行
-- 本地 `resources/tools/` 与 `resources/skills/` 的发现
+- 本地 `resources/tools/` 中 `tool({...})` 工具模块与 `resources/skills/` 的发现
 - 持久化的线程、运行、审批、事件、队列状态与恢复元数据
 
 仓库自带的默认配置刻意做成「形状完整」。随仓库提供的 YAML 对重要的运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
@@ -183,6 +183,26 @@ const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to
 
 `createAgentHarness(...)` 会加载工作区、解析 `resources/`、在 `runRoot` 下初始化持久化，并启动运行时维护任务。
 
+`createAgentHarness(..., { load })` 支持工作区加载控制。
+
+合并顺序是确定性的：
+
+- 框架默认配置
+- 每个 `overlayRoots` 条目（按数组顺序）
+- workspace 根目录
+
+后者会覆盖前者；数组会被直接替换，普通对象会执行深度合并。
+
+```ts
+import { createAgentHarness } from "@botbotgo/agent-harness";
+
+const runtime = await createAgentHarness("/path/to/workspace", {
+  load: {
+    overlayRoots: ["/path/to/framework-defaults", "/path/to/product-overrides"],
+  },
+});
+```
+
 ### 发起一次运行
 
 ```ts
@@ -343,6 +363,9 @@ await stop(runtime);
 - `resources/tools/`
 - `resources/skills/`
 
+`resources/tools/` 下的工作区本地工具模块应统一用 `tool({...})` 导出。
+不支持历史/兼容写法，任何不带该导出形式的工具模块都会在工作区加载时被拒绝。
+
 主要有三层配置：
 
 - `config/workspace.yaml` 中的运行时策略
@@ -377,12 +400,18 @@ await stop(runtime);
 - `routing.systemPrompt`
 - `routing.modelRouting`
 - `maintenance.checkpoints`
+- `maintenance.records`
 - `recovery.enabled`
 - `recovery.resumeResumingRunsOnStartup`
 - `recovery.maxRecoveryAttempts`
 
 `recovery.resumeResumingRunsOnStartup` 将 checkpoint 恢复保持为运行时拥有的生命周期行为，而不是把 checkpoint 编排暴露为主 API。
 
+`maintenance.checkpoints` 与 `maintenance.records` 是两层独立的保留策略：
+
+- `maintenance.checkpoints` 清理后端用于 resume/recovery 的 checkpoint 状态
+- `maintenance.records` 清理 harness 自己保存在 `runtime.sqlite` 中、已结束的 thread/run 记录
+
 示例：
 
 ```yaml
@@ -400,6 +429,8 @@ spec:
   maintenance:
     checkpoints:
       enabled: true
+    records:
+      enabled: false
   recovery:
     enabled: true
     resumeResumingRunsOnStartup: true

package/dist/api.d.ts

@@ -5,6 +5,10 @@ import type { RequirementAssessmentOptions } from "./runtime/skill-requirements.
 import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 type CreateAgentHarnessOptions = {
+    /**
+     * Workspace loading behavior.
+     * overlayRoots are merged after framework defaults and before workspaceRoot.
+     */
     load?: WorkspaceLoadOptions;
     adapter?: RuntimeAdapterOptions;
 };

package/dist/contracts/types.d.ts

@@ -220,6 +220,12 @@ export type WorkspaceBundle = {
     bindings: Map<string, CompiledAgentBinding>;
 };
 export type WorkspaceLoadOptions = {
+    /**
+     * Additional workspace roots to load before the runtime workspace root.
+     * Merge order is deterministic:
+     * framework defaults -> each overlayRoot (in order) -> workspaceRoot.
+     * Later values always override earlier values.
+     */
     overlayRoots?: string[];
     resourceSources?: string[];
 };

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.68";
+export declare const AGENT_HARNESS_VERSION = "0.0.70";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.68";
+export const AGENT_HARNESS_VERSION = "0.0.70";

package/dist/tool-modules.d.ts

@@ -1,18 +1,13 @@
+import { normalizeToolSchema } from "./tools.js";
 type ImportedToolModule = Record<string, unknown>;
-type SchemaLike = {
-    parse: (input: unknown) => unknown;
-    description?: string;
-    shape?: Record<string, unknown>;
-};
 export type LoadedToolModule = {
     implementationName: string;
     invoke: (input: unknown, context?: Record<string, unknown>) => Promise<unknown> | unknown;
-    schema: SchemaLike;
+    schema: ReturnType<typeof normalizeToolSchema>;
     description: string;
     retryable?: boolean;
 };
 export declare function isSupportedToolModulePath(filePath: string): boolean;
-export declare function discoverAnnotatedFunctionNames(sourceText: string): string[];
-export declare function discoverToolModuleDefinitions(sourceText: string, imported: ImportedToolModule): LoadedToolModule[];
+export declare function discoverToolModuleDefinitions(_sourceText: string, imported: ImportedToolModule): LoadedToolModule[];
 export declare function loadToolModuleDefinition(imported: ImportedToolModule, implementationName: string): LoadedToolModule;
 export {};

package/dist/tool-modules.js

@@ -1,65 +1,9 @@
 import path from "node:path";
-import { z } from "zod";
 import { TOOL_DEFINITION_MARKER, normalizeToolSchema } from "./tools.js";
 const TOOL_MODULE_EXTENSIONS = new Set([".mjs", ".js", ".cjs"]);
-const ANNOTATED_TOOL_EXPORT_PATTERN = /(?:\/\*\*?[\s\S]*?@tool[\s\S]*?\*\/\s*|\/\/[^\n]*@tool[^\n]*\n\s*)export\s+(?:async\s+)?(?:function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(|const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?:async\s*)?(?:function\b|\())/g;
-function asRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? value
-        : undefined;
-}
-function isSchemaLike(value) {
-    return typeof value === "object" && value !== null && typeof value.parse === "function";
-}
 function isToolDefinitionObject(value) {
     return typeof value === "object" && value !== null && value[TOOL_DEFINITION_MARKER] === true;
 }
-function buildSchemaFromShape(shape, description) {
-    const record = asRecord(shape);
-    if (!record) {
-        return null;
-    }
-    const schema = z.object(record);
-    return description ? schema.describe(description) : schema;
-}
-function readToolDescription(imported, implementationName, schema) {
-    const explicit = typeof imported[`${implementationName}Description`] === "string"
-        ? String(imported[`${implementationName}Description`])
-        : typeof imported.description === "string"
-            ? String(imported.description)
-            : undefined;
-    return explicit?.trim() || schema.description?.trim() || `Auto-discovered tool ${implementationName}`;
-}
-function resolveToolSchema(imported, implementationName, allowGenericExports) {
-    const namedSchema = imported[`${implementationName}Schema`];
-    if (isSchemaLike(namedSchema)) {
-        return namedSchema;
-    }
-    const namedShape = imported[`${implementationName}SchemaShape`];
-    const namedDescription = typeof imported[`${implementationName}Description`] === "string"
-        ? String(imported[`${implementationName}Description`])
-        : undefined;
-    const schemaFromNamedShape = buildSchemaFromShape(namedShape, namedDescription);
-    if (schemaFromNamedShape) {
-        return schemaFromNamedShape;
-    }
-    if (!allowGenericExports) {
-        return null;
-    }
-    const genericSchema = imported.schema;
-    if (isSchemaLike(genericSchema)) {
-        return genericSchema;
-    }
-    const genericShape = imported.schemaShape ?? imported.schema;
-    const genericDescription = typeof imported.description === "string" ? String(imported.description) : undefined;
-    return buildSchemaFromShape(genericShape, genericDescription);
-}
-function discoverExportedFunctionNames(imported) {
-    return Object.entries(imported)
-        .filter(([name, value]) => name !== "default" && typeof value === "function")
-        .map(([name]) => name)
-        .sort();
-}
 function discoverExportedToolObjectNames(imported) {
     return Object.entries(imported)
         .filter(([name, value]) => name !== "default" && isToolDefinitionObject(value))
@@ -82,46 +26,10 @@ function loadToolObjectDefinition(imported, exportName) {
 export function isSupportedToolModulePath(filePath) {
     return TOOL_MODULE_EXTENSIONS.has(path.extname(filePath));
 }
-export function discoverAnnotatedFunctionNames(sourceText) {
-    const matches = sourceText.matchAll(ANNOTATED_TOOL_EXPORT_PATTERN);
-    return Array.from(matches, (match) => match[1] ?? match[2]).filter((name) => Boolean(name));
-}
-export function discoverToolModuleDefinitions(sourceText, imported) {
-    const objectDefinitions = discoverExportedToolObjectNames(imported)
+export function discoverToolModuleDefinitions(_sourceText, imported) {
+    return discoverExportedToolObjectNames(imported)
         .map((exportName) => loadToolObjectDefinition(imported, exportName))
         .filter((definition) => Boolean(definition));
-    if (objectDefinitions.length > 0) {
-        return objectDefinitions;
-    }
-    const annotatedNames = new Set(discoverAnnotatedFunctionNames(sourceText));
-    const functionNames = discoverExportedFunctionNames(imported);
-    const allowGenericExports = functionNames.length === 1;
-    const discovered = [];
-    for (const implementationName of functionNames) {
-        const invoke = imported[implementationName];
-        if (typeof invoke !== "function") {
-            continue;
-        }
-        const schema = resolveToolSchema(imported, implementationName, allowGenericExports);
-        if (!schema && !annotatedNames.has(implementationName)) {
-            continue;
-        }
-        if (!schema) {
-            throw new Error(`Tool module must export ${implementationName}Schema, ${implementationName}SchemaShape, or generic schema/schemaShape metadata.`);
-        }
-        discovered.push({
-            implementationName,
-            invoke: invoke,
-            schema,
-            description: readToolDescription(imported, implementationName, schema),
-            retryable: typeof imported[`${implementationName}Retryable`] === "boolean"
-                ? imported[`${implementationName}Retryable`] === true
-                : typeof imported.retryable === "boolean"
-                    ? imported.retryable === true
-                    : undefined,
-        });
-    }
-    return discovered;
 }
 export function loadToolModuleDefinition(imported, implementationName) {
     for (const exportName of discoverExportedToolObjectNames(imported)) {
@@ -130,25 +38,5 @@ export function loadToolModuleDefinition(imported, implementationName) {
             return loaded;
         }
     }
-    const functionNames = discoverExportedFunctionNames(imported);
-    const allowGenericExports = functionNames.length === 1;
-    const invoke = imported[implementationName];
-    if (typeof invoke !== "function") {
-        throw new Error(`Tool module must export function ${implementationName}.`);
-    }
-    const schema = resolveToolSchema(imported, implementationName, allowGenericExports);
-    if (!schema) {
-        throw new Error(`Tool module must export ${implementationName}Schema, ${implementationName}SchemaShape, or generic schema/schemaShape metadata.`);
-    }
-    return {
-        implementationName,
-        invoke: invoke,
-        schema,
-        description: readToolDescription(imported, implementationName, schema),
-        retryable: typeof imported[`${implementationName}Retryable`] === "boolean"
-            ? imported[`${implementationName}Retryable`] === true
-            : typeof imported.retryable === "boolean"
-                ? imported.retryable === true
-                : undefined,
-    };
+    throw new Error(`Tool module must export a tool({...}) definition named ${implementationName}.`);
 }

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

@@ -17,5 +17,17 @@ export declare function readToolModuleItems(root: string): Promise<Array<{
     item: Record<string, unknown>;
     sourcePath: string;
 }>>;
+/**
+ * Load and merge workspace objects in deterministic order:
+ * 1) framework workspace defaults
+ * 2) overlay roots in order
+ * 3) workspaceRoot
+ *
+ * Merge semantics:
+ * - later sources override earlier sources
+ * - arrays are replaced, not concatenated
+ * - plain objects are merged recursively
+ * - scalars and non-plain objects are replaced
+ */
 export declare function loadWorkspaceObjects(workspaceRoot: string, options?: WorkspaceLoadOptions): Promise<WorkspaceObjects>;
 export {};

package/dist/workspace/object-loader.js

@@ -624,6 +624,18 @@ export async function readToolModuleItems(root) {
 function inferExecutionMode(item, current) {
     return resolveExecutionBackend(item, current);
 }
+/**
+ * Load and merge workspace objects in deterministic order:
+ * 1) framework workspace defaults
+ * 2) overlay roots in order
+ * 3) workspaceRoot
+ *
+ * Merge semantics:
+ * - later sources override earlier sources
+ * - arrays are replaced, not concatenated
+ * - plain objects are merged recursively
+ * - scalars and non-plain objects are replaced
+ */
 export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
     const refs = new Map();
     const mergedAgents = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.69",
+  "version": "0.0.71",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",