@botbotgo/agent-harness 0.0.1

package/dist/workspace/object-loader.js

@@ -0,0 +1,405 @@
+import path from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { parseAllDocuments } from "yaml";
+import { fileExists, listFilesRecursive, readYamlOrJson } from "../utils/fs.js";
+const ROOT_AGENT_FILENAMES = [
+    "agent.yaml",
+    "agent.yml",
+    "orchestra.yaml",
+    "orchestra.yml",
+    "direct.yaml",
+    "direct.yml",
+    "research.yaml",
+    "research.yml",
+];
+const LEGACY_GLOBAL_AGENT_FILENAMES = ["agent.yaml", "agent.yml"];
+function frameworkConfigRoot() {
+    const resolved = fileURLToPath(new URL("../../config", import.meta.url));
+    const distSegment = `${path.sep}dist${path.sep}config`;
+    if (!resolved.includes(distSegment)) {
+        return resolved;
+    }
+    const sourceConfigRoot = resolved.replace(distSegment, `${path.sep}config`);
+    if (!existsSync(sourceConfigRoot)) {
+        return resolved;
+    }
+    try {
+        return statSync(sourceConfigRoot).mtimeMs >= statSync(resolved).mtimeMs ? sourceConfigRoot : resolved;
+    }
+    catch {
+        return sourceConfigRoot;
+    }
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asObject(value) {
+    return typeof value === "object" && value ? value : undefined;
+}
+function normalizeKind(kind) {
+    switch (kind) {
+        case "LangChainAgent":
+            return "langchain-agent";
+        case "DeepAgent":
+            return "deepagent";
+        case "FileStore":
+            return "file-store";
+        case "InMemoryStore":
+            return "in-memory-store";
+        case "RedisStore":
+            return "redis-store";
+        case "PostgresStore":
+            return "postgres-store";
+        case "SqliteSaver":
+            return "sqlite-saver";
+        case "FileCheckpointer":
+            return "file-checkpointer";
+        case "Checkpointer":
+            return "checkpointer";
+        case "Model":
+            return "model";
+        case "EmbeddingModel":
+            return "embedding-model";
+        case "VectorStore":
+            return "vector-store";
+        case "Backend":
+            return "backend";
+        case "Store":
+            return "store";
+        case "Memory":
+            return "memory";
+        case "Tool":
+            return "tool";
+        case "Skill":
+            return "skill";
+        case "Runtime":
+            return "runtime";
+        case "Prompt":
+            return "prompt";
+        default:
+            return kind;
+    }
+}
+export function normalizeYamlItem(item) {
+    const metadata = asObject(item.metadata);
+    const spec = asObject(item.spec);
+    const kind = typeof item.kind === "string" ? normalizeKind(item.kind) : undefined;
+    const name = typeof metadata?.name === "string" ? metadata.name : undefined;
+    const description = typeof metadata?.description === "string" ? metadata.description : undefined;
+    if (!spec && !metadata) {
+        return kind ? { ...item, kind } : item;
+    }
+    if (!spec && metadata) {
+        return {
+            ...item,
+            ...(description ? { description } : {}),
+            ...(name ? { id: name } : {}),
+            ...(kind ? { kind } : {}),
+        };
+    }
+    return {
+        ...(spec ?? {}),
+        ...(description ? { description } : {}),
+        ...(name ? { id: name } : {}),
+        ...(kind ? { kind } : {}),
+    };
+}
+function normalizeCatalogItem(item) {
+    if ("metadata" in item || "spec" in item || "path" in item || typeof item.name !== "string") {
+        return item;
+    }
+    const { name, description, kind, ...spec } = item;
+    return {
+        ...(typeof kind === "string" ? { kind } : {}),
+        metadata: {
+            name,
+            ...(typeof description === "string" ? { description } : {}),
+        },
+        spec,
+    };
+}
+function readRefArray(items) {
+    return toArray(items)
+        .map((item) => (typeof item === "object" && item && "ref" in item ? item.ref : undefined))
+        .filter((item) => Boolean(item));
+}
+function readPathArray(items) {
+    return toArray(items)
+        .map((item) => typeof item === "string"
+        ? item
+        : typeof item === "object" && item && "path" in item && typeof item.path === "string"
+            ? item.path
+            : undefined)
+        .filter((item) => Boolean(item));
+}
+function readSingleRef(value) {
+    if (typeof value === "string" && value.trim()) {
+        return value;
+    }
+    if (typeof value === "object" && value && "ref" in value && typeof value.ref === "string") {
+        return value.ref;
+    }
+    return undefined;
+}
+export function parseAgentItem(item, sourcePath) {
+    const subagentRefs = readRefArray(item.subagents);
+    const subagentPathRefs = readPathArray(item.subagents);
+    const kind = typeof item.kind === "string" ? item.kind : "agent";
+    const executionMode = String((kind === "langchain-agent" ? "langchain-v1" : undefined) ??
+        (kind === "deepagent" ? "deepagent" : undefined) ??
+        "deepagent");
+    return {
+        id: String(item.id),
+        executionMode: executionMode,
+        description: String(item.description ?? ""),
+        modelRef: readSingleRef(item.modelRef) ?? "",
+        runRoot: typeof item.runRoot === "string" ? item.runRoot : undefined,
+        toolRefs: readRefArray(item.tools),
+        skillPathRefs: readPathArray(item.skills),
+        memorySources: readPathArray(item.memory),
+        subagentRefs,
+        subagentPathRefs,
+        langchainAgentConfig: {
+            ...(typeof item.systemPrompt === "string" || typeof item.interruptOn === "object" || typeof item.checkpointer === "object"
+                ? {
+                    ...(typeof item.systemPrompt === "string" ? { systemPrompt: item.systemPrompt } : {}),
+                    ...(typeof item.interruptOn === "object" && item.interruptOn ? { interruptOn: item.interruptOn } : {}),
+                    ...(typeof item.checkpointer === "object" && item.checkpointer ? { checkpointer: item.checkpointer } : {}),
+                }
+                : {}),
+        },
+        deepAgentConfig: {
+            ...(typeof item.systemPrompt === "string" ||
+                typeof item.backend === "object" ||
+                typeof item.store === "object" ||
+                typeof item.checkpointer === "object" ||
+                typeof item.interruptOn === "object"
+                ? {
+                    ...(typeof item.systemPrompt === "string" ? { systemPrompt: item.systemPrompt } : {}),
+                    ...(typeof item.backend === "object" && item.backend ? { backend: item.backend } : {}),
+                    ...(typeof item.store === "object" && item.store ? { store: item.store } : {}),
+                    ...(typeof item.checkpointer === "object" && item.checkpointer ? { checkpointer: item.checkpointer } : {}),
+                    ...(typeof item.interruptOn === "object" && item.interruptOn ? { interruptOn: item.interruptOn } : {}),
+                }
+                : {}),
+        },
+        sourcePath,
+    };
+}
+async function objectItemsFromDocument(document, sourcePath) {
+    if (typeof document !== "object" || !document) {
+        return [];
+    }
+    const items = document.items;
+    if (Array.isArray(items)) {
+        const records = [];
+        for (const item of items) {
+            if (typeof item !== "object" || !item) {
+                continue;
+            }
+            const typedItem = item;
+            if (typeof typedItem.path === "string" && typedItem.path.trim()) {
+                const referencedPath = path.isAbsolute(typedItem.path)
+                    ? typedItem.path
+                    : path.join(path.dirname(sourcePath), typedItem.path);
+                if (existsSync(referencedPath) && statSync(referencedPath).isDirectory()) {
+                    const discoveredItems = await readYamlItems(referencedPath, undefined, { recursive: true });
+                    records.push(...discoveredItems.map(({ item }) => item));
+                    continue;
+                }
+                const parsedDocuments = parseAllDocuments(await readYamlOrJson(referencedPath));
+                for (const parsedDocument of parsedDocuments) {
+                    records.push(...(await objectItemsFromDocument(parsedDocument.toJSON(), referencedPath)));
+                }
+                continue;
+            }
+            records.push(normalizeCatalogItem(typedItem));
+        }
+        return records;
+    }
+    return [document];
+}
+function parseWorkspaceObject(item, sourcePath) {
+    if (typeof item.id !== "string") {
+        return null;
+    }
+    const inferredKind = typeof item.kind === "string"
+        ? item.kind
+        : path.basename(sourcePath).replace(/\.(yaml|yml|json)$/i, "");
+    if (!inferredKind) {
+        return null;
+    }
+    return {
+        id: item.id,
+        kind: inferredKind,
+        sourcePath,
+        value: item,
+    };
+}
+function mergeValues(base, override) {
+    if (override === undefined) {
+        return base;
+    }
+    if (Array.isArray(base) && Array.isArray(override)) {
+        return override;
+    }
+    if (typeof base === "object" && base && typeof override === "object" && override && !Array.isArray(base) && !Array.isArray(override)) {
+        const merged = { ...base };
+        for (const [key, value] of Object.entries(override)) {
+            merged[key] = key in merged ? mergeValues(merged[key], value) : value;
+        }
+        return merged;
+    }
+    return override;
+}
+export async function readYamlItems(root, relativeDir, options = {}) {
+    const targetRoot = relativeDir ? path.join(root, relativeDir) : root;
+    if (!(await fileExists(targetRoot))) {
+        return [];
+    }
+    const files = options.recursive
+        ? await listFilesRecursive(targetRoot, ".yaml")
+        : (await readdir(targetRoot, { withFileTypes: true }))
+            .filter((entry) => entry.isFile() && /\.ya?ml$/i.test(entry.name))
+            .map((entry) => path.join(targetRoot, entry.name))
+            .sort();
+    const records = [];
+    for (const filePath of files) {
+        const parsedDocuments = parseAllDocuments(await readYamlOrJson(filePath));
+        for (const parsedDocument of parsedDocuments) {
+            for (const item of await objectItemsFromDocument(parsedDocument.toJSON(), filePath)) {
+                records.push({ item: normalizeYamlItem(item), sourcePath: filePath });
+            }
+        }
+    }
+    return records;
+}
+async function readNamedYamlItems(root, filenames) {
+    const records = [];
+    for (const filename of filenames) {
+        const filePath = path.join(root, filename);
+        if (!(await fileExists(filePath))) {
+            continue;
+        }
+        const parsedDocuments = parseAllDocuments(await readYamlOrJson(filePath));
+        for (const parsedDocument of parsedDocuments) {
+            for (const item of await objectItemsFromDocument(parsedDocument.toJSON(), filePath)) {
+                records.push({ item: normalizeYamlItem(item), sourcePath: filePath });
+            }
+        }
+    }
+    return records;
+}
+function isPrimaryAgentFile(sourcePath) {
+    const base = path.basename(sourcePath).toLowerCase();
+    return ROOT_AGENT_FILENAMES.includes(base);
+}
+function inferExecutionMode(item, current) {
+    const kind = typeof item.kind === "string" ? item.kind : typeof current?.kind === "string" ? current.kind : undefined;
+    if (kind === "langchain-agent") {
+        return "langchain-v1";
+    }
+    if (kind === "deepagent") {
+        return "deepagent";
+    }
+    return undefined;
+}
+function extractSharedAgentDefaults(item) {
+    const defaults = {};
+    for (const key of ["modelRef", "runRoot", "checkpointer", "interruptOn"]) {
+        if (key in item) {
+            defaults[key] = item[key];
+        }
+    }
+    return defaults;
+}
+function applySharedAgentDefaults(globalDefaults, defaultsByMode, item, current) {
+    const executionMode = inferExecutionMode(item, current);
+    const defaults = {
+        ...globalDefaults,
+        ...(executionMode ? defaultsByMode[executionMode] : {}),
+    };
+    const merged = { ...item };
+    for (const [key, value] of Object.entries(defaults)) {
+        if (key in merged) {
+            continue;
+        }
+        if (current && key in current) {
+            continue;
+        }
+        merged[key] = value;
+    }
+    return merged;
+}
+export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
+    const refs = new Map();
+    const mergedAgents = new Map();
+    const mergedObjects = new Map();
+    const roots = [frameworkConfigRoot(), ...(options.overlayRoots ?? []), workspaceRoot];
+    let sharedAgentDefaults = {};
+    let sharedAgentDefaultsByMode = {};
+    for (const root of roots) {
+        for (const { item, sourcePath } of await readNamedYamlItems(root, [...ROOT_AGENT_FILENAMES])) {
+            const id = typeof item.id === "string" ? item.id : undefined;
+            if (!id) {
+                continue;
+            }
+            const current = mergedAgents.get(id);
+            mergedAgents.set(id, {
+                item: current ? mergeValues(current.item, item) : item,
+                sourcePath,
+            });
+            const filename = path.basename(sourcePath).toLowerCase();
+            if (LEGACY_GLOBAL_AGENT_FILENAMES.includes(filename)) {
+                sharedAgentDefaults = mergeValues(sharedAgentDefaults, extractSharedAgentDefaults(item));
+            }
+            else {
+                const executionMode = inferExecutionMode(item, current?.item);
+                if (executionMode) {
+                    sharedAgentDefaultsByMode = {
+                        ...sharedAgentDefaultsByMode,
+                        [executionMode]: mergeValues(sharedAgentDefaultsByMode[executionMode] ?? {}, extractSharedAgentDefaults(item)),
+                    };
+                }
+            }
+        }
+        for (const { item, sourcePath } of await readYamlItems(root, "agents", { recursive: true })) {
+            const id = typeof item.id === "string" ? item.id : undefined;
+            if (!id) {
+                continue;
+            }
+            const current = mergedAgents.get(id);
+            const itemWithDefaults = applySharedAgentDefaults(sharedAgentDefaults, sharedAgentDefaultsByMode, item, current?.item);
+            mergedAgents.set(id, {
+                item: current ? mergeValues(current.item, itemWithDefaults) : itemWithDefaults,
+                sourcePath,
+            });
+        }
+        for (const { item, sourcePath } of (await readYamlItems(root)).filter(({ sourcePath: fullPath }) => !fullPath.includes(`${path.sep}agents${path.sep}`) && !isPrimaryAgentFile(fullPath))) {
+            const workspaceObject = parseWorkspaceObject(item, sourcePath);
+            if (!workspaceObject) {
+                continue;
+            }
+            const ref = `${workspaceObject.kind}/${workspaceObject.id}`;
+            const current = mergedObjects.get(ref);
+            mergedObjects.set(ref, {
+                item: current ? mergeValues(current.item, item) : item,
+                sourcePath,
+            });
+        }
+    }
+    const agents = Array.from(mergedAgents.values()).map(({ item, sourcePath }) => parseAgentItem(item, sourcePath));
+    for (const [ref, { item, sourcePath }] of mergedObjects) {
+        const workspaceObject = parseWorkspaceObject(item, sourcePath);
+        if (!workspaceObject) {
+            continue;
+        }
+        refs.set(ref, workspaceObject);
+    }
+    for (const agent of agents) {
+        refs.set(`agent/${agent.id}`, agent);
+    }
+    return { refs, agents };
+}

package/dist/workspace/resource-compilers.d.ts

@@ -0,0 +1,13 @@
+import type { CompiledEmbeddingModel, CompiledModel, CompiledVectorStore, ParsedEmbeddingModelObject, ParsedVectorStoreObject, CompiledTool, ParsedModelObject, ParsedToolObject, WorkspaceObject } from "../contracts/types.js";
+export declare function parseModelObject(object: WorkspaceObject): ParsedModelObject;
+export declare function parseEmbeddingModelObject(object: WorkspaceObject): ParsedEmbeddingModelObject;
+export declare function parseVectorStoreObject(object: WorkspaceObject): ParsedVectorStoreObject;
+export declare function validateModelObject(model: ParsedModelObject, models: Map<string, ParsedModelObject>): void;
+export declare function validateEmbeddingModelObject(model: ParsedEmbeddingModelObject): void;
+export declare function validateVectorStoreObject(vectorStore: ParsedVectorStoreObject): void;
+export declare function compileModel(model: ParsedModelObject): CompiledModel;
+export declare function compileVectorStore(vectorStore: ParsedVectorStoreObject): CompiledVectorStore;
+export declare function compileEmbeddingModel(model: ParsedEmbeddingModelObject): CompiledEmbeddingModel;
+export declare function parseToolObject(object: WorkspaceObject): ParsedToolObject;
+export declare function validateToolObject(tool: ParsedToolObject, tools: Map<string, ParsedToolObject>): void;
+export declare function compileTool(tool: ParsedToolObject, tools: Map<string, ParsedToolObject>): CompiledTool[];

package/dist/workspace/resource-compilers.js

@@ -0,0 +1,182 @@
+import { compileToolWithRegistry, validateToolWithRegistry } from "../extensions.js";
+function asObject(value) {
+    return typeof value === "object" && value ? value : undefined;
+}
+function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function asRefArray(value) {
+    return toArray(value)
+        .map((item) => typeof item === "string" ? item : typeof item === "object" && item && "ref" in item ? String(item.ref) : undefined)
+        .filter((item) => Boolean(item));
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function parseHitlPolicy(value) {
+    const record = asObject(value);
+    if (!record) {
+        return undefined;
+    }
+    const enabled = record.enabled === true;
+    const allow = Array.isArray(record.allow)
+        ? record.allow.filter((item) => item === "approve" || item === "edit" || item === "reject")
+        : undefined;
+    return {
+        enabled,
+        allow: allow && allow.length > 0 ? allow : undefined,
+    };
+}
+export function parseModelObject(object) {
+    const value = object.value;
+    const provider = String(value.provider ?? "").trim();
+    const model = String((value.model ?? value.name) ?? "").trim();
+    const init = asObject(value.init) ?? {};
+    const fallbacks = Array.isArray(value.fallbacks)
+        ? value.fallbacks
+            .map((item) => (typeof item === "object" && item && "ref" in item ? String(item.ref) : undefined))
+            .filter((item) => Boolean(item))
+        : [];
+    return {
+        id: object.id,
+        provider,
+        model,
+        init,
+        clientRef: typeof value.clientRef === "string" ? value.clientRef : undefined,
+        fallbacks,
+        metadata: asObject(value.metadata),
+        sourcePath: object.sourcePath,
+    };
+}
+export function parseEmbeddingModelObject(object) {
+    const value = object.value;
+    const provider = String(value.provider ?? "").trim();
+    const model = String((value.model ?? value.name) ?? "").trim();
+    const init = asObject(value.init) ?? {};
+    return {
+        id: object.id,
+        provider,
+        model,
+        init,
+        clientRef: typeof value.clientRef === "string" ? value.clientRef : undefined,
+        metadata: asObject(value.metadata),
+        sourcePath: object.sourcePath,
+    };
+}
+export function parseVectorStoreObject(object) {
+    const value = object.value;
+    return {
+        id: object.id,
+        kind: String(value.storeKind ?? value.kind ?? "LibSQLVectorStore").trim(),
+        url: typeof value.url === "string" ? value.url : undefined,
+        authToken: typeof value.authToken === "string" ? value.authToken : undefined,
+        table: typeof value.table === "string" ? value.table : undefined,
+        column: typeof value.column === "string" ? value.column : undefined,
+        embeddingModelRef: typeof value.embeddingModelRef === "string"
+            ? value.embeddingModelRef
+            : typeof asObject(value.embeddingModel)?.ref === "string"
+                ? String(asObject(value.embeddingModel)?.ref)
+                : undefined,
+        metadata: asObject(value.metadata),
+        sourcePath: object.sourcePath,
+    };
+}
+export function validateModelObject(model, models) {
+    if (!model.provider) {
+        throw new Error(`Model ${model.id} provider must not be empty`);
+    }
+    if (!model.model) {
+        throw new Error(`Model ${model.id} model must not be empty`);
+    }
+    for (const fallback of model.fallbacks) {
+        const targetId = fallback.split("/").slice(1).join("/");
+        if (!models.has(targetId)) {
+            throw new Error(`Model ${model.id} fallback ${fallback} does not exist`);
+        }
+    }
+}
+export function validateEmbeddingModelObject(model) {
+    if (!model.provider) {
+        throw new Error(`Embedding model ${model.id} provider must not be empty`);
+    }
+    if (!model.model) {
+        throw new Error(`Embedding model ${model.id} model must not be empty`);
+    }
+}
+export function validateVectorStoreObject(vectorStore) {
+    if (!vectorStore.kind) {
+        throw new Error(`Vector store ${vectorStore.id} kind must not be empty`);
+    }
+    if ((vectorStore.kind === "LibSQLVectorStore" || vectorStore.kind === "LlamaIndexSimpleVectorStore") && !vectorStore.url) {
+        throw new Error(`Vector store ${vectorStore.id} url must not be empty for ${vectorStore.kind}`);
+    }
+}
+export function compileModel(model) {
+    return {
+        id: model.id,
+        provider: model.provider,
+        model: model.model,
+        init: model.init,
+        clientRef: model.clientRef,
+        fallbacks: model.fallbacks,
+        runtimeValue: `${model.provider}:${model.model}`,
+    };
+}
+export function compileVectorStore(vectorStore) {
+    return {
+        id: vectorStore.id,
+        kind: vectorStore.kind,
+        url: vectorStore.url,
+        authToken: vectorStore.authToken,
+        table: vectorStore.table,
+        column: vectorStore.column,
+        embeddingModelRef: vectorStore.embeddingModelRef,
+        runtimeValue: vectorStore.kind,
+    };
+}
+export function compileEmbeddingModel(model) {
+    return {
+        id: model.id,
+        provider: model.provider,
+        model: model.model,
+        init: model.init,
+        clientRef: model.clientRef,
+        runtimeValue: `${model.provider}:${model.model}`,
+    };
+}
+export function parseToolObject(object) {
+    const value = object.value;
+    const backend = asObject(value.backend);
+    const mcp = asObject(value.mcp);
+    const bundleRefs = asRefArray(value.refs ?? value.bundle);
+    const inferredType = typeof value.type === "string"
+        ? value.type
+        : bundleRefs.length > 0
+            ? "bundle"
+            : backend || mcp
+                ? "backend"
+                : "function";
+    return {
+        id: object.id,
+        type: String(inferredType),
+        name: String(value.name ?? "").trim(),
+        description: String(value.description ?? "").trim(),
+        config: asObject(value.config),
+        inputSchemaRef: typeof asObject(value.inputSchema)?.ref === "string" ? String(asObject(value.inputSchema)?.ref) : undefined,
+        backendOperation: typeof backend?.operation === "string"
+            ? backend.operation
+            : typeof value.operation === "string"
+                ? value.operation
+                : undefined,
+        mcpRef: typeof mcp?.ref === "string" ? mcp.ref : undefined,
+        bundleRefs,
+        hitl: parseHitlPolicy(value.hitl),
+        sourcePath: object.sourcePath,
+    };
+}
+export function validateToolObject(tool, tools) {
+    validateToolWithRegistry(tool, tools);
+}
+export function compileTool(tool, tools) {
+    return compileToolWithRegistry(tool, tools);
+}

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

@@ -0,0 +1,5 @@
+import type { ParsedAgentObject } from "../../contracts/types.js";
+export declare function ensureDiscoverySources(locators: string[], workspaceRoot: string): Promise<void>;
+export declare function resolveDiscoveryRoot(ref: string, workspaceRoot: string, kind: "skills" | "subagents"): string;
+export declare function discoverSkillPaths(rootRefs: string[], workspaceRoot: string): string[];
+export declare function discoverSubagents(agents: ParsedAgentObject[], workspaceRoot: string): Promise<ParsedAgentObject[]>;