@botbotgo/agent-harness 0.0.345 → 0.0.347

package/dist/workspace/framework-contract-validation.js

@@ -1,8 +1,11 @@
-import { readFileSync } from "node:fs";
 import path from "node:path";
 import { validateSkillMetadata } from "../runtime/skills/skill-metadata.js";
 import { getAgentExecutionConfigValue } from "./support/agent-execution-config.js";
 import { resolvePromptValue } from "./support/workspace-ref-utils.js";
+const FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME = "general-purpose";
+const FRAMEWORK_AGENT_TOOL_NAMES = new Set(["task"]);
+const FRAMEWORK_EXECUTION_TOOL_NAMES = new Set(["write_todos", "read_todos"]);
+const TERMINAL_STATUS_VALUES = new Set(["completed", "blocked", "failed", "refused"]);
 function normalizeMode(mode) {
     if (mode === "warn" || mode === "error") {
         return mode;
@@ -29,7 +32,76 @@ function isWorkspaceOwnedPath(candidate, roots) {
 function addIssue(issues, code, message) {
     issues.push({ code, message });
 }
-function validateAgentContract(agent, referencedSubagentIds, issues) {
+function stripRefPrefix(value, prefix) {
+    return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+function resolveRefId(value) {
+    return stripRefPrefix(stripRefPrefix(value, "agent/"), "tool/");
+}
+function readBuiltinToolsConfig(agent) {
+    const value = getAgentExecutionConfigValue(agent, "builtinTools");
+    return typeof value === "object" && value && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function readExecutionContractConfig(agent) {
+    const value = getAgentExecutionConfigValue(agent, "executionContract");
+    return typeof value === "object" && value && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function collectAgentToolNames(agent, tools, ownsDelegation) {
+    const names = new Set(FRAMEWORK_EXECUTION_TOOL_NAMES);
+    if (ownsDelegation) {
+        for (const toolName of FRAMEWORK_AGENT_TOOL_NAMES) {
+            names.add(toolName);
+        }
+    }
+    for (const ref of agent.toolRefs) {
+        const tool = tools.get(resolveRefId(ref));
+        if (tool) {
+            names.add(tool.id);
+            names.add(tool.name);
+        }
+        names.add(resolveRefId(ref));
+    }
+    for (const binding of agent.toolBindings ?? []) {
+        const tool = tools.get(resolveRefId(binding.ref));
+        if (tool) {
+            names.add(tool.id);
+            names.add(tool.name);
+        }
+        names.add(resolveRefId(binding.ref));
+    }
+    for (const tool of agent.inlineTools ?? []) {
+        names.add(tool.id);
+        names.add(tool.name);
+    }
+    return names;
+}
+function hasDuplicateValues(values) {
+    return new Set(values).size !== values.length;
+}
+function readObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function validateResponseFormatTerminalStatus(agent, responseFormat, issues) {
+    const schema = readObject(responseFormat);
+    const properties = readObject(schema?.properties);
+    const statusProperty = readObject(properties?.status);
+    const required = Array.isArray(schema?.required) ? schema.required : [];
+    if (!statusProperty || !required.includes("status")) {
+        addIssue(issues, "agent.response_format.missing_terminal_status", `Agent ${agent.id} responseFormat must require a status field so parents can distinguish completed, blocked, failed, and refused terminal states.`);
+        return;
+    }
+    const statusEnum = Array.isArray(statusProperty.enum) ? statusProperty.enum : [];
+    if (!Array.from(TERMINAL_STATUS_VALUES).every((value) => statusEnum.includes(value))) {
+        addIssue(issues, "agent.response_format.incomplete_terminal_status_enum", `Agent ${agent.id} responseFormat status enum must include completed, blocked, failed, and refused.`);
+    }
+}
+function validateAgentContract(agent, referencedSubagentIds, tools, issues) {
     const description = agent.description.trim();
     const systemPrompt = resolvePromptValue(getAgentExecutionConfigValue(agent, "systemPrompt"), path.dirname(agent.sourcePath));
     const ownsDelegation = agent.subagentRefs.length > 0 || agent.subagentPathRefs.length > 0 || (agent.asyncSubagents?.length ?? 0) > 0;
@@ -38,45 +110,72 @@ function validateAgentContract(agent, referencedSubagentIds, issues) {
         || (agent.toolBindings?.length ?? 0) > 0
         || (agent.inlineTools?.length ?? 0) > 0;
     const responseFormat = getAgentExecutionConfigValue(agent, "responseFormat");
+    const builtinTools = readBuiltinToolsConfig(agent);
+    const executionContract = readExecutionContractConfig(agent);
+    const localSubagentNames = [
+        ...agent.subagentRefs.map(resolveRefId),
+        ...(agent.asyncSubagents ?? []).map((subagent) => subagent.name),
+    ];
+    if (agent.id === FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME) {
+        addIssue(issues, "agent.general_purpose.forbidden", `Agent ${agent.id} uses the reserved general-purpose subagent name. Define explicit specialists with narrow responsibilities instead.`);
+    }
+    for (const asyncSubagent of agent.asyncSubagents ?? []) {
+        if (asyncSubagent.name === FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME) {
+            addIssue(issues, "agent.general_purpose.forbidden", `Agent ${agent.id} defines async subagent ${asyncSubagent.name}. Define explicit specialists with narrow responsibilities instead.`);
+        }
+    }
+    if (localSubagentNames.includes(FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME)) {
+        addIssue(issues, "agent.general_purpose.forbidden", `Agent ${agent.id} references reserved subagent name ${FORBIDDEN_GENERAL_PURPOSE_SUBAGENT_NAME}. Define explicit specialists with narrow responsibilities instead.`);
+    }
+    if (hasDuplicateValues(localSubagentNames)) {
+        addIssue(issues, "agent.subagent.duplicate_name", `Agent ${agent.id} exposes duplicate subagent names. Each delegated capability must have one stable owner.`);
+    }
     if (description.length < 24) {
         addIssue(issues, "agent.description.too_short", `Agent ${agent.id} should use a more specific description that explains when it should be used.`);
     }
+    if (executionContract?.requiresPlan === true && builtinTools?.todos === false) {
+        addIssue(issues, "agent.execution_contract.plan_without_todos", `Agent ${agent.id} requires plan evidence but disables todo tools. Enable todo tools or remove config.executionContract.requiresPlan.`);
+    }
     if (ownsDelegation) {
+        if (hasTools) {
+            addIssue(issues, "agent.orchestrator.mixed_tool_surface", `Delegating agent ${agent.id} defines both subagents and direct tools. Keep routing agents focused on delegation, and move execution tools to specialist agents.`);
+        }
+        if (builtinTools?.modelExposed !== false) {
+            addIssue(issues, "agent.orchestrator.model_exposed_builtins", `Delegating agent ${agent.id} should set config.builtinTools.modelExposed: false so raw built-in tools do not compete with specialist routing.`);
+        }
         if (!systemPrompt?.trim()) {
             addIssue(issues, "agent.orchestrator.missing_prompt", `Delegating agent ${agent.id} should define a systemPrompt that explains decomposition, delegation, synthesis, and stop conditions.`);
         }
-        if (!/(delegate|delegation|subagent|decompose|synthesi|answer directly|parallel)/i.test(description)) {
-            addIssue(issues, "agent.orchestrator.description_boundary", `Delegating agent ${agent.id} description should make its delegation boundary explicit, for example when it should answer directly versus delegate.`);
-        }
     }
     if (isSubagent) {
         if (!systemPrompt?.trim()) {
             addIssue(issues, "agent.subagent.missing_prompt", `Subagent ${agent.id} should define a systemPrompt that makes its operating boundary and output contract explicit.`);
         }
-        if (!/(use this when|when the task|for .*?(analysis|research|search|debug|review|triage|inspection|extraction|comparison|validation|implementation))/i.test(description)) {
-            addIssue(issues, "agent.subagent.description_trigger", `Subagent ${agent.id} description should clarify when it should be delegated to and what narrow task class it owns.`);
-        }
         if (agent.executionMode === "deepagent" && hasTools && responseFormat === undefined) {
             addIssue(issues, "agent.subagent.deepagent.missing_response_format", `DeepAgents subagent ${agent.id} exposes tools, so it should define config.responseFormat to guarantee a stable task result for its parent agent.`);
         }
+        if (agent.executionMode === "deepagent" && hasTools && responseFormat !== undefined) {
+            validateResponseFormatTerminalStatus(agent, responseFormat, issues);
+        }
+        if (hasTools && agent.skillPathRefs.length === 0) {
+            addIssue(issues, "agent.subagent.tools_without_skills", `Subagent ${agent.id} exposes execution tools but no skills. Add skills that describe tool-selection workflows and boundaries.`);
+        }
+    }
+    const toolNames = collectAgentToolNames(agent, tools, ownsDelegation);
+    for (const skillPath of agent.skillPathRefs) {
+        const metadata = validateSkillMetadata(skillPath);
+        for (const allowedTool of metadata.allowedTools ?? []) {
+            if (!toolNames.has(allowedTool)) {
+                addIssue(issues, "agent.skill.allowed_tool_unavailable", `Agent ${agent.id} attaches skill ${metadata.name}, but that skill allows tool ${allowedTool} which is not available to the agent.`);
+            }
+        }
     }
-}
-function stripFrontmatter(document) {
-    return document.replace(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/, "");
 }
 function validateSkillContract(skillRoot, issues) {
     const metadata = validateSkillMetadata(skillRoot);
-    const document = readFileSync(path.join(skillRoot, "SKILL.md"), "utf8");
-    const body = stripFrontmatter(document);
     const skillName = metadata.name || path.basename(skillRoot);
-    if (!/(Use this skill when|Use this when)/i.test(body)) {
-        addIssue(issues, "skill.missing_trigger", `Skill ${skillName} should explain when it should be used, preferably with a clear "Use this skill when..." trigger.`);
-    }
-    if (!/(## Workflow|^## Workflow|^\d+\.\s)/m.test(body)) {
-        addIssue(issues, "skill.missing_workflow", `Skill ${skillName} should define an explicit workflow instead of only background prose.`);
-    }
-    if (!/(## Rules|Do not|Output|Caveat|Caveats)/i.test(body)) {
-        addIssue(issues, "skill.missing_boundaries", `Skill ${skillName} should include execution boundaries such as rules, non-goals, caveats, or output expectations.`);
+    if (!metadata.description?.trim()) {
+        addIssue(issues, "skill.description.missing", `Skill ${skillName} must define a frontmatter description so agents can compare its boundary without reading the whole document.`);
     }
 }
 function validateToolContract(tool, issues) {
@@ -85,9 +184,6 @@ function validateToolContract(tool, issues) {
         addIssue(issues, "tool.description.too_short", `Tool ${tool.id} should use a more specific description that explains invocation boundaries and argument expectations.`);
         return;
     }
-    if (!/(Use this when|Do not use|Before calling)/i.test(description)) {
-        addIssue(issues, "tool.description.missing_boundary", `Tool ${tool.id} description should describe when to call it and, ideally, when not to call it or what must be true before calling it.`);
-    }
 }
 export function validateFrameworkContracts(input) {
     const mode = normalizeMode(input.mode);
@@ -95,12 +191,12 @@ export function validateFrameworkContracts(input) {
         return;
     }
     const issues = [];
-    const referencedSubagentIds = new Set(input.agents.flatMap((agent) => agent.subagentRefs.map((ref) => ref.replace(/^agent\//, ""))));
+    const referencedSubagentIds = new Set(input.agents.flatMap((agent) => agent.subagentRefs.map(resolveRefId)));
     for (const agent of input.agents) {
         if (!isWorkspaceOwnedPath(agent.sourcePath, input.ownedRoots)) {
             continue;
         }
-        validateAgentContract(agent, referencedSubagentIds, issues);
+        validateAgentContract(agent, referencedSubagentIds, input.tools, issues);
     }
     for (const [skillName, skillRoot] of input.skillRegistry) {
         if (!isWorkspaceOwnedPath(skillRoot, input.ownedRoots)) {

package/dist/workspace/object-loader.js

@@ -29,6 +29,7 @@ const CONSUMED_AGENT_CONFIG_KEYS = [
     "filesystem",
     "builtinTools",
     "interactionMode",
+    "executionContract",
 ];
 const NON_AGENT_CONFIG_ITEM_KEYS = [
     "id",
@@ -65,6 +66,7 @@ const MIGRATED_AGENT_CONFIG_KEYS = [
     "filesystem",
     "builtinTools",
     "interactionMode",
+    "executionContract",
 ];
 function normalizeAgentItemForMerge(item) {
     const normalized = { ...item };
@@ -267,6 +269,7 @@ function readSharedAgentConfig(config) {
         ...(config.includeAgentName === "inline" ? { includeAgentName: "inline" } : {}),
         ...(config.version === "v1" || config.version === "v2" ? { version: config.version } : {}),
         ...(typeof config.filesystem === "object" && config.filesystem ? { filesystem: config.filesystem } : {}),
+        ...(typeof config.executionContract === "object" && config.executionContract ? { executionContract: config.executionContract } : {}),
         ...(backend ? { backend } : {}),
         ...(store ? { store } : {}),
         ...(middleware ? { middleware } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.345",
+  "version": "0.0.347",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",