@botbotgo/agent-harness 0.0.475 → 0.0.476

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

@@ -1,322 +1,2 @@
-import path from "node:path";
-import { validateSkillMetadata } from "../runtime/skills/skill-metadata.js";
-import { getAgentExecutionConfigValue } from "./support/agent-execution-config.js";
-import { getRuntimeAgentDefaults, getWorkspaceObject, resolvePromptValue } from "./support/workspace-ref-utils.js";
-const UPSTREAM_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;
-    }
-    return "off";
-}
-export function resolveFrameworkContractValidationMode(mode) {
-    if (mode === "warn" || mode === "error" || mode === "off") {
-        return mode;
-    }
-    const envValue = process.env.AGENT_HARNESS_FRAMEWORK_CONTRACT_VALIDATION?.trim().toLowerCase();
-    if (envValue === "warn" || envValue === "error" || envValue === "off") {
-        return envValue;
-    }
-    return "off";
-}
-function isPathWithinRoot(candidate, root) {
-    const relative = path.relative(path.resolve(root), path.resolve(candidate));
-    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-function isWorkspaceOwnedPath(candidate, roots) {
-    return roots.some((root) => isPathWithinRoot(candidate, root));
-}
-function addIssue(issues, code, message) {
-    issues.push({ code, message });
-}
-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 readRecoveryEvidenceToolName(value) {
-    if (typeof value === "string") {
-        return value.trim();
-    }
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return "";
-    }
-    const name = value.name;
-    return typeof name === "string" ? name.trim() : "";
-}
-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 normalizeResponseFormatRef(ref) {
-    return ref.startsWith("response-format/") ? ref : `response-format/${ref}`;
-}
-function resolveResponseFormatRef(refs, ref) {
-    if (!refs || !ref) {
-        return undefined;
-    }
-    const object = getWorkspaceObject(refs, normalizeResponseFormatRef(ref));
-    if (!object || object.kind !== "response-format") {
-        return undefined;
-    }
-    return object.value.format;
-}
-function mergeResponseFormats(base, override) {
-    if (override === undefined) {
-        return base;
-    }
-    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)) {
-            if (key === "required" && Array.isArray(merged.required) && Array.isArray(value)) {
-                merged.required = Array.from(new Set([...merged.required, ...value]));
-                continue;
-            }
-            if (key === "properties" &&
-                typeof merged.properties === "object" &&
-                merged.properties &&
-                !Array.isArray(merged.properties) &&
-                typeof value === "object" &&
-                value &&
-                !Array.isArray(value)) {
-                merged.properties = {
-                    ...merged.properties,
-                    ...value,
-                };
-                continue;
-            }
-            merged[key] = key in merged ? mergeResponseFormats(merged[key], value) : value;
-        }
-        return merged;
-    }
-    return override;
-}
-function resolveInheritedResponseFormat(agent, refs) {
-    if (!refs) {
-        return undefined;
-    }
-    const defaults = getRuntimeAgentDefaults(refs);
-    if (defaults && "responseFormat" in defaults) {
-        return defaults.responseFormat === null ? undefined : defaults.responseFormat;
-    }
-    const defaultRef = typeof defaults?.responseFormatRef === "string" ? defaults.responseFormatRef.trim() : "";
-    return defaultRef ? resolveResponseFormatRef(refs, defaultRef) : undefined;
-}
-function resolveEffectiveResponseFormat(agent, refs) {
-    const explicitResponseFormat = getAgentExecutionConfigValue(agent, "responseFormat");
-    if (explicitResponseFormat !== undefined) {
-        return explicitResponseFormat === null
-            ? undefined
-            : mergeResponseFormats(resolveInheritedResponseFormat(agent, refs), explicitResponseFormat);
-    }
-    const explicitRef = getAgentExecutionConfigValue(agent, "responseFormatRef");
-    if (typeof explicitRef === "string" && explicitRef.trim().length > 0) {
-        return resolveResponseFormatRef(refs, explicitRef.trim());
-    }
-    return resolveInheritedResponseFormat(agent, refs);
-}
-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, refs, 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;
-    const isSubagent = referencedSubagentIds.has(agent.id);
-    const hasTools = agent.toolRefs.length > 0
-        || (agent.toolBindings?.length ?? 0) > 0
-        || (agent.inlineTools?.length ?? 0) > 0;
-    const responseFormat = resolveEffectiveResponseFormat(agent, refs);
-    const builtinTools = readBuiltinToolsConfig(agent);
-    const executionContract = readExecutionContractConfig(agent);
-    const localSubagentNames = [
-        ...agent.subagentRefs.map(resolveRefId),
-        ...(agent.asyncSubagents ?? []).map((subagent) => subagent.name),
-    ];
-    const isDeepAgentsGeneralPurposeSubagentOverride = agent.executionMode === "deepagent"
-        && isSubagent
-        && agent.id === UPSTREAM_GENERAL_PURPOSE_SUBAGENT_NAME;
-    if (agent.id === UPSTREAM_GENERAL_PURPOSE_SUBAGENT_NAME && !isDeepAgentsGeneralPurposeSubagentOverride) {
-        addIssue(issues, "agent.general_purpose.forbidden", `Agent ${agent.id} uses the upstream DeepAgents general-purpose subagent name outside a DeepAgents subagent override. Define a product agent with a narrow runtime boundary instead.`);
-    }
-    for (const asyncSubagent of agent.asyncSubagents ?? []) {
-        if (asyncSubagent.name === UPSTREAM_GENERAL_PURPOSE_SUBAGENT_NAME) {
-            addIssue(issues, "agent.general_purpose.forbidden", `Agent ${agent.id} defines async subagent ${asyncSubagent.name}. DeepAgents reserves that name for its inline general-purpose subagent surface.`);
-        }
-    }
-    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.`);
-    }
-    const recoveryEvidenceToolName = readRecoveryEvidenceToolName(executionContract?.recoveryEvidenceTool);
-    if (recoveryEvidenceToolName) {
-        const toolNames = collectAgentToolNames(agent, tools, ownsDelegation);
-        if (FRAMEWORK_EXECUTION_TOOL_NAMES.has(recoveryEvidenceToolName) || !toolNames.has(recoveryEvidenceToolName)) {
-            addIssue(issues, "agent.execution_contract.invalid_recovery_evidence_tool", `Agent ${agent.id} config.executionContract.recoveryEvidenceTool must name one declared non-planning tool.`);
-        }
-    }
-    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.`);
-        }
-        const modelExposedBuiltins = builtinTools?.modelExposed;
-        const exposesOnlyTask = Array.isArray(modelExposedBuiltins)
-            && modelExposedBuiltins.length === 1
-            && modelExposedBuiltins[0] === "task";
-        if (modelExposedBuiltins !== false && !exposesOnlyTask) {
-            addIssue(issues, "agent.orchestrator.model_exposed_builtins", `Delegating agent ${agent.id} should expose only the task builtin or 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 (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 (agent.executionMode === "deepagent" && hasTools && responseFormat === undefined) {
-            addIssue(issues, "agent.subagent.deepagent.missing_response_format", `DeepAgents subagent ${agent.id} exposes tools, so it should inherit or define a 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 validateSkillContract(skillRoot, issues) {
-    const metadata = validateSkillMetadata(skillRoot);
-    const skillName = metadata.name || path.basename(skillRoot);
-    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) {
-    const description = tool.description.trim();
-    if (description.length < 20) {
-        addIssue(issues, "tool.description.too_short", `Tool ${tool.id} should use a more specific description that explains invocation boundaries and argument expectations.`);
-        return;
-    }
-}
-export function validateFrameworkContracts(input) {
-    const mode = normalizeMode(input.mode);
-    if (mode === "off") {
-        return;
-    }
-    const issues = [];
-    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, input.tools, input.refs, issues);
-    }
-    for (const [skillName, skillRoot] of input.skillRegistry) {
-        if (!isWorkspaceOwnedPath(skillRoot, input.ownedRoots)) {
-            continue;
-        }
-        validateSkillContract(skillRoot, issues);
-        if (!skillName.trim()) {
-            addIssue(issues, "skill.name.empty", `Skill ${skillRoot} must define a stable name in frontmatter.`);
-        }
-    }
-    for (const tool of input.tools.values()) {
-        if (!isWorkspaceOwnedPath(tool.sourcePath, input.ownedRoots)) {
-            continue;
-        }
-        validateToolContract(tool, issues);
-    }
-    if (issues.length === 0) {
-        return;
-    }
-    const message = [
-        "Framework contract validation failed.",
-        "The workspace should follow the agent-harness contract-writing guidance for agents, skills, and tools.",
-        ...issues.map((issue) => `- [${issue.code}] ${issue.message}`),
-    ].join("\n");
-    if (mode === "warn") {
-        console.warn(`[agent-harness] ${message}`);
-        return;
-    }
-    throw new Error(message);
-}
+import c from"node:path";import{validateSkillMetadata as x}from"../runtime/skills/skill-metadata.js";import{getAgentExecutionConfigValue as f}from"./support/agent-execution-config.js";import{getRuntimeAgentDefaults as O,getWorkspaceObject as M,resolvePromptValue as j}from"./support/workspace-ref-utils.js";const y="general-purpose",D=new Set(["task"]),E=new Set(["write_todos","read_todos"]),q=new Set(["completed","blocked","failed","refused"]);function W(e){return e==="warn"||e==="error"?e:"off"}function te(e){if(e==="warn"||e==="error"||e==="off")return e;const t=process.env.AGENT_HARNESS_FRAMEWORK_CONTRACT_VALIDATION?.trim().toLowerCase();return t==="warn"||t==="error"||t==="off"?t:"off"}function I(e,t){const o=c.relative(c.resolve(t),c.resolve(e));return o===""||!o.startsWith("..")&&!c.isAbsolute(o)}function A(e,t){return t.some(o=>I(e,o))}function i(e,t,o){e.push({code:t,message:o})}function S(e,t){return e.startsWith(t)?e.slice(t.length):e}function d(e){return S(S(e,"agent/"),"tool/")}function L(e){const t=f(e,"builtinTools");return typeof t=="object"&&t&&!Array.isArray(t)?t:void 0}function V(e){const t=f(e,"executionContract");return typeof t=="object"&&t&&!Array.isArray(t)?t:void 0}function U(e){if(typeof e=="string")return e.trim();if(typeof e!="object"||e===null||Array.isArray(e))return"";const t=e.name;return typeof t=="string"?t.trim():""}function T(e,t,o){const r=new Set(E);if(o)for(const n of D)r.add(n);for(const n of e.toolRefs){const s=t.get(d(n));s&&(r.add(s.id),r.add(s.name)),r.add(d(n))}for(const n of e.toolBindings??[]){const s=t.get(d(n.ref));s&&(r.add(s.id),r.add(s.name)),r.add(d(n.ref))}for(const n of e.inlineTools??[])r.add(n.id),r.add(n.name);return r}function B(e){return new Set(e).size!==e.length}function _(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)?e:void 0}function G(e){return e.startsWith("response-format/")?e:`response-format/${e}`}function v(e,t){if(!e||!t)return;const o=M(e,G(t));if(!(!o||o.kind!=="response-format"))return o.value.format}function $(e,t){if(t===void 0)return e;if(typeof e=="object"&&e&&typeof t=="object"&&t&&!Array.isArray(e)&&!Array.isArray(t)){const o={...e};for(const[r,n]of Object.entries(t)){if(r==="required"&&Array.isArray(o.required)&&Array.isArray(n)){o.required=Array.from(new Set([...o.required,...n]));continue}if(r==="properties"&&typeof o.properties=="object"&&o.properties&&!Array.isArray(o.properties)&&typeof n=="object"&&n&&!Array.isArray(n)){o.properties={...o.properties,...n};continue}o[r]=r in o?$(o[r],n):n}return o}return t}function F(e,t){if(!t)return;const o=O(t);if(o&&"responseFormat"in o)return o.responseFormat===null?void 0:o.responseFormat;const r=typeof o?.responseFormatRef=="string"?o.responseFormatRef.trim():"";return r?v(t,r):void 0}function K(e,t){const o=f(e,"responseFormat");if(o!==void 0)return o===null?void 0:$(F(e,t),o);const r=f(e,"responseFormatRef");return typeof r=="string"&&r.trim().length>0?v(t,r.trim()):F(e,t)}function z(e,t,o){const r=_(t),n=_(r?.properties),s=_(n?.status),l=Array.isArray(r?.required)?r.required:[];if(!s||!l.includes("status")){i(o,"agent.response_format.missing_terminal_status",`Agent ${e.id} responseFormat must require a status field so parents can distinguish completed, blocked, failed, and refused terminal states.`);return}const u=Array.isArray(s.enum)?s.enum:[];Array.from(q).every(m=>u.includes(m))||i(o,"agent.response_format.incomplete_terminal_status_enum",`Agent ${e.id} responseFormat status enum must include completed, blocked, failed, and refused.`)}function H(e,t,o,r,n){const s=e.description.trim(),l=j(f(e,"systemPrompt"),c.dirname(e.sourcePath)),u=e.subagentRefs.length>0||e.subagentPathRefs.length>0||(e.asyncSubagents?.length??0)>0,m=t.has(e.id),p=e.toolRefs.length>0||(e.toolBindings?.length??0)>0||(e.inlineTools?.length??0)>0,h=K(e,r),w=L(e),R=V(e),P=[...e.subagentRefs.map(d),...(e.asyncSubagents??[]).map(a=>a.name)],N=e.executionMode==="deepagent"&&m&&e.id===y;e.id===y&&!N&&i(n,"agent.general_purpose.forbidden",`Agent ${e.id} uses the upstream DeepAgents general-purpose subagent name outside a DeepAgents subagent override. Define a product agent with a narrow runtime boundary instead.`);for(const a of e.asyncSubagents??[])a.name===y&&i(n,"agent.general_purpose.forbidden",`Agent ${e.id} defines async subagent ${a.name}. DeepAgents reserves that name for its inline general-purpose subagent surface.`);B(P)&&i(n,"agent.subagent.duplicate_name",`Agent ${e.id} exposes duplicate subagent names. Each delegated capability must have one stable owner.`),s.length<24&&i(n,"agent.description.too_short",`Agent ${e.id} should use a more specific description that explains when it should be used.`),R?.requiresPlan===!0&&w?.todos===!1&&i(n,"agent.execution_contract.plan_without_todos",`Agent ${e.id} requires plan evidence but disables todo tools. Enable todo tools or remove config.executionContract.requiresPlan.`);const b=U(R?.recoveryEvidenceTool);if(b){const a=T(e,o,u);(E.has(b)||!a.has(b))&&i(n,"agent.execution_contract.invalid_recovery_evidence_tool",`Agent ${e.id} config.executionContract.recoveryEvidenceTool must name one declared non-planning tool.`)}if(u){p&&i(n,"agent.orchestrator.mixed_tool_surface",`Delegating agent ${e.id} defines both subagents and direct tools. Keep routing agents focused on delegation, and move execution tools to specialist agents.`);const a=w?.modelExposed,g=Array.isArray(a)&&a.length===1&&a[0]==="task";a!==!1&&!g&&i(n,"agent.orchestrator.model_exposed_builtins",`Delegating agent ${e.id} should expose only the task builtin or set config.builtinTools.modelExposed: false so raw built-in tools do not compete with specialist routing.`),l?.trim()||i(n,"agent.orchestrator.missing_prompt",`Delegating agent ${e.id} should define a systemPrompt that explains decomposition, delegation, synthesis, and stop conditions.`)}m&&(l?.trim()||i(n,"agent.subagent.missing_prompt",`Subagent ${e.id} should define a systemPrompt that makes its operating boundary and output contract explicit.`),e.executionMode==="deepagent"&&p&&h===void 0&&i(n,"agent.subagent.deepagent.missing_response_format",`DeepAgents subagent ${e.id} exposes tools, so it should inherit or define a responseFormat to guarantee a stable task result for its parent agent.`),e.executionMode==="deepagent"&&p&&h!==void 0&&z(e,h,n),p&&e.skillPathRefs.length===0&&i(n,"agent.subagent.tools_without_skills",`Subagent ${e.id} exposes execution tools but no skills. Add skills that describe tool-selection workflows and boundaries.`));const C=T(e,o,u);for(const a of e.skillPathRefs){const g=x(a);for(const k of g.allowedTools??[])C.has(k)||i(n,"agent.skill.allowed_tool_unavailable",`Agent ${e.id} attaches skill ${g.name}, but that skill allows tool ${k} which is not available to the agent.`)}}function X(e,t){const o=x(e),r=o.name||c.basename(e);o.description?.trim()||i(t,"skill.description.missing",`Skill ${r} must define a frontmatter description so agents can compare its boundary without reading the whole document.`)}function J(e,t){if(e.description.trim().length<20){i(t,"tool.description.too_short",`Tool ${e.id} should use a more specific description that explains invocation boundaries and argument expectations.`);return}}function oe(e){const t=W(e.mode);if(t==="off")return;const o=[],r=new Set(e.agents.flatMap(s=>s.subagentRefs.map(d)));for(const s of e.agents)A(s.sourcePath,e.ownedRoots)&&H(s,r,e.tools,e.refs,o);for(const[s,l]of e.skillRegistry)A(l,e.ownedRoots)&&(X(l,o),s.trim()||i(o,"skill.name.empty",`Skill ${l} must define a stable name in frontmatter.`));for(const s of e.tools.values())A(s.sourcePath,e.ownedRoots)&&J(s,o);if(o.length===0)return;const n=["Framework contract validation failed.","The workspace should follow the agent-harness contract-writing guidance for agents, skills, and tools.",...o.map(s=>`- [${s.code}] ${s.message}`)].join(`
+`);if(t==="warn"){console.warn(`[agent-harness] ${n}`);return}throw new Error(n)}export{te as resolveFrameworkContractValidationMode,oe as validateFrameworkContracts};

package/dist/workspace/index.js

@@ -1 +1 @@
-export { loadWorkspace } from "./compile.js";
+import{loadWorkspace as a}from"./compile.js";export{a as loadWorkspace};

package/dist/workspace/object-loader-paths.js

@@ -1,71 +1 @@
-import path from "node:path";
-import { existsSync, statSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { isExternalSourceLocator, resolveResourcePackageRoot } from "../resource/sources.js";
-export const CONVENTIONAL_OBJECT_DIRECTORIES = ["tools"];
-export const MODULE_AGENT_FILENAMES = ["agent.yaml", "agent.yml"];
-export const MODULE_TOOL_FILENAMES = ["tool.yaml", "tool.yml"];
-export const MODULE_TOOL_ENTRY_FILENAMES = ["index.mjs", "index.js", "index.cjs"];
-export function moduleCollectionRoot(root, kind) {
-    return path.join(root, "modules", kind);
-}
-function isModuleDefinitionPath(sourcePath, kind) {
-    const normalized = sourcePath.split(path.sep).join("/");
-    const suffix = kind === "agents" ? "/agent.yaml" : "/tool.yaml";
-    const altSuffix = kind === "agents" ? "/agent.yml" : "/tool.yml";
-    return normalized.includes(`/modules/${kind}/`) && (normalized.endsWith(suffix) || normalized.endsWith(altSuffix));
-}
-export function moduleRootForSourcePath(sourcePath, kind) {
-    if (!isModuleDefinitionPath(sourcePath, kind)) {
-        return undefined;
-    }
-    return path.dirname(sourcePath);
-}
-export function conventionalConfigRoot(root) {
-    if (path.basename(root) === "config" && existsSync(root) && statSync(root).isDirectory()) {
-        return root;
-    }
-    const candidate = path.join(root, "config");
-    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
-        return candidate;
-    }
-    return null;
-}
-function conventionalDirectoryRoots(root, relativeDir) {
-    const resourceRoot = resolveResourcePackageRoot(root);
-    const candidates = [
-        ...(resourceRoot ? [path.join(resourceRoot, relativeDir)] : []),
-        path.join(root, relativeDir),
-    ];
-    return Array.from(new Set(candidates));
-}
-export function conventionalPackageRoots(root, relativeDir) {
-    const resourceRoot = resolveResourcePackageRoot(root);
-    const candidates = resourceRoot ? [path.join(resourceRoot, relativeDir), resourceRoot] : [];
-    return Array.from(new Set(candidates));
-}
-export function conventionalObjectRoots(root) {
-    return CONVENTIONAL_OBJECT_DIRECTORIES.flatMap((directory) => conventionalDirectoryRoots(root, directory));
-}
-export function resolveFrameworkWorkspaceRoot(resolved) {
-    const baseName = path.basename(resolved);
-    if (baseName === "dist") {
-        return resolved;
-    }
-    if (baseName === "src") {
-        return path.dirname(resolved);
-    }
-    return resolved;
-}
-export function frameworkWorkspaceRoot() {
-    return resolveFrameworkWorkspaceRoot(fileURLToPath(new URL("..", import.meta.url)));
-}
-function isModuleRelativePathCandidate(value) {
-    return !path.isAbsolute(value) && !isExternalSourceLocator(value) && !value.includes("://");
-}
-export function resolveModuleRelativePath(value, moduleRoot) {
-    if (!moduleRoot || !isModuleRelativePathCandidate(value)) {
-        return value;
-    }
-    return path.resolve(moduleRoot, value);
-}
+import n from"node:path";import{existsSync as i,statSync as c}from"node:fs";import{fileURLToPath as u}from"node:url";import{isExternalSourceLocator as f,resolveResourcePackageRoot as s}from"../resource/sources.js";const l=["tools"],O=["agent.yaml","agent.yml"],g=["tool.yaml","tool.yml"],S=["index.mjs","index.js","index.cjs"];function j(o,t){return n.join(o,"modules",t)}function m(o,t){const e=o.split(n.sep).join("/"),r=t==="agents"?"/agent.yaml":"/tool.yaml",a=t==="agents"?"/agent.yml":"/tool.yml";return e.includes(`/modules/${t}/`)&&(e.endsWith(r)||e.endsWith(a))}function M(o,t){if(m(o,t))return n.dirname(o)}function N(o){if(n.basename(o)==="config"&&i(o)&&c(o).isDirectory())return o;const t=n.join(o,"config");return i(t)&&c(t).isDirectory()?t:null}function p(o,t){const e=s(o),r=[...e?[n.join(e,t)]:[],n.join(o,t)];return Array.from(new Set(r))}function _(o,t){const e=s(o),r=e?[n.join(e,t),e]:[];return Array.from(new Set(r))}function A(o){return l.flatMap(t=>p(o,t))}function d(o){const t=n.basename(o);return t==="dist"?o:t==="src"?n.dirname(o):o}function T(){return d(u(new URL("..",import.meta.url)))}function x(o){return!n.isAbsolute(o)&&!f(o)&&!o.includes("://")}function h(o,t){return!t||!x(o)?o:n.resolve(t,o)}export{l as CONVENTIONAL_OBJECT_DIRECTORIES,O as MODULE_AGENT_FILENAMES,S as MODULE_TOOL_ENTRY_FILENAMES,g as MODULE_TOOL_FILENAMES,N as conventionalConfigRoot,A as conventionalObjectRoots,_ as conventionalPackageRoots,T as frameworkWorkspaceRoot,j as moduleCollectionRoot,M as moduleRootForSourcePath,d as resolveFrameworkWorkspaceRoot,h as resolveModuleRelativePath};

package/dist/workspace/object-loader-readers.js

@@ -1,187 +1 @@
-export function toArray(value) {
-    return Array.isArray(value) ? value : [];
-}
-export function asObject(value) {
-    return typeof value === "object" && value ? value : undefined;
-}
-export function asMutableObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? { ...value }
-        : undefined;
-}
-export function cloneConfigValue(value) {
-    if (Array.isArray(value)) {
-        return value.map((item) => cloneConfigValue(item));
-    }
-    if (typeof value === "object" && value !== null) {
-        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneConfigValue(entry)]));
-    }
-    return value;
-}
-export function readRefArray(items) {
-    return toArray(items)
-        .map((item) => typeof item === "string"
-        ? item
-        : typeof item === "object" && item && "ref" in item
-            ? item.ref
-            : undefined)
-        .filter((item) => Boolean(item));
-}
-export function readStringRecord(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return undefined;
-    }
-    const entries = Object.entries(value)
-        .filter((entry) => typeof entry[1] === "string");
-    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
-}
-export function readAsyncSubAgentArray(items) {
-    return toArray(items)
-        .flatMap((item) => {
-        if (typeof item !== "object" || item === null || Array.isArray(item)) {
-            return [];
-        }
-        const typed = item;
-        const name = typeof typed.name === "string" ? typed.name.trim() : "";
-        const description = typeof typed.description === "string" ? typed.description.trim() : "";
-        const graphId = typeof typed.graphId === "string" ? typed.graphId.trim() : "";
-        if (!name || !description || !graphId) {
-            return [];
-        }
-        const headers = readStringRecord(typed.headers);
-        return [{
-                name,
-                description,
-                graphId,
-                ...(typeof typed.url === "string" && typed.url.trim().length > 0 ? { url: typed.url.trim() } : {}),
-                ...(headers ? { headers } : {}),
-            }];
-    });
-}
-export function readPrefixedRefArray(items, prefix) {
-    return toArray(items)
-        .map((item) => {
-        if (typeof item === "string") {
-            const value = item.trim();
-            if (!value) {
-                return undefined;
-            }
-            return value.startsWith(`${prefix}/`) ? value : `${prefix}/${value}`;
-        }
-        if (typeof item === "object" && item && "ref" in item && typeof item.ref === "string") {
-            const value = String(item.ref).trim();
-            return value || undefined;
-        }
-        return undefined;
-    })
-        .filter((item) => Boolean(item));
-}
-export function normalizeToolUsageOverrides(value) {
-    const record = asMutableObject(value);
-    if (!record) {
-        return undefined;
-    }
-    const directKeys = new Set(["config", "hitl", "retryable", "subprocess", "embeddingModel", "embeddingModelRef"]);
-    const directOverrides = {};
-    const configOverrides = {};
-    for (const [key, entry] of Object.entries(record)) {
-        if (directKeys.has(key)) {
-            directOverrides[key] = cloneConfigValue(entry);
-            continue;
-        }
-        configOverrides[key] = cloneConfigValue(entry);
-    }
-    return {
-        ...directOverrides,
-        ...(Object.keys(configOverrides).length > 0
-            ? {
-                config: {
-                    ...(asMutableObject(directOverrides.config) ?? {}),
-                    ...configOverrides,
-                },
-            }
-            : {}),
-    };
-}
-export function readToolBindingArray(items) {
-    return toArray(items)
-        .map((item) => {
-        if (typeof item === "string") {
-            return { ref: item };
-        }
-        if (typeof item !== "object" || !item || Array.isArray(item)) {
-            return undefined;
-        }
-        const entries = Object.entries(item);
-        if (entries.length !== 1 || typeof entries[0]?.[0] !== "string") {
-            throw new Error("Agent tools entries must be either a tool name string or a single-key override object");
-        }
-        const [ref, rawOverride] = entries[0];
-        const overrides = normalizeToolUsageOverrides(rawOverride);
-        return {
-            ref,
-            ...(overrides ? { overrides } : {}),
-        };
-    })
-        .filter((item) => Boolean(item));
-}
-export 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));
-}
-export function readStringArray(items) {
-    return toArray(items)
-        .filter((item) => typeof item === "string" && item.trim().length > 0)
-        .map((item) => item.trim());
-}
-export 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 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 readObjectArray(items) {
-    const records = toArray(items)
-        .filter((item) => typeof item === "object" && item !== null && !Array.isArray(item))
-        .map((item) => ({ ...item }));
-    return records.length > 0 ? records : undefined;
-}
-export function readMcpServerArray(items) {
-    const records = toArray(items)
-        .map((item) => {
-        if (typeof item === "string" && item.trim()) {
-            return { ref: item.startsWith("mcp/") ? item : `mcp/${item.trim()}` };
-        }
-        if (typeof item === "object" && item !== null && !Array.isArray(item)) {
-            return { ...item };
-        }
-        return undefined;
-    })
-        .filter((item) => Boolean(item));
-    return records.length > 0 ? records : undefined;
-}
-export function readCapabilities(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return undefined;
-    }
-    const typed = value;
-    const capabilities = {
-        ...(typeof typed.delegation === "boolean" ? { delegation: typed.delegation } : {}),
-        ...(typeof typed.memory === "boolean" ? { memory: typed.memory } : {}),
-    };
-    return Object.keys(capabilities).length > 0 ? capabilities : undefined;
-}
+function i(e){return Array.isArray(e)?e:[]}function y(e){return typeof e=="object"&&e?e:void 0}function d(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)?{...e}:void 0}function c(e){return Array.isArray(e)?e.map(r=>c(r)):typeof e=="object"&&e!==null?Object.fromEntries(Object.entries(e).map(([r,n])=>[r,c(n)])):e}function u(e){return i(e).map(r=>typeof r=="string"?r:typeof r=="object"&&r&&"ref"in r?r.ref:void 0).filter(r=>!!r)}function p(e){if(typeof e!="object"||e===null||Array.isArray(e))return;const r=Object.entries(e).filter(n=>typeof n[1]=="string");return r.length>0?Object.fromEntries(r):void 0}function g(e){return i(e).flatMap(r=>{if(typeof r!="object"||r===null||Array.isArray(r))return[];const n=r,t=typeof n.name=="string"?n.name.trim():"",f=typeof n.description=="string"?n.description.trim():"",o=typeof n.graphId=="string"?n.graphId.trim():"";if(!t||!f||!o)return[];const s=p(n.headers);return[{name:t,description:f,graphId:o,...typeof n.url=="string"&&n.url.trim().length>0?{url:n.url.trim()}:{},...s?{headers:s}:{}}]})}function l(e,r){return i(e).map(n=>{if(typeof n=="string"){const t=n.trim();return t?t.startsWith(`${r}/`)?t:`${r}/${t}`:void 0}if(typeof n=="object"&&n&&"ref"in n&&typeof n.ref=="string")return String(n.ref).trim()||void 0}).filter(n=>!!n)}function a(e){const r=d(e);if(!r)return;const n=new Set(["config","hitl","retryable","subprocess","embeddingModel","embeddingModelRef"]),t={},f={};for(const[o,s]of Object.entries(r)){if(n.has(o)){t[o]=c(s);continue}f[o]=c(s)}return{...t,...Object.keys(f).length>0?{config:{...d(t.config)??{},...f}}:{}}}function b(e){return i(e).map(r=>{if(typeof r=="string")return{ref:r};if(typeof r!="object"||!r||Array.isArray(r))return;const n=Object.entries(r);if(n.length!==1||typeof n[0]?.[0]!="string")throw new Error("Agent tools entries must be either a tool name string or a single-key override object");const[t,f]=n[0],o=a(f);return{ref:t,...o?{overrides:o}:{}}}).filter(r=>!!r)}function A(e){return i(e).map(r=>typeof r=="string"?r:typeof r=="object"&&r&&"path"in r&&typeof r.path=="string"?r.path:void 0).filter(r=>!!r)}function j(e){return i(e).filter(r=>typeof r=="string"&&r.trim().length>0).map(r=>r.trim())}function h(e){if(typeof e=="string"&&e.trim())return e;if(typeof e=="object"&&e&&"ref"in e&&typeof e.ref=="string")return e.ref}function x(e){const r=i(e).filter(n=>typeof n=="object"&&n!==null&&!Array.isArray(n)).map(n=>({...n}));return r.length>0?r:void 0}function O(e){const r=i(e).filter(n=>typeof n=="object"&&n!==null&&!Array.isArray(n)).map(n=>({...n}));return r.length>0?r:void 0}function S(e){const r=i(e).map(n=>{if(typeof n=="string"&&n.trim())return{ref:n.startsWith("mcp/")?n:`mcp/${n.trim()}`};if(typeof n=="object"&&n!==null&&!Array.isArray(n))return{...n}}).filter(n=>!!n);return r.length>0?r:void 0}function w(e){if(typeof e!="object"||e===null||Array.isArray(e))return;const r=e,n={...typeof r.delegation=="boolean"?{delegation:r.delegation}:{},...typeof r.memory=="boolean"?{memory:r.memory}:{}};return Object.keys(n).length>0?n:void 0}export{d as asMutableObject,y as asObject,c as cloneConfigValue,a as normalizeToolUsageOverrides,g as readAsyncSubAgentArray,w as readCapabilities,S as readMcpServerArray,x as readMiddlewareArray,O as readObjectArray,A as readPathArray,l as readPrefixedRefArray,u as readRefArray,h as readSingleRef,j as readStringArray,p as readStringRecord,b as readToolBindingArray,i as toArray};