@botbotgo/agent-harness 0.0.70 → 0.0.71

package/README.md

@@ -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

package/README.zh.md

@@ -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

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.69";
+export declare const AGENT_HARNESS_VERSION = "0.0.70";

package/dist/package-version.js

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

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.70",
+  "version": "0.0.71",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",