@botbotgo/agent-harness 0.0.70 → 0.0.72

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

@@ -3,8 +3,14 @@ import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/inventory.js";
 import type { RequirementAssessmentOptions } from "./runtime/skill-requirements.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
+import type { PrepareWorkspaceMetadata, PrepareWorkspaceOptions } from "./workspace/bootstrap.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
+export type { PrepareWorkspaceMetadata, PrepareWorkspaceOptions };
 type CreateAgentHarnessOptions = {
+    /**
+     * Workspace loading behavior.
+     * overlayRoots are merged after framework defaults and before workspaceRoot.
+     */
     load?: WorkspaceLoadOptions;
     adapter?: RuntimeAdapterOptions;
 };
@@ -28,3 +34,4 @@ export declare function resolveApproval(runtime: AgentHarnessRuntime, options: R
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;
 export declare function createToolMcpServer(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
 export declare function serveToolsOverStdio(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
+export declare function prepareWorkspace(workspaceRoot: string, options?: PrepareWorkspaceOptions): Promise<PrepareWorkspaceMetadata>;

package/dist/api.js

@@ -1,5 +1,6 @@
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import { loadWorkspace } from "./workspace/compile.js";
+import { prepareWorkspace as prepareWorkspaceFromBootstrap } from "./workspace/bootstrap.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 export async function createAgentHarness(workspaceRoot = process.cwd(), options = {}) {
     const workspace = await loadWorkspace(workspaceRoot, options.load ?? {});
@@ -52,3 +53,6 @@ export async function createToolMcpServer(runtime, options) {
 export async function serveToolsOverStdio(runtime, options) {
     return runtime.serveToolsOverStdio(options);
 }
+export function prepareWorkspace(workspaceRoot, options) {
+    return prepareWorkspaceFromBootstrap(workspaceRoot, options);
+}

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

@@ -1,3 +1,3 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getRun, getThread, listAgentSkills, listApprovals, listRuns, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, prepareWorkspace, createToolMcpServer, deleteThread, describeInventory, getApproval, getRun, getThread, listAgentSkills, listApprovals, listRuns, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getRun, getThread, listAgentSkills, listApprovals, listRuns, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, prepareWorkspace, createToolMcpServer, deleteThread, describeInventory, getApproval, getRun, getThread, listAgentSkills, listApprovals, listRuns, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export { tool } from "./tools.js";

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.71";

package/dist/package-version.js

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

package/dist/workspace/bootstrap.d.ts

@@ -0,0 +1,29 @@
+type WorkspaceBootstrapOptions = {
+    sourceConfigRoot?: string;
+    sourceResourcesRoot?: string;
+    removePatterns?: string[];
+    postCopyRemoveFiles?: string[];
+    lock?: {
+        enabled?: boolean;
+        path?: string;
+        maxAttempts?: number;
+        retryDelayMs?: number;
+    };
+    operations?: {
+        copy?: (source: string, destination: string) => Promise<void>;
+        remove?: (target: string) => Promise<void>;
+        mkdir?: (target: string) => Promise<void>;
+    };
+};
+export type PrepareWorkspaceOptions = WorkspaceBootstrapOptions;
+export type PrepareWorkspaceMetadata = {
+    workspaceRoot: string;
+    configRoot: string;
+    resourcesRoot: string;
+    sourceConfigRoot: string;
+    sourceResourcesRoot: string;
+    removed: string[];
+    copied: string[];
+};
+export declare function prepareWorkspace(workspaceRoot: string, options?: PrepareWorkspaceOptions): Promise<PrepareWorkspaceMetadata>;
+export {};

package/dist/workspace/bootstrap.js

@@ -0,0 +1,131 @@
+import { cp, mkdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const DEFAULT_REMOVE_PATTERNS = [
+    "direct.yaml",
+    "orchestra.yaml",
+    "runtime.yaml",
+    "agent.yaml",
+    "memory.yaml",
+    "model.yaml",
+    "tool.yaml",
+    "toolkit.yaml",
+    "agents",
+    "config",
+    "resources",
+];
+const DEFAULT_POST_COPY_REMOVE_FILES = ["agent.yaml", "memory.yaml", "model.yaml", "tool.yaml", "toolkit.yaml"];
+function resolveFrameworkRoot() {
+    const base = path.dirname(fileURLToPath(import.meta.url));
+    const resolved = path.resolve(base, "..", "..");
+    return resolved;
+}
+function resolveFrameworkConfigRoot() {
+    return path.join(resolveFrameworkRoot(), "config");
+}
+function resolveFrameworkResourcesRoot() {
+    return path.join(resolveFrameworkRoot(), "resources");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isErrnoCode(error, code) {
+    return error?.code === code;
+}
+async function exists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT")) {
+            return false;
+        }
+        throw error;
+    }
+}
+async function acquireWorkspaceBootstrapLock(lockPath, options) {
+    let attempt = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        try {
+            await mkdir(lockPath);
+            return async () => {
+                await rm(lockPath, { recursive: true, force: true });
+            };
+        }
+        catch (error) {
+            attempt += 1;
+            if (!isErrnoCode(error, "EEXIST") || attempt >= options.maxAttempts) {
+                throw new Error(`Failed to prepare workspace at ${lockPath}; lock was not released after ${attempt} attempts.`);
+            }
+            await sleep(options.retryDelayMs);
+        }
+    }
+}
+export async function prepareWorkspace(workspaceRoot, options = {}) {
+    const resolvedWorkspaceRoot = path.resolve(workspaceRoot);
+    const removePatterns = options.removePatterns && options.removePatterns.length > 0
+        ? [...new Set(options.removePatterns.map((entry) => entry.trim()).filter(Boolean))]
+        : [...DEFAULT_REMOVE_PATTERNS];
+    const postCopyRemoveFiles = options.postCopyRemoveFiles && options.postCopyRemoveFiles.length > 0
+        ? [...new Set(options.postCopyRemoveFiles.map((entry) => entry.trim()).filter(Boolean))]
+        : [...DEFAULT_POST_COPY_REMOVE_FILES];
+    const sourceConfigRoot = path.resolve(options.sourceConfigRoot ?? resolveFrameworkConfigRoot());
+    const sourceResourcesRoot = path.resolve(options.sourceResourcesRoot ?? resolveFrameworkResourcesRoot());
+    const configRoot = path.join(resolvedWorkspaceRoot, "config");
+    const resourcesRoot = path.join(resolvedWorkspaceRoot, "resources");
+    const lockOptions = options.lock?.enabled === false
+        ? null
+        : {
+            path: options.lock?.path ?? path.join(resolvedWorkspaceRoot, ".agent-harness-bootstrap.lock"),
+            maxAttempts: options.lock?.maxAttempts ?? 40,
+            retryDelayMs: options.lock?.retryDelayMs ?? 25,
+        };
+    const operations = {
+        copy: options.operations?.copy ?? ((source, destination) => cp(source, destination, { recursive: true, force: true })),
+        remove: options.operations?.remove ?? ((target) => rm(target, { recursive: true, force: true })),
+        mkdir: options.operations?.mkdir ?? ((target) => mkdir(target, { recursive: true })),
+    };
+    await operations.mkdir(resolvedWorkspaceRoot);
+    const lock = await (lockOptions
+        ? acquireWorkspaceBootstrapLock(lockOptions.path, lockOptions)
+        : async () => undefined);
+    const removed = [];
+    const copied = [];
+    try {
+        for (const pattern of removePatterns) {
+            const target = path.join(resolvedWorkspaceRoot, pattern);
+            removed.push(target);
+            await operations.remove(target);
+        }
+        await operations.mkdir(configRoot);
+        await operations.mkdir(path.join(configRoot, "agents"));
+        await operations.mkdir(resourcesRoot);
+        if (await exists(sourceConfigRoot)) {
+            await operations.copy(sourceConfigRoot, configRoot);
+            copied.push(configRoot);
+        }
+        if (await exists(sourceResourcesRoot)) {
+            await operations.copy(sourceResourcesRoot, resourcesRoot);
+            copied.push(resourcesRoot);
+        }
+        for (const file of postCopyRemoveFiles) {
+            await operations.remove(path.join(configRoot, file));
+        }
+        return {
+            workspaceRoot: resolvedWorkspaceRoot,
+            configRoot,
+            resourcesRoot,
+            sourceConfigRoot,
+            sourceResourcesRoot,
+            removed,
+            copied,
+        };
+    }
+    finally {
+        if (lockOptions) {
+            await lock();
+        }
+    }
+}

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