@kody-ade/kody-engine 0.4.508 → 0.4.510

package/dist/bin/kody.js

@@ -15,7 +15,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@kody-ade/kody-engine",
-      version: "0.4.508",
+      version: "0.4.510",
       description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative implementation profiles.",
       license: "MIT",
       type: "module",
@@ -809,6 +809,16 @@ async function enforceSubagentModelInheritance(input) {
     }
   };
 }
+function createSubagentInvocationHook(invokedSubagents) {
+  return async (input) => {
+    const toolInput = input.tool_input;
+    if (toolInput && typeof toolInput === "object" && !Array.isArray(toolInput)) {
+      const subagentType = toolInput.subagent_type;
+      if (typeof subagentType === "string" && subagentType.length > 0) invokedSubagents.add(subagentType);
+    }
+    return {};
+  };
+}
 function splitFrontmatter(raw) {
   const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw);
   if (!match) return { fm: {}, body: raw.trim() };
@@ -1959,8 +1969,17 @@ function parseCapabilityContract(raw) {
   if (timeoutMs !== void 0 && parsed.execution !== "script") {
     throw new Error('contract.json timeoutMs is supported only when execution is "script"');
   }
+  const requiredSubagents = parsed.requiredSubagents === void 0 ? void 0 : Array.isArray(parsed.requiredSubagents) && parsed.requiredSubagents.length > 0 && parsed.requiredSubagents.every(
+    (name) => typeof name === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(name)
+  ) ? [...new Set(parsed.requiredSubagents)] : null;
+  if (requiredSubagents === null) {
+    throw new Error("contract.json requiredSubagents must contain valid specialist names");
+  }
+  if (requiredSubagents && parsed.execution !== "agent") {
+    throw new Error('contract.json requiredSubagents are supported only when execution is "agent"');
+  }
   const unsupported = Object.keys(parsed).filter(
-    (key) => key !== "execution" && key !== "secrets" && key !== "timeoutMs" && key !== "input" && key !== "output"
+    (key) => key !== "execution" && key !== "secrets" && key !== "timeoutMs" && key !== "requiredSubagents" && key !== "input" && key !== "output"
   );
   if (unsupported.length > 0) {
     throw new Error(`contract.json contains unsupported fields: ${unsupported.join(", ")}`);
@@ -1969,6 +1988,7 @@ function parseCapabilityContract(raw) {
     ...parsed.execution ? { execution: parsed.execution } : {},
     ...secrets ? { secrets } : {},
     ...timeoutMs !== void 0 ? { timeoutMs } : {},
+    ...requiredSubagents ? { requiredSubagents } : {},
     input: parsed.input,
     output: parsed.output
   };
@@ -3717,6 +3737,8 @@ async function runAgent(opts) {
   let messageCount = 0;
   let finalText = "";
   let getSubmitted;
+  const invokedSubagents = /* @__PURE__ */ new Set();
+  const subagentInvocationHook = createSubagentInvocationHook(invokedSubagents);
   for (let attempt = 0; ; attempt++) {
     let ndjsonWriteFailed = false;
     let ndjsonWriteError;
@@ -3751,6 +3773,12 @@ async function runAgent(opts) {
               matcher: "Agent",
               hooks: [enforceSubagentModelInheritance]
             }
+          ],
+          PostToolUse: [
+            {
+              matcher: "Agent",
+              hooks: [subagentInvocationHook]
+            }
           ]
         }
       };
@@ -4072,7 +4100,8 @@ async function runAgent(opts) {
     durationMs: Date.now() - startedAt,
     tokens,
     costUsd,
-    messageCount
+    messageCount,
+    invokedSubagents: [...invokedSubagents]
   };
 }
 var DEFAULT_ALLOWED_TOOLS, DEFAULT_TURN_TIMEOUT_MS, MAX_CONNECTION_RETRIES, CONNECTION_RETRY_BASE_MS, MUTATING_FILE_TOOLS, BASH_WRITE_VERB, AGENT_KEEP_SECRETS;
@@ -15770,6 +15799,13 @@ var init_loadSimpleCapability = __esm({
       if (ctx.data.capabilityExecution === "agent") {
         registerCapabilitySubagents(profile, toolRoot, toolFiles);
       }
+      const requiredSubagents = capability.contract?.requiredSubagents ?? [];
+      for (const required2 of requiredSubagents) {
+        if (!profile.claudeCode.subagents.includes(required2)) {
+          throw new Error(`Capability "${slug}" required specialist ${required2} is not available`);
+        }
+      }
+      if (requiredSubagents.length > 0) ctx.data.requiredSubagents = requiredSubagents;
       if (capability.contract?.execution === "script") {
         ctx.data.capabilityScriptPath = path40.join(capability.dir, "tools", "run.sh");
         ctx.data.capabilitySecretNames = capability.contract.secrets ?? [];
@@ -15827,7 +15863,14 @@ var init_loadSimpleCapability = __esm({
             outputPath,
             "The Engine reads this file as the authoritative result. Do not write markdown to it."
           ] : []
-        ] : ["Return one JSON value."]
+        ] : ["Return one JSON value."],
+        ...requiredSubagents.length > 0 ? [
+          "",
+          "## Required specialists",
+          "",
+          `You must invoke each of these private specialists before returning: ${requiredSubagents.join(", ")}.`,
+          "The Engine verifies the actual Agent calls and blocks the capability if any are skipped."
+        ] : []
       ].join("\n");
     };
   }
@@ -16775,6 +16818,9 @@ var init_parseReproOutput = __esm({
 
 // src/scripts/parseSimpleCapabilityOutput.ts
 import * as fs45 from "fs";
+function stringList2(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
 function readOutputFile(outputPath) {
   if (!outputPath || !fs45.existsSync(outputPath)) return { found: false };
   try {
@@ -16822,6 +16868,28 @@ var init_parseSimpleCapabilityOutput = __esm({
     init_capability_contract_validation();
     init_capabilityResult();
     parseSimpleCapabilityOutput = async (ctx, _profile, agentResult) => {
+      const requiredSubagents = stringList2(ctx.data.requiredSubagents);
+      const invokedSubagents = new Set(agentResult?.invokedSubagents ?? []);
+      const missingSubagents = requiredSubagents.filter((name) => !invokedSubagents.has(name));
+      if (missingSubagents.length > 0) {
+        const label = missingSubagents.length === 1 ? "specialist was" : "specialists were";
+        const reason2 = `Required ${label} not invoked: ${missingSubagents.join(", ")}`;
+        ctx.output.exitCode = 64;
+        ctx.output.reason = reason2;
+        ctx.data.capabilityOutput = { status: "blocked", reason: reason2, summary: reason2 };
+        ctx.data.capabilityResults = [
+          {
+            version: 1,
+            status: "blocked",
+            summary: reason2,
+            facts: {},
+            artifacts: [],
+            missingEvidence: [],
+            blockers: [reason2]
+          }
+        ];
+        return;
+      }
       const outputPath = typeof ctx.data.capabilityOutputPath === "string" ? ctx.data.capabilityOutputPath : void 0;
       const fileOutput = readOutputFile(outputPath);
       const output = fileOutput.found ? fileOutput.value : Object.hasOwn(ctx.data, "capabilityScriptOutput") ? ctx.data.capabilityScriptOutput : parseOutput(agentResult?.finalText);
@@ -22560,7 +22628,8 @@ async function runGraphCapabilityWorkflow(parent, workflow, capability, base, ch
     }
     const transition = selectWorkflowTransition(step, chainData, state.transitionCounts);
     if (!transition) {
-      const reason = `workflow step ${step.id} has no available connection`;
+      const exhausted = exhaustedWorkflowTransitions(step, chainData, state.transitionCounts);
+      const reason = exhausted.length > 0 ? `workflow step ${step.id} reached iteration limit: ${exhausted.join(", ")}` : `workflow step ${step.id} has no available connection`;
       state.status = "blocked";
       state.blocker = reason;
       await checkpoint?.(state);
@@ -22636,6 +22705,15 @@ function selectWorkflowTransition(step, data, counts) {
   }
   return fallback;
 }
+function exhaustedWorkflowTransitions(step, data, counts) {
+  return (step.next ?? []).flatMap((transition) => {
+    if (transition.maxIterations === void 0) return [];
+    const key = `${step.id}->${transition.to}`;
+    if ((counts[key] ?? 0) < transition.maxIterations) return [];
+    const matches = transition.default === true || !transition.when || conditionMatches(transition.when, workflowConditionContext(data));
+    return matches ? [`${key} (${transition.maxIterations})`] : [];
+  });
+}
 function workflowResultConditionPaths(transitions) {
   return transitions.flatMap(
     (transition) => Object.keys(transition.when ?? {}).filter((path53) => path53.startsWith("result."))
@@ -24840,8 +24918,13 @@ Exit codes (inherited from kody run):
   2   verify failed (no PR opened \u2014 branch pushed for inspection)
   3   no commits to ship
   4   PR creation failed
+  64  capability or workflow blocked by an invalid or exhausted route
+  124 execution timed out
   99  wrapper crashed
 `;
+function normalizeJobExitCode(exitCode) {
+  return Number.isInteger(exitCode) && exitCode >= 0 && exitCode <= 255 ? exitCode : 99;
+}
 function parseCiArgs(argv) {
   const result = { errors: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -25332,7 +25415,9 @@ async function runCi(argv) {
       }
     );
     const ec = result.exitCode;
-    return ec === 0 || ec === 1 || ec === 2 ? ec : 99;
+    if (ec !== 0 && result.reason) process.stderr.write(`[kody] ${result.reason}
+`);
+    return normalizeJobExitCode(ec);
   }
   if (!args.issueNumber && !autoFallback && runRequestFanOut) {
     return runScheduledFanOut(cwd, args, { force: runRequestFanOutForce });
@@ -28433,7 +28518,9 @@ function envRunRequest(env = process.env) {
   const { target } = parsed.request;
   if (target.type === "chat") return { ...result, command: "chat", chatArgv: [] };
   if (target.type === "issue") return { ...result, command: "ci", ciArgv: ["--issue", String(target.id)] };
-  if (target.type === "goal" || target.type === "workflow") return { ...result, command: "ci", ciArgv: [] };
+  if (target.type === "goal" || target.type === "loop" || target.type === "workflow") {
+    return { ...result, command: "ci", ciArgv: [] };
+  }
   return { ...result, errors: [`unsupported runRequest target: ${target.type ?? "unknown"}`] };
 }
 var HELP_TEXT = `kody-engine \u2014 single-session autonomous engineer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.508",
+  "version": "0.4.510",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative implementation profiles.",
   "license": "MIT",
   "type": "module",