@botbotgo/agent-harness 0.0.15 → 0.0.17

package/dist/contracts/types.d.ts

@@ -75,6 +75,7 @@ export type LangChainAgentParams = {
     systemPrompt?: string;
     responseFormat?: unknown;
     contextSchema?: unknown;
+    middleware?: Array<Record<string, unknown>>;
     description: string;
 };
 export type CompiledSubAgent = {
@@ -88,6 +89,7 @@ export type CompiledSubAgent = {
     memory?: string[];
     responseFormat?: unknown;
     contextSchema?: unknown;
+    middleware?: Array<Record<string, unknown>>;
 };
 export type DeepAgentParams = {
     model: CompiledModel;
@@ -95,6 +97,7 @@ export type DeepAgentParams = {
     systemPrompt?: string;
     responseFormat?: unknown;
     contextSchema?: unknown;
+    middleware?: Array<Record<string, unknown>>;
     description: string;
     subagents: CompiledSubAgent[];
     interruptOn?: Record<string, boolean | object>;

package/dist/runtime/agent-runtime-adapter.js

@@ -8,6 +8,7 @@ import { createAgent, humanInTheLoopMiddleware, initChatModel } from "langchain"
 import { extractEmptyAssistantMessageFailure, extractReasoningText, extractToolFallbackContext, extractVisibleOutput, isLikelyToolArgsObject, isToolCallParseFailure, STRICT_TOOL_JSON_INSTRUCTION, sanitizeVisibleText, tryParseJson, wrapResolvedModel, } from "./parsing/output-parsing.js";
 import { extractAgentStep, extractInterruptPayload, extractReasoningStreamOutput, extractTerminalStreamOutput, extractToolResult, normalizeTerminalOutputKey, readStreamDelta, } from "./parsing/stream-event-parsing.js";
 import { wrapToolForExecution } from "./tool-hitl.js";
+import { resolveDeclaredMiddleware } from "./declared-middleware.js";
 const AGENT_INTERRUPT_SENTINEL_PREFIX = "__agent_harness_interrupt__:";
 const MODEL_SAFE_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 function asObject(value) {
@@ -266,8 +267,15 @@ export class AgentRuntimeAdapter {
         }
         return this.compileInterruptOn(binding.langchainAgentParams?.tools ?? [], binding.agent.langchainAgentConfig?.interruptOn);
     }
-    resolveMiddleware(binding, interruptOn) {
-        const middleware = this.options.middlewareResolver ? this.options.middlewareResolver(binding) : [];
+    async resolveMiddleware(binding, interruptOn) {
+        const declarativeMiddleware = await resolveDeclaredMiddleware(binding.langchainAgentParams?.middleware ??
+            binding.deepAgentParams?.middleware, {
+            resolveModel: (model) => this.resolveModel(model),
+        });
+        const middleware = [
+            ...declarativeMiddleware,
+            ...(this.options.middlewareResolver ? this.options.middlewareResolver(binding) : []),
+        ];
         if (interruptOn && Object.keys(interruptOn).length > 0) {
             middleware.push(humanInTheLoopMiddleware({ interruptOn }));
         }
@@ -304,6 +312,9 @@ export class AgentRuntimeAdapter {
             interruptOn: this.compileInterruptOn(subagent.tools ?? [], subagent.interruptOn),
             responseFormat: subagent.responseFormat,
             contextSchema: subagent.contextSchema,
+            middleware: (await resolveDeclaredMiddleware(subagent.middleware, {
+                resolveModel: (model) => this.resolveModel(model),
+            })),
         })));
     }
     async create(binding) {
@@ -320,7 +331,7 @@ export class AgentRuntimeAdapter {
                 systemPrompt: binding.langchainAgentParams.systemPrompt,
                 responseFormat: binding.langchainAgentParams.responseFormat,
                 contextSchema: binding.langchainAgentParams.contextSchema,
-                middleware: this.resolveMiddleware(binding, interruptOn),
+                middleware: (await this.resolveMiddleware(binding, interruptOn)),
                 checkpointer: this.resolveCheckpointer(binding),
             });
         }
@@ -334,7 +345,7 @@ export class AgentRuntimeAdapter {
             systemPrompt: params.systemPrompt,
             responseFormat: params.responseFormat,
             contextSchema: params.contextSchema,
-            middleware: this.resolveMiddleware(binding),
+            middleware: (await this.resolveMiddleware(binding)),
             subagents: (await this.resolveSubagents(params.subagents)),
             checkpointer: this.resolveCheckpointer(binding),
             store: this.options.storeResolver?.(binding),

package/dist/runtime/declared-middleware.d.ts

@@ -0,0 +1,4 @@
+import type { CompiledModel } from "../contracts/types.js";
+export declare function resolveDeclaredMiddleware(middlewareConfigs: unknown[] | undefined, options: {
+    resolveModel: (model: CompiledModel) => Promise<unknown>;
+}): Promise<unknown[]>;

package/dist/runtime/declared-middleware.js

@@ -0,0 +1,56 @@
+import { modelCallLimitMiddleware, modelRetryMiddleware, summarizationMiddleware, todoListMiddleware, toolCallLimitMiddleware, toolRetryMiddleware, } from "langchain";
+function asMiddlewareConfig(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? { ...value } : null;
+}
+function requireKind(config) {
+    const kind = typeof config.kind === "string" ? config.kind.trim() : "";
+    if (!kind) {
+        throw new Error("Declarative middleware entries must include a non-empty kind");
+    }
+    return kind;
+}
+function omitKind(config) {
+    const { kind: _kind, ...rest } = config;
+    return rest;
+}
+export async function resolveDeclaredMiddleware(middlewareConfigs, options) {
+    const resolved = [];
+    for (const rawConfig of middlewareConfigs ?? []) {
+        const config = asMiddlewareConfig(rawConfig);
+        if (!config) {
+            continue;
+        }
+        const kind = requireKind(config);
+        const runtimeConfig = omitKind(config);
+        switch (kind) {
+            case "summarization": {
+                if (runtimeConfig.model && typeof runtimeConfig.model === "object" && runtimeConfig.model !== null && "id" in runtimeConfig.model) {
+                    runtimeConfig.model = await options.resolveModel(runtimeConfig.model);
+                }
+                if (runtimeConfig.model === undefined) {
+                    throw new Error("summarization middleware requires model or modelRef");
+                }
+                resolved.push(summarizationMiddleware(runtimeConfig));
+                break;
+            }
+            case "modelRetry":
+                resolved.push(modelRetryMiddleware(runtimeConfig));
+                break;
+            case "toolRetry":
+                resolved.push(toolRetryMiddleware(runtimeConfig));
+                break;
+            case "toolCallLimit":
+                resolved.push(toolCallLimitMiddleware(runtimeConfig));
+                break;
+            case "modelCallLimit":
+                resolved.push(modelCallLimitMiddleware(runtimeConfig));
+                break;
+            case "todoList":
+                resolved.push(todoListMiddleware(runtimeConfig));
+                break;
+            default:
+                throw new Error(`Unsupported declarative middleware kind ${kind}`);
+        }
+    }
+    return resolved;
+}

package/dist/runtime/inventory.d.ts

@@ -6,6 +6,11 @@ export type InventoryToolRecord = {
 export type InventorySkillRecord = {
     name: string;
     path: string;
+    description?: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    allowedTools?: string[];
 };
 export type InventoryAgentRecord = {
     id: string;

package/dist/runtime/inventory.js

@@ -1,4 +1,4 @@
-import { readSkillName } from "./support/skill-metadata.js";
+import { readSkillMetadata } from "./support/skill-metadata.js";
 function listHostBindings(workspace) {
     return Array.from(workspace.bindings.values()).filter((binding) => binding.harnessRuntime.hostFacing);
 }
@@ -13,10 +13,18 @@ function dedupeTools(tools) {
     return Array.from(deduped.values());
 }
 function toSkillRecords(skillPaths) {
-    return Array.from(new Set(skillPaths)).map((skillPath) => ({
-        name: readSkillName(skillPath),
-        path: skillPath,
-    }));
+    return Array.from(new Set(skillPaths)).map((skillPath) => {
+        const metadata = readSkillMetadata(skillPath);
+        return {
+            name: metadata.name,
+            path: skillPath,
+            description: metadata.description,
+            license: metadata.license,
+            compatibility: metadata.compatibility,
+            metadata: metadata.metadata,
+            allowedTools: metadata.allowedTools,
+        };
+    });
 }
 export function listAgentTools(workspace, agentId) {
     const binding = findAgentBinding(workspace, agentId);

package/dist/runtime/support/skill-metadata.d.ts

@@ -1 +1,11 @@
+export type SkillMetadata = {
+    name: string;
+    description?: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    allowedTools?: string[];
+};
+export declare function readSkillMetadata(skillPath: string): SkillMetadata;
+export declare function validateSkillMetadata(skillPath: string): SkillMetadata;
 export declare function readSkillName(skillPath: string): string;

package/dist/runtime/support/skill-metadata.js

@@ -1,34 +1,147 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
-const skillNameCache = new Map();
-function parseFrontmatterName(document) {
+import { parse } from "yaml";
+const skillMetadataCache = new Map();
+const skillValidationCache = new Map();
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function parseFrontmatterSource(document) {
     const match = document.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
-    if (!match) {
+    return match?.[1];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeMetadata(value, strict) {
+    if (value === undefined) {
         return undefined;
     }
-    const nameLine = match[1]
-        .split("\n")
-        .map((line) => line.trim())
-        .find((line) => line.startsWith("name:"));
-    if (!nameLine) {
+    if (!isRecord(value)) {
+        if (strict) {
+            throw new Error("metadata must be a string key-value map");
+        }
         return undefined;
     }
-    const value = nameLine.slice("name:".length).trim().replace(/^["']|["']$/g, "");
-    return value || undefined;
+    const normalized = Object.entries(value).reduce((acc, [key, item]) => {
+        if (typeof item === "string") {
+            acc[key] = item;
+        }
+        return acc;
+    }, {});
+    if (strict && Object.keys(normalized).length !== Object.keys(value).length) {
+        throw new Error("metadata values must all be strings");
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
-export function readSkillName(skillPath) {
-    const cached = skillNameCache.get(skillPath);
+function toAllowedTools(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const tools = value.split(/\s+/).filter(Boolean);
+    return tools.length > 0 ? tools : undefined;
+}
+function parseFrontmatter(document, strict = false) {
+    const source = parseFrontmatterSource(document);
+    if (!source) {
+        return undefined;
+    }
+    const parsed = parse(source);
+    if (!isRecord(parsed)) {
+        return undefined;
+    }
+    return {
+        name: typeof parsed.name === "string" ? parsed.name : "",
+        description: typeof parsed.description === "string" ? parsed.description : undefined,
+        license: typeof parsed.license === "string" ? parsed.license : undefined,
+        compatibility: typeof parsed.compatibility === "string" ? parsed.compatibility : undefined,
+        metadata: normalizeMetadata(parsed.metadata, strict),
+        allowedTools: toAllowedTools(parsed["allowed-tools"]),
+    };
+}
+function isLegacyBuiltinSkillName(name) {
+    return /^builtin\.[a-z0-9-]+$/.test(name);
+}
+function validateSkillName(name, skillPath) {
+    if (!name || name.length > 64) {
+        throw new Error(`Skill ${skillPath} must define a name between 1 and 64 characters`);
+    }
+    if (!SKILL_NAME_PATTERN.test(name) && !isLegacyBuiltinSkillName(name)) {
+        throw new Error(`Skill ${skillPath} has invalid name ${name}. Standard skill names must use lowercase letters, numbers, and single hyphens`);
+    }
+    if (SKILL_NAME_PATTERN.test(name) && path.basename(skillPath) !== name) {
+        throw new Error(`Skill ${skillPath} must use a directory name that matches its frontmatter name ${name}`);
+    }
+}
+function validateSkillDescription(description, skillPath) {
+    if (!description || !description.trim() || description.length > 1024) {
+        throw new Error(`Skill ${skillPath} must define a description between 1 and 1024 characters`);
+    }
+}
+function validateCompatibility(value, skillPath) {
+    if (value !== undefined && (!value.trim() || value.length > 500)) {
+        throw new Error(`Skill ${skillPath} compatibility must be between 1 and 500 characters when provided`);
+    }
+}
+function validateMetadata(metadata, skillPath) {
+    if (!metadata) {
+        return;
+    }
+    if (Object.keys(metadata).length === 0) {
+        throw new Error(`Skill ${skillPath} metadata must contain string key-value pairs when provided`);
+    }
+}
+function parseSkillMetadataFromDocument(document, skillPath, strict) {
+    const parsed = parseFrontmatter(document, strict);
+    if (!parsed) {
+        if (strict) {
+            throw new Error(`Skill ${skillPath} must contain YAML frontmatter in SKILL.md`);
+        }
+        return { name: path.basename(skillPath) };
+    }
+    const metadata = {
+        name: strict ? parsed.name : parsed.name || path.basename(skillPath),
+        description: parsed.description,
+        license: parsed.license,
+        compatibility: parsed.compatibility,
+        metadata: parsed.metadata,
+        allowedTools: parsed.allowedTools,
+    };
+    if (strict) {
+        validateSkillName(metadata.name, skillPath);
+        validateSkillDescription(metadata.description, skillPath);
+        validateCompatibility(metadata.compatibility, skillPath);
+        validateMetadata(metadata.metadata, skillPath);
+    }
+    return metadata;
+}
+export function readSkillMetadata(skillPath) {
+    const cached = skillMetadataCache.get(skillPath);
     if (cached) {
         return cached;
     }
-    let resolvedName = path.basename(skillPath);
+    const metadata = {
+        name: path.basename(skillPath),
+    };
     try {
         const document = readFileSync(path.join(skillPath, "SKILL.md"), "utf8");
-        resolvedName = parseFrontmatterName(document) ?? resolvedName;
+        Object.assign(metadata, parseSkillMetadataFromDocument(document, skillPath, false));
     }
     catch {
         // Fall back to the directory name when the skill doc cannot be read.
     }
-    skillNameCache.set(skillPath, resolvedName);
-    return resolvedName;
+    skillMetadataCache.set(skillPath, metadata);
+    return metadata;
+}
+export function validateSkillMetadata(skillPath) {
+    const cached = skillValidationCache.get(skillPath);
+    if (cached) {
+        return cached;
+    }
+    const document = readFileSync(path.join(skillPath, "SKILL.md"), "utf8");
+    const metadata = parseSkillMetadataFromDocument(document, skillPath, true);
+    skillValidationCache.set(skillPath, metadata);
+    skillMetadataCache.set(skillPath, metadata);
+    return metadata;
+}
+export function readSkillName(skillPath) {
+    return readSkillMetadata(skillPath).name;
 }

package/dist/workspace/agent-binding-compiler.js

@@ -30,6 +30,19 @@ function requireModel(models, ref, ownerId) {
     }
     return compileModel(model);
 }
+function compileMiddlewareConfigs(middleware, models, ownerId) {
+    if (!middleware || middleware.length === 0) {
+        return undefined;
+    }
+    return middleware.map((config) => {
+        const compiled = { ...config };
+        if (compiled.kind === "summarization" && typeof compiled.modelRef === "string") {
+            compiled.model = requireModel(models, compiled.modelRef, ownerId);
+            delete compiled.modelRef;
+        }
+        return compiled;
+    });
+}
 function resolveAgentRuntimeName(agent) {
     const baseName = agent.id;
     if (baseName.includes(".")) {
@@ -74,6 +87,7 @@ function buildSubagent(agent, workspaceRoot, models, tools, parentSkills, parent
         memory: ownMemory.length > 0 ? ownMemory : parentMemory,
         responseFormat: agent.deepAgentConfig?.responseFormat,
         contextSchema: agent.deepAgentConfig?.contextSchema,
+        middleware: compileMiddlewareConfigs(agent.deepAgentConfig?.middleware, models, agent.id),
     };
 }
 function resolveDirectPrompt(agent) {
@@ -152,6 +166,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             systemPrompt: resolveSystemPrompt(agent),
             responseFormat: agent.langchainAgentConfig?.responseFormat,
             contextSchema: agent.langchainAgentConfig?.contextSchema,
+            middleware: compileMiddlewareConfigs(agent.langchainAgentConfig?.middleware, models, agent.id),
             description: agent.description,
         };
         return {
@@ -168,6 +183,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             systemPrompt: resolveSystemPrompt(agent),
             responseFormat: agent.deepAgentConfig?.responseFormat,
             contextSchema: agent.deepAgentConfig?.contextSchema,
+            middleware: compileMiddlewareConfigs(agent.deepAgentConfig?.middleware, models, agent.id),
             description: agent.description,
             subagents: agent.subagentRefs.map((ref) => {
                 const subagent = agents.get(resolveRefId(ref));

package/dist/workspace/object-loader.js

@@ -174,6 +174,12 @@ function readSingleRef(value) {
     }
     return undefined;
 }
+function readMiddlewareArray(items) {
+    const middleware = toArray(items)
+        .filter((item) => typeof item === "object" && item !== null && !Array.isArray(item))
+        .map((item) => ({ ...item }));
+    return middleware.length > 0 ? middleware : undefined;
+}
 export function parseAgentItem(item, sourcePath) {
     const subagentRefs = readRefArray(item.subagents);
     const subagentPathRefs = readPathArray(item.subagents);
@@ -197,13 +203,15 @@ export function parseAgentItem(item, sourcePath) {
                 typeof item.interruptOn === "object" ||
                 typeof item.checkpointer === "object" ||
                 item.responseFormat !== undefined ||
-                item.contextSchema !== undefined
+                item.contextSchema !== undefined ||
+                item.middleware !== undefined
                 ? {
                     ...(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 } : {}),
                     ...(item.responseFormat !== undefined ? { responseFormat: item.responseFormat } : {}),
                     ...(item.contextSchema !== undefined ? { contextSchema: item.contextSchema } : {}),
+                    ...(readMiddlewareArray(item.middleware) ? { middleware: readMiddlewareArray(item.middleware) } : {}),
                 }
                 : {}),
         },
@@ -214,7 +222,8 @@ export function parseAgentItem(item, sourcePath) {
                 typeof item.checkpointer === "object" ||
                 typeof item.interruptOn === "object" ||
                 item.responseFormat !== undefined ||
-                item.contextSchema !== undefined
+                item.contextSchema !== undefined ||
+                item.middleware !== undefined
                 ? {
                     ...(typeof item.systemPrompt === "string" ? { systemPrompt: item.systemPrompt } : {}),
                     ...(typeof item.backend === "object" && item.backend ? { backend: item.backend } : {}),
@@ -223,6 +232,7 @@ export function parseAgentItem(item, sourcePath) {
                     ...(typeof item.interruptOn === "object" && item.interruptOn ? { interruptOn: item.interruptOn } : {}),
                     ...(item.responseFormat !== undefined ? { responseFormat: item.responseFormat } : {}),
                     ...(item.contextSchema !== undefined ? { contextSchema: item.contextSchema } : {}),
+                    ...(readMiddlewareArray(item.middleware) ? { middleware: readMiddlewareArray(item.middleware) } : {}),
                 }
                 : {}),
         },

package/dist/workspace/support/discovery.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { defaultResourceConfigRoot, defaultResourceSkillsRoot } from "../../resource/resource.js";
+import { validateSkillMetadata } from "../../runtime/support/skill-metadata.js";
 import { ensureExternalResourceSource, isDirectoryPath, isExternalSourceLocator, resolveExternalResourcePath, resolveResourcePackageRoot, } from "../../resource/sources.js";
 import { parseAgentItem, readYamlItems } from "../object-loader.js";
 function resolveBuiltinPath(kind, ref) {
@@ -93,6 +94,7 @@ export function discoverSkillPaths(rootRefs, workspaceRoot) {
             throw new Error(`Skill discovery root ${rootRef} does not exist`);
         }
         if (existsSync(path.join(root, "SKILL.md"))) {
+            validateSkillMetadata(root);
             discovered.set(path.basename(root), root);
             continue;
         }
@@ -102,6 +104,7 @@ export function discoverSkillPaths(rootRefs, workspaceRoot) {
             }
             const skillRoot = path.join(root, entry.name);
             if (existsSync(path.join(skillRoot, "SKILL.md"))) {
+                validateSkillMetadata(skillRoot);
                 discovered.set(entry.name, skillRoot);
             }
         }

package/dist/workspace/validate.js

@@ -1,4 +1,12 @@
 const allowedExecutionModes = new Set(["deepagent", "langchain-v1"]);
+const allowedMiddlewareKinds = new Set([
+    "summarization",
+    "modelRetry",
+    "toolRetry",
+    "toolCallLimit",
+    "modelCallLimit",
+    "todoList",
+]);
 function hasPromptContent(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
@@ -15,6 +23,25 @@ function validateCheckpointerConfig(agent) {
         throw new Error(`Agent ${agent.id} checkpointer.path is not supported for kind MemorySaver`);
     }
 }
+function validateMiddlewareConfig(agent) {
+    const middlewareConfigs = [
+        ...(agent.langchainAgentConfig?.middleware ?? []),
+        ...(agent.deepAgentConfig?.middleware ?? []),
+    ];
+    for (const config of middlewareConfigs) {
+        if (typeof config !== "object" || config === null || Array.isArray(config)) {
+            throw new Error(`Agent ${agent.id} middleware entries must be objects`);
+        }
+        const typed = config;
+        const kind = typeof typed.kind === "string" ? typed.kind : "";
+        if (!allowedMiddlewareKinds.has(kind)) {
+            throw new Error(`Agent ${agent.id} middleware kind ${kind || "(missing)"} is not supported`);
+        }
+        if (kind === "summarization" && typed.model === undefined && typeof typed.modelRef !== "string") {
+            throw new Error(`Agent ${agent.id} summarization middleware requires model or modelRef`);
+        }
+    }
+}
 export function validateAgent(agent) {
     if (!agent.id) {
         throw new Error(`Agent id is required in ${agent.sourcePath}`);
@@ -35,6 +62,7 @@ export function validateAgent(agent) {
         throw new Error(`Agent ${agent.id} must use deepagent execution when subagents are defined`);
     }
     validateCheckpointerConfig(agent);
+    validateMiddlewareConfig(agent);
 }
 export function validateTopology(agents) {
     const ids = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Agent Harness framework package",
   "type": "module",
   "packageManager": "npm@10.9.2",