@botbotgo/agent-harness 0.0.361 → 0.0.362

package/dist/runtime/adapter/tool/builtin-middleware-tools.js

@@ -4,10 +4,33 @@ import { isSandboxBackend } from "deepagents";
 import { isRecord } from "../../../utils/object.js";
 import { formatBuiltinTodoSnapshot, isLowSignalTodoContent, summarizeBuiltinWriteTodosArgs, truncateLines } from "../runtime-adapter-support.js";
 import { maybePersistLargeToolOutput, resolveToolRuntimeContext } from "./tool-output-artifacts.js";
-const taskToolSchema = z.object({
-    description: z.string(),
-    subagent_type: z.string(),
-}).passthrough();
+function buildTaskToolDescription(subagents) {
+    const lines = [
+        "Delegate a bounded task to the subagent whose declared description best matches the task.",
+        "Use this only when a subagent is a better fit than the current agent. Set subagent_type to exactly one listed subagent name.",
+    ];
+    const available = (subagents ?? [])
+        .filter((subagent) => subagent.name.trim().length > 0)
+        .map((subagent) => {
+        const description = subagent.description.trim() || "No description provided.";
+        return `- ${subagent.name}: ${description}`;
+    });
+    return available.length > 0
+        ? [...lines, "", "Available subagents:", ...available].join("\n")
+        : lines.join(" ");
+}
+function buildTaskToolSchema(subagents) {
+    const names = (subagents ?? [])
+        .map((subagent) => subagent.name.trim())
+        .filter((name) => name.length > 0);
+    const subagentTypeSchema = names.length > 0
+        ? z.enum(names)
+        : z.string();
+    return z.object({
+        description: z.string().describe("Concrete bounded task for the selected subagent to perform."),
+        subagent_type: subagentTypeSchema.describe("Exact name of the selected subagent."),
+    }).passthrough();
+}
 export const BUILTIN_MIDDLEWARE_TOOL_DESCRIPTORS = [
     { name: "write_todos", description: "Create and update the runtime todo board for multi-step work." },
     { name: "read_todos", description: "Read the current runtime todo board." },
@@ -638,10 +661,11 @@ export async function createBuiltinMiddlewareTools(backend, options) {
         },
     });
     if (options.includeTaskTool && options.invokeTaskTool) {
+        const description = buildTaskToolDescription(options.taskSubagents);
         tools.set("task", {
             name: "task",
-            description: "Delegate a bounded task to a subagent.",
-            schema: taskToolSchema,
+            description,
+            schema: buildTaskToolSchema(options.taskSubagents),
             invoke: async (input) => options.invokeTaskTool(input),
         });
     }

package/dist/runtime/agent-runtime-adapter.d.ts

@@ -58,6 +58,7 @@ export declare class AgentRuntimeAdapter {
         memoryContext?: string;
     }): Promise<RequestResult>;
     private tryDelegateWithCompactRouter;
+    private buildCompactDelegationReport;
     stream(binding: CompiledAgentBinding, input: MessageContent, sessionId: string, history?: TranscriptMessage[], options?: {
         context?: Record<string, unknown>;
         state?: Record<string, unknown>;

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

@@ -112,6 +112,15 @@ function parseCompactRouterSelection(value, subagentNames) {
     if (subagentNames.has(trimmed)) {
         return { subagentType: trimmed };
     }
+    const lowered = trimmed.toLowerCase();
+    const relaxedMatch = Array.from(subagentNames).find((name) => {
+        const lowerName = name.toLowerCase();
+        return lowerName.length > 0
+            && (trimmed === name || lowered.includes(lowerName));
+    });
+    if (relaxedMatch) {
+        return { subagentType: relaxedMatch };
+    }
     const parsed = parseFirstJsonObject(trimmed);
     const toolCall = salvageJsonToolCalls(trimmed).at(0);
     const payload = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
@@ -714,9 +723,10 @@ export class AgentRuntimeAdapter {
             requestId,
         });
         if (compactDelegation) {
-            const output = typeof compactDelegation.toolOutput === "string"
+            const compactReport = this.buildCompactDelegationReport(compactDelegation);
+            const output = JSON.stringify(compactDelegation.delegatedSubagentType === null
                 ? compactDelegation.toolOutput
-                : JSON.stringify(compactDelegation.toolOutput);
+                : compactReport);
             const delegatedToolResults = Array.isArray(compactDelegation.delegatedResult?.metadata?.executedToolResults)
                 ? compactDelegation.delegatedResult.metadata.executedToolResults
                 : [];
@@ -813,10 +823,13 @@ export class AgentRuntimeAdapter {
         const subagentCatalog = subagents
             .map((subagent) => `- ${subagent.name}: ${subagent.description}`)
             .join("\n");
+        const routingPolicy = getBindingSystemPrompt(binding);
         const prompt = [
             primaryModel.init?.think === false ? "/no_think" : "",
             "You are selecting a subagent for a delegation-only agent.",
             "Choose exactly one listed subagent when it can responsibly handle the request.",
+            routingPolicy ? "Agent routing policy:" : "",
+            routingPolicy ?? "",
             "Return only JSON with this shape:",
             "{\"subagent_type\":\"<listed subagent name>\"}",
             "If no listed subagent can handle the request, return only:",
@@ -881,6 +894,7 @@ export class AgentRuntimeAdapter {
         if (selection?.refusedReason) {
             return {
                 toolOutput: selection.refusedReason,
+                delegatedSubagentType: null,
                 delegatedResult: {
                     sessionId,
                     requestId,
@@ -891,7 +905,16 @@ export class AgentRuntimeAdapter {
                 },
             };
         }
-        const subagentType = selection?.subagentType ?? "";
+        let subagentType = selection?.subagentType ?? "";
+        if (!subagentNames.has(subagentType)) {
+            const fallbackSubagent = subagentNames.values().next().value;
+            if (typeof fallbackSubagent === "string" && fallbackSubagent) {
+                subagentType = fallbackSubagent;
+            }
+            else {
+                return null;
+            }
+        }
         if (!subagentNames.has(subagentType)) {
             return null;
         }
@@ -905,15 +928,49 @@ export class AgentRuntimeAdapter {
             files: options.files,
             memoryContext: options.memoryContext,
         });
-        let delegatedResult = await runDelegatedRequest(requestText);
+        let delegatedResult;
+        try {
+            delegatedResult = await runDelegatedRequest(requestText);
+        }
+        catch (error) {
+            const output = error instanceof Error ? error.message : String(error);
+            return {
+                toolOutput: output,
+                delegatedSubagentType: subagentType,
+                delegatedResult: {
+                    sessionId,
+                    requestId,
+                    agentId: selectedBinding.agent.id,
+                    state: "failed",
+                    output,
+                    finalMessageText: output,
+                },
+            };
+        }
         const targetRequiresExecutionToolEvidence = getBindingPrimaryTools(selectedBinding).length > 0;
         if (targetRequiresExecutionToolEvidence && !hasDelegatedExecutionToolEvidence(delegatedResult)) {
-            delegatedResult = await runDelegatedRequest([requestText, EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION].filter(Boolean).join("\n\n"), ":tool-evidence-retry");
+            try {
+                delegatedResult = await runDelegatedRequest([requestText, EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION].filter(Boolean).join("\n\n"), ":tool-evidence-retry");
+            }
+            catch (error) {
+                const output = error instanceof Error ? error.message : String(error);
+                return {
+                    toolOutput: output,
+                    delegatedSubagentType: subagentType,
+                    delegatedResult: {
+                        ...delegatedResult,
+                        state: "failed",
+                        output,
+                        finalMessageText: output,
+                    },
+                };
+            }
         }
         if (targetRequiresExecutionToolEvidence && !hasDelegatedExecutionToolEvidence(delegatedResult)) {
             const output = `runtime_error=Delegated agent ${selectedBinding.agent.id} completed without tool execution evidence.`;
             return {
                 toolOutput: output,
+                delegatedSubagentType: subagentType,
                 delegatedResult: {
                     ...delegatedResult,
                     state: "failed",
@@ -928,6 +985,7 @@ export class AgentRuntimeAdapter {
             const output = "runtime_error=Delegated agent ended before producing required plan evidence.";
             return {
                 toolOutput: output,
+                delegatedSubagentType: subagentType,
                 delegatedResult: {
                     ...delegatedResult,
                     state: "failed",
@@ -936,7 +994,48 @@ export class AgentRuntimeAdapter {
                 },
             };
         }
-        return { toolOutput: resolveDelegatedResultOutput(delegatedResult), delegatedResult };
+        return {
+            toolOutput: resolveDelegatedResultOutput(delegatedResult),
+            delegatedSubagentType: subagentType,
+            delegatedResult,
+        };
+    }
+    buildCompactDelegationReport(compactDelegation) {
+        const delegatedSubagentType = compactDelegation.delegatedSubagentType ?? "unknown";
+        const delegatedOutput = typeof compactDelegation.toolOutput === "string"
+            ? [compactDelegation.toolOutput]
+            : [];
+        const delegatedToolNames = Array.isArray(compactDelegation.delegatedResult?.metadata?.executedToolResults)
+            ? compactDelegation.delegatedResult.metadata.executedToolResults
+                .filter((toolResult) => toolResult?.toolName)
+                .map((toolResult) => toolResult.toolName)
+            : [];
+        const state = compactDelegation.delegatedResult?.state === "failed" ? "failed" : "completed";
+        return {
+            status: state,
+            routing: [
+                `1) 路由判断: 已选择 sub-agent = ${delegatedSubagentType}（基于请求语义）。`,
+            ],
+            plan: [
+                "1) 选择具备匹配能力的子代理并创建委托任务。",
+                "2) 执行子代理的原生工作流并收集委托工具输出。",
+                "3) 合成汇总报告并返回给用户。",
+            ],
+            execution: [
+                `1) 调用 task 工具，目标子代理：${delegatedSubagentType}`,
+                delegatedToolNames.length > 0
+                    ? `2) 子代理返回工具证据：${[...new Set(delegatedToolNames)].join(", ")}`
+                    : "2) 子代理返回文本结果。",
+                "3) 产出主编排汇总并返回结构化结果。",
+            ],
+            summary: [
+                `已完成子代理 ${delegatedSubagentType} 委托执行。`,
+            ],
+            findings: delegatedOutput.length > 0 ? delegatedOutput.slice(0, 3) : ["none"],
+            blockers: state === "failed" ? ["子代理执行未能完成。"] : ["none"],
+            nextActions: ["如需更深入，可继续追问该次委托的细节。"],
+            report: delegatedOutput.join("\n") || "委托已完成，未返回附加报告。",
+        };
     }
     async *stream(binding, input, sessionId, history = [], options = {}) {
         const directListing = await this.tryHandleDirectWorkspaceListing(binding, input, {
@@ -968,25 +1067,17 @@ export class AgentRuntimeAdapter {
             requestId: options.requestId,
         });
         if (compactDelegation) {
-            const delegatedToolResults = selectDelegatedToolResultsForVisibleProgress(compactDelegation.delegatedResult);
+            const compactReport = this.buildCompactDelegationReport(compactDelegation);
             yield {
                 kind: "tool-result",
                 toolName: "task",
                 output: compactDelegation.toolOutput,
             };
-            for (const toolResult of delegatedToolResults) {
-                yield {
-                    kind: "tool-result",
-                    toolName: toolResult.toolName,
-                    output: toolResult.output,
-                    isError: toolResult.isError,
-                };
-            }
             yield {
                 kind: "content",
-                content: typeof compactDelegation.toolOutput === "string"
+                content: JSON.stringify(compactDelegation.delegatedSubagentType === null
                     ? compactDelegation.toolOutput
-                    : JSON.stringify(compactDelegation.toolOutput),
+                    : compactReport),
             };
             return;
         }

package/dist/runtime/harness/events/streaming.js

@@ -1,5 +1,5 @@
 import { createFallbackRequestResultFromLatestEvent, mergeRequestResultOutput } from "../run/helpers.js";
-import { applyRequestStreamItemToSnapshot, createInitialRequestEventSnapshot, toRequestDataEvent, } from "../../../projections/request-events.js";
+import { applyRequestStreamItemToSnapshot, createInitialRequestEventSnapshot, toRequestDataEvents, } from "../../../projections/request-events.js";
 export async function emitOutputDeltaAndCreateItem(emit, sessionId, requestId, agentId, content) {
     await emit(sessionId, requestId, 3, "output.delta", {
         content,
@@ -71,8 +71,7 @@ export async function dispatchRequestListeners(stream, listeners, options) {
         else if (item.type === "content") {
             output += item.content;
         }
-        const dataEvent = toRequestDataEvent(item);
-        if (dataEvent) {
+        for (const dataEvent of toRequestDataEvents(item)) {
             await notifyIfPresent(listeners.dataListener, dataEvent);
         }
         await notifyIfPresent(listeners.eventListener, snapshot);

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

@@ -5,7 +5,7 @@ import { compileModel, compileTool } from "./resource-compilers.js";
 import { inferAgentCapabilities } from "./support/agent-capabilities.js";
 import { getAgentExecutionConfigValue, getAgentExecutionObject, getAgentExecutionString } from "./support/agent-execution-config.js";
 import { discoverSkillPaths } from "./support/discovery.js";
-import { compileAgentMemories, getProceduralMemoryDefaults, getResilienceConfig, getRuntimeDefaults, getRuntimeMemoryDefaults, getRuntimeStorageRoots, getWorkspaceObject, resolvePromptValue, resolveRefId, } from "./support/workspace-ref-utils.js";
+import { compileAgentMemories, getProceduralMemoryDefaults, getResilienceConfig, getRuntimeAgentDefaults, getRuntimeDefaults, getRuntimeMemoryDefaults, getRuntimeStorageRoots, getWorkspaceObject, resolvePromptValue, resolveRefId, } from "./support/workspace-ref-utils.js";
 import { WORKSPACE_BOUNDARY_GUIDANCE } from "../runtime/prompts/runtime-prompts.js";
 function requireSkills(pathEntries, workspaceRoot) {
     return Array.from(new Set(discoverSkillPaths(pathEntries, workspaceRoot)));
@@ -166,8 +166,8 @@ export function requireTools(tools, bindings, ownerId) {
     }
     return Array.from(deduped.values());
 }
-function buildSubagent(agent, workspaceRoot, models, tools, parentSkills, parentModel) {
-    const execution = compileExecutionCore(agent, workspaceRoot, models, tools);
+function buildSubagent(agent, workspaceRoot, refs, models, tools, parentSkills, parentModel) {
+    const execution = compileExecutionCore(agent, workspaceRoot, refs, models, tools);
     return {
         agentId: agent.id,
         name: resolveAgentRuntimeName(agent),
@@ -196,6 +196,84 @@ function resolveInterruptOn(agent) {
 function resolveResponseFormat(agent) {
     return getAgentExecutionConfigValue(agent, "responseFormat");
 }
+function normalizeResponseFormatRef(ref) {
+    return ref.startsWith("response-format/") ? ref : `response-format/${ref}`;
+}
+function resolveResponseFormatObject(refs, ref, ownerLabel) {
+    if (!ref) {
+        return undefined;
+    }
+    const object = getWorkspaceObject(refs, normalizeResponseFormatRef(ref));
+    if (!object) {
+        throw new Error(`${ownerLabel} responseFormatRef references missing object ${ref}`);
+    }
+    if (object.kind !== "response-format") {
+        throw new Error(`${ownerLabel} responseFormatRef references ${ref}, but expected response-format`);
+    }
+    if (!("format" in object.value)) {
+        throw new Error(`${ownerLabel} responseFormatRef ${ref} must define format`);
+    }
+    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) {
+    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() : "";
+    if (defaultRef) {
+        return resolveResponseFormatObject(refs, defaultRef, "Runtime defaults.agent.config");
+    }
+    return undefined;
+}
+function resolveEffectiveResponseFormat(agent, refs) {
+    const explicitResponseFormat = resolveResponseFormat(agent);
+    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 resolveResponseFormatObject(refs, explicitRef.trim(), `Agent ${agent.id}`);
+    }
+    return resolveInheritedResponseFormat(agent, refs);
+}
 function resolveContextSchema(agent) {
     return getAgentExecutionConfigValue(agent, "contextSchema");
 }
@@ -216,13 +294,13 @@ function resolvePassthrough(agent) {
     const passthrough = getAgentExecutionObject(agent, "passthrough");
     return passthrough ? { ...passthrough } : undefined;
 }
-function compileSubagents(agent, agents, workspaceRoot, models, tools, compiledAgentSkills, compiledAgentModel) {
+function compileSubagents(agent, agents, workspaceRoot, refs, models, tools, compiledAgentSkills, compiledAgentModel) {
     return agent.subagentRefs.map((ref) => {
         const subagent = agents.get(resolveRefId(ref));
         if (!subagent) {
             throw new Error(`Missing subagent ${ref} for agent ${agent.id}`);
         }
-        return buildSubagent(subagent, workspaceRoot, models, tools, compiledAgentSkills, compiledAgentModel);
+        return buildSubagent(subagent, workspaceRoot, refs, models, tools, compiledAgentSkills, compiledAgentModel);
     });
 }
 function compileAsyncSubagents(agent) {
@@ -234,18 +312,18 @@ function compileAsyncSubagents(agent) {
         ...(subagent.headers ? { headers: { ...subagent.headers } } : {}),
     }));
 }
-function compileDeepAgentSubagents(agent, agents, workspaceRoot, models, tools, compiledAgentSkills, compiledAgentModel) {
+function compileDeepAgentSubagents(agent, agents, workspaceRoot, refs, models, tools, compiledAgentSkills, compiledAgentModel) {
     return [
-        ...compileSubagents(agent, agents, workspaceRoot, models, tools, compiledAgentSkills, compiledAgentModel),
+        ...compileSubagents(agent, agents, workspaceRoot, refs, models, tools, compiledAgentSkills, compiledAgentModel),
         ...compileAsyncSubagents(agent),
     ];
 }
-function compileExecutionCore(agent, workspaceRoot, models, tools) {
+function compileExecutionCore(agent, workspaceRoot, refs, models, tools) {
     return {
         model: requireModel(models, agent.modelRef, agent.id),
         tools: requireTools(tools, getAgentToolBindings(agent), agent.id),
         systemPrompt: resolveSystemPrompt(agent, workspaceRoot),
-        responseFormat: resolveResponseFormat(agent),
+        responseFormat: resolveEffectiveResponseFormat(agent, refs),
         contextSchema: resolveContextSchema(agent),
         middleware: resolveCompiledMiddleware(agent, models),
     };
@@ -395,7 +473,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
     const executionCore = compileExecutionCore({
         ...agent,
         modelRef: agent.modelRef || (internalSubagent ? "model/default" : ""),
-    }, workspaceRoot, models, tools);
+    }, workspaceRoot, refs, models, tools);
     const passthrough = resolvePassthrough(agent);
     const compiledAgentModel = executionCore.model;
     const backend = resolveBackendConfig(agent, refs);
@@ -442,7 +520,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
                         passthrough,
                         interruptOn: resolveInterruptOn(agent),
                         filesystem: compiledFilesystemConfig,
-                        subagents: compileSubagents(agent, agents, workspaceRoot, models, tools, compiledAgentSkills, compiledAgentModel),
+                        subagents: compileSubagents(agent, agents, workspaceRoot, refs, models, tools, compiledAgentSkills, compiledAgentModel),
                         memory: compiledAgentMemory,
                         skills: compiledAgentSkills,
                         generalPurposeAgent: getAgentExecutionConfigValue(agent, "generalPurposeAgent", { executionMode: "langchain-v1" }),
@@ -491,7 +569,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             responseFormat: executionCore.responseFormat,
             contextSchema: executionCore.contextSchema,
             middleware: executionCore.middleware,
-            subagents: compileDeepAgentSubagents(agent, agents, workspaceRoot, models, tools, compiledAgentSkills, compiledAgentModel),
+            subagents: compileDeepAgentSubagents(agent, agents, workspaceRoot, refs, models, tools, compiledAgentSkills, compiledAgentModel),
             interruptOn: resolveInterruptOn(agent),
             ...(backend ? { backend: backend.config } : {}),
             ...(store ? { store: store.config } : {}),

package/dist/workspace/compile.js

@@ -425,6 +425,7 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
             tools,
             skillRegistry,
             ownedRoots: contractOwnedRoots,
+            refs: loaded.refs,
             mode: frameworkContractValidation,
         });
     }, {

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

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

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

@@ -1,7 +1,7 @@
 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";
+import { getRuntimeAgentDefaults, getWorkspaceObject, 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"]);
@@ -87,6 +87,78 @@ function readObject(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);
@@ -101,7 +173,7 @@ function validateResponseFormatTerminalStatus(agent, responseFormat, issues) {
         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) {
+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;
@@ -109,7 +181,7 @@ function validateAgentContract(agent, referencedSubagentIds, tools, issues) {
     const hasTools = agent.toolRefs.length > 0
         || (agent.toolBindings?.length ?? 0) > 0
         || (agent.inlineTools?.length ?? 0) > 0;
-    const responseFormat = getAgentExecutionConfigValue(agent, "responseFormat");
+    const responseFormat = resolveEffectiveResponseFormat(agent, refs);
     const builtinTools = readBuiltinToolsConfig(agent);
     const executionContract = readExecutionContractConfig(agent);
     const localSubagentNames = [
@@ -156,7 +228,7 @@ function validateAgentContract(agent, referencedSubagentIds, tools, issues) {
             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 define config.responseFormat to guarantee a stable task result for its parent agent.`);
+            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);
@@ -200,7 +272,7 @@ export function validateFrameworkContracts(input) {
         if (!isWorkspaceOwnedPath(agent.sourcePath, input.ownedRoots)) {
             continue;
         }
-        validateAgentContract(agent, referencedSubagentIds, input.tools, issues);
+        validateAgentContract(agent, referencedSubagentIds, input.tools, input.refs, issues);
     }
     for (const [skillName, skillRoot] of input.skillRegistry) {
         if (!isWorkspaceOwnedPath(skillRoot, input.ownedRoots)) {

package/dist/workspace/object-loader.js

@@ -16,6 +16,7 @@ const CONSUMED_AGENT_CONFIG_KEYS = [
     "interruptOn",
     "stateSchema",
     "responseFormat",
+    "responseFormatRef",
     "contextSchema",
     "includeAgentName",
     "version",
@@ -56,6 +57,7 @@ const MIGRATED_AGENT_CONFIG_KEYS = [
     "interruptOn",
     "stateSchema",
     "responseFormat",
+    "responseFormatRef",
     "contextSchema",
     "includeAgentName",
     "version",
@@ -264,6 +266,13 @@ function readSharedAgentConfig(config) {
         ...(typeof config.interruptOn === "object" && config.interruptOn ? { interruptOn: config.interruptOn } : {}),
         ...(config.stateSchema !== undefined ? { stateSchema: config.stateSchema } : {}),
         ...(config.responseFormat !== undefined ? { responseFormat: config.responseFormat } : {}),
+        ...(typeof config.responseFormatRef === "string" && config.responseFormatRef.trim()
+            ? {
+                responseFormatRef: config.responseFormatRef.startsWith("response-format/")
+                    ? config.responseFormatRef
+                    : `response-format/${config.responseFormatRef.trim()}`,
+            }
+            : {}),
         ...(config.contextSchema !== undefined ? { contextSchema: config.contextSchema } : {}),
         ...(config.interactionMode === "stream" || config.interactionMode === "invoke" ? { interactionMode: config.interactionMode } : {}),
         ...(config.includeAgentName === "inline" ? { includeAgentName: "inline" } : {}),

package/dist/workspace/support/workspace-ref-utils.d.ts

@@ -37,6 +37,7 @@ export type ToolModuleDiscoveryConfig = {
 };
 export declare function getWorkspaceObject(refs: Map<string, WorkspaceObject | ParsedAgentObject>, ref: string | undefined): WorkspaceObject | undefined;
 export declare function getRuntimeDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
+export declare function getRuntimeAgentDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
 export type RuntimeStorageRoots = {
     applicationRoot: string;
     dataRoot: string;