@kody-ade/kody-engine 0.4.509 → 0.4.511

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.509",
+      version: "0.4.511",
       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,15 @@ 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 +1986,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 +3735,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 +3771,12 @@ async function runAgent(opts) {
               matcher: "Agent",
               hooks: [enforceSubagentModelInheritance]
             }
+          ],
+          PostToolUse: [
+            {
+              matcher: "Agent",
+              hooks: [subagentInvocationHook]
+            }
           ]
         }
       };
@@ -4072,7 +4098,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;
@@ -4884,9 +4911,7 @@ var init_capability_contract_validation = __esm({
           const property = error.keyword === "additionalProperties" && typeof error.params.additionalProperty === "string" ? ` (${error.params.additionalProperty})` : "";
           return `${location}: ${error.message ?? error.keyword}${property}`;
         }).join("; ");
-        super(
-          `Capability ${boundary} does not match its declared contract: ${details}`
-        );
+        super(`Capability ${boundary} does not match its declared contract: ${details}`);
         this.boundary = boundary;
         this.errors = errors;
         this.name = "CapabilityContractValidationError";
@@ -7921,10 +7946,7 @@ function capabilityInputEnvironment(input) {
 function capabilityConfigEnvironment(config) {
   if (!config || typeof config !== "object" || Array.isArray(config)) return {};
   return Object.fromEntries(
-    flattenConfig(config).map(([key, value]) => [
-      `KODY_CFG_${key}`,
-      value
-    ])
+    flattenConfig(config).map(([key, value]) => [`KODY_CFG_${key}`, value])
   );
 }
 function flattenConfig(config, prefix = "") {
@@ -7937,9 +7959,7 @@ function flattenConfig(config, prefix = "") {
     } else if (Array.isArray(value)) {
       entries.push([key, JSON.stringify(value)]);
     } else if (typeof value === "object") {
-      entries.push(
-        ...flattenConfig(value, key)
-      );
+      entries.push(...flattenConfig(value, key));
     }
   }
   return entries;
@@ -13619,9 +13639,7 @@ import { randomUUID } from "crypto";
 function assertLoopDispatchesSucceeded(results) {
   const failed = results.filter((result) => result.status === "failed");
   if (failed.length === 0) return;
-  throw new Error(
-    `Loop dispatch failed: ${failed.map((result) => `${result.loopId}: ${result.reason}`).join("; ")}`
-  );
+  throw new Error(`Loop dispatch failed: ${failed.map((result) => `${result.loopId}: ${result.reason}`).join("; ")}`);
 }
 async function dispatchLoopsWith(input) {
   const results = [];
@@ -15668,10 +15686,10 @@ var init_loadQaContext = __esm({
 });
 
 // src/scripts/loadSimpleCapability.ts
+import { randomUUID as randomUUID2 } from "crypto";
 import * as fs43 from "fs";
-import * as path40 from "path";
 import * as os6 from "os";
-import { randomUUID as randomUUID2 } from "crypto";
+import * as path40 from "path";
 function registerCapabilitySubagents(profile, toolRoot, toolFiles) {
   const subagentFiles = toolFiles.flatMap((file) => {
     const match = /^agents\/([a-z][a-z0-9-]{0,63})\.md$/.exec(file);
@@ -15770,6 +15788,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 +15852,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 +16807,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 +16857,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);
@@ -21076,9 +21133,7 @@ async function runImplementation(profileName, input) {
           profile.inputs,
           args,
           profile.canonicalContract.capabilityId,
-          Object.keys(
-            profile.canonicalContract.inputSchema.properties ?? {}
-          )
+          Object.keys(profile.canonicalContract.inputSchema.properties ?? {})
         )
       );
     }
@@ -22560,7 +22615,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 +22692,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 +24905,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 +25402,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 });

package/package.json

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