@kody-ade/kody-engine 0.4.458 → 0.4.459

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.458",
+      version: "0.4.459",
       description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative implementation profiles.",
       license: "MIT",
       type: "module",
@@ -1651,15 +1651,7 @@ import * as fs4 from "fs";
 import * as path5 from "path";
 function capabilityOutputConditionPaths(config) {
   if (config.outputSchema) {
-    const properties = isPlainObject(config.outputSchema.properties) ? config.outputSchema.properties : void 0;
-    const factContract = isPlainObject(properties?.facts) ? properties.facts : void 0;
-    const facts = isPlainObject(factContract?.properties) ? factContract.properties : void 0;
-    return /* @__PURE__ */ new Set([
-      ...properties?.status ? ["result.status"] : [],
-      ...properties?.summary ? ["result.summary"] : [],
-      ...properties?.resultClass ? ["result.resultClass"] : [],
-      ...Object.keys(facts ?? {}).map((fact) => `result.facts.${fact}`)
-    ]);
+    return new Set(schemaPropertyPaths(config.outputSchema, "result"));
   }
   const result = config.output?.result;
   if (!result) return /* @__PURE__ */ new Set();
@@ -1684,35 +1676,61 @@ function isCapabilityFolder(dir) {
   if (!fs4.existsSync(path5.join(dir, CAPABILITY_BODY_FILE))) return false;
   const entries = fs4.readdirSync(dir, { withFileTypes: true });
   return entries.every(
-    (entry) => entry.name === CAPABILITY_BODY_FILE || entry.isDirectory() && (entry.name === "skills" || entry.name === "tools")
+    (entry) => entry.name === CAPABILITY_BODY_FILE || entry.name === CAPABILITY_CONTRACT_FILE || entry.isDirectory() && (entry.name === "skills" || entry.name === "tools")
   );
 }
 function readCapabilityFolder(root, slug) {
   const dir = path5.join(root, slug);
   const bodyPath = path5.join(dir, CAPABILITY_BODY_FILE);
+  const contractPath = path5.join(dir, CAPABILITY_CONTRACT_FILE);
   if (!fs4.existsSync(bodyPath) || !fs4.statSync(bodyPath).isFile()) return null;
   if (!isCapabilityFolder(dir)) return null;
   try {
     const rawBody = fs4.readFileSync(bodyPath, "utf-8");
+    const contract = fs4.existsSync(contractPath) ? parseCapabilityContract(fs4.readFileSync(contractPath, "utf-8")) : void 0;
     const { title, body } = parseCapabilityBody(rawBody, slug);
     return {
       slug,
       dir,
       profilePath: bodyPath,
       bodyPath,
+      ...contract ? { contractPath } : {},
       title,
       body,
       rawBody,
       config: {
         action: slug,
-        describe: title
+        describe: title,
+        ...contract ? {
+          inputSchema: contract.input,
+          outputSchema: contract.output
+        } : {}
       },
-      rawProfile: {}
+      rawProfile: contract ? { input: contract.input, output: contract.output } : {},
+      ...contract ? { contract } : {}
     };
   } catch {
     return null;
   }
 }
+function parseCapabilityContract(raw) {
+  const parsed = JSON.parse(raw);
+  if (!isPlainObject(parsed) || !isPlainObject(parsed.input) || !isPlainObject(parsed.output)) {
+    throw new Error("contract.json must contain input and output JSON schemas");
+  }
+  const unsupported = Object.keys(parsed).filter((key) => key !== "input" && key !== "output");
+  if (unsupported.length > 0) {
+    throw new Error(`contract.json contains unsupported fields: ${unsupported.join(", ")}`);
+  }
+  return { input: parsed.input, output: parsed.output };
+}
+function schemaPropertyPaths(schema, prefix) {
+  const properties = isPlainObject(schema.properties) ? schema.properties : {};
+  return Object.entries(properties).flatMap(([name, property]) => {
+    const path53 = `${prefix}.${name}`;
+    return isPlainObject(property) ? [path53, ...schemaPropertyPaths(property, path53)] : [path53];
+  });
+}
 function parseCapabilityBody(raw, slug) {
   const trimmed = raw.trim();
   const firstLine2 = trimmed.split("\n", 1)[0] ?? "";
@@ -1848,11 +1866,12 @@ function isSafeSlug(value) {
 function isSafeStepId(value) {
   return /^[A-Za-z][A-Za-z0-9_-]*$/.test(value) && !value.includes("..");
 }
-var CAPABILITY_BODY_FILE, CAPABILITY_PROFILE_FILE;
+var CAPABILITY_BODY_FILE, CAPABILITY_CONTRACT_FILE, CAPABILITY_PROFILE_FILE;
 var init_capabilityFolders = __esm({
   "src/capabilityFolders.ts"() {
     "use strict";
     CAPABILITY_BODY_FILE = "instructions.md";
+    CAPABILITY_CONTRACT_FILE = "contract.json";
     CAPABILITY_PROFILE_FILE = CAPABILITY_BODY_FILE;
   }
 });
@@ -4214,24 +4233,6 @@ var init_agencyBoundaryEval = __esm({
   }
 });
 
-// src/capabilityDelivery.ts
-function capabilityDeliveryTarget(input) {
-  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
-  const value = input;
-  const issue2 = positiveInteger(value.issue);
-  const pr = positiveInteger(value.pr);
-  if (issue2 === null === (pr === null)) return null;
-  return issue2 === null ? { kind: "pr", number: pr } : { kind: "issue", number: issue2 };
-}
-function positiveInteger(value) {
-  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
-}
-var init_capabilityDelivery = __esm({
-  "src/capabilityDelivery.ts"() {
-    "use strict";
-  }
-});
-
 // src/agency/capability-contract-validation.ts
 import Ajv from "ajv";
 function validateCapabilityContractValue(boundary, schema, value) {
@@ -4252,7 +4253,7 @@ var init_capability_contract_validation = __esm({
     CapabilityContractValidationError = class extends Error {
       constructor(boundary, errors) {
         super(
-          `Capability ${boundary} does not match its canonical contract: ${validator.errorsText([...errors], {
+          `Capability ${boundary} does not match its declared contract: ${validator.errorsText([...errors], {
             separator: "; "
           })}`
         );
@@ -4370,7 +4371,7 @@ function parseGoalEvidenceProgress(value) {
     ...stringField2(raw.reason) ? { reason: stringField2(raw.reason) } : {},
     ...stringField2(raw.nextAction) ? { nextAction: stringField2(raw.nextAction) } : {},
     ...stringField2(raw.nextRetryAt) ? { nextRetryAt: stringField2(raw.nextRetryAt) } : {},
-    ...positiveInteger2(raw.issue) ? { issue: positiveInteger2(raw.issue) } : {},
+    ...positiveInteger(raw.issue) ? { issue: positiveInteger(raw.issue) } : {},
     ...stringField2(raw.updatedAt) ? { updatedAt: stringField2(raw.updatedAt) } : {}
   };
 }
@@ -4386,7 +4387,7 @@ function definedProgressFields(update) {
 function stringField2(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
-function positiveInteger2(value) {
+function positiveInteger(value) {
   if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
   return void 0;
 }
@@ -9010,6 +9011,13 @@ function validateWorkflow(value, options = {}) {
         issue(issues, "invalid_transition_target", `${base}.to`, "workflow connection must name a valid target step");
         return;
       }
+      if (raw.default === true && raw.when !== void 0) {
+        issue(issues, "conflicting_transition", base, "workflow connection cannot be both conditional and default");
+      }
+      if (raw.when !== void 0) {
+        const outputPaths = options.capabilityOutputs?.get(sourceCapability ?? "");
+        validateDataMatch(raw.when, `${base}.when`, issues, outputPaths);
+      }
       if (target === "$end") {
         explicitEndSources.add(id);
         return;
@@ -9024,13 +9032,6 @@ function validateWorkflow(value, options = {}) {
       } else {
         adjacency.get(id)?.push(target);
       }
-      if (raw.default === true && raw.when !== void 0) {
-        issue(issues, "conflicting_transition", base, "workflow connection cannot be both conditional and default");
-      }
-      if (raw.when !== void 0) {
-        const outputPaths = options.capabilityOutputs?.get(sourceCapability ?? "");
-        validateDataMatch(raw.when, `${base}.when`, issues, outputPaths);
-      }
       const targetIndex = ids.indexOf(target ?? "");
       const iterations = raw.maxIterations;
       if (targetIndex >= 0 && targetIndex <= index) {
@@ -16222,6 +16223,7 @@ var loadSimpleCapability;
 var init_loadSimpleCapability = __esm({
   "src/scripts/loadSimpleCapability.ts"() {
     "use strict";
+    init_capability_contract_validation();
     init_capabilityFolders();
     init_definition_paths();
     loadSimpleCapability = async (ctx) => {
@@ -16238,9 +16240,14 @@ var init_loadSimpleCapability = __esm({
       const toolFiles = listFiles(toolRoot);
       const skillFiles = listFiles(skillRoot);
       const input = parseInput(ctx.args.input);
-      const delivery = ctx.data.jobDelivery === "pull-request";
+      if (capability.config.inputSchema) {
+        validateCapabilityContractValue("input", capability.config.inputSchema, input);
+      }
       ctx.data.jobCapability = slug;
       ctx.data.capabilityInput = input;
+      if (capability.config.outputSchema) {
+        ctx.data.capabilityOutputSchema = capability.config.outputSchema;
+      }
       ctx.data.capabilityEnvironment = capabilityEnvironment(input);
       ctx.data.prompt = [
         capability.rawBody.trim(),
@@ -16251,21 +16258,6 @@ var init_loadSimpleCapability = __esm({
         JSON.stringify(input ?? null, null, 2),
         "```",
         "",
-        ...delivery ? [
-          "## Delivery",
-          "",
-          "The wrapper owns git commits, pushes, and pull requests. Do not run git or gh write commands.",
-          "Finish with exactly this structure:",
-          "",
-          "DONE",
-          "PLAN_DEVIATIONS: none",
-          "COMMIT_MSG: <conventional commit message>",
-          "PR_SUMMARY:",
-          "- <what changed>",
-          "```json",
-          '{"summary":"<result>","status":"changed"}',
-          "```"
-        ] : ["Return one JSON value."],
         ...skillFiles.length ? [
           "",
           "## Skills",
@@ -16283,7 +16275,17 @@ var init_loadSimpleCapability = __esm({
           "",
           "Inspect or run these capability-owned files when needed:",
           ...toolFiles.map((file) => `- ${path40.join(toolRoot, file)}`)
-        ] : []
+        ] : [],
+        "",
+        ...capability.config.outputSchema ? [
+          "## Output contract",
+          "",
+          "Produce one JSON result matching this schema:",
+          "",
+          "```json",
+          JSON.stringify(capability.config.outputSchema, null, 2),
+          "```"
+        ] : ["Return one JSON value."]
       ].join("\n");
     };
   }
@@ -17266,6 +17268,7 @@ var parseSimpleCapabilityOutput;
 var init_parseSimpleCapabilityOutput = __esm({
   "src/scripts/parseSimpleCapabilityOutput.ts"() {
     "use strict";
+    init_capability_contract_validation();
     parseSimpleCapabilityOutput = async (ctx, _profile, agentResult) => {
       const output = parseOutput(agentResult?.finalText);
       if (output === void 0) {
@@ -17290,6 +17293,29 @@ var init_parseSimpleCapabilityOutput = __esm({
         ];
         return;
       }
+      const outputSchema = isObject2(ctx.data.capabilityOutputSchema) ? ctx.data.capabilityOutputSchema : void 0;
+      if (outputSchema) {
+        try {
+          validateCapabilityContractValue("output", outputSchema, output);
+        } catch (error) {
+          const reason2 = error instanceof Error ? error.message : String(error);
+          ctx.output.exitCode = 64;
+          ctx.output.reason = reason2;
+          ctx.data.capabilityOutput = output;
+          ctx.data.capabilityResults = [
+            {
+              version: 1,
+              status: "blocked",
+              summary: reason2,
+              facts: {},
+              artifacts: [],
+              missingEvidence: [],
+              blockers: [reason2]
+            }
+          ];
+          return;
+        }
+      }
       ctx.data.capabilityOutput = output;
       const result = isObject2(output) ? output : {};
       const data = isObject2(result.data) ? result.data : isObject2(output) ? output : { output };
@@ -17965,6 +17991,24 @@ var init_prepareBrowserAuth = __esm({
   }
 });
 
+// src/capabilityDelivery.ts
+function capabilityDeliveryTarget(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+  const value = input;
+  const issue2 = positiveInteger2(value.issue);
+  const pr = positiveInteger2(value.pr);
+  if (issue2 === null === (pr === null)) return null;
+  return issue2 === null ? { kind: "pr", number: pr } : { kind: "issue", number: issue2 };
+}
+function positiveInteger2(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}
+var init_capabilityDelivery = __esm({
+  "src/capabilityDelivery.ts"() {
+    "use strict";
+  }
+});
+
 // src/scripts/runFlow.ts
 function tryPost(issueNumber, body, cwd) {
   try {
@@ -22274,6 +22318,34 @@ var init_executor = __esm({
   }
 });
 
+// src/simpleCapabilityRuntime.ts
+function resolveSimpleCapabilityRuntime(implementation, delivery) {
+  if (implementation !== SIMPLE_CAPABILITY_RUNTIME) return null;
+  return {
+    implementation: delivery ? DELIVERY_RUNTIMES[delivery] : SIMPLE_CAPABILITY_RUNTIME,
+    ...delivery ? { delivery } : {}
+  };
+}
+function simpleCapabilityRuntimeArgs(runtime, capability, input) {
+  const deliveryTarget = runtime.delivery ? capabilityDeliveryTarget(input) : null;
+  return {
+    capability,
+    ...input !== void 0 ? { input: JSON.stringify(input) } : {},
+    ...deliveryTarget ? { [deliveryTarget.kind]: deliveryTarget.number } : {}
+  };
+}
+var SIMPLE_CAPABILITY_RUNTIME, DELIVERY_RUNTIMES;
+var init_simpleCapabilityRuntime = __esm({
+  "src/simpleCapabilityRuntime.ts"() {
+    "use strict";
+    init_capabilityDelivery();
+    SIMPLE_CAPABILITY_RUNTIME = "capability-run";
+    DELIVERY_RUNTIMES = {
+      "pull-request": "capability-delivery"
+    };
+  }
+});
+
 // src/workflowRunState.ts
 function workflowRunStatePath(workflowId, runId) {
   if (!SAFE_ID.test(workflowId)) throw new Error(`invalid workflow id ${workflowId}`);
@@ -22434,7 +22506,8 @@ async function runJob(job, base) {
   }
   const workflow = capabilityContext?.config.workflow ?? workflowContext?.config.workflow;
   const workflowIdentity = valid.workflow ?? capabilityIdentity ?? workflowContext?.slug;
-  const capabilitySelectedImplementation = valid.delivery === "pull-request" && resolvedCapability?.implementation === "capability-run" ? "capability-delivery" : resolvedCapability?.implementation ?? capabilityContext?.config.implementation ?? capabilityContext?.config.implementations?.[0] ?? (capabilityContext?.config.role ? capabilityContext.slug : void 0) ?? (capabilityContext?.config.tickScript ? "capability-tick-scripted" : void 0);
+  const simpleCapabilityRuntime = resolveSimpleCapabilityRuntime(resolvedCapability?.implementation, valid.delivery);
+  const capabilitySelectedImplementation = simpleCapabilityRuntime?.implementation ?? resolvedCapability?.implementation ?? capabilityContext?.config.implementation ?? capabilityContext?.config.implementations?.[0] ?? (capabilityContext?.config.role ? capabilityContext.slug : void 0) ?? (capabilityContext?.config.tickScript ? "capability-tick-scripted" : void 0);
   const profileName = explicitImplementation ?? capabilitySelectedImplementation;
   if (workflow && shouldRunCapabilityWorkflow(valid, workflow, workflowIdentity, capabilitySelectedImplementation, base)) {
     const workflowCapability = capabilityContext ?? workflowContext;
@@ -22519,6 +22592,7 @@ async function runDefaultCapabilityWorkflow(job, profileName, capabilityIdentity
   );
 }
 async function runCapabilityImplementationStep(valid, profileName, capabilityIdentity, capabilityContext, resolvedCapability, base) {
+  const simpleCapabilityRuntime = resolveSimpleCapabilityRuntime(resolvedCapability?.implementation, valid.delivery);
   const preloadedData = { ...base.preloadedData ?? {} };
   preloadedData.jobId = newJobId(valid.flavor);
   preloadedData.jobKey = stableJobKey(valid);
@@ -22564,14 +22638,9 @@ async function runCapabilityImplementationStep(valid, profileName, capabilityIde
   };
   const shouldApplyResolvedCapabilityArgs = valid.implementation === void 0 && resolvedCapability && profileName === resolvedCapability.implementation;
   input.cliArgs = shouldApplyResolvedCapabilityArgs ? { ...resolvedCapability.cliArgs, ...input.cliArgs } : input.cliArgs;
-  if ((profileName === "capability-run" || profileName === "capability-delivery") && capabilityIdentity) {
+  if (simpleCapabilityRuntime && profileName === simpleCapabilityRuntime.implementation && capabilityIdentity) {
     const capabilityInput = Object.keys(valid.cliArgs).length > 0 ? genericInputFromArgs(valid.cliArgs) : void 0;
-    const deliveryTarget = profileName === "capability-delivery" && capabilityInput && typeof capabilityInput === "object" ? capabilityDeliveryArgs(capabilityInput) : {};
-    input.cliArgs = {
-      capability: capabilityIdentity,
-      ...capabilityInput !== void 0 ? { input: JSON.stringify(capabilityInput) } : {},
-      ...deliveryTarget
-    };
+    input.cliArgs = simpleCapabilityRuntimeArgs(simpleCapabilityRuntime, capabilityIdentity, capabilityInput);
   }
   const run = base.chain === false ? runImplementation : runImplementationChain;
   return run(profileName, input);
@@ -22937,10 +23006,6 @@ function workflowStepToJob(step, parent, chainData, cwd) {
     ...parent.resultTarget ? { resultTarget: parent.resultTarget } : {}
   };
 }
-function capabilityDeliveryArgs(input) {
-  const target = capabilityDeliveryTarget(input);
-  return target ? { [target.kind]: target.number } : {};
-}
 function usesGenericCapabilityInput(action, cwd) {
   const inputs = getCapabilityActionInputs(action, hydratedCapabilitiesRoot(cwd));
   return Boolean(inputs?.length === 1 && inputs[0]?.name === "input" && inputs[0]?.flag === "--input");
@@ -23105,12 +23170,12 @@ var init_job = __esm({
   "src/job.ts"() {
     "use strict";
     init_agencyBoundaryEval();
-    init_capabilityDelivery();
     init_capabilityFolders();
     init_definition_paths();
     init_executor();
     init_registry();
     init_runIndex();
+    init_simpleCapabilityRuntime();
     init_state_backend();
     init_workflowDefinitions();
     init_workflowRunState();

package/dist/runtime-services/capability-delivery/prompt.md

@@ -1 +1,17 @@
 {{prompt}}
+
+## Delivery
+
+The delivery wrapper owns git commits, pushes, and pull requests. Do not run
+git or GitHub write commands.
+
+After completing the capability work, finish with exactly this structure:
+
+DONE
+PLAN_DEVIATIONS: none
+COMMIT_MSG: <conventional commit message>
+PR_SUMMARY:
+- <what changed>
+```json
+<the capability result matching its output contract>
+```

package/package.json

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