@botbotgo/agent-harness 0.0.335 → 0.0.337

package/README.md

@@ -534,10 +534,19 @@ import { createAgentHarness } from "@botbotgo/agent-harness";
 const runtime = await createAgentHarness("/path/to/workspace", {
   load: {
     overlayRoots: ["/path/to/framework-defaults", "/path/to/product-overrides"],
+    frameworkContractValidation: "warn",
   },
 });
 ```
 
+Framework contract validation modes:
+
+- `off` keeps startup behavior unchanged
+- `warn` loads the workspace and emits contract-quality warnings for workspace-owned agents, skills, and tools
+- `error` fails startup when those workspace-owned definitions drift away from the framework contract
+
+You can also control the same startup behavior with `AGENT_HARNESS_FRAMEWORK_CONTRACT_VALIDATION=warn|error|off`.
+
 ### Run A Request
 
 ```ts

package/dist/contracts/workspace.d.ts

@@ -314,4 +314,5 @@ export type WorkspaceLoadOptions = {
      */
     overlayRoots?: string[];
     resources?: string[];
+    frameworkContractValidation?: "off" | "warn" | "error";
 };

package/dist/package-version.d.ts

@@ -1,2 +1,2 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.334";
+export declare const AGENT_HARNESS_VERSION = "0.0.336";
 export declare const AGENT_HARNESS_RELEASE_DATE = "2026-04-23";

package/dist/package-version.js

@@ -1,2 +1,2 @@
-export const AGENT_HARNESS_VERSION = "0.0.334";
+export const AGENT_HARNESS_VERSION = "0.0.336";
 export const AGENT_HARNESS_RELEASE_DATE = "2026-04-23";

package/dist/runtime/adapter/flow/stream-runtime.js

@@ -1,4 +1,4 @@
-import { extractVisibleOutput, isToolCallRecoveryFailure, isRetrySafeInvalidToolSelectionError, resolveExecutionWithoutToolEvidenceTextInstruction, shouldValidateExecutionWithoutToolEvidence, resolveToolCallRecoveryInstruction, sanitizeVisibleText, INVALID_TOOL_SELECTION_RECOVERY_INSTRUCTION, } from "../../parsing/output-parsing.js";
+import { extractVisibleOutput, isToolCallRecoveryFailure, isRetrySafeInvalidToolSelectionError, resolveExecutionWithoutToolEvidenceTextInstruction, shouldValidateExecutionWithoutToolEvidence, resolveToolCallRecoveryInstruction, sanitizeVisibleText, EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION, INVALID_TOOL_SELECTION_RECOVERY_INSTRUCTION, } from "../../parsing/output-parsing.js";
 import { buildInvocationRequest } from "../model/invocation-request.js";
 import { buildRawModelMessages } from "../model/message-assembly.js";
 import { projectRuntimeStreamEvent, createStreamEventProjectionState } from "../stream-event-projection.js";
@@ -79,11 +79,21 @@ function hasUnresolvedExecution(evidence) {
         || evidence.hasOpenTaskDelegation);
 }
 function hasMissingDelegatedExecutionEvidence(evidence) {
-    return evidence.hasDelegatedAgentWithConfiguredTools && !evidence.hasDelegatedExecutionToolEvidence;
+    return false;
 }
 function hasMissingDelegatedFindings(evidence) {
     return evidence.hasDelegatedAgentWithConfiguredTools && evidence.hasOnlyPlaceholderTaskCompletion;
 }
+function resolveDelegatedExecutionRecoveryInstruction(evidence) {
+    if (hasMissingDelegatedFindings(evidence)
+        || (evidence.hasOpenTaskDelegation
+            && evidence.hasDelegatedAgentWithConfiguredTools
+            && !evidence.hasPlanStateEvidence
+            && !evidence.hasFailedTaskDelegation)) {
+        return EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION;
+    }
+    return null;
+}
 function createUnresolvedExecutionError(evidence) {
     const reasons = [];
     if (evidence.hasIncompletePlanState) {
@@ -95,9 +105,6 @@ function createUnresolvedExecutionError(evidence) {
     if (evidence.hasOpenTaskDelegation) {
         reasons.push("delegated task has not finished");
     }
-    if (hasMissingDelegatedExecutionEvidence(evidence)) {
-        reasons.push("delegated agent ended without surfacing any real tool execution evidence");
-    }
     if (hasMissingDelegatedFindings(evidence)) {
         reasons.push("delegated task returned only the upstream placeholder result without surfaced final findings");
     }
@@ -400,7 +407,10 @@ export async function* streamRuntimeExecution(options) {
                 throw error;
             }
             const streamedExecutionEvidence = buildExecutionRecoveryEvidence({ projectionState });
-            if (hasUnresolvedExecution(streamedExecutionEvidence)) {
+            const delegatedExecutionRecoveryInstruction = !emittedUnsafeStreamSideEffects
+                ? resolveDelegatedExecutionRecoveryInstruction(streamedExecutionEvidence)
+                : null;
+            if (hasUnresolvedExecution(streamedExecutionEvidence) && !delegatedExecutionRecoveryInstruction) {
                 throw createUnresolvedExecutionError(streamedExecutionEvidence);
             }
             const executionWithoutToolEvidenceInstruction = projectionState.emittedOutput
@@ -411,7 +421,7 @@ export async function* streamRuntimeExecution(options) {
                 : null;
             const retryInstruction = !emittedUnsafeStreamSideEffects && sawRetrySafeInvalidToolSelectionError
                 ? INVALID_TOOL_SELECTION_RECOVERY_INSTRUCTION
-                : executionWithoutToolEvidenceInstruction;
+                : delegatedExecutionRecoveryInstruction ?? executionWithoutToolEvidenceInstruction;
             if (retryInstruction) {
                 let retried;
                 retried = await options.invoke(options.applyToolRecoveryInstruction(options.binding, retryInstruction), options.input, options.sessionId, options.runtimeOptions.requestId ?? options.sessionId, undefined, options.history, options.runtimeOptions);
@@ -609,7 +619,7 @@ export async function* streamRuntimeExecution(options) {
                 ...invokeExecutionEvidence,
                 hasMissingDelegatedExecutionEvidence: hasMissingDelegatedExecutionEvidence(invokeExecutionEvidence),
             })
-            : null;
+            : resolveDelegatedExecutionRecoveryInstruction(invokeExecutionEvidence);
         if (invokeFallbackRecoveryInstruction) {
             const recovered = await options.invoke(options.applyToolRecoveryInstruction(options.binding, invokeFallbackRecoveryInstruction), options.input, options.sessionId, options.runtimeOptions.requestId ?? options.sessionId, undefined, options.history, options.runtimeOptions);
             const recoveredToolResults = Array.isArray(recovered.metadata?.executedToolResults)

package/dist/runtime/adapter/invocation-result.js

@@ -17,19 +17,35 @@ function isPlaceholderTaskCompletion(value) {
     const normalized = sanitizeVisibleText(value).trim();
     return normalized === "Task completed";
 }
+function isLowSignalStructuredCompletion(value) {
+    const normalized = sanitizeVisibleText(value).trim();
+    if (!normalized) {
+        return false;
+    }
+    return /Status:\s*completed[\s\S]*Summary:\s*-\s*none[\s\S]*Likely Causes:\s*-\s*none[\s\S]*Blockers:\s*-\s*none[\s\S]*Next Commands:\s*-\s*none/i.test(normalized);
+}
 function normalizeToolOutputText(output) {
     const directText = typeof output === "string"
         ? sanitizeVisibleText(output).trim()
         : "";
-    if (directText && !looksLikeLeakedToolCallText(directText) && !isPlaceholderTaskCompletion(directText)) {
+    if (directText
+        && !looksLikeLeakedToolCallText(directText)
+        && !isPlaceholderTaskCompletion(directText)
+        && !isLowSignalStructuredCompletion(directText)) {
         return directText;
     }
     const visibleOutput = sanitizeVisibleText(extractVisibleOutput(output)).trim();
-    if (visibleOutput && !looksLikeLeakedToolCallText(visibleOutput) && !isPlaceholderTaskCompletion(visibleOutput)) {
+    if (visibleOutput
+        && !looksLikeLeakedToolCallText(visibleOutput)
+        && !isPlaceholderTaskCompletion(visibleOutput)
+        && !isLowSignalStructuredCompletion(visibleOutput)) {
         return visibleOutput;
     }
     const fallbackContext = sanitizeVisibleText(extractToolFallbackContext(output)).trim();
-    if (fallbackContext && !looksLikeLeakedToolCallText(fallbackContext) && !isPlaceholderTaskCompletion(fallbackContext)) {
+    if (fallbackContext
+        && !looksLikeLeakedToolCallText(fallbackContext)
+        && !isPlaceholderTaskCompletion(fallbackContext)
+        && !isLowSignalStructuredCompletion(fallbackContext)) {
         return fallbackContext;
     }
     return "";
@@ -72,7 +88,7 @@ export function resolveDeterministicFinalOutput(params) {
     const sanitizedVisibleOutput = visibleOutput && !looksLikeLeakedToolCallText(visibleOutput)
         ? sanitizeVisibleText(visibleOutput).trim()
         : "";
-    if (sanitizedVisibleOutput) {
+    if (sanitizedVisibleOutput && !isLowSignalStructuredCompletion(sanitizedVisibleOutput)) {
         return sanitizedVisibleOutput;
     }
     const successfulToolOutput = extractLatestSuccessfulNonTodoToolResultText(executedToolResults);
@@ -82,7 +98,7 @@ export function resolveDeterministicFinalOutput(params) {
     const sanitizedToolFallback = toolFallback && !looksLikeLeakedToolCallText(toolFallback)
         ? sanitizeVisibleText(toolFallback).trim()
         : "";
-    return sanitizedToolFallback;
+    return isLowSignalStructuredCompletion(sanitizedToolFallback) ? "" : sanitizedToolFallback;
 }
 export function extractDelegatedFindingsText(executedToolResults) {
     return extractLatestSuccessfulTaskResultText(executedToolResults);

package/dist/runtime/adapter/middleware-assembly.js

@@ -73,9 +73,6 @@ function hasIncompletePlanStateInValue(value) {
 function hasUnresolvedDelegatedExecution(state) {
     return state.hasIncompletePlanState || state.openTaskDelegations > 0;
 }
-function hasMissingDelegatedToolExecutionEvidence(state, subagentHasTools) {
-    return subagentHasTools && !state.emittedToolResult && !state.emittedToolError;
-}
 function formatDelegatedExecutionBlocker(state) {
     const summary = state.emittedOutput.trim();
     if (summary) {
@@ -90,7 +87,7 @@ function formatDelegatedExecutionBlocker(state) {
     return "Delegated investigation ended before the plan was completed.";
 }
 function requiresDelegatedExecutionRecovery(state) {
-    return hasUnresolvedDelegatedExecution(state) || (state.emittedToolResult && !state.emittedOutput.trim());
+    return hasUnresolvedDelegatedExecution(state);
 }
 const DELEGATED_FAILURE_PLAN_RECONCILIATION_INSTRUCTION = [
     "Your previous attempt ended with a tool failure while the todo board still had unfinished work.",
@@ -246,7 +243,6 @@ export async function invokeBuiltinTaskTool(input) {
         summarizationModel,
     });
     const resolvedSubagentTools = selectedSubagent.tools ?? input.resolveTools(primaryTools, input.binding);
-    const subagentHasTools = (resolvedSubagentTools?.length ?? 0) > 0;
     const runnable = createAgent({
         model: (selectedSubagent.model ?? resolvedHostModel),
         tools: resolvedSubagentTools,
@@ -297,17 +293,39 @@ export async function invokeBuiltinTaskTool(input) {
         };
         let { projectionState, executedToolResults } = await runWithStreamInspection();
         if (requiresDelegatedExecutionRecovery(projectionState)) {
+            const initialProjectionState = projectionState;
+            const initialExecutedToolResults = executedToolResults;
+            const initialDeterministicOutput = resolveDeterministicFinalOutput({
+                visibleOutput: initialProjectionState.emittedOutput.trim(),
+                executedToolResults: initialExecutedToolResults,
+            });
             const recoveryInstruction = projectionState.hasIncompletePlanState && projectionState.emittedToolError
                 ? `${AUTONOMOUS_INVESTIGATION_RECOVERY_INSTRUCTION}\n\n${DELEGATED_FAILURE_PLAN_RECONCILIATION_INSTRUCTION}`
                 : AUTONOMOUS_INVESTIGATION_RECOVERY_INSTRUCTION;
-            ({ projectionState, executedToolResults } = await runWithStreamInspection(recoveryInstruction));
+            const recovered = await runWithStreamInspection(recoveryInstruction);
+            const recoveredDeterministicOutput = resolveDeterministicFinalOutput({
+                visibleOutput: recovered.projectionState.emittedOutput.trim(),
+                executedToolResults: recovered.executedToolResults,
+            });
+            const recoveredHasSubstantiveExecution = recoveredDeterministicOutput.length > 0;
+            if (recoveredHasSubstantiveExecution) {
+                projectionState = recovered.projectionState;
+                executedToolResults = recovered.executedToolResults;
+            }
+            else {
+                projectionState = initialProjectionState;
+                executedToolResults = initialExecutedToolResults;
+                if (initialDeterministicOutput) {
+                    projectionState = {
+                        ...projectionState,
+                        emittedOutput: initialDeterministicOutput,
+                    };
+                }
+            }
         }
         if (requiresDelegatedExecutionRecovery(projectionState)) {
             throw new Error(formatDelegatedExecutionBlocker(projectionState));
         }
-        if (hasMissingDelegatedToolExecutionEvidence(projectionState, subagentHasTools)) {
-            throw new Error("Delegated investigation ended without any real tool execution evidence.");
-        }
         if (projectionState.emittedToolError) {
             const blockerMessage = resolveDeterministicFinalOutput({
                 visibleOutput: projectionState.emittedOutput.trim(),
@@ -335,12 +353,12 @@ export async function invokeBuiltinTaskTool(input) {
     if (hasIncompletePlanStateInValue(result)) {
         throw new Error(extractVisibleOutput(result) || extractToolFallbackContext(result) || "Delegated investigation ended before the plan was completed.");
     }
-    if (subagentHasTools) {
-        throw new Error("Delegated investigation ended without any real tool execution evidence.");
-    }
     const visibleOutput = extractVisibleOutput(result);
     const fallbackOutput = extractToolFallbackContext(result);
-    return visibleOutput || fallbackOutput || JSON.stringify(result);
+    const structuredResponse = typeof result === "object" && result !== null && "structuredResponse" in result
+        ? result.structuredResponse
+        : undefined;
+    return visibleOutput || fallbackOutput || (structuredResponse !== undefined ? JSON.stringify(structuredResponse) : "") || JSON.stringify(result);
 }
 export async function resolveBuiltinMiddlewareTools(input) {
     const backend = input.resolveBuiltinMiddlewareBackend(input.binding, input.options);

package/dist/runtime/adapter/stream-event-projection.js

@@ -210,9 +210,32 @@ function normalizeDelegatedFindingsText(value) {
         return "";
     }
     const normalized = sanitizeVisibleText(directText).trim();
-    return normalized === "Task completed" ? "" : normalized;
+    if (normalized === "Task completed") {
+        return "";
+    }
+    if (/Status:\s*completed[\s\S]*Summary:\s*-\s*none[\s\S]*Likely Causes:\s*-\s*none[\s\S]*Blockers:\s*-\s*none[\s\S]*Next Commands:\s*-\s*none/i.test(normalized)) {
+        return "";
+    }
+    return normalized;
+}
+function isInternalRuntimeSpillPathErrorValue(value) {
+    const directText = typeof value === "string"
+        ? value
+        : extractToolFallbackContext(value) || extractVisibleOutput(value) || readTextContent(value);
+    if (directText && /\/large_tool_results\/|internal runtime spill path/i.test(directText)) {
+        return true;
+    }
+    if (typeof value === "object" && value !== null) {
+        try {
+            return /\/large_tool_results\/|internal runtime spill path/i.test(JSON.stringify(value));
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
 }
-function recordDelegatedFindings(state, value) {
+function recordDelegatedFindings(state, value, source = "tool") {
     if (state.taskDelegationFindingsStack.length === 0) {
         return;
     }
@@ -220,6 +243,10 @@ function recordDelegatedFindings(state, value) {
     if (!normalized) {
         return;
     }
+    const current = state.taskDelegationFindingsStack[state.taskDelegationFindingsStack.length - 1] ?? "";
+    if (source === "terminal" && current) {
+        return;
+    }
     state.taskDelegationFindingsStack[state.taskDelegationFindingsStack.length - 1] = normalized;
 }
 function updateDelegationState(state, event, countConfiguredToolsForAgentId) {
@@ -315,36 +342,47 @@ export function projectRuntimeStreamEvent(params) {
     const toolResult = extractToolResult(event);
     if (toolResult) {
         const isTodoTool = toolResult.toolName === "write_todos" || toolResult.toolName === "read_todos";
-        const isSuccessfulTaskResult = toolResult.toolName === "task" && toolResult.isError !== true;
+        const salvagedTaskErrorFindings = toolResult.toolName === "task"
+            && toolResult.isError === true
+            && !!state.lastCompletedTaskDelegationFindings
+            && isInternalRuntimeSpillPathErrorValue(toolResult.output)
+            ? state.lastCompletedTaskDelegationFindings
+            : "";
+        const effectiveToolOutput = salvagedTaskErrorFindings || toolResult.output;
+        const effectiveToolIsError = salvagedTaskErrorFindings ? false : toolResult.isError;
+        const isSuccessfulTaskResult = toolResult.toolName === "task" && effectiveToolIsError !== true;
         const isDelegatedExecutionTool = (isDelegatedAgentEvent || state.openToolCapableTaskDelegations > 0)
             && toolResult.toolName !== "write_todos"
             && toolResult.toolName !== "read_todos"
             && toolResult.toolName !== "task";
         if (isDelegatedExecutionTool && toolResult.isError !== true) {
-            recordDelegatedFindings(state, toolResult.output);
+            recordDelegatedFindings(state, toolResult.output, "tool");
         }
-        const delegatedTaskFindings = isSuccessfulTaskResult && isUpstreamPlaceholderTaskResult(toolResult.output)
+        const delegatedTaskFindings = isSuccessfulTaskResult && state.lastCompletedTaskDelegationFindings
             ? state.lastCompletedTaskDelegationFindings
             : "";
-        const effectiveToolOutput = delegatedTaskFindings || toolResult.output;
+        const resolvedToolOutput = delegatedTaskFindings || effectiveToolOutput;
         const isPlaceholderTaskResult = isSuccessfulTaskResult
             && !delegatedTaskFindings
             && isUpstreamPlaceholderTaskResult(toolResult.output);
         state.emittedToolResult = true;
-        state.emittedToolError = state.emittedToolError || toolResult.isError === true;
-        state.emittedSuccessfulToolResult = state.emittedSuccessfulToolResult || toolResult.isError !== true;
+        state.emittedToolError = state.emittedToolError || effectiveToolIsError === true;
+        state.emittedSuccessfulToolResult = state.emittedSuccessfulToolResult || effectiveToolIsError !== true;
         state.emittedSuccessfulTaskResult = state.emittedSuccessfulTaskResult || isSuccessfulTaskResult;
         state.emittedPlaceholderTaskResult = state.emittedPlaceholderTaskResult || isPlaceholderTaskResult;
         state.emittedNonTodoToolResult = state.emittedNonTodoToolResult || !isTodoTool;
-        state.emittedSuccessfulNonTodoToolResult = state.emittedSuccessfulNonTodoToolResult || (!isTodoTool && toolResult.isError !== true);
-        state.emittedDelegatedExecutionToolResult = state.emittedDelegatedExecutionToolResult || isDelegatedExecutionTool;
+        state.emittedSuccessfulNonTodoToolResult = state.emittedSuccessfulNonTodoToolResult || (!isTodoTool && effectiveToolIsError !== true);
+        state.emittedDelegatedExecutionToolResult = state.emittedDelegatedExecutionToolResult || isDelegatedExecutionTool || !!salvagedTaskErrorFindings;
         state.emittedSuccessfulDelegatedExecutionToolResult =
-            state.emittedSuccessfulDelegatedExecutionToolResult || (isDelegatedExecutionTool && toolResult.isError !== true);
+            state.emittedSuccessfulDelegatedExecutionToolResult || (isDelegatedExecutionTool && effectiveToolIsError !== true) || !!salvagedTaskErrorFindings;
+        if (salvagedTaskErrorFindings) {
+            state.hasFailedTaskDelegation = false;
+        }
         chunks.push({
             kind: "tool-result",
             toolName: resolveModelFacingToolName(toolResult.toolName, toolNameMapping, primaryTools),
-            output: effectiveToolOutput,
-            isError: toolResult.isError,
+            output: resolvedToolOutput,
+            isError: effectiveToolIsError,
         });
         if (toolResult.toolName === "task") {
             state.lastCompletedTaskDelegationFindings = "";
@@ -355,7 +393,7 @@ export function projectRuntimeStreamEvent(params) {
         const delegatedTerminalOutput = extractTerminalStreamOutput(event);
         if (delegatedTerminalOutput) {
             state.emittedDelegatedTerminalOutput = true;
-            recordDelegatedFindings(state, delegatedTerminalOutput);
+            recordDelegatedFindings(state, delegatedTerminalOutput, "terminal");
         }
     }
     if (output && !shouldSuppressVisibleToolCallText(output)) {

package/dist/scaffold/init-project.js

@@ -406,7 +406,7 @@ kind: ToolSets
 spec:
   - name: web-search
     type: provider
-    description: ${options.provider} web search tool for current research.
+    description: Use this when the runtime needs current web discovery for research tasks. Do not use this as a substitute for synthesis or comparison.
     providerTool:
       provider: ${options.provider}
       tool: webSearch
@@ -421,7 +421,7 @@ function renderResearchAgentYaml(options) {
 kind: Agent
 metadata:
   name: research
-  description: Host-facing research agent for investigating and synthesizing answers.
+  description: Use this when a research request needs synthesis, bounded tool use, or specialist delegation. Answer directly when one pass is enough; delegate only when the sub-task boundary is clear.
 spec:
   runtime:
     runtimeMemory: default
@@ -447,7 +447,7 @@ function renderResearchAnalystYaml(options) {
 kind: Agent
 metadata:
   name: research-analyst
-  description: Analyst subagent for source gathering, comparison, and evidence extraction.
+  description: Use this when the task needs source gathering, comparison, and evidence extraction for a bounded research sub-task. Do not use this for final answer ownership.
 spec:
   runtime:
     runtimeMemory: default
@@ -494,6 +494,12 @@ ${stepTwo}
 3. Compare evidence instead of trusting a single source.
 4. Separate verified facts from inference.
 5. End with a concise synthesis, explicit caveats, and source links when available.
+
+## Rules
+
+- Do not rely on one source when the question requires comparison.
+- Do not present inference as a verified fact.
+- If current information is required, prefer fresh sources over model memory.
 `;
 }
 function renderStarterSkill(name) {

package/dist/workspace/compile.js

@@ -9,6 +9,7 @@ import { validateSkillMetadata } from "../runtime/skills/skill-metadata.js";
 import { parseEmbeddingModelObject, parseMcpServerObject, parseModelObject, parseToolObject, parseVectorStoreObject, validateEmbeddingModelObject, validateMcpServerObject, validateModelObject, validateToolObject, validateVectorStoreObject, } from "./resource-compilers.js";
 import { validateAgent, validateTopology } from "./validate.js";
 import { compileBinding } from "./agent-binding-compiler.js";
+import { resolveFrameworkContractValidationMode, validateFrameworkContracts, } from "./framework-contract-validation.js";
 import { discoverSubagents, ensureDiscoverySources } from "./support/discovery.js";
 import { collectAgentDiscoverySourceRefs, collectToolSourceRefs } from "./support/source-collectors.js";
 import { getRoutingDefaultAgentId, getRuntimeSources, getRuntimeResources, getRuntimeStorageRoots, getToolModuleDiscoveryConfig, getRoutingRules, resolveRefId, } from "./support/workspace-ref-utils.js";
@@ -412,6 +413,24 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
         externalResourceCount: externalResources.length,
     });
     validateToolNameConflicts(tools);
+    const frameworkContractValidation = resolveFrameworkContractValidationMode(options.frameworkContractValidation);
+    const contractOwnedRoots = Array.from(new Set([
+        workspaceRoot,
+        ...(localResourceRoot ? [localResourceRoot] : []),
+        ...resolvedConfiguredResources.map((resource) => resource.root),
+    ]));
+    await traceStartupStage("workspace.validate.frameworkContracts", async () => {
+        validateFrameworkContracts({
+            agents: loaded.agents,
+            tools,
+            skillRegistry,
+            ownedRoots: contractOwnedRoots,
+            mode: frameworkContractValidation,
+        });
+    }, {
+        workspaceRoot,
+        mode: frameworkContractValidation,
+    });
     const resources = Array.from(new Set([
         ...(localResourceRoot ? [localResourceRoot] : []),
         ...runtimeSources.tools.filter((source) => isNpmSourceUri(source)),

package/dist/workspace/framework-contract-validation.d.ts

@@ -0,0 +1,10 @@
+import type { ParsedAgentObject, ParsedToolObject } from "../contracts/types.js";
+export type FrameworkContractValidationMode = "off" | "warn" | "error";
+export declare function resolveFrameworkContractValidationMode(mode: FrameworkContractValidationMode | undefined): FrameworkContractValidationMode;
+export declare function validateFrameworkContracts(input: {
+    agents: ParsedAgentObject[];
+    tools: Map<string, ParsedToolObject>;
+    skillRegistry: Map<string, string>;
+    ownedRoots: string[];
+    mode?: FrameworkContractValidationMode;
+}): void;

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

@@ -0,0 +1,133 @@
+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";
+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 validateAgentContract(agent, referencedSubagentIds, 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 = getAgentExecutionConfigValue(agent, "responseFormat");
+    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 (ownsDelegation) {
+        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.`);
+        }
+    }
+}
+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.`);
+    }
+}
+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;
+    }
+    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);
+    if (mode === "off") {
+        return;
+    }
+    const issues = [];
+    const referencedSubagentIds = new Set(input.agents.flatMap((agent) => agent.subagentRefs.map((ref) => ref.replace(/^agent\//, ""))));
+    for (const agent of input.agents) {
+        if (!isWorkspaceOwnedPath(agent.sourcePath, input.ownedRoots)) {
+            continue;
+        }
+        validateAgentContract(agent, referencedSubagentIds, 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);
+}

package/package.json

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