@kody-ade/kody-engine 0.4.430 → 0.4.431

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.430",
+      version: "0.4.431",
       description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative implementation profiles.",
       license: "MIT",
       type: "module",
@@ -54,6 +54,7 @@ var init_package = __esm({
         "@anthropic-ai/claude-agent-sdk": "0.2.119",
         "@kody-ade/agency-domain": "0.5.1",
         "@modelcontextprotocol/sdk": "^1.29.0",
+        ajv: "^8.18.0",
         convex: "^1.17.0",
         zod: "^4.0.0"
       },
@@ -255,6 +256,7 @@ function loadConfig(projectDir = process.cwd()) {
       ...parsePerImplementationReasoningEffort(agent.perImplementationReasoningEffort),
       ...parseAgentReasoningEffort(agent.reasoningEffort)
     },
+    execution: parseExecutionConfig(raw.execution),
     issueContext: parseIssueContext(raw.issueContext),
     testRequirements: parseTestRequirements(raw.testRequirements),
     defaultImplementation: typeof raw.defaultImplementation === "string" && raw.defaultImplementation.length > 0 ? raw.defaultImplementation : "run",
@@ -267,6 +269,18 @@ function loadConfig(projectDir = process.cwd()) {
     access: parseAccessConfig(raw.access)
   };
 }
+function parseExecutionConfig(value) {
+  const execution = recordValue(value);
+  const bindings = recordValue(execution?.capabilityBindings);
+  if (!bindings) return void 0;
+  const capabilityBindings = {};
+  for (const [capabilityId, implementationId] of Object.entries(bindings)) {
+    if (/^[a-z][a-z0-9-]*$/.test(capabilityId) && typeof implementationId === "string" && /^[a-z][a-z0-9-]*$/.test(implementationId)) {
+      capabilityBindings[capabilityId] = implementationId;
+    }
+  }
+  return Object.keys(capabilityBindings).length > 0 ? { capabilityBindings } : void 0;
+}
 function parseAccessConfig(raw) {
   if (raw === void 0 || raw === null) {
     return { allowedAssociations: [...DEFAULT_ALLOWED_ASSOCIATIONS] };
@@ -1631,10 +1645,71 @@ var init_issue = __esm({
   }
 });
 
+// src/agency/implementation-resolution.ts
+function resolveCapabilityImplementation(input) {
+  const compatible = input.implementations.filter(
+    (implementation) => implementation.capabilityRef.id === input.capabilityId && implementation.compatibleCapabilityRevision === input.capabilityRevision
+  );
+  if (input.explicitOverride) {
+    if (!input.authorizeOverride?.(input.explicitOverride)) {
+      throw new ImplementationResolutionError(`Implementation override "${input.explicitOverride}" is not authorized`);
+    }
+    return selectNamed(input.explicitOverride, input, compatible, "override");
+  }
+  if (input.repositoryBinding) {
+    return selectNamed(input.repositoryBinding, input, compatible, "repository binding");
+  }
+  if (compatible.length === 1) return compatible[0];
+  if (compatible.length === 0) {
+    throw new ImplementationResolutionError(
+      `No compatible Implementation is available for Capability "${input.capabilityId}" at revision "${input.capabilityRevision}"`
+    );
+  }
+  throw new ImplementationResolutionError(
+    `Capability "${input.capabilityId}" has ${compatible.length} compatible Implementations; configure a repository binding`
+  );
+}
+function selectNamed(id, input, compatible, source) {
+  const known = input.implementations.find((implementation) => implementation.id === id);
+  if (!known) {
+    throw new ImplementationResolutionError(`Implementation ${source} "${id}" is not available`);
+  }
+  const selected = compatible.find((implementation) => implementation.id === id);
+  if (!selected) {
+    throw new ImplementationResolutionError(
+      `Implementation ${source} "${id}" is not compatible with Capability "${input.capabilityId}" at revision "${input.capabilityRevision}"`
+    );
+  }
+  return selected;
+}
+var ImplementationResolutionError;
+var init_implementation_resolution = __esm({
+  "src/agency/implementation-resolution.ts"() {
+    "use strict";
+    ImplementationResolutionError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "ImplementationResolutionError";
+      }
+    };
+  }
+});
+
 // src/capabilityFolders.ts
 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}`)
+    ]);
+  }
   const result = config.output?.result;
   if (!result) return /* @__PURE__ */ new Set();
   return /* @__PURE__ */ new Set([
@@ -1655,16 +1730,19 @@ function listCapabilityFolderSlugs(absDir) {
   return entries.filter((e) => e.isDirectory() && !e.name.startsWith("_") && !e.name.startsWith(".")).filter((e) => isCapabilityFolder(path5.join(absDir, e.name))).map((e) => e.name).sort();
 }
 function isCapabilityFolder(dir) {
-  return fs4.existsSync(path5.join(dir, CAPABILITY_PROFILE_FILE)) && fs4.existsSync(path5.join(dir, CAPABILITY_BODY_FILE));
+  return (fs4.existsSync(path5.join(dir, CAPABILITY_DEFINITION_FILE)) || fs4.existsSync(path5.join(dir, CAPABILITY_PROFILE_FILE))) && fs4.existsSync(path5.join(dir, CAPABILITY_BODY_FILE));
 }
 function readCapabilityFolder(root, slug) {
   const dir = path5.join(root, slug);
-  const profilePath = path5.join(dir, CAPABILITY_PROFILE_FILE);
+  const definitionPath = path5.join(dir, CAPABILITY_DEFINITION_FILE);
+  const legacyProfilePath = path5.join(dir, CAPABILITY_PROFILE_FILE);
+  const profilePath = fs4.existsSync(definitionPath) ? definitionPath : legacyProfilePath;
   const bodyPath = path5.join(dir, CAPABILITY_BODY_FILE);
   if (!fs4.existsSync(profilePath) || !fs4.statSync(profilePath).isFile()) return null;
   if (!fs4.existsSync(bodyPath) || !fs4.statSync(bodyPath).isFile()) return null;
   try {
-    const rawProfile = JSON.parse(fs4.readFileSync(profilePath, "utf-8"));
+    const rawDefinition = JSON.parse(fs4.readFileSync(profilePath, "utf-8"));
+    const rawProfile = rawDefinition;
     const rawBody = fs4.readFileSync(bodyPath, "utf-8");
     const { title, body } = parseCapabilityBody(rawBody, slug);
     return {
@@ -1700,11 +1778,12 @@ function parseCapabilityConfig(raw) {
     capabilityToolMode: parseCapabilityToolMode(raw.capabilityToolMode),
     implementations,
     role: stringField(raw.role),
-    describe: stringField(raw.describe),
+    describe: stringField(raw.describe) ?? stringField(raw.purpose),
     stage: stringField(raw.stage),
     readsFrom: stringList(raw.readsFrom ?? raw.reads_from),
     writesTo: stringList(raw.writesTo ?? raw.writes_to),
     output: parseCapabilityOutput(raw.output),
+    outputSchema: isPlainObject(raw.outputSchema) ? raw.outputSchema : void 0,
     workflow: parseCapabilityWorkflow(raw.workflow)
   };
 }
@@ -1873,11 +1952,12 @@ function isSafeSlug(value) {
 function isSafeStepId(value) {
   return /^[A-Za-z][A-Za-z0-9_-]*$/.test(value) && !value.includes("..");
 }
-var CAPABILITY_PROFILE_FILE, CAPABILITY_BODY_FILE;
+var CAPABILITY_PROFILE_FILE, CAPABILITY_DEFINITION_FILE, CAPABILITY_BODY_FILE;
 var init_capabilityFolders = __esm({
   "src/capabilityFolders.ts"() {
     "use strict";
     CAPABILITY_PROFILE_FILE = "profile.json";
+    CAPABILITY_DEFINITION_FILE = "definition.json";
     CAPABILITY_BODY_FILE = "capability.md";
   }
 });
@@ -1903,6 +1983,9 @@ function hasExplicitDefinitionsRoot(cwd = process.cwd(), env = process.env) {
 function capabilitiesRoot(cwd = process.cwd()) {
   return path6.join(definitionsRoot(cwd), "capabilities");
 }
+function implementationsRoot(cwd = process.cwd()) {
+  return path6.join(definitionsRoot(cwd), "implementations");
+}
 function agentsRoot(cwd = process.cwd()) {
   return path6.join(definitionsRoot(cwd), "agents");
 }
@@ -1913,6 +1996,7 @@ var init_definition_paths = __esm({
 });
 
 // src/registry.ts
+import { createHash as createHash2 } from "crypto";
 import * as fs6 from "fs";
 import * as path7 from "path";
 function getImplementationsRoot() {
@@ -1952,7 +2036,7 @@ function getImplementationRoots() {
   return getImplementationRootsForCwd(process.cwd());
 }
 function getImplementationRootsForCwd(cwd) {
-  return [capabilitiesRoot(cwd), getImplementationsRoot()];
+  return [implementationsRoot(cwd), getImplementationsRoot()];
 }
 function getCapabilityRoots(projectCapabilitiesRoot = getProjectCapabilitiesRoot()) {
   return [projectCapabilitiesRoot, getBuiltinCapabilitiesRoot()];
@@ -1968,7 +2052,7 @@ function listImplementations(roots = getImplementationRoots()) {
     for (const ent of entries) {
       if (!ent.isDirectory()) continue;
       if (seen.has(ent.name)) continue;
-      const profilePath = path7.join(root, ent.name, CAPABILITY_PROFILE_FILE);
+      const profilePath = implementationRuntimePath(root, ent.name);
       if (fs6.existsSync(profilePath) && fs6.statSync(profilePath).isFile() && isImplementationProfile(profilePath, requireImplementationProfile)) {
         out.push({ name: ent.name, profilePath });
         seen.add(ent.name);
@@ -1985,7 +2069,7 @@ function resolveImplementationCandidates(name, roots = getImplementationRoots())
   const rootList = typeof roots === "string" ? [roots] : roots;
   const out = [];
   for (const root of rootList) {
-    const profilePath = path7.join(root, name, "profile.json");
+    const profilePath = implementationRuntimePath(root, name);
     if (fs6.existsSync(profilePath) && fs6.statSync(profilePath).isFile() && isImplementationProfile(profilePath, isCapabilityRoot(root))) {
       out.push(profilePath);
     }
@@ -2023,9 +2107,43 @@ function resolveCapabilityFolder(slug, projectCapabilitiesRoot = getProjectCapab
 function getCapabilityActionInputs(action, projectCapabilitiesRoot = getProjectCapabilitiesRoot()) {
   const resolved = resolveCapabilityAction(action, projectCapabilitiesRoot);
   if (!resolved) return null;
+  const capability = resolveCapabilityFolder(resolved.capability, projectCapabilitiesRoot);
+  if (capability && path7.basename(capability.profilePath) === "definition.json") {
+    const schema = capability.rawProfile.inputSchema;
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) return [];
+    const properties = schema.properties;
+    if (!properties || typeof properties !== "object" || Array.isArray(properties)) return [];
+    const required2 = new Set(
+      Array.isArray(schema.required) ? schema.required.filter((value) => typeof value === "string") : []
+    );
+    return Object.entries(properties).map(([name, value]) => {
+      const property = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+      const type = property.type === "integer" ? "int" : property.type === "boolean" ? "bool" : Array.isArray(property.enum) ? "enum" : "string";
+      return {
+        name,
+        flag: `--${name}`,
+        type,
+        required: required2.has(name),
+        ...type === "enum" && Array.isArray(property.enum) ? { values: property.enum.filter((item) => typeof item === "string") } : {},
+        describe: typeof property.description === "string" ? property.description : name
+      };
+    });
+  }
   return getProfileInputs(resolved.implementation);
 }
 function resolveCapabilityExecution(capability, cwd = process.cwd()) {
+  if (path7.basename(capability.profilePath) === "definition.json") {
+    const implementations = readExternalImplementations(cwd);
+    const definition = JSON.parse(fs6.readFileSync(capability.profilePath, "utf-8"));
+    const capabilityRevision = createHash2("sha256").update(canonical(definition)).digest("hex");
+    const selected = resolveCapabilityImplementation({
+      capabilityId: capability.slug,
+      capabilityRevision,
+      implementations,
+      repositoryBinding: repositoryImplementationBinding(capability.slug, cwd)
+    });
+    return { implementation: selected.id, cliArgs: {} };
+  }
   const firstWorkflowStep = capability.config.workflow?.steps[0];
   if (firstWorkflowStep) {
     const implementation2 = firstWorkflowStep.implementation ?? firstWorkflowStep.capability;
@@ -2035,11 +2153,42 @@ function resolveCapabilityExecution(capability, cwd = process.cwd()) {
   const cliArgs = implementationDeclaresInput(implementation, "capability", cwd) ? { capability: capability.slug } : {};
   return { implementation, cliArgs };
 }
+function repositoryImplementationBinding(capabilityId, cwd) {
+  try {
+    return loadConfig(cwd).execution?.capabilityBindings[capabilityId];
+  } catch {
+    return void 0;
+  }
+}
+function readExternalImplementations(cwd) {
+  const root = implementationsRoot(cwd);
+  if (!fs6.existsSync(root)) return [];
+  const definitions = [];
+  for (const entry of fs6.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !isSafeName(entry.name)) continue;
+    const definitionPath = path7.join(root, entry.name, "definition.json");
+    if (!fs6.existsSync(definitionPath)) continue;
+    try {
+      const definition = JSON.parse(fs6.readFileSync(definitionPath, "utf-8"));
+      definitions.push(definition);
+    } catch {
+    }
+  }
+  return definitions;
+}
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
 function implementationDeclaresInput(implementation, inputName, cwd = process.cwd()) {
   const profilePath = resolveImplementation(implementation, getImplementationRootsForCwd(cwd));
   if (!profilePath) return false;
   try {
-    const raw = JSON.parse(fs6.readFileSync(profilePath, "utf-8"));
+    const document = JSON.parse(fs6.readFileSync(profilePath, "utf-8"));
+    const raw = document.config ?? document;
     if (!Array.isArray(raw.inputs)) return false;
     return raw.inputs.some((entry) => {
       if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
@@ -2059,6 +2208,10 @@ function isCapabilityRoot(root) {
   const knownRoots = [getProjectCapabilitiesRoot(), getBuiltinCapabilitiesRoot()];
   return knownRoots.some((candidate) => candidate && path7.normalize(candidate) === normalized);
 }
+function implementationRuntimePath(root, name) {
+  const runtimePath = path7.join(root, name, "runtime.json");
+  return fs6.existsSync(runtimePath) ? runtimePath : path7.join(root, name, CAPABILITY_PROFILE_FILE);
+}
 function isImplementationProfile(profilePath, requireImplementationProfile) {
   if (!requireImplementationProfile) return true;
   try {
@@ -2126,8 +2279,10 @@ function getProfileInputs(name, roots = getImplementationRoots()) {
   const profilePath = resolveImplementation(name, roots);
   if (!profilePath) return null;
   try {
-    const raw = JSON.parse(fs6.readFileSync(profilePath, "utf-8"));
-    if (!raw || typeof raw !== "object" || !Array.isArray(raw.inputs)) return [];
+    const document = JSON.parse(fs6.readFileSync(profilePath, "utf-8"));
+    if (!document || typeof document !== "object") return [];
+    const raw = "config" in document && document.config && typeof document.config === "object" ? document.config : document;
+    if (!Array.isArray(raw.inputs)) return [];
     return raw.inputs;
   } catch {
     return null;
@@ -2162,7 +2317,9 @@ var PUBLIC_IMPLEMENTATION_ROLES;
 var init_registry = __esm({
   "src/registry.ts"() {
     "use strict";
+    init_implementation_resolution();
     init_capabilityFolders();
+    init_config();
     init_definition_paths();
     PUBLIC_IMPLEMENTATION_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "container", "watch", "utility"]);
   }
@@ -4166,6 +4323,40 @@ var init_agencyBoundaryEval = __esm({
   }
 });
 
+// src/agency/capability-contract-validation.ts
+import Ajv from "ajv";
+function validateCapabilityContractValue(boundary, schema, value) {
+  const validate = validator.compile(schema);
+  if (!validate(value)) {
+    throw new CapabilityContractValidationError(boundary, validate.errors ?? []);
+  }
+}
+var validator, CapabilityContractValidationError;
+var init_capability_contract_validation = __esm({
+  "src/agency/capability-contract-validation.ts"() {
+    "use strict";
+    validator = new Ajv({
+      allErrors: true,
+      strict: true,
+      validateFormats: false
+    });
+    CapabilityContractValidationError = class extends Error {
+      constructor(boundary, errors) {
+        super(
+          `Capability ${boundary} does not match its canonical contract: ${validator.errorsText([...errors], {
+            separator: "; "
+          })}`
+        );
+        this.boundary = boundary;
+        this.errors = errors;
+        this.name = "CapabilityContractValidationError";
+      }
+      boundary;
+      errors;
+    };
+  }
+});
+
 // src/capabilityReport.ts
 function parseCapabilityReportsFromText(text2) {
   const reports = [];
@@ -4715,6 +4906,7 @@ var init_subagents = __esm({
 });
 
 // src/profile.ts
+import { createHash as createHash3 } from "crypto";
 import * as fs20 from "fs";
 import * as path19 from "path";
 function loadProfile(profilePath) {
@@ -4730,7 +4922,8 @@ function loadProfile(profilePath) {
   if (!raw || typeof raw !== "object") {
     throw new ProfileError(profilePath, "profile must be a JSON object");
   }
-  const r = raw;
+  const document = raw;
+  const r = compileRuntimeDocument(profilePath, document);
   const unknownKeys = Object.keys(r).filter((k) => !KNOWN_PROFILE_KEYS.has(k));
   if (unknownKeys.length > 0) {
     process.stderr.write(
@@ -4877,6 +5070,67 @@ function loadProfile(profilePath) {
   profile.subagentTemplates = captureSubagentTemplates(profile);
   return profile;
 }
+function compileRuntimeDocument(runtimePath, document) {
+  if (path19.basename(runtimePath) !== "runtime.json") return document;
+  if (document.adapter !== "kody-engine-profile") {
+    throw new ProfileError(runtimePath, "unsupported runtime adapter document");
+  }
+  const implementationDir = path19.dirname(runtimePath);
+  const implementation = readJsonObject(path19.join(implementationDir, "definition.json"), "Implementation definition");
+  const definitionsRoot2 = path19.dirname(path19.dirname(implementationDir));
+  const capabilityId = implementation.capabilityRef && typeof implementation.capabilityRef === "object" && !Array.isArray(implementation.capabilityRef) ? implementation.capabilityRef.id : void 0;
+  if (typeof capabilityId !== "string" || !capabilityId) {
+    throw new ProfileError(runtimePath, "Implementation capabilityRef is invalid");
+  }
+  const capability = readJsonObject(
+    path19.join(definitionsRoot2, "capabilities", capabilityId, "definition.json"),
+    "Capability definition"
+  );
+  const {
+    adapter: _adapter,
+    inputBindings: _inputBindings,
+    outputBindings: _outputBindings,
+    requirements: _requirements,
+    config: nestedConfig,
+    ...inlineConfig
+  } = document;
+  const config = nestedConfig && typeof nestedConfig === "object" && !Array.isArray(nestedConfig) ? nestedConfig : inlineConfig;
+  const agentRef = implementation.agentRef && typeof implementation.agentRef === "object" && !Array.isArray(implementation.agentRef) ? implementation.agentRef.id : void 0;
+  return {
+    ...config,
+    name: implementation.id,
+    action: capability.action,
+    describe: capability.purpose,
+    inputs: config.inputs ?? [],
+    agent: agentRef,
+    canonicalContract: {
+      capabilityId,
+      capabilityRevision: createHash3("sha256").update(canonical2(capability)).digest("hex"),
+      implementationId: String(implementation.id),
+      implementationRevision: createHash3("sha256").update(canonical2(implementation)).digest("hex"),
+      inputSchema: capability.inputSchema,
+      outputSchema: capability.outputSchema
+    }
+  };
+}
+function canonical2(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical2).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonical2(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function readJsonObject(filePath, label) {
+  try {
+    const value = JSON.parse(fs20.readFileSync(filePath, "utf-8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("must be an object");
+    }
+    return value;
+  } catch (error) {
+    throw new ProfileError(filePath, `${label} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
 function parseCapabilityToolMode2(profilePath, raw) {
   if (raw === void 0 || raw === null || raw === "") return void 0;
   if (raw === "lock" || raw === "append") return raw;
@@ -5256,6 +5510,7 @@ var init_profile = __esm({
     VALID_CONTAINER_CHILD_TARGETS = /* @__PURE__ */ new Set(["issue", "pr"]);
     VALID_PHASES = /* @__PURE__ */ new Set(["research", "planning", "implementing", "reviewing", "shipped", "failed", "idle"]);
     KNOWN_PROFILE_KEYS = /* @__PURE__ */ new Set([
+      "canonicalContract",
       "name",
       "action",
       "implementation",
@@ -6899,6 +7154,9 @@ function runIndexRowFromJobContext(input) {
     capability: stringValue(input.data.jobCapability) ?? void 0,
     workflow: workflow ?? void 0,
     implementation: stringValue(input.data.selectedImplementation) ?? input.profileName,
+    parentRunId: stringValue(input.data.parentRunId) ?? void 0,
+    capabilityRevision: stringValue(input.data.capabilityRevision) ?? void 0,
+    implementationRevision: stringValue(input.data.implementationRevision) ?? void 0,
     agent: stringValue(input.data.jobAgent) ?? input.profile.agent ?? void 0,
     model: stringValue(input.data.jobModel) ?? void 0,
     modelProvider: stringValue(input.data.jobModelProvider) ?? void 0,
@@ -6963,7 +7221,7 @@ function statusFromExitCode(exitCode) {
   return exitCode === 0 ? "success" : "failed";
 }
 function isRunSubjectType(value) {
-  return value === "goal" || value === "loop" || value === "workflow";
+  return value === "goal" || value === "loop" || value === "workflow" || value === "capability";
 }
 function stagedRunIndexRows(data) {
   const value = data[STAGED_RUN_INDEX_ROWS_KEY];
@@ -8472,9 +8730,9 @@ function goalInstanceTime(state) {
   return Number.isNaN(parsed) ? 0 : parsed;
 }
 function loadGoalTemplate(cwd, targetId) {
-  return readJsonObject(path24.join(cwd, ".kody-engine", "definitions", "goals", targetId, "state.json"));
+  return readJsonObject2(path24.join(cwd, ".kody-engine", "definitions", "goals", targetId, "state.json"));
 }
-function readJsonObject(filePath) {
+function readJsonObject2(filePath) {
   if (!fs27.existsSync(filePath)) return null;
   const parsed = JSON.parse(fs27.readFileSync(filePath, "utf8"));
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
@@ -9504,6 +9762,7 @@ async function planGoalCapabilitySchedule(opts) {
       capability2,
       slug,
       backend,
+      opts.cwd,
       opts.previousScheduleState?.capabilities[slug]
     );
     statuses[slug] = status;
@@ -9558,21 +9817,19 @@ async function planGoalCapabilitySchedule(opts) {
     }
   };
 }
-async function describeCapabilitySchedule(capability, slug, backend, previous) {
+async function describeCapabilitySchedule(capability, slug, backend, cwd, previous) {
   if (!capability) return { slug, state: "blocked", reason: "capability folder missing" };
-  const { config } = capability;
-  if (config.disabled === true) {
+  if (capability.config.disabled === true) {
     return { slug, title: capability.title, state: "disabled", reason: "disabled" };
   }
-  if (!config.agent || config.agent.trim().length === 0) {
-    return { slug, title: capability.title, state: "blocked", reason: "no agent assigned" };
-  }
-  if (config.implementations && config.implementations.length > 1) {
+  try {
+    resolveCapabilityExecution(capability, cwd);
+  } catch (error) {
     return {
       slug,
       title: capability.title,
       state: "blocked",
-      reason: "multi-implementation capability needs task-jobs route"
+      reason: error instanceof Error ? error.message : "Implementation unavailable"
     };
   }
   let lastFiredAt = validIso(previous?.lastFiredAt) ? previous?.lastFiredAt : void 0;
@@ -13242,7 +13499,7 @@ var init_triggerDispatcher = __esm({
 });
 
 // src/goal/policyResolver.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 function resolveDispatchPolicy(input) {
   const operation = input.catalog.operations.get(input.owner.definition.operationId);
   if (!operation) throw new Error(`Dispatch blocked: Operation "${input.owner.definition.operationId}" is unresolved`);
@@ -13260,7 +13517,7 @@ function resolveDispatchPolicy(input) {
   const snapshotValue = { policy, constraints };
   return {
     snapshot: {
-      hash: createHash2("sha256").update(stableJson(snapshotValue)).digest("hex"),
+      hash: createHash4("sha256").update(stableJson(snapshotValue)).digest("hex"),
       ...snapshotValue
     },
     operation,
@@ -15531,9 +15788,9 @@ var init_kodyVariables = __esm({
 });
 
 // src/backendVault.ts
-import { createDecipheriv, createHash as createHash3 } from "crypto";
+import { createDecipheriv, createHash as createHash5 } from "crypto";
 function cacheKey(owner, repo, masterKey) {
-  const keyHash = createHash3("sha256").update(masterKey).digest("hex").slice(0, 16);
+  const keyHash = createHash5("sha256").update(masterKey).digest("hex").slice(0, 16);
   return `${owner}/${repo}:${keyHash}`.toLowerCase();
 }
 function decryptVault(payload, masterKey) {
@@ -16182,7 +16439,7 @@ var init_notifyTerminal = __esm({
 });
 
 // src/scripts/openAgencyModelReviewPr.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 function parseAgencyModelProposal(raw) {
   const text2 = raw.trim();
   const jsonText = (text2.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/i)?.[1] ?? text2).trim();
@@ -16234,7 +16491,7 @@ function normalizeBundleFiles(bundle) {
   });
 }
 function buildProposalId(issueNumber, bundle, sourceLabel) {
-  const digest = createHash4("sha256").update(JSON.stringify({ issueNumber, sourceLabel, title: bundle.title, files: normalizeBundleFiles(bundle) })).digest("hex").slice(0, 16);
+  const digest = createHash6("sha256").update(JSON.stringify({ issueNumber, sourceLabel, title: bundle.title, files: normalizeBundleFiles(bundle) })).digest("hex").slice(0, 16);
   return `issue-${issueNumber}-${digest}`;
 }
 function isDryRun(ctx) {
@@ -18306,9 +18563,9 @@ var init_runFlow = __esm({
 });
 
 // src/scripts/previewBuildHelpers.ts
-import { createDecipheriv as createDecipheriv2, createHash as createHash5, hkdfSync as hkdfSync2 } from "crypto";
+import { createDecipheriv as createDecipheriv2, createHash as createHash7, hkdfSync as hkdfSync2 } from "crypto";
 function shortHash(s) {
-  return createHash5("sha256").update(s).digest("hex").slice(0, 6);
+  return createHash7("sha256").update(s).digest("hex").slice(0, 6);
 }
 function previewAppName(repo, pr) {
   const [owner, name] = repo.split("/");
@@ -18341,7 +18598,7 @@ function formatPreviewComment(args) {
   ].join("\n");
 }
 function defaultImageTag(repo, ref) {
-  return createHash5("sha256").update(`${repo}@${ref}`).digest("hex").slice(0, 12);
+  return createHash7("sha256").update(`${repo}@${ref}`).digest("hex").slice(0, 12);
 }
 var init_previewBuildHelpers = __esm({
   "src/scripts/previewBuildHelpers.ts"() {
@@ -20747,6 +21004,9 @@ async function runImplementation(profileName, input) {
   let args;
   try {
     args = validateInputs(profile.inputs, input.cliArgs);
+    if (profile.canonicalContract) {
+      validateCapabilityContractValue("input", profile.canonicalContract.inputSchema, args);
+    }
   } catch (err) {
     return finishAndEnd({ exitCode: 64, reason: err instanceof Error ? err.message : String(err) });
   }
@@ -20807,6 +21067,12 @@ async function runImplementation(profileName, input) {
   ctx.data.jobModelProvider = model.provider;
   ctx.data.jobModelName = model.model;
   if (reasoningEffort) ctx.data.jobReasoningEffort = reasoningEffort;
+  if (profile.canonicalContract) {
+    ctx.data.jobCapability = profile.canonicalContract.capabilityId;
+    ctx.data.selectedImplementation = profile.canonicalContract.implementationId;
+    ctx.data.capabilityRevision = profile.canonicalContract.capabilityRevision;
+    ctx.data.implementationRevision = profile.canonicalContract.implementationRevision;
+  }
   const runIndexStartedAt = new Date(stageStartedAt).toISOString();
   if (!input.skipConfig) {
     await upsertRunIndexRowBestEffortAsync(
@@ -21116,6 +21382,25 @@ async function runImplementation(profileName, input) {
         outcome: postOutcome
       });
     }
+    const capabilityResults = Array.isArray(ctx.data.capabilityResults) ? ctx.data.capabilityResults : void 0;
+    if (profile.canonicalContract) {
+      try {
+        validateCapabilityContractValue(
+          "output",
+          profile.canonicalContract.outputSchema,
+          capabilityResults?.at(-1) ?? {
+            exitCode: ctx.output.exitCode ?? 0,
+            reason: ctx.output.reason,
+            prUrl: ctx.output.prUrl
+          }
+        );
+      } catch (error) {
+        return finishAndEnd({
+          exitCode: 99,
+          reason: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
     return finishAndEnd({
       exitCode: ctx.output.exitCode ?? 0,
       prUrl: ctx.output.prUrl,
@@ -21124,7 +21409,7 @@ async function runImplementation(profileName, input) {
       nextJob: ctx.output.nextJob,
       afterNextJob: ctx.output.afterNextJob,
       taskState: ctx.data.taskState,
-      capabilityResults: Array.isArray(ctx.data.capabilityResults) ? ctx.data.capabilityResults : void 0
+      capabilityResults
     });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -21328,10 +21613,7 @@ function resolveProfilePath(profileName, cwd = process.cwd()) {
   return candidates[0];
 }
 function loadRunnableProfile(profileName, cwd) {
-  const candidates = resolveImplementationCandidates(
-    profileName,
-    getImplementationRootsForCwd(cwd)
-  );
+  const candidates = resolveImplementationCandidates(profileName, getImplementationRootsForCwd(cwd));
   const skipped = [];
   for (const profilePath2 of candidates) {
     const profile2 = loadProfile(profilePath2);
@@ -21583,6 +21865,7 @@ var MUTATING_POSTFLIGHTS, SHELL_MARKER_RE, TASK_ARTIFACT_WRITE_TOOLS, MAX_CHAIN_
 var init_executor = __esm({
   "src/executor.ts"() {
     "use strict";
+    init_capability_contract_validation();
     init_agent();
     init_agents();
     init_capabilityReport();
@@ -21786,7 +22069,52 @@ async function runJob(job, base) {
       ...valid.workflowState ?? persistedState ? { workflowState: valid.workflowState ?? persistedState ?? void 0 } : {}
     };
     const checkpoint = valid.workflowRunId && workflowIdentity && base.config ? (state) => writeWorkflowRunState(base.config, base.cwd, workflowIdentity, valid.workflowRunId, state) : void 0;
-    const result = await runCapabilityWorkflow(workflowJob, workflow, workflowCapability, base, checkpoint);
+    const parentRunId = `workflow:${workflowIdentity}:${valid.workflowRunId ?? newJobId(valid.flavor)}`;
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const parentRow = {
+      version: 1,
+      id: parentRunId,
+      subjectType: "workflow",
+      subjectId: workflowIdentity,
+      subjectLabel: workflowCapability.title,
+      status: "running",
+      title: workflowCapability.title,
+      startedAt,
+      updatedAt: startedAt,
+      workflow: workflowIdentity,
+      kodyRunId: valid.workflowRunId,
+      sourceType: "job"
+    };
+    const persistRun = Boolean(base.config && !base.skipConfig && hasStateBackendConfig());
+    if (base.config && persistRun) {
+      await upsertRunIndexRowBestEffortAsync(base.config, base.cwd, parentRow);
+    }
+    const workflowBase = {
+      ...base,
+      preloadedData: { ...base.preloadedData ?? {}, parentRunId }
+    };
+    let result;
+    try {
+      result = await runCapabilityWorkflow(workflowJob, workflow, workflowCapability, workflowBase, checkpoint);
+    } catch (error) {
+      if (base.config && persistRun) {
+        await upsertRunIndexRowBestEffortAsync(base.config, base.cwd, {
+          ...parentRow,
+          status: "failed",
+          summary: error instanceof Error ? error.message : String(error),
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      throw error;
+    }
+    if (base.config && persistRun) {
+      await upsertRunIndexRowBestEffortAsync(base.config, base.cwd, {
+        ...parentRow,
+        status: result.exitCode === 0 ? "success" : "failed",
+        summary: result.reason,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
     if (valid.workflowRunId && workflowIdentity && base.config && result.workflowState) {
       await writeWorkflowRunState(base.config, base.cwd, workflowIdentity, valid.workflowRunId, result.workflowState);
     }
@@ -21926,6 +22254,9 @@ async function runLinearCapabilityWorkflow(parent, workflow, capability, base) {
       ...base,
       preloadedData: {
         ...chainData,
+        runSubjectType: "capability",
+        runSubjectId: step.capability,
+        runSubjectLabel: label,
         workflowStep: label,
         workflowStepIndex: index + 1,
         workflowStepReason: step.reason,
@@ -22070,6 +22401,9 @@ async function runGraphCapabilityWorkflow(parent, workflow, capability, base, ch
       ...base,
       preloadedData: {
         ...chainData,
+        runSubjectType: "capability",
+        runSubjectId: step.capability,
+        runSubjectLabel: step.id,
         workflowStep: step.id,
         workflowStepIndex: index + 1,
         workflowStepReason: step.reason,
@@ -22323,7 +22657,7 @@ function hydratedCapabilitiesRoot(cwd) {
   return path46.join(cwd, ".kody-engine", "definitions", "capabilities");
 }
 function loadWorkflowContext(slug, base) {
-  if (!slug || !base.config || !isWorkflowDefinitionId(slug)) return null;
+  if (!slug || !isWorkflowDefinitionId(slug)) return null;
   const workflow = readWorkflowDefinition(base.config, base.cwd, slug);
   return workflow ? workflowDefinitionToCapabilityFolder(slug, workflow) : null;
 }
@@ -22359,6 +22693,8 @@ var init_job = __esm({
     init_capabilityFolders();
     init_executor();
     init_registry();
+    init_runIndex();
+    init_state_backend();
     init_workflowDefinitions();
     init_workflowRunState();
     init_workflowValidation();
@@ -26384,7 +26720,7 @@ init_definition_paths();
 
 // src/definition-hydration.ts
 init_state_backend();
-import { createHash as createHash6 } from "crypto";
+import { createHash as createHash8 } from "crypto";
 import * as fs50 from "fs";
 import * as path51 from "path";
 var SLUG_RE2 = /^[a-z0-9][a-z0-9_-]{0,63}$/;
@@ -26405,7 +26741,7 @@ function normalizeDefinitionBundle(bundle) {
   return { schemaVersion: 1, files };
 }
 function definitionVersion(bundle) {
-  return `sha256:${createHash6("sha256").update(JSON.stringify(normalizeDefinitionBundle(bundle))).digest("hex")}`;
+  return `sha256:${createHash8("sha256").update(JSON.stringify(normalizeDefinitionBundle(bundle))).digest("hex")}`;
 }
 function verifyDefinition(definition) {
   if (!SLUG_RE2.test(definition.slug)) throw new Error(`invalid definition slug: ${definition.slug}`);

package/dist/capabilities/run/definition.json

@@ -0,0 +1,42 @@
+{
+  "id": "run",
+  "action": "run",
+  "purpose": "Implement one GitHub issue end-to-end.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "issue": {
+        "type": "integer",
+        "description": "GitHub issue number to implement."
+      },
+      "base": {
+        "type": "string",
+        "description": "Optional safe base branch override for manual branch targeting (see resolveBaseOverride in runFlow.ts)."
+      }
+    },
+    "required": [
+      "issue"
+    ],
+    "additionalProperties": false
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "reason": {
+        "type": "string"
+      },
+      "summary": {
+        "type": "string"
+      },
+      "data": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    },
+    "additionalProperties": true
+  },
+  "effects": [],
+  "permissions": [],
+  "success": "The requested issue is implemented and the canonical result is returned.",
+  "failure": "The issue cannot be implemented safely or no valid canonical result is returned."
+}

package/dist/implementations/run/definition.json

@@ -0,0 +1,13 @@
+{
+  "id": "run",
+  "capabilityRef": {
+    "kind": "capability",
+    "id": "run"
+  },
+  "compatibleCapabilityRevision": "c50fdcd64daedbcde4428b2985a68a8a11ece518f00a0f5a0c0a2c9d38b5e9c1",
+  "type": "agent",
+  "agentRef": {
+    "kind": "agent",
+    "id": "kody"
+  }
+}

package/dist/implementations/run/{profile.json → runtime.json}

@@ -1,7 +1,6 @@
 {
-  "name": "run",
+  "adapter": "kody-engine-profile",
   "role": "primitive",
-  "describe": "Implement a GitHub issue end-to-end: branch, code, commit, open PR.",
   "inputs": [
     {
       "name": "issue",

package/dist/implementations/types.ts

@@ -40,6 +40,14 @@ export interface AuthSpec {
 }
 
 export interface Profile {
+  canonicalContract?: {
+    capabilityId: string
+    capabilityRevision: string
+    implementationId: string
+    implementationRevision: string
+    inputSchema: Record<string, unknown>
+    outputSchema: Record<string, unknown>
+  }
   name: string
   /**
    * Public action name owned by a capability. A user may type `@kody <action>`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.430",
+  "version": "0.4.431",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative implementation profiles.",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,7 @@
     "@anthropic-ai/claude-agent-sdk": "0.2.119",
     "@kody-ade/agency-domain": "0.5.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ajv": "^8.18.0",
     "convex": "^1.17.0",
     "zod": "^4.0.0"
   },

package/dist/capabilities/run/profile.json

@@ -1,6 +0,0 @@
-{
-  "name": "run",
-  "action": "run",
-  "implementation": "run",
-  "describe": "Implement a GitHub issue end-to-end."
-}