@botbotgo/agent-harness 0.0.346 → 0.0.348

package/dist/runtime/adapter/model/model-providers.js

@@ -13,8 +13,16 @@ const NODE_LLAMA_CPP_TOOL_CALL_INSTRUCTION = [
     "If you need a tool, respond with only one JSON object.",
     'Use this exact shape: {"name":"tool_name","arguments":{"key":"value"}}',
     "Do not add markdown, prose, or code fences unless the output is wrapped inside <tool_call>...</tool_call>.",
+    "When the latest user message explicitly requests a tool call or provides a tool-call JSON object, call that tool instead of answering locally.",
+    "If the conversation already contains TOOL_RESULT for the requested work, answer from that result instead of repeating the same tool call.",
     "If no tool is needed, answer normally.",
 ].join("\n");
+const PROMPTED_JSON_FINAL_TOOL_CALL_REMINDER = [
+    "Final tool-call rule:",
+    "If the correct next step is a tool call, return exactly one JSON object and no prose.",
+    "If a TOOL_RESULT is already present for the requested work, do not repeat that tool call; answer normally.",
+    'Shape: {"name":"tool_name","arguments":{}}',
+].join("\n");
 function readModelText(value) {
     if (typeof value === "string") {
         return value.trim();
@@ -175,6 +183,23 @@ function readToolMessageMetadata(value) {
                 : undefined;
     return { name, toolCallId };
 }
+function hasPriorToolResultForToolName(input, toolName) {
+    if (!toolName) {
+        return false;
+    }
+    if (Array.isArray(input)) {
+        return input.some((message) => {
+            if (mapMessageRole(message) !== "TOOL") {
+                return false;
+            }
+            return readToolMessageMetadata(message).name === toolName;
+        });
+    }
+    if (typeof input === "object" && input !== null && Array.isArray(input.messages)) {
+        return hasPriorToolResultForToolName(input.messages, toolName);
+    }
+    return false;
+}
 function normalizeReadFileToolContent(name, content) {
     if (name !== "read_file") {
         return content;
@@ -274,22 +299,75 @@ function extractToolCallPayload(text) {
     if (direct) {
         return direct;
     }
-    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
+    const fenced = extractFencePayload(trimmed);
     if (fenced) {
         const parsed = tryParseJson(fenced);
         if (parsed) {
             return parsed;
         }
     }
-    const xml = trimmed.match(/<tool_call>\s*([\s\S]*?)\s*<\/tool_call>/i)?.[1]?.trim();
+    const xml = extractTaggedContent(trimmed, "tool_call");
     if (xml) {
         const parsed = tryParseJson(xml);
         if (parsed) {
             return parsed;
         }
     }
+    const toolCallsXml = extractTaggedContent(trimmed, "tool_calls");
+    if (toolCallsXml) {
+        const parsed = tryParseJson(toolCallsXml);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    const codeBlock = extractToolCodePayload(trimmed);
+    if (codeBlock) {
+        return codeBlock;
+    }
     return null;
 }
+function extractFencePayload(text) {
+    const start = text.indexOf("```");
+    if (start < 0) {
+        return null;
+    }
+    const contentStart = text.indexOf("\n", start + 3);
+    const bodyStart = contentStart >= 0 ? contentStart + 1 : start + 3;
+    const end = text.indexOf("```", bodyStart);
+    if (end < 0) {
+        return null;
+    }
+    return text.slice(bodyStart, end).trim();
+}
+function extractTaggedContent(text, tagName) {
+    const lowerText = text.toLowerCase();
+    const openTag = `<${tagName}>`;
+    const closeTag = `</${tagName}>`;
+    const start = lowerText.indexOf(openTag);
+    if (start < 0) {
+        return null;
+    }
+    const bodyStart = start + openTag.length;
+    const end = lowerText.indexOf(closeTag, bodyStart);
+    if (end < 0) {
+        return null;
+    }
+    return text.slice(bodyStart, end).trim();
+}
+function extractToolCodePayload(text) {
+    const name = extractTaggedContent(text, "tool_code");
+    if (!name) {
+        return null;
+    }
+    const rawArgs = extractTaggedContent(text, "tool_args");
+    const parsedArgs = rawArgs ? tryParseJson(rawArgs.trim()) : null;
+    const args = typeof parsedArgs === "object" && parsedArgs !== null && !Array.isArray(parsedArgs)
+        ? parsedArgs
+        : Array.isArray(parsedArgs)
+            ? { args: parsedArgs }
+            : {};
+    return { name, arguments: args };
+}
 function normalizeParsedToolCall(payload) {
     if (typeof payload !== "object" || payload === null) {
         return null;
@@ -305,7 +383,9 @@ function normalizeParsedToolCall(payload) {
         return null;
     }
     const argsCandidate = typed.arguments ?? typed.args ?? typed.parameters ?? typed.input ?? functionPayload?.arguments ?? {};
-    const args = salvageToolArgs(argsCandidate) ?? {};
+    const args = Array.isArray(argsCandidate)
+        ? { args: argsCandidate }
+        : salvageToolArgs(argsCandidate) ?? {};
     return { name, args };
 }
 function formatBoundToolInstruction(tool) {
@@ -325,16 +405,16 @@ function formatBoundToolInstruction(tool) {
         `Arguments JSON schema: ${JSON.stringify(schema)}`,
     ].filter(Boolean).join("\n");
 }
-function withNodeLlamaCppToolPrompt(input, tools) {
+function withPromptedJsonToolPrompt(input, tools) {
     const toolInstructions = tools.map((tool) => formatBoundToolInstruction(tool)).filter((value) => Boolean(value));
     if (toolInstructions.length === 0) {
         return stringifyNodeLlamaCppInput(input);
     }
     const systemContent = `${NODE_LLAMA_CPP_TOOL_CALL_INSTRUCTION}\n\n${toolInstructions.join("\n\n")}`;
     const prompt = stringifyNodeLlamaCppInput(input);
-    return [systemContent, prompt].filter(Boolean).join("\n\n");
+    return [systemContent, prompt, PROMPTED_JSON_FINAL_TOOL_CALL_REMINDER].filter(Boolean).join("\n\n");
 }
-function createNodeLlamaCppToolBindableModel(model, boundTools = []) {
+function createPromptedJsonToolBindableModel(model, boundTools = []) {
     return new Proxy(model, {
         has(target, prop) {
             if (prop === "bindTools" || prop === "invoke" || prop === "stream" || prop === "withConfig") {
@@ -344,11 +424,11 @@ function createNodeLlamaCppToolBindableModel(model, boundTools = []) {
         },
         get(target, prop, receiver) {
             if (prop === "bindTools") {
-                return (tools) => createNodeLlamaCppToolBindableModel(target, tools);
+                return (tools) => createPromptedJsonToolBindableModel(target, tools);
             }
             if (prop === "invoke") {
                 return async (input, config) => {
-                    const rawResult = await target.invoke(boundTools.length > 0 ? withNodeLlamaCppToolPrompt(input, boundTools) : input, config);
+                    const rawResult = await target.invoke(boundTools.length > 0 ? withPromptedJsonToolPrompt(input, boundTools) : input, config);
                     if (boundTools.length === 0) {
                         return rawResult;
                     }
@@ -357,6 +437,9 @@ function createNodeLlamaCppToolBindableModel(model, boundTools = []) {
                     if (!parsedToolCall) {
                         return rawResult;
                     }
+                    if (hasPriorToolResultForToolName(input, parsedToolCall.name)) {
+                        return rawResult;
+                    }
                     return new AIMessage({
                         content: "",
                         tool_calls: [{
@@ -377,7 +460,7 @@ function createNodeLlamaCppToolBindableModel(model, boundTools = []) {
                 };
             }
             if (prop === "withConfig" && typeof target.withConfig === "function") {
-                return (config) => createNodeLlamaCppToolBindableModel(target.withConfig(config), boundTools);
+                return (config) => createPromptedJsonToolBindableModel(target.withConfig(config), boundTools);
             }
             const member = Reflect.get(target, prop, receiver);
             return typeof member === "function" ? member.bind(target) : member;
@@ -409,7 +492,7 @@ async function createNodeLlamaCppModel(model) {
     }
     try {
         const { ChatLlamaCpp } = await import("@langchain/community/chat_models/llama_cpp");
-        return createNodeLlamaCppToolBindableModel(await ChatLlamaCpp.initialize({
+        return createPromptedJsonToolBindableModel(await ChatLlamaCpp.initialize({
             ...model.init,
             modelPath,
         }));
@@ -423,10 +506,23 @@ export async function createResolvedModel(model, modelResolver) {
         return modelResolver(model.id);
     }
     if (model.provider === "ollama") {
-        return createProviderToolMessageCompatModel(new ChatOllama({ model: model.model, ...model.init }));
+        const { toolCallingMode, ...init } = model.init ?? {};
+        const resolved = new ChatOllama({ model: model.model, ...init });
+        if (toolCallingMode === "prompted-json") {
+            return createPromptedJsonToolBindableModel(resolved);
+        }
+        return createProviderToolMessageCompatModel(resolved);
     }
     if (model.provider === "openai-compatible") {
-        return createProviderToolMessageCompatModel(new ChatOpenAI({ model: model.model, ...normalizeOpenAICompatibleInit(model.init) }));
+        const { toolCallingMode, ...init } = model.init ?? {};
+        const resolved = new ChatOpenAI({
+            model: model.model,
+            ...normalizeOpenAICompatibleInit(init),
+        });
+        if (toolCallingMode === "prompted-json") {
+            return createPromptedJsonToolBindableModel(resolved);
+        }
+        return createProviderToolMessageCompatModel(resolved);
     }
     if (model.provider === "openai") {
         return createProviderToolMessageCompatModel(new ChatOpenAI({ model: model.model, ...model.init }));

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

@@ -350,7 +350,9 @@ export function projectRuntimeStreamEvent(params) {
             ? state.lastCompletedTaskDelegationFindings
             : "";
         const effectiveToolOutput = salvagedTaskErrorFindings || toolResult.output;
-        const effectiveToolIsError = salvagedTaskErrorFindings ? false : toolResult.isError;
+        const effectiveToolIsError = salvagedTaskErrorFindings
+            ? false
+            : toolResult.isError === true;
         const isSuccessfulTaskResult = toolResult.toolName === "task" && effectiveToolIsError !== true;
         const isDelegatedExecutionTool = (isDelegatedAgentEvent || state.openToolCapableTaskDelegations > 0)
             && toolResult.toolName !== "write_todos"

package/dist/runtime/adapter/terminal-status.d.ts

@@ -0,0 +1,4 @@
+import type { RequestState, TerminalExecutionStatus } from "../../contracts/types.js";
+export declare function readTerminalExecutionStatus(value: unknown): TerminalExecutionStatus | null;
+export declare function mapTerminalStatusToRequestState(status: TerminalExecutionStatus | null): RequestState;
+export declare function mapTerminalStatusToPlanItemStatus(status: TerminalExecutionStatus): "completed" | "failed";

package/dist/runtime/adapter/terminal-status.js

@@ -0,0 +1,67 @@
+const TERMINAL_STATUSES = new Set(["completed", "blocked", "failed", "refused"]);
+function normalizeTerminalStatus(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase();
+    return TERMINAL_STATUSES.has(normalized)
+        ? normalized
+        : null;
+}
+function readStatusLine(value) {
+    for (const line of value.split("\n")) {
+        const [key, ...rest] = line.split(":");
+        if (key?.trim().toLowerCase() !== "status") {
+            continue;
+        }
+        const statusValue = rest.join(":").trim().split(/\s+/)[0];
+        const status = normalizeTerminalStatus(statusValue);
+        if (status) {
+            return status;
+        }
+    }
+    return null;
+}
+export function readTerminalExecutionStatus(value) {
+    const direct = normalizeTerminalStatus(value);
+    if (direct) {
+        return direct;
+    }
+    if (typeof value === "string") {
+        try {
+            return readTerminalExecutionStatus(JSON.parse(value));
+        }
+        catch {
+            return readStatusLine(value);
+        }
+    }
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        for (let index = value.length - 1; index >= 0; index -= 1) {
+            const status = readTerminalExecutionStatus(value[index]);
+            if (status) {
+                return status;
+            }
+        }
+        return null;
+    }
+    const typed = value;
+    return (readTerminalExecutionStatus(typed.status)
+        ?? readTerminalExecutionStatus(typed.structuredResponse)
+        ?? readTerminalExecutionStatus(typed.messages)
+        ?? readTerminalExecutionStatus(typed.content)
+        ?? readTerminalExecutionStatus(typed.kwargs?.content)
+        ?? readTerminalExecutionStatus(typed.lc_kwargs?.content)
+        ?? readTerminalExecutionStatus(typed.output)
+        ?? readTerminalExecutionStatus(typed.data));
+}
+export function mapTerminalStatusToRequestState(status) {
+    return status === "blocked" || status === "failed" || status === "refused"
+        ? "failed"
+        : "completed";
+}
+export function mapTerminalStatusToPlanItemStatus(status) {
+    return status === "completed" ? "completed" : "failed";
+}

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

@@ -1,9 +1,10 @@
 import path from "node:path";
-import { GENERAL_PURPOSE_SUBAGENT, createAsyncSubAgentMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSkillsMiddleware, createSummarizationMiddleware, createSubAgentMiddleware, FilesystemBackend, StateBackend, } from "deepagents";
+import { createAsyncSubAgentMiddleware, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSkillsMiddleware, createSummarizationMiddleware, createSubAgentMiddleware, FilesystemBackend, StateBackend, } from "deepagents";
 import { createAgent, humanInTheLoopMiddleware, todoListMiddleware } from "langchain";
 import { wrapResolvedModel, } from "./parsing/output-parsing.js";
-import { AGENT_INTERRUPT_SENTINEL_PREFIX, buildDeepAgentCreateParams, buildLangChainCreateParams, DEFAULT_DEEPAGENT_RECURSION_LIMIT, materializeModelExposedBuiltinMiddlewareTools, resolveLangChainInvocationConfig, resolveRunnableCheckpointer, resolveRunnableInterruptOn, shouldAttachDeepAgentBackend, shouldAttachDeepAgentCheckpointer, shouldAttachDeepAgentStore, } from "./agent-runtime-assembly.js";
+import { AGENT_INTERRUPT_SENTINEL_PREFIX, buildDeepAgentCreateParams, buildDeepAgentSystemPromptWithCapabilityHierarchy, buildLangChainCreateParams, DEFAULT_DEEPAGENT_RECURSION_LIMIT, materializeModelExposedBuiltinMiddlewareTools, resolveLangChainInvocationConfig, resolveRunnableCheckpointer, resolveRunnableInterruptOn, shouldAttachDeepAgentBackend, shouldAttachDeepAgentCheckpointer, shouldAttachDeepAgentStore, } from "./agent-runtime-assembly.js";
 import { resolveDeepAgentSkillSourcePaths, } from "./adapter/compat/deepagent-compat.js";
+import { EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION } from "./prompts/runtime-prompts.js";
 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";
@@ -21,8 +22,22 @@ export { buildAuthOmittingFetch, normalizeOpenAICompatibleInit } from "./adapter
 export { buildToolNameMapping, createModelFacingToolNameCandidates, createModelFacingToolNameLookupCandidates, resolveModelFacingToolName, sanitizeToolNameForModel, } from "./adapter/tool/tool-name-mapping.js";
 export { computeRemainingTimeoutMs, isRetryableProviderError, resolveBindingTimeout, resolveProviderRetryPolicy, resolveStreamIdleTimeout, resolveTimeoutMs, } from "./adapter/resilience.js";
 import { getBindingAdapterKind, getBindingBuiltinToolsConfig, getBindingDeepAgentSubagents, getBindingExecutionParams, getBindingExecutionKind, getBindingFilesystemConfig, getBindingMemorySources, getBindingPrimaryModel, getBindingSkills, getBindingToolCount, getBindingPrimaryTools, getBindingSystemPrompt, isDeepAgentBinding, isLangChainBinding, } from "./support/compiled-binding.js";
+class DelegatedExecutionNoToolEvidenceError extends Error {
+    constructor(agentId) {
+        super(`Delegated agent ${agentId} completed without tool execution evidence.`);
+        this.name = "DelegatedExecutionNoToolEvidenceError";
+    }
+}
+function hasDelegatedExecutionToolEvidence(result) {
+    const executedToolResults = Array.isArray(result.metadata?.executedToolResults)
+        ? result.metadata.executedToolResults
+        : [];
+    return executedToolResults.some((toolResult) => (toolResult.isError !== true
+        && toolResult.toolName !== "write_todos"
+        && toolResult.toolName !== "read_todos"));
+}
 function shouldUseConfigurableDeepAgentAssembly(binding) {
-    return getBindingBuiltinToolsConfig(binding) !== undefined;
+    return getBindingExecutionKind(binding) === "deepagent";
 }
 export class AgentRuntimeAdapter {
     options;
@@ -319,9 +334,18 @@ export class AgentRuntimeAdapter {
                         const childSessionId = `${sessionId}:delegated:${resolvedSubagent.name}`;
                         const childRequestId = `${requestId}:delegated:${resolvedSubagent.name}:${Date.now().toString(36)}`;
                         try {
-                            const result = await this.invoke(targetBinding, requestText, childSessionId, childRequestId, undefined, [], {
+                            const invokeOptions = {
                                 ...(typeof config?.context === "object" && config.context ? { context: config.context } : {}),
-                            });
+                            };
+                            const runDelegatedRequest = (text, requestSuffix = "") => this.invoke(targetBinding, text, childSessionId, `${childRequestId}${requestSuffix}`, undefined, [], invokeOptions);
+                            let result = await runDelegatedRequest(requestText);
+                            const targetRequiresExecutionToolEvidence = getBindingPrimaryTools(targetBinding).length > 0;
+                            if (targetRequiresExecutionToolEvidence && !hasDelegatedExecutionToolEvidence(result)) {
+                                result = await runDelegatedRequest([requestText, EXECUTION_WITH_TOOL_EVIDENCE_RETRY_INSTRUCTION].filter(Boolean).join("\n\n"), ":tool-evidence-retry");
+                                if (!hasDelegatedExecutionToolEvidence(result)) {
+                                    throw new DelegatedExecutionNoToolEvidenceError(targetBinding.agent.id);
+                                }
+                            }
                             return wrapRequestResultAsSubagentResponse({
                                 output: result.output,
                                 structuredResponse: result.structuredResponse,
@@ -331,9 +355,7 @@ export class AgentRuntimeAdapter {
                             const message = error instanceof Error && error.message.trim().length > 0
                                 ? error.message.trim()
                                 : "delegated execution failed";
-                            return wrapRequestResultAsSubagentResponse({
-                                output: `Blocked: ${message}`,
-                            });
+                            throw new Error(message);
                         }
                     },
                 },
@@ -422,18 +444,6 @@ export class AgentRuntimeAdapter {
             ownerId: binding.agent.id,
             skillPaths: getBindingSkills(binding),
         }) ?? [];
-        const deepAgentConfig = buildDeepAgentCreateParams({
-            binding,
-            resolvedModel,
-            resolvedTools: [...resolvedTools, ...builtinMiddlewareTools],
-            resolvedMiddleware,
-            resolvedSubagents,
-            resolvedCheckpointer,
-            resolvedStore,
-            resolvedBackend,
-            resolvedInterruptOn,
-            resolvedSkills,
-        });
         if (shouldUseConfigurableDeepAgentAssembly(binding)) {
             return this.createConfigurableDeepAgentRunnable(binding, {
                 resolvedModel,
@@ -441,36 +451,33 @@ export class AgentRuntimeAdapter {
                 resolvedMiddleware,
                 resolvedSubagents,
                 resolvedInterruptOn,
+                resolvedCheckpointer,
+                resolvedStore,
                 resolvedBackend,
                 resolvedSkills,
             });
         }
-        return createDeepAgent(deepAgentConfig);
+        throw new Error(`Agent ${binding.agent.id} has no supported deepagent assembly path`);
     }
     createConfigurableDeepAgentRunnable(binding, input) {
         const builtinTools = getBindingBuiltinToolsConfig(binding) ?? {};
         const backend = (input.resolvedBackend ?? new StateBackend({}));
         const inlineSubagents = input.resolvedSubagents.filter((subagent) => !("graphId" in subagent));
         const asyncSubagents = input.resolvedSubagents.filter((subagent) => "graphId" in subagent);
-        const subagents = inlineSubagents.some((subagent) => subagent.name === GENERAL_PURPOSE_SUBAGENT.name)
-            ? inlineSubagents
-            : [{
-                    ...GENERAL_PURPOSE_SUBAGENT,
-                    model: input.resolvedModel,
-                    tools: input.resolvedTools,
-                    skills: input.resolvedSkills,
-                }, ...inlineSubagents];
+        const subagents = inlineSubagents;
         const middleware = [
             ...(builtinTools.todos === false ? [] : [todoListMiddleware()]),
             ...(input.resolvedSkills.length > 0 ? [createSkillsMiddleware({ backend, sources: input.resolvedSkills })] : []),
             ...(builtinTools.filesystem === false ? [] : [createFilesystemMiddleware({ backend })]),
-            createSubAgentMiddleware({
-                defaultModel: input.resolvedModel,
-                defaultTools: input.resolvedTools,
-                defaultInterruptOn: input.resolvedInterruptOn,
-                subagents: subagents,
-                generalPurposeAgent: false,
-            }),
+            ...(subagents.length > 0
+                ? [createSubAgentMiddleware({
+                        defaultModel: input.resolvedModel,
+                        defaultTools: input.resolvedTools,
+                        defaultInterruptOn: input.resolvedInterruptOn,
+                        subagents: subagents,
+                        generalPurposeAgent: false,
+                    })]
+                : []),
             createSummarizationMiddleware({
                 model: input.resolvedModel,
                 backend,
@@ -487,10 +494,17 @@ export class AgentRuntimeAdapter {
             : undefined;
         return createAgent({
             model: input.resolvedModel,
-            systemPrompt: getBindingSystemPrompt(binding),
+            systemPrompt: buildDeepAgentSystemPromptWithCapabilityHierarchy({
+                systemPrompt: getBindingSystemPrompt(binding),
+                subagents: input.resolvedSubagents,
+                skills: input.resolvedSkills,
+                tools: getBindingPrimaryTools(binding),
+            }),
             tools: input.resolvedTools,
             middleware: middleware,
             name: binding.agent.id,
+            ...(input.resolvedCheckpointer !== undefined ? { checkpointer: input.resolvedCheckpointer } : {}),
+            ...(input.resolvedStore !== undefined ? { store: input.resolvedStore } : {}),
             ...(responseFormat !== undefined ? { responseFormat: responseFormat } : {}),
         });
     }

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

@@ -8,6 +8,16 @@ export declare function materializeModelExposedBuiltinMiddlewareTools(input: {
     explicitToolNames?: string[];
     modelExposed?: boolean | string[];
 }): unknown[];
+export declare function buildDeepAgentSystemPromptWithCapabilityHierarchy(input: {
+    systemPrompt?: unknown;
+    subagents: Array<Pick<UpstreamSubagentConfig, "name" | "description"> | Pick<CompiledAsyncSubAgent, "name" | "description">>;
+    skills?: string[];
+    tools?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}): unknown;
+export declare const buildDeepAgentSystemPromptWithSubagentCatalog: typeof buildDeepAgentSystemPromptWithCapabilityHierarchy;
 export declare function resolveRunnableCheckpointer(options: RuntimeAdapterOptions, binding: CompiledAgentBinding): unknown;
 export declare function resolveRunnableInterruptOn(binding: CompiledAgentBinding): Record<string, {
     allowedDecisions: import("./adapter/tool/interrupt-policy.js").InterruptDecision[];

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

@@ -2,6 +2,7 @@ import { MemorySaver } from "@langchain/langgraph";
 import { UPSTREAM_REQUEST_CONFIG_KEY, UPSTREAM_SESSION_CONFIG_KEY } from "./adapter/upstream-configurable-keys.js";
 import { asStructuredExecutableTool } from "./adapter/tool/resolved-tool.js";
 import { compileInterruptOn } from "./adapter/tool/interrupt-policy.js";
+import { readSkillMetadata } from "./skills/skill-metadata.js";
 import { getBindingBackendConfig, getBindingExecutionKind, getBindingExecutionParams, getBindingInterruptCompatibilityRules, getBindingMemorySources, getBindingMiddlewareConfigs, getBindingPrimaryTools, getBindingSkills, getBindingStoreConfig, } from "./support/compiled-binding.js";
 export const AGENT_INTERRUPT_SENTINEL_PREFIX = "__agent_harness_interrupt__:";
 export const DEFAULT_DEEPAGENT_RECURSION_LIMIT = 100;
@@ -37,6 +38,67 @@ export function materializeModelExposedBuiltinMiddlewareTools(input) {
     }
     return tools;
 }
+function formatCapabilityLine(item) {
+    const description = typeof item.description === "string" && item.description.length > 0
+        ? `: ${item.description}`
+        : "";
+    return `- ${JSON.stringify(item.name)}${description}`;
+}
+function buildSkillCatalog(skillPaths) {
+    return skillPaths.map((skillPath) => {
+        const metadata = readSkillMetadata(skillPath);
+        return {
+            name: metadata.name,
+            ...(metadata.description ? { description: metadata.description } : {}),
+        };
+    });
+}
+export function buildDeepAgentSystemPromptWithCapabilityHierarchy(input) {
+    const basePrompt = typeof input.systemPrompt === "string" ? input.systemPrompt : undefined;
+    const skills = buildSkillCatalog(input.skills ?? []);
+    const tools = input.tools ?? [];
+    if (input.subagents.length === 0 && skills.length === 0 && tools.length === 0) {
+        return input.systemPrompt;
+    }
+    const catalogPrompt = [
+        "Capability selection hierarchy:",
+        "1. If the current request fits an available subagent, delegate with the task tool before using local skills or raw tools.",
+        "2. If you are the selected agent and an available skill fits the request, read and follow that skill before calling raw tools.",
+        "3. Use raw tools as execution primitives for the selected agent or skill, or when no listed skill applies.",
+        "Keep each selection inside the selected capability's described responsibility boundary.",
+        "If no listed subagent, skill, or tool can responsibly handle the request, do not invent a path. Return a terminal response with status \"refused\" and explain the missing capability.",
+        "If a selected capability cannot complete after using its available tools, return a terminal response with status \"blocked\" or \"failed\" and include the blocker evidence.",
+        ...(input.subagents.length > 0
+            ? [
+                "",
+                "Available subagents for task delegation:",
+                ...input.subagents.map(formatCapabilityLine),
+                "",
+                "When using the task tool, set subagent_type to exactly one of the listed subagent names. Do not create, translate, alias, or modify subagent names.",
+            ]
+            : [
+                "",
+                "No configured specialist subagents are available for this agent. Do not use task delegation for role-internal work; select a skill first, then tools.",
+            ]),
+        ...(skills.length > 0
+            ? [
+                "",
+                "Available skills for this agent:",
+                ...skills.map(formatCapabilityLine),
+            ]
+            : []),
+        ...(tools.length > 0
+            ? [
+                "",
+                "Raw tools available to this agent:",
+                ...tools.map(formatCapabilityLine),
+            ]
+            : []),
+        "",
+    ].join("\n");
+    return [basePrompt, catalogPrompt].filter((part) => typeof part === "string" && part.length > 0).join("\n\n");
+}
+export const buildDeepAgentSystemPromptWithSubagentCatalog = buildDeepAgentSystemPromptWithCapabilityHierarchy;
 export function resolveRunnableCheckpointer(options, binding) {
     return options.checkpointerResolver ? options.checkpointerResolver(binding) : new MemorySaver();
 }
@@ -146,6 +208,12 @@ export function buildDeepAgentCreateParams(input) {
     ]);
     return {
         ...upstreamParams,
+        systemPrompt: buildDeepAgentSystemPromptWithSubagentCatalog({
+            systemPrompt: upstreamParams.systemPrompt,
+            subagents: input.resolvedSubagents,
+            skills: input.resolvedSkills,
+            tools: getBindingPrimaryTools(input.binding),
+        }),
         skills: input.resolvedSkills,
         model: input.resolvedModel,
         tools: input.resolvedTools,