@botbotgo/agent-harness 0.0.359 → 0.0.362

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

@@ -362,17 +362,32 @@ export async function invokeBuiltinTaskTool(input) {
     const typedInput = isRecord(input.toolInput) ? input.toolInput : {};
     const description = typeof typedInput.description === "string"
         ? typedInput.description
-        : "";
+        : typeof typedInput.instruction === "string"
+            ? typedInput.instruction
+            : typeof typedInput.task === "string"
+                ? typedInput.task
+                : typeof typedInput.prompt === "string"
+                    ? typedInput.prompt
+                    : "";
     const subagentType = typeof typedInput.subagent_type === "string"
         ? typedInput.subagent_type
-        : "";
+        : typeof typedInput.agentId === "string"
+            ? typedInput.agentId
+            : typeof typedInput.agent_id === "string"
+                ? typedInput.agent_id
+                : typeof typedInput.subagent === "string"
+                    ? typedInput.subagent
+                    : "";
     const builtinBackend = input.resolveBuiltinMiddlewareBackend(input.binding, input.options);
     const resolvedSubagents = await input.resolveSubagents(compiledSubagents, input.binding);
     const selectedSubagent = resolvedSubagents.find((subagent) => subagent.name === subagentType);
     const selectedCompiledSubagent = compiledSubagents.find((subagent) => subagent.name === subagentType);
     if (!selectedSubagent) {
         const allowed = resolvedSubagents.map((subagent) => subagent.name);
-        throw new Error(`Error: invoked agent of type ${subagentType}, the only allowed types are ${allowed.map((name) => `\`${name}\``).join(", ")}`);
+        const available = resolvedSubagents
+            .map((subagent) => `- ${subagent.name}: ${subagent.description}`)
+            .join("\n");
+        throw new Error(`Error: invoked agent of type ${subagentType}, the only allowed types are ${allowed.map((name) => `\`${name}\``).join(", ")}.${available ? `\nAvailable subagents:\n${available}` : ""}`);
     }
     const resolvedHostModel = selectedSubagent.model ? undefined : await input.resolveModel(primaryModel);
     const summarizationModel = selectedSubagent.model ?? resolvedHostModel;
@@ -446,8 +461,15 @@ export async function resolveBuiltinMiddlewareTools(input) {
         ...(input.binding.agent.asyncSubagents ?? []),
     ];
     const includeTaskTool = configuredSubagents.length > 0;
+    const taskSubagents = getBindingDeepAgentSubagents(input.binding)
+        .filter((subagent) => !("graphId" in subagent))
+        .map((subagent) => ({
+        name: subagent.name,
+        description: subagent.description,
+    }));
     const tools = (await createBuiltinMiddlewareTools(backend, {
         includeTaskTool,
+        taskSubagents,
         workspaceRoot: input.binding.harnessRuntime.workspaceRoot,
         toolRuntimeContext: input.options?.toolRuntimeContext,
         invokeTaskTool: includeTaskTool

package/dist/runtime/adapter/tool/builtin-middleware-tools.d.ts

@@ -188,6 +188,10 @@ export type BuiltinExecutableTool = {
     schema: unknown;
     invoke: (input: unknown, config?: Record<string, unknown>) => Promise<unknown>;
 };
+export type BuiltinTaskSubagentDescriptor = {
+    name: string;
+    description: string;
+};
 export declare const BUILTIN_MIDDLEWARE_TOOL_DESCRIPTORS: readonly [{
     readonly name: "write_todos";
     readonly description: "Create and update the runtime todo board for multi-step work.";
@@ -254,6 +258,7 @@ export declare function filterBuiltinMiddlewareToolDescriptors(options?: {
 export declare function createBuiltinMiddlewareTools(backend: BuiltinMiddlewareBackend, options: {
     includeTaskTool: boolean;
     invokeTaskTool?: (input: unknown) => Promise<unknown>;
+    taskSubagents?: BuiltinTaskSubagentDescriptor[];
     workspaceRoot?: string;
     toolRuntimeContext?: Record<string, unknown>;
 }): Promise<Map<string, BuiltinExecutableTool>>;

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

@@ -10,6 +10,7 @@ import { EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION } from "./prompts/runtim
 import { buildToolNameMapping, } from "./adapter/tool/tool-name-mapping.js";
 import { executeRequestInvocation } from "./adapter/flow/invocation-flow.js";
 import { streamRuntimeExecution } from "./adapter/flow/stream-runtime.js";
+import { resolveDeterministicFinalOutput } from "./adapter/invocation-result.js";
 import { applyToolRecoveryInstruction as applyToolRecoveryInstructionHelper, applyStrictToolJsonInstruction as applyStrictToolJsonInstructionHelper, callRuntimeWithToolParseRecovery as callRuntimeWithToolParseRecoveryHelper, createModelFallbackRunnable as createModelFallbackRunnableHelper, invokeWithProviderRetry as invokeWithProviderRetryHelper, iterateWithTimeout as iterateWithTimeoutHelper, materializeModelStream as materializeModelStreamHelper, RuntimeOperationTimeoutError, withRuntimeTimeout, } from "./adapter/runtime-shell.js";
 import { extractSubagentRequestText, invokeBuiltinTaskTool as invokeBuiltinTaskToolHelper, materializeAutomaticSummarizationMiddleware as materializeAutomaticSummarizationMiddlewareHelper, resolveBuiltinMiddlewareBackend as resolveBuiltinMiddlewareBackendHelper, resolveBuiltinMiddlewareTools as resolveBuiltinMiddlewareToolsHelper, resolveLangChainRuntimeExtensionMiddleware as resolveLangChainRuntimeExtensionMiddlewareHelper, resolveMiddleware as resolveMiddlewareHelper, resolveSubagents as resolveSubagentsHelper, wrapRequestResultAsSubagentResponse, } from "./adapter/middleware-assembly.js";
 import { isEmptyFinalAiMessageError, resolveBindingTimeout, resolveStreamIdleTimeout, } from "./adapter/resilience.js";
@@ -111,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)
@@ -154,6 +164,29 @@ function hasDelegatedPlanEvidence(result) {
     return Array.isArray(toolResults)
         && toolResults.some((item) => item.toolName === "write_todos" || item.toolName === "read_todos");
 }
+function resolveDelegatedResultOutput(result) {
+    const executedToolResults = Array.isArray(result.metadata?.executedToolResults)
+        ? result.metadata.executedToolResults
+        : [];
+    const deterministicOutput = resolveDeterministicFinalOutput({
+        visibleOutput: typeof result.output === "string" ? result.output : "",
+        executedToolResults,
+    });
+    return deterministicOutput || result.output;
+}
+function selectDelegatedToolResultsForVisibleProgress(result) {
+    const executedToolResults = Array.isArray(result?.metadata?.executedToolResults)
+        ? result.metadata.executedToolResults
+        : [];
+    const hasSuccessfulExecutionEvidence = executedToolResults.some((toolResult) => (toolResult.isError !== true
+        && toolResult.toolName !== "write_todos"
+        && toolResult.toolName !== "read_todos"));
+    return hasSuccessfulExecutionEvidence
+        ? executedToolResults.filter((toolResult) => (toolResult.isError !== true
+            && toolResult.toolName !== "write_todos"
+            && toolResult.toolName !== "read_todos"))
+        : executedToolResults;
+}
 export class AgentRuntimeAdapter {
     options;
     modelCache = new Map();
@@ -690,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
                 : [];
@@ -789,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:",
@@ -806,7 +843,7 @@ export class AgentRuntimeAdapter {
         if (typeof model.invoke !== "function") {
             return null;
         }
-        const raw = await this.invokeWithProviderRetry(binding, () => this.withTimeout(() => model.invoke(prompt, resolveLangChainInvocationConfig(binding, {
+        const invokeRouter = async (activePrompt, operationName) => this.invokeWithProviderRetry(binding, () => this.withTimeout(() => model.invoke(activePrompt, resolveLangChainInvocationConfig(binding, {
             sessionId,
             requestId,
             context: options.context,
@@ -815,32 +852,49 @@ export class AgentRuntimeAdapter {
                 sessionId,
                 requestId,
             }),
-        })), resolveBindingTimeout(binding), "delegation router invoke", "invoke"));
-        const rawText = readModelText(raw);
-        let selection = parseCompactRouterSelection(rawText, subagentNames);
-        if (!selection) {
-            const retryPrompt = [
+        })), resolveBindingTimeout(binding), operationName, "invoke"));
+        const routerPrompts = [
+            prompt,
+            [
                 prompt,
                 "Your previous router output was invalid.",
-                "Previous output:",
-                rawText,
                 "Return only one JSON object now. Do not include prose, markdown, labels, or tool-call wrappers.",
-            ].join("\n\n");
-            const retryRaw = await this.invokeWithProviderRetry(binding, () => this.withTimeout(() => model.invoke(retryPrompt, resolveLangChainInvocationConfig(binding, {
-                sessionId,
-                requestId,
-                context: options.context,
-                toolRuntimeContext: this.buildFunctionToolRuntimeContext(binding, {
-                    ...options,
-                    sessionId,
-                    requestId,
-                }),
-            })), resolveBindingTimeout(binding), "delegation router retry invoke", "invoke"));
-            selection = parseCompactRouterSelection(readModelText(retryRaw), subagentNames);
+            ].join("\n\n"),
+            [
+                primaryModel.init?.think === false ? "/no_think" : "",
+                "Select one subagent from this exact list:",
+                Array.from(subagentNames).join(", "),
+                "Return JSON only:",
+                "{\"subagent_type\":\"<one exact listed name>\"}",
+                "User request:",
+                requestText,
+            ].filter(Boolean).join("\n\n"),
+            [
+                primaryModel.init?.think === false ? "/no_think" : "",
+                "JSON only. Pick a listed subagent or refuse.",
+                "Listed subagents:",
+                Array.from(subagentNames).join(", "),
+                "Allowed outputs:",
+                "{\"subagent_type\":\"<listed name>\"}",
+                "{\"status\":\"refused\",\"reason\":\"No configured subagent can handle the request.\"}",
+                "Request:",
+                requestText,
+            ].filter(Boolean).join("\n\n"),
+        ];
+        let selection = null;
+        let previousRawText = "";
+        for (let index = 0; index < routerPrompts.length && !selection; index += 1) {
+            const activePrompt = index <= 1 || !previousRawText
+                ? routerPrompts[index]
+                : [routerPrompts[index], "Previous output:", previousRawText].join("\n\n");
+            const raw = await invokeRouter(activePrompt, index === 0 ? "delegation router invoke" : `delegation router retry invoke ${index}`);
+            previousRawText = readModelText(raw);
+            selection = parseCompactRouterSelection(previousRawText, subagentNames);
         }
         if (selection?.refusedReason) {
             return {
                 toolOutput: selection.refusedReason,
+                delegatedSubagentType: null,
                 delegatedResult: {
                     sessionId,
                     requestId,
@@ -851,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;
         }
@@ -865,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",
@@ -888,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",
@@ -896,7 +994,48 @@ export class AgentRuntimeAdapter {
                 },
             };
         }
-        return { toolOutput: delegatedResult.output, 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, {
@@ -916,12 +1055,19 @@ export class AgentRuntimeAdapter {
             };
             return;
         }
+        if (isDelegationOnlyDeepAgentBinding(binding)) {
+            yield {
+                kind: "commentary",
+                content: "Selecting a specialist for delegated execution.",
+            };
+        }
         const compactDelegation = await this.tryDelegateWithCompactRouter(binding, input, sessionId, options.requestId ?? sessionId, {
             ...options,
             sessionId,
             requestId: options.requestId,
         });
         if (compactDelegation) {
+            const compactReport = this.buildCompactDelegationReport(compactDelegation);
             yield {
                 kind: "tool-result",
                 toolName: "task",
@@ -929,9 +1075,9 @@ export class AgentRuntimeAdapter {
             };
             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;