@botbotgo/agent-harness 0.0.1

package/dist/workspace/support/discovery.js

@@ -0,0 +1,108 @@
+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 { parseAgentItem, readYamlItems } from "../object-loader.js";
+function resolveBuiltinPath(kind, ref) {
+    const normalized = ref.replace(/^builtin:\/\//, "").replace(/^\/+/, "");
+    if (kind === "skills") {
+        if (!normalized.startsWith("skills")) {
+            throw new Error(`Unsupported builtin skill discovery path ${ref}`);
+        }
+        const suffix = normalized.replace(/^skills\/?/, "");
+        return suffix ? path.join(builtinSkillsRoot(), suffix) : builtinSkillsRoot();
+    }
+    if (!normalized.startsWith("agents")) {
+        throw new Error(`Unsupported builtin subagent discovery path ${ref}`);
+    }
+    const suffix = normalized.replace(/^agents\/?/, "");
+    return suffix ? path.join(builtinConfigRoot(), "agents", suffix) : path.join(builtinConfigRoot(), "agents");
+}
+function preferPackageConvention(root, kind) {
+    const candidates = kind === "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;
+        }
+    }
+    return root;
+}
+export async function ensureDiscoverySources(locators, workspaceRoot) {
+    await Promise.all(Array.from(new Set(locators))
+        .filter((locator) => isExternalSourceLocator(locator))
+        .map((locator) => ensureExternalSource(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 path.resolve(workspaceRoot, ref);
+}
+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 path.resolve(workspaceRoot, ref);
+}
+export function discoverSkillPaths(rootRefs, workspaceRoot) {
+    const discovered = new Map();
+    for (const rootRef of rootRefs) {
+        const root = resolveDiscoveryRoot(rootRef, workspaceRoot, "skills");
+        if (!existsSync(root) || !statSync(root).isDirectory()) {
+            throw new Error(`Skill discovery root ${rootRef} does not exist`);
+        }
+        if (existsSync(path.join(root, "SKILL.md"))) {
+            discovered.set(path.basename(root), root);
+            continue;
+        }
+        for (const entry of readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const skillRoot = path.join(root, entry.name);
+            if (existsSync(path.join(skillRoot, "SKILL.md"))) {
+                discovered.set(entry.name, skillRoot);
+            }
+        }
+    }
+    return Array.from(discovered.values());
+}
+export async function discoverSubagents(agents, workspaceRoot) {
+    const discovered = new Map(agents.map((agent) => [agent.id, agent]));
+    const visitedRoots = new Set();
+    let cursor = 0;
+    const queue = [...agents];
+    while (cursor < queue.length) {
+        const agent = queue[cursor++];
+        for (const rootRef of agent.subagentPathRefs) {
+            const root = await resolveDiscoveryRootAsync(rootRef, workspaceRoot, "subagents");
+            const cacheKey = `${agent.id}:${root}`;
+            if (visitedRoots.has(cacheKey)) {
+                continue;
+            }
+            visitedRoots.add(cacheKey);
+            if (!existsSync(root) || !statSync(root).isDirectory()) {
+                throw new Error(`Subagent discovery root ${rootRef} does not exist`);
+            }
+            const discoveredRefs = [];
+            for (const { item, sourcePath } of await readYamlItems(root, undefined, { recursive: true })) {
+                const discoveredAgent = parseAgentItem(item, sourcePath);
+                discovered.set(discoveredAgent.id, discoveredAgent);
+                discoveredRefs.push(`agent/${discoveredAgent.id}`);
+                if (!queue.some((queued) => queued.id === discoveredAgent.id)) {
+                    queue.push(discoveredAgent);
+                }
+            }
+            agent.subagentRefs = Array.from(new Set([...agent.subagentRefs, ...discoveredRefs]));
+        }
+    }
+    return Array.from(discovered.values());
+}

package/dist/workspace/support/index.d.ts

@@ -0,0 +1,2 @@
+export { collectAgentDiscoverySourceRefs, collectToolSourceRefs } from "./source-collectors.js";
+export { compileAgentMemories, getRuntimeDefaults, getWorkspaceObject, resolvePathList, resolvePromptValue, resolveRefId, } from "./workspace-ref-utils.js";

package/dist/workspace/support/index.js

@@ -0,0 +1,2 @@
+export { collectAgentDiscoverySourceRefs, collectToolSourceRefs } from "./source-collectors.js";
+export { compileAgentMemories, getRuntimeDefaults, getWorkspaceObject, resolvePathList, resolvePromptValue, resolveRefId, } from "./workspace-ref-utils.js";

package/dist/workspace/support/source-collectors.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedAgentObject, ParsedToolObject, WorkspaceLoadOptions } from "../../contracts/types.js";
+export declare function collectToolSourceRefs(tools: Map<string, ParsedToolObject>, agents: ParsedAgentObject[], options: WorkspaceLoadOptions): string[];
+export declare function collectAgentDiscoverySourceRefs(agents: ParsedAgentObject[]): string[];

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

@@ -0,0 +1,30 @@
+import { isExternalSourceLocator } from "../../vendor/sources.js";
+export function collectToolSourceRefs(tools, agents, options) {
+    const refs = new Set(options.builtinSources ?? []);
+    for (const tool of tools.values()) {
+        for (const ref of tool.bundleRefs) {
+            if (isExternalSourceLocator(ref)) {
+                refs.add(ref);
+            }
+        }
+    }
+    for (const agent of agents) {
+        for (const ref of agent.toolRefs) {
+            if (isExternalSourceLocator(ref)) {
+                refs.add(ref);
+            }
+        }
+    }
+    return Array.from(refs);
+}
+export function collectAgentDiscoverySourceRefs(agents) {
+    const refs = new Set();
+    for (const agent of agents) {
+        for (const ref of [...agent.skillPathRefs, ...agent.subagentPathRefs]) {
+            if (isExternalSourceLocator(ref)) {
+                refs.add(ref);
+            }
+        }
+    }
+    return Array.from(refs);
+}

package/dist/workspace/support/workspace-ref-utils.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedAgentObject, WorkspaceObject } from "../../contracts/types.js";
+export declare function getWorkspaceObject(refs: Map<string, WorkspaceObject | ParsedAgentObject>, ref: string | undefined): WorkspaceObject | undefined;
+export declare function getRuntimeDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
+export declare function getRoutingSystemPrompt(refs: Map<string, WorkspaceObject | ParsedAgentObject>): string | undefined;
+export declare function resolvePromptValue(promptConfig: unknown): string | undefined;
+export declare function resolveRefId(ref: string): string;
+export declare function resolvePathList(refs: Map<string, WorkspaceObject | ParsedAgentObject>, workspaceRoot: string, refList: string[]): string[];
+export declare function compileAgentMemories(workspaceRoot: string, sources: string[]): string[];

package/dist/workspace/support/workspace-ref-utils.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+export function getWorkspaceObject(refs, ref) {
+    if (!ref) {
+        return undefined;
+    }
+    const object = refs.get(ref);
+    if (!object || "executionMode" in object) {
+        return undefined;
+    }
+    return object;
+}
+export function getRuntimeDefaults(refs) {
+    const runtimes = Array.from(refs.values()).filter((object) => !("executionMode" in object) && object.kind === "runtime");
+    if (runtimes.length === 0) {
+        return undefined;
+    }
+    if (runtimes.length > 1) {
+        throw new Error(`Expected at most one Runtime object, found ${runtimes.length}`);
+    }
+    return runtimes[0].value;
+}
+export function getRoutingSystemPrompt(refs) {
+    const runtimeDefaults = getRuntimeDefaults(refs);
+    const routing = typeof runtimeDefaults?.routing === "object" && runtimeDefaults.routing
+        ? runtimeDefaults.routing
+        : undefined;
+    return typeof routing?.systemPrompt === "string" && routing.systemPrompt.trim() ? routing.systemPrompt : undefined;
+}
+export function resolvePromptValue(promptConfig) {
+    if (typeof promptConfig === "string" && promptConfig.trim()) {
+        return promptConfig;
+    }
+    return undefined;
+}
+export function resolveRefId(ref) {
+    if (ref.startsWith("builtin/")) {
+        return ref;
+    }
+    return ref.split("/").slice(1).join("/");
+}
+export function resolvePathList(refs, workspaceRoot, refList) {
+    return refList.map((ref) => {
+        const object = getWorkspaceObject(refs, ref);
+        const maybePath = typeof object?.value.path === "string" ? object.value.path : resolveRefId(ref);
+        return path.isAbsolute(maybePath) ? maybePath : path.resolve(workspaceRoot, maybePath);
+    });
+}
+export function compileAgentMemories(workspaceRoot, sources) {
+    return sources.map((source) => (path.isAbsolute(source) ? source : path.resolve(workspaceRoot, source)));
+}

package/dist/workspace/validate.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedAgentObject } from "../contracts/types.js";
+export declare function validateAgent(agent: ParsedAgentObject): void;
+export declare function validateTopology(agents: ParsedAgentObject[]): void;

package/dist/workspace/validate.js

@@ -0,0 +1,65 @@
+const allowedExecutionModes = new Set(["deepagent", "langchain-v1"]);
+function hasPromptContent(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function validateCheckpointerConfig(agent) {
+    const checkpointer = (typeof agent.deepAgentConfig?.checkpointer === "object" && agent.deepAgentConfig.checkpointer) ||
+        (typeof agent.langchainAgentConfig?.checkpointer === "object" && agent.langchainAgentConfig.checkpointer);
+    if (!checkpointer) {
+        return;
+    }
+    const typedCheckpointer = checkpointer;
+    const kind = typeof typedCheckpointer.kind === "string" ? typedCheckpointer.kind : "FileCheckpointer";
+    const hasPath = typeof typedCheckpointer.path === "string" && typedCheckpointer.path.trim().length > 0;
+    if (kind === "MemorySaver" && hasPath) {
+        throw new Error(`Agent ${agent.id} checkpointer.path is not supported for kind MemorySaver`);
+    }
+}
+export function validateAgent(agent) {
+    if (!agent.id) {
+        throw new Error(`Agent id is required in ${agent.sourcePath}`);
+    }
+    if (!allowedExecutionModes.has(agent.executionMode)) {
+        throw new Error(`Agent ${agent.id} has unsupported execution mode ${agent.executionMode}`);
+    }
+    if (!agent.description.trim()) {
+        throw new Error(`Agent ${agent.id} description must not be empty`);
+    }
+    if (agent.executionMode === "langchain-v1" && (agent.subagentRefs.length > 0 || agent.subagentPathRefs.length > 0)) {
+        throw new Error(`Agent ${agent.id} cannot define subagents unless execution.mode is deepagent`);
+    }
+    if (agent.executionMode === "langchain-v1" && agent.memorySources.length > 0) {
+        throw new Error(`Agent ${agent.id} cannot define memory unless execution.mode is deepagent`);
+    }
+    if ((agent.subagentRefs.length > 0 || agent.subagentPathRefs.length > 0) && agent.executionMode !== "deepagent") {
+        throw new Error(`Agent ${agent.id} must use deepagent execution when subagents are defined`);
+    }
+    validateCheckpointerConfig(agent);
+}
+export function validateTopology(agents) {
+    const ids = new Set();
+    const referencedSubagentIds = new Set();
+    for (const agent of agents) {
+        if (ids.has(agent.id)) {
+            throw new Error(`Duplicate agent id ${agent.id}`);
+        }
+        ids.add(agent.id);
+        for (const ref of agent.subagentRefs) {
+            referencedSubagentIds.add(ref.replace(/^agent\//, ""));
+        }
+    }
+    for (const agent of agents) {
+        if (!referencedSubagentIds.has(agent.id) && !agent.modelRef) {
+            throw new Error(`Agent ${agent.id} modelRef is required`);
+        }
+        if (!referencedSubagentIds.has(agent.id)) {
+            continue;
+        }
+        if (agent.executionMode !== "deepagent") {
+            throw new Error(`Subagent ${agent.id} must use deepagent execution`);
+        }
+        if (!hasPromptContent(agent.deepAgentConfig?.systemPrompt)) {
+            throw new Error(`Subagent ${agent.id} requires deepagent.systemPrompt`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@botbotgo/agent-harness",
+  "version": "0.0.1",
+  "description": "Agent Harness framework package",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/botbotgo/agent-harness.git",
+    "directory": "packages/framework"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@botbotgo/agent-harness-builtin": "workspace:*"
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}