@kody-ade/kody-engine 0.4.642 → 0.4.644

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.642",
+      version: "0.4.644",
       description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative implementation profiles.",
       license: "MIT",
       repository: {
@@ -2334,7 +2334,7 @@ function parseCapabilityContract(raw) {
   if (parsed.execution !== void 0 && parsed.execution !== "agent" && parsed.execution !== "script") {
     throw new Error('contract.json execution must be "agent" or "script"');
   }
-  const requirements = parseCapabilityRequirements(parsed.requirements);
+  const requirements = parseCapabilityRequirements(parsed.requirements, parsed.execution);
   const secrets = parsed.secrets === void 0 ? void 0 : Array.isArray(parsed.secrets) && parsed.secrets.every((name) => typeof name === "string" && /^[A-Z][A-Z0-9_]*$/.test(name)) ? [...new Set(parsed.secrets)] : null;
   if (secrets === null) {
     throw new Error("contract.json secrets must contain valid environment variable names");
@@ -2342,6 +2342,13 @@ function parseCapabilityContract(raw) {
   if (secrets && parsed.execution !== "script") {
     throw new Error('contract.json secrets are supported only when execution is "script"');
   }
+  const connections = parsed.connections === void 0 ? void 0 : Array.isArray(parsed.connections) && parsed.connections.length > 0 && parsed.connections.every((id) => typeof id === "string" && /^[a-z0-9][a-z0-9_-]{0,79}$/.test(id)) ? [...new Set(parsed.connections)] : null;
+  if (connections === null) {
+    throw new Error("contract.json connections must contain valid Connection ids");
+  }
+  if (connections && parsed.execution !== "script") {
+    throw new Error('contract.json connections are supported only when execution is "script"');
+  }
   const timeoutMs = parsed.timeoutMs === void 0 ? void 0 : typeof parsed.timeoutMs === "number" && Number.isInteger(parsed.timeoutMs) && parsed.timeoutMs >= 1e3 && parsed.timeoutMs <= 6 * 60 * 60 * 1e3 ? parsed.timeoutMs : null;
   if (timeoutMs === null) {
     throw new Error("contract.json timeoutMs must be an integer from 1000 to 21600000");
@@ -2362,7 +2369,7 @@ function parseCapabilityContract(raw) {
     throw new Error("contract.json deliveryConfigAllowlist files must also be deliveryPathAllowlist entries");
   }
   const unsupported = Object.keys(parsed).filter(
-    (key) => key !== "execution" && key !== "deliveryPolicy" && key !== "deliveryPathAllowlist" && key !== "deliveryConfigAllowlist" && key !== "requirements" && key !== "secrets" && key !== "timeoutMs" && key !== "requiredSubagents" && key !== "input" && key !== "output"
+    (key) => key !== "execution" && key !== "deliveryPolicy" && key !== "deliveryPathAllowlist" && key !== "deliveryConfigAllowlist" && key !== "requirements" && key !== "connections" && key !== "secrets" && key !== "timeoutMs" && key !== "requiredSubagents" && key !== "input" && key !== "output"
   );
   if (unsupported.length > 0) {
     throw new Error(`contract.json contains unsupported fields: ${unsupported.join(", ")}`);
@@ -2379,6 +2386,7 @@ function parseCapabilityContract(raw) {
     ...deliveryPathAllowlist ? { deliveryPathAllowlist } : {},
     ...deliveryConfigAllowlist ? { deliveryConfigAllowlist } : {},
     ...requirements ? { requirements } : {},
+    ...connections ? { connections } : {},
     ...secrets ? { secrets } : {},
     ...timeoutMs !== void 0 ? { timeoutMs } : {},
     ...requiredSubagents ? { requiredSubagents } : {},
@@ -2425,11 +2433,11 @@ function parseDeliveryPathAllowlist(raw) {
   }
   return paths;
 }
-function parseCapabilityRequirements(raw) {
+function parseCapabilityRequirements(raw, execution) {
   if (raw === void 0) return void 0;
   if (!isPlainObject(raw)) throw new Error("contract.json requirements must be an object");
   const unsupported = Object.keys(raw).filter(
-    (key) => key !== "cms" && key !== "browser" && key !== "qaCredentials" && key !== "githubTestToken" && key !== "qaAccountCredentials" && key !== "qaAccountModelSettings" && key !== "browserOnly"
+    (key) => key !== "cms" && key !== "browser" && key !== "qaCredentials" && key !== "githubTestToken" && key !== "qaAccountCredentials" && key !== "qaAccountModelSettings" && key !== "browserOnly" && key !== "browserSession" && key !== "browserActions" && key !== "browserOrigins" && key !== "browserFileRoots"
   );
   if (unsupported.length > 0) {
     throw new Error(`contract.json requirements contains unsupported fields: ${unsupported.join(", ")}`);
@@ -2455,8 +2463,30 @@ function parseCapabilityRequirements(raw) {
   if (raw.browserOnly !== void 0 && typeof raw.browserOnly !== "boolean") {
     throw new Error("contract.json requirements.browserOnly must be boolean");
   }
-  if ((raw.qaCredentials === true || raw.githubTestToken === true || raw.qaAccountCredentials !== void 0 || raw.qaAccountModelSettings !== void 0 || raw.browserOnly === true) && raw.browser !== true) {
-    throw new Error("contract.json authentication requirements require browser");
+  if (raw.browserSession !== void 0 && raw.browserSession !== "user") {
+    throw new Error('contract.json requirements.browserSession must be "user"');
+  }
+  const browserActions = parseUserBrowserActions(raw.browserActions);
+  const browserOrigins = parseUserBrowserOrigins(raw.browserOrigins);
+  const browserFileRoots = parseUserBrowserFileRoots(raw.browserFileRoots);
+  if ((raw.qaCredentials === true || raw.githubTestToken === true || raw.qaAccountCredentials !== void 0 || raw.qaAccountModelSettings !== void 0 || raw.browserOnly === true || raw.browserSession === "user") && raw.browser !== true) {
+    throw new Error("contract.json protected browser requirement requires browser");
+  }
+  if (raw.browserSession === "user") {
+    if (execution !== "agent") {
+      throw new Error('contract.json requirements.browserSession "user" is supported only when execution is "agent"');
+    }
+    if (!browserActions?.length) {
+      throw new Error("contract.json user browser requirements need browserActions");
+    }
+    if (!browserOrigins?.length) {
+      throw new Error("contract.json user browser requirements need browserOrigins");
+    }
+    if (browserActions.includes("upload") && !browserFileRoots?.length) {
+      throw new Error("contract.json browser upload requires browserFileRoots");
+    }
+  } else if (browserActions !== void 0 || browserOrigins !== void 0 || browserFileRoots !== void 0) {
+    throw new Error('contract.json browserActions, browserOrigins, and browserFileRoots require browserSession "user"');
   }
   const requirements = {
     ...raw.cms === true ? { cms: true } : {},
@@ -2465,10 +2495,58 @@ function parseCapabilityRequirements(raw) {
     ...raw.githubTestToken === true ? { githubTestToken: true } : {},
     ...Array.isArray(raw.qaAccountCredentials) ? { qaAccountCredentials: [...new Set(raw.qaAccountCredentials)] } : {},
     ...isPlainObject(raw.qaAccountModelSettings) ? { qaAccountModelSettings: raw.qaAccountModelSettings } : {},
-    ...raw.browserOnly === true ? { browserOnly: true } : {}
+    ...raw.browserOnly === true ? { browserOnly: true } : {},
+    ...raw.browserSession === "user" ? { browserSession: "user" } : {},
+    ...browserActions ? { browserActions } : {},
+    ...browserOrigins ? { browserOrigins } : {},
+    ...browserFileRoots ? { browserFileRoots } : {}
   };
   return Object.keys(requirements).length > 0 ? requirements : void 0;
 }
+function parseUserBrowserActions(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.length === 0 || value.length > USER_BROWSER_ACTIONS.length || !value.every(
+    (action) => typeof action === "string" && USER_BROWSER_ACTIONS.includes(action)
+  )) {
+    throw new Error(`contract.json requirements.browserActions must contain only ${USER_BROWSER_ACTIONS.join(", ")}`);
+  }
+  return [...new Set(value)];
+}
+function parseUserBrowserOrigins(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.length === 0 || value.length > 20) {
+    throw new Error("contract.json requirements.browserOrigins must be a non-empty array");
+  }
+  const origins = value.map((raw) => {
+    if (typeof raw !== "string") throw new Error("invalid browser origin");
+    let parsed;
+    try {
+      parsed = new URL(raw);
+    } catch {
+      throw new Error("invalid browser origin");
+    }
+    if (parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.origin !== raw.replace(/\/$/, "")) {
+      throw new Error("contract.json requirements.browserOrigins must contain HTTPS origins only");
+    }
+    return parsed.origin;
+  });
+  return [...new Set(origins)];
+}
+function parseUserBrowserFileRoots(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.length === 0 || value.length > 20) {
+    throw new Error("contract.json requirements.browserFileRoots must be a non-empty array");
+  }
+  const roots = value.map((raw) => {
+    if (typeof raw !== "string") throw new Error("invalid browser file root");
+    const root = raw.replaceAll("\\", "/").replace(/^\/+|\/+$/g, "");
+    if (!root || root.length > 300 || root.split("/").some((part) => !part || part === "." || part === "..")) {
+      throw new Error("contract.json requirements.browserFileRoots contains an unsafe path");
+    }
+    return root;
+  });
+  return [...new Set(roots)];
+}
 function isRegularFile(filePath) {
   try {
     const stat = fs8.lstatSync(filePath);
@@ -2545,6 +2623,7 @@ function parseWorkflowStep(value) {
   const target = stringField(raw.target);
   const delivery = stringField(raw.delivery);
   const targetFact = stringField(raw.targetFact ?? raw.target_fact);
+  const approval = stringField(raw.approval);
   const timeoutSeconds = typeof raw.timeoutSeconds === "number" && Number.isInteger(raw.timeoutSeconds) && raw.timeoutSeconds > 0 && raw.timeoutSeconds <= 3600 ? raw.timeoutSeconds : void 0;
   const hasInput = Object.hasOwn(raw, "input");
   const inputs = parseWorkflowInputBindings(raw.inputs);
@@ -2562,6 +2641,7 @@ function parseWorkflowStep(value) {
     ...targetFact ? { targetFact } : {},
     ...reason ? { reason } : {},
     ...timeoutSeconds ? { timeoutSeconds } : {},
+    ...approval === "required" ? { approval: "required" } : {},
     ...next ? { next } : {},
     ...isPlainObject(raw.runWhen) ? { runWhen: raw.runWhen } : {},
     ...stringList(raw.continueOn ?? raw.continue_on).length > 0 ? { continueOn: stringList(raw.continueOn ?? raw.continue_on) } : {},
@@ -2636,7 +2716,7 @@ function isSafeSlug(value) {
 function isSafeStepId(value) {
   return /^[A-Za-z][A-Za-z0-9_-]*$/.test(value) && !value.includes("..");
 }
-var CAPABILITY_BODY_FILE, CAPABILITY_CONTRACT_FILE, CAPABILITY_PROFILE_FILE, CANONICAL_CAPABILITY_BODY_FILE, CANONICAL_CAPABILITY_DEFINITION_FILE;
+var CAPABILITY_BODY_FILE, CAPABILITY_CONTRACT_FILE, CAPABILITY_PROFILE_FILE, CANONICAL_CAPABILITY_BODY_FILE, CANONICAL_CAPABILITY_DEFINITION_FILE, USER_BROWSER_ACTIONS;
 var init_capabilityFolders = __esm({
   "src/capabilityFolders.ts"() {
     "use strict";
@@ -2645,6 +2725,7 @@ var init_capabilityFolders = __esm({
     CAPABILITY_PROFILE_FILE = CAPABILITY_BODY_FILE;
     CANONICAL_CAPABILITY_BODY_FILE = "capability.md";
     CANONICAL_CAPABILITY_DEFINITION_FILE = "definition.json";
+    USER_BROWSER_ACTIONS = ["navigate", "click", "fill", "upload", "scroll", "wait"];
   }
 });
 
@@ -3165,6 +3246,19 @@ async function readRuntimeSecretFromKody(name, env = process.env) {
   const body = await response.json();
   return typeof body.value === "string" ? body.value : null;
 }
+async function readRuntimeConnectionFromKody(id, env = process.env) {
+  const token = await githubOidcToken(env);
+  const response = await fetch(`${resolveKodyApiUrl(env)}/api/kody/engine/connection`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ id }),
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (response.status === 404) return null;
+  if (!response.ok) throw new Error(`Kody Connection request failed (${response.status})`);
+  const body = await response.json();
+  return body.connection ?? null;
+}
 async function writeRuntimeSecretsToKody(secrets, env = process.env) {
   const token = await githubOidcToken(env);
   const response = await fetch(`${resolveKodyApiUrl(env)}/api/kody/engine/secret`, {
@@ -4108,7 +4202,7 @@ function capabilityToolDefinitions(opts) {
     description: "Idempotently create, update, close, or reopen one canonical repository Todo for a recurring problem. The Todo family is derived from reportSlug and the stable item id prevents duplicates. Repeating the same state is a no-op; unrelated items in an existing Todo are preserved.",
     inputSchema: {
       slug: z3.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/).optional().describe("Deprecated; the canonical Todo slug is reportSlug."),
-      itemId: z3.string().regex(/^[a-z0-9][a-z0-9_-]{0,79}$/).optional(),
+      itemId: z3.string().regex(/^[a-z0-9][a-z0-9_-]{0,79}$/),
       title: z3.string().min(1).max(160),
       description: z3.string().max(2e4).optional(),
       status: z3.enum(["open", "resolved"]),
@@ -4119,7 +4213,7 @@ function capabilityToolDefinitions(opts) {
     handler: async (args) => {
       const reportSlug = String(args.reportSlug);
       const slug = reportSlug;
-      const itemId = typeof args.itemId === "string" ? args.itemId : "finding";
+      const itemId = String(args.itemId);
       const title = String(args.title).trim();
       const description = typeof args.description === "string" ? args.description.trim() : "";
       const status = args.status === "resolved" ? "resolved" : "open";
@@ -4136,10 +4230,17 @@ function capabilityToolDefinitions(opts) {
           const currentItems = Array.isArray(current.items) ? current.items.filter(
             (item) => Boolean(item && typeof item === "object" && !Array.isArray(item))
           ) : [];
-          const previous = currentItems.find((item) => item.id === itemId);
+          const isLegacyFallbackForReport = (item) => {
+            if (itemId === "finding" || item.id !== "finding") return false;
+            const meta = item.meta && typeof item.meta === "object" && !Array.isArray(item.meta) ? item.meta : {};
+            return meta.reportSlug === reportSlug;
+          };
+          const removedLegacyFallback = currentItems.some(isLegacyFallbackForReport);
+          const canonicalItems = currentItems.filter((item) => !isLegacyFallbackForReport(item));
+          const previous = canonicalItems.find((item) => item.id === itemId);
           const previousMeta = previous?.meta && typeof previous.meta === "object" && !Array.isArray(previous.meta) ? previous.meta : {};
           const unchanged = Boolean(
-            previous && previous.completed === completed && previous.title === title && String(previous.body ?? "") === evidence && previousMeta.reportSlug === reportSlug
+            previous && !removedLegacyFallback && previous.completed === completed && previous.title === title && String(previous.body ?? "") === evidence && previousMeta.reportSlug === reportSlug
           );
           if (unchanged) {
             return {
@@ -4162,7 +4263,7 @@ function capabilityToolDefinitions(opts) {
               status
             }
           };
-          const items = previous ? currentItems.map((item) => item.id === itemId ? nextItem : item) : [...currentItems, nextItem];
+          const items = previous ? canonicalItems.map((item) => item.id === itemId ? nextItem : item) : [...canonicalItems, nextItem];
           const doc = {
             ...current,
             version: 1,
@@ -5264,6 +5365,17 @@ function validateWorkflow(value, options = {}) {
         "workflow step timeoutSeconds must be an integer from 1 to 3600"
       );
     }
+    if (step.approval !== void 0 && step.approval !== "required") {
+      issue(issues, "invalid_step_approval", `${base}.approval`, 'workflow step approval must be "required"');
+    }
+    if (step.approval === "required" && !text(step.id)) {
+      issue(
+        issues,
+        "approval_requires_step_id",
+        `${base}.approval`,
+        "an approval-gated workflow step must have a stable id"
+      );
+    }
     validateInputBindings(
       step.inputs,
       `${base}.inputs`,
@@ -5557,6 +5669,7 @@ var init_workflowValidation = __esm({
       "targetFact",
       "reason",
       "timeoutSeconds",
+      "approval",
       "next",
       "runWhen",
       "continueOn",
@@ -17182,6 +17295,7 @@ var init_loadSimpleCapability = __esm({
       if (requiredSubagents.length > 0) ctx.data.requiredSubagents = requiredSubagents;
       if (capability.contract?.execution === "script") {
         ctx.data.capabilityScriptPath = path43.join(capability.dir, "tools", "run.sh");
+        ctx.data.capabilityConnectionIds = capability.contract.connections ?? [];
         ctx.data.capabilitySecretNames = capability.contract.secrets ?? [];
         ctx.data.capabilityScriptTimeoutMs = capability.contract.timeoutMs;
       }
@@ -19454,6 +19568,9 @@ var init_prepareSimpleCapabilityRuntime = __esm({
     prepareSimpleCapabilityRuntime = async (ctx, profile) => {
       const requirements = requirementsFrom(ctx);
       if (!requirements.browser) return;
+      if (requirements.browserSession === "user") {
+        throw new Error("Capability requires the Dashboard user browser session and cannot run in CI");
+      }
       configureBrowser(ctx, profile, requirements);
       if (requirements.qaCredentials) {
         await loadQaContext(ctx, profile);
@@ -21223,6 +21340,33 @@ var init_runScheduledImplementationTick = __esm({
   }
 });
 
+// src/scripts/runtimeConnections.ts
+async function resolveRuntimeConnections(ids, declaredSecrets, load = readRuntimeConnectionFromKody) {
+  const requested = Array.isArray(ids) ? [...new Set(ids.filter((id) => typeof id === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(id)))] : [];
+  const allowedSecrets = new Set(
+    Array.isArray(declaredSecrets) ? declaredSecrets.filter((name) => typeof name === "string") : []
+  );
+  const connections = [];
+  for (const id of requested) {
+    const connection = await load(id);
+    if (!connection) throw new Error(`Connection ${id} was not found`);
+    if (connection.status !== "connected") throw new Error(`Connection ${id} is not connected`);
+    for (const secretName of Object.values(connection.credentialRefs)) {
+      if (!allowedSecrets.has(secretName)) {
+        throw new Error(`Connection ${id} credential ${secretName} is not allowlisted by the Capability`);
+      }
+    }
+    connections.push(connection);
+  }
+  return connections;
+}
+var init_runtimeConnections = __esm({
+  "src/scripts/runtimeConnections.ts"() {
+    "use strict";
+    init_kody_api_client();
+  }
+});
+
 // src/scripts/runSimpleCapabilityScript.ts
 import { spawnSync as spawnSync3 } from "child_process";
 import * as fs51 from "fs";
@@ -21245,6 +21389,7 @@ var init_runSimpleCapabilityScript = __esm({
   "src/scripts/runSimpleCapabilityScript.ts"() {
     "use strict";
     init_capabilityResult();
+    init_runtimeConnections();
     init_runtimeSecrets();
     init_tickShellRunner();
     DEFAULT_SCRIPT_TIMEOUT_MS = 5 * 60 * 1e3;
@@ -21258,6 +21403,14 @@ var init_runSimpleCapabilityScript = __esm({
         return;
       }
       const capabilityEnvironment = isStringRecord(ctx.data.capabilityEnvironment) ? ctx.data.capabilityEnvironment : {};
+      let connections;
+      try {
+        connections = await resolveRuntimeConnections(ctx.data.capabilityConnectionIds, ctx.data.capabilitySecretNames);
+      } catch (error) {
+        ctx.output.exitCode = 78;
+        ctx.output.reason = error instanceof Error ? error.message : "Capability Connection loading failed";
+        return;
+      }
       const capabilitySecrets = await resolveRuntimeSecrets(ctx.data.capabilitySecretNames, ctx);
       for (const warning of capabilitySecrets.warnings) {
         process.stderr.write(`\u2192 kody: WARNING ${warning}
@@ -21269,7 +21422,11 @@ var init_runSimpleCapabilityScript = __esm({
         env: {
           ...buildTickChildEnv(process.env, false),
           ...capabilitySecrets.environment,
-          ...capabilityEnvironment
+          ...capabilityEnvironment,
+          ...connections.length > 0 ? {
+            KODY_CONNECTIONS_JSON: JSON.stringify(connections),
+            ...connections.length === 1 ? { KODY_CONNECTION_JSON: JSON.stringify(connections[0]) } : {}
+          } : {}
         },
         stdio: ["ignore", "pipe", "pipe"],
         encoding: "utf-8",
@@ -24272,7 +24429,7 @@ function workflowRunStatePath(workflowId, runId) {
 function parseWorkflowRunState(raw) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
   const state = raw;
-  if (state.status !== "running" && state.status !== "blocked" && state.status !== "failed" && state.status !== "done")
+  if (state.status !== "running" && state.status !== "waiting-approval" && state.status !== "blocked" && state.status !== "failed" && state.status !== "done")
     return null;
   const completedStepIds = Array.isArray(state.completedStepIds) ? state.completedStepIds.filter((value) => typeof value === "string") : [];
   const transitionCounts = state.transitionCounts && typeof state.transitionCounts === "object" && !Array.isArray(state.transitionCounts) ? Object.fromEntries(
@@ -24292,6 +24449,7 @@ function parseWorkflowRunState(raw) {
     ...typeof state.currentStepId === "string" ? { currentStepId: state.currentStepId } : {},
     completedStepIds,
     transitionCounts,
+    ...parseWorkflowApproval(state.approval) ? { approval: parseWorkflowApproval(state.approval) } : {},
     ...input ? { input: { ...input } } : {},
     ...typeof state.definitionHash === "string" && state.definitionHash.trim() ? { definitionHash: state.definitionHash.trim() } : {},
     ...steps ? { steps } : {},
@@ -24301,6 +24459,20 @@ function parseWorkflowRunState(raw) {
     ...typeof state.blocker === "string" ? { blocker: state.blocker } : {}
   };
 }
+function parseWorkflowApproval(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const approval = value;
+  if (typeof approval.stepId !== "string" || typeof approval.action !== "string" || typeof approval.contextHash !== "string" || approval.status !== "pending" && approval.status !== "approved" && approval.status !== "consumed")
+    return void 0;
+  return {
+    stepId: approval.stepId,
+    action: approval.action,
+    contextHash: approval.contextHash,
+    status: approval.status,
+    ...typeof approval.approvedAt === "string" ? { approvedAt: approval.approvedAt } : {},
+    ...typeof approval.approvedBy === "string" ? { approvedBy: approval.approvedBy } : {}
+  };
+}
 function parseWorkflowSteps(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
   const steps = {};
@@ -24351,6 +24523,50 @@ var init_workflowRunState = __esm({
   }
 });
 
+// src/workflowStepApproval.ts
+import { createHash as createHash9 } from "crypto";
+function workflowStepApprovalContextHash(state, stepId) {
+  const value = stableJson2({
+    stepId,
+    definitionHash: state.definitionHash ?? null,
+    input: state.input ?? {},
+    facts: state.facts ?? {}
+  });
+  return `sha256:${createHash9("sha256").update(value).digest("hex")}`;
+}
+function requireWorkflowStepApproval(state, stepId) {
+  const contextHash = workflowStepApprovalContextHash(state, stepId);
+  if (state.approval?.stepId === stepId && state.approval.contextHash === contextHash && state.approval.status === "approved") {
+    return {
+      ...state,
+      status: "running",
+      approval: { ...state.approval, status: "consumed" }
+    };
+  }
+  return {
+    ...state,
+    status: "waiting-approval",
+    approval: {
+      stepId,
+      action: `workflow-step:${stepId}`,
+      contextHash,
+      status: "pending"
+    }
+  };
+}
+function stableJson2(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson2).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson2(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "undefined";
+}
+var init_workflowStepApproval = __esm({
+  "src/workflowStepApproval.ts"() {
+    "use strict";
+  }
+});
+
 // src/job.ts
 var job_exports = {};
 __export(job_exports, {
@@ -24521,7 +24737,7 @@ async function runJob(job, base) {
       if (base.config && persistRun) {
         await upsertRunIndexRowBestEffortAsync(base.config, base.cwd, {
           ...parentRow,
-          status: result.exitCode === 0 ? "success" : "failed",
+          status: result.workflowState?.status === "waiting-approval" ? "waiting" : result.exitCode === 0 ? "success" : "failed",
           summary: result.reason,
           updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         });
@@ -24530,7 +24746,7 @@ async function runJob(job, base) {
         await lease?.checkpoint();
         await writeWorkflowRunState(base.config, base.cwd, workflowIdentity, valid.workflowRunId, result.workflowState);
       }
-      if (valid.workflowRunId && workflowIdentity && hasGitHubActionsIdentity()) {
+      if (valid.workflowRunId && workflowIdentity && hasGitHubActionsIdentity() && result.workflowState?.status !== "waiting-approval") {
         const facts = result.workflowState?.facts ?? {};
         await notifyWorkflowCompleted({
           workflowId: workflowIdentity,
@@ -24822,6 +25038,7 @@ function initialWorkflowState(parent, workflow) {
       status: "done",
       completedStepIds: [...prior.completedStepIds],
       transitionCounts: { ...prior.transitionCounts },
+      ...prior.approval ? { approval: { ...prior.approval } } : {},
       ...prior.input ? { input: { ...prior.input } } : {},
       ...prior.steps ? { steps: cloneWorkflowSteps(prior.steps) } : {},
       facts: { ...prior.facts },
@@ -24838,6 +25055,7 @@ function initialWorkflowState(parent, workflow) {
     ...currentStepId ? { currentStepId } : {},
     completedStepIds: [...prior?.completedStepIds ?? []],
     transitionCounts: { ...prior?.transitionCounts ?? {} },
+    ...prior?.approval ? { approval: { ...prior.approval } } : {},
     steps: cloneWorkflowSteps(prior?.steps ?? {}),
     facts: {
       ...workflowInputContext(parent.cliArgs),
@@ -24896,6 +25114,20 @@ async function runGraphCapabilityWorkflow(parent, workflow, capability, base, ch
       return { ...result, exitCode: 64, reason, workflowState: state };
     }
     const label = step.action ?? step.capability;
+    if (step.approval === "required") {
+      const approvalState = requireWorkflowStepApproval(state, step.id);
+      state.status = approvalState.status;
+      state.approval = approvalState.approval;
+      await checkpoint?.(state);
+      if (state.status === "waiting-approval") {
+        return {
+          ...result,
+          exitCode: 0,
+          reason: `Approval required before workflow step ${step.id}`,
+          workflowState: state
+        };
+      }
+    }
     await checkpoint?.(state);
     let child;
     try {
@@ -25111,7 +25343,8 @@ function workflowStepToJob(step, parent, chainData, cwd) {
   const action = step.action ?? step.capability;
   const targetNumber = workflowStepTargetNumber(step, parent, chainData);
   const mappedInputs = resolveWorkflowStepInputs(step, chainData, cwd);
-  const rawArgs = mappedInputs ? { ...mappedInputs } : { ...parent.cliArgs };
+  const genericCapability = usesGenericCapabilityInput(action, cwd);
+  const rawArgs = mappedInputs ? { ...mappedInputs } : genericCapability ? inheritedGenericStepInput(step.capability, parent.cliArgs, cwd) : { ...parent.cliArgs };
   if (step.target === "pr") {
     if (typeof targetNumber !== "number") {
       throw new InvalidJobError(`workflow step ${action} needs a PR target but no prior PR URL is available`);
@@ -25121,11 +25354,11 @@ function workflowStepToJob(step, parent, chainData, cwd) {
     rawArgs.issue = targetNumber;
   }
   const genericInput = capabilityStepInput(
-    step.input ?? mappedInputs ?? chainData.workflowInput ?? genericInputFromArgs(rawArgs),
+    step.input ?? mappedInputs ?? genericInputFromArgs(rawArgs),
     step.target,
     targetNumber
   );
-  const cliArgs = usesGenericCapabilityInput(action, cwd) ? genericInput === void 0 ? {} : { input: JSON.stringify(genericInput) } : filterCliArgsForStep(action, rawArgs);
+  const cliArgs = genericCapability ? genericInput === void 0 ? {} : { input: JSON.stringify(genericInput) } : filterCliArgsForStep(action, rawArgs);
   const target = typeof targetNumber === "number" ? targetNumber : typeof parent.target === "number" ? parent.target : targetFromCliArgs(cliArgs);
   return {
     action,
@@ -25176,6 +25409,17 @@ function capabilityInputNames(folder) {
   if (!properties || typeof properties !== "object" || Array.isArray(properties)) return /* @__PURE__ */ new Set();
   return new Set(Object.keys(properties));
 }
+function inheritedGenericStepInput(capability, parentArgs, cwd) {
+  const input = workflowInputContext(parentArgs);
+  const folder = resolveCapabilityFolder(capability, hydratedCapabilitiesRoot(cwd));
+  if (!folder) return input;
+  if (!folder.contractPath) return input;
+  if (folder.config.inputSchema?.additionalProperties !== false) return input;
+  const accepted = capabilityInputNames(folder);
+  if (accepted.size === 0) return input;
+  const routing = /* @__PURE__ */ new Set(["base"]);
+  return Object.fromEntries(Object.entries(input).filter(([name]) => accepted.has(name) || routing.has(name)));
+}
 function cloneWorkflowSteps(steps) {
   return Object.fromEntries(Object.entries(steps).map(([id, step]) => [id, { ...step }]));
 }
@@ -25447,6 +25691,7 @@ var init_job = __esm({
     init_workflowDefinitions();
     init_workflowRunLease();
     init_workflowRunState();
+    init_workflowStepApproval();
     init_workflowValidation();
     init_jobIdentity();
     init_jobIdentity();
@@ -29774,7 +30019,7 @@ import { createInterface as createInterface2 } from "readline";
 
 // src/terminal/brain-terminal-adapters.ts
 import { spawn as spawn9 } from "child_process";
-import { createHash as createHash9, randomBytes as randomBytes2 } from "crypto";
+import { createHash as createHash10, randomBytes as randomBytes2 } from "crypto";
 import { mkdir, readFile, rename, writeFile as writeFile2 } from "fs/promises";
 import * as path57 from "path";
 function runTerminalCommand(command, args, input) {
@@ -29797,7 +30042,7 @@ function runTerminalCommand(command, args, input) {
   });
 }
 function storeKey(id) {
-  return createHash9("sha256").update(id).digest("hex");
+  return createHash10("sha256").update(id).digest("hex");
 }
 function isStoredSession(value) {
   if (!value || typeof value !== "object") return false;
@@ -29902,7 +30147,7 @@ var TmuxBrainTerminalRuntime = class {
 };
 
 // src/terminal/brain-terminal-session.ts
-import { createHash as createHash10 } from "crypto";
+import { createHash as createHash11 } from "crypto";
 var MAX_CAPTURE_CHARS = 2e5;
 function requiredIdentifier(value, name, max = 240) {
   if (typeof value !== "string" || !value.trim() || value.length > max) {
@@ -29983,7 +30228,7 @@ function parseBrainTerminalCommand(value) {
   }
 }
 function sessionName(id) {
-  return `kody_${createHash10("sha256").update(id).digest("hex").slice(0, 32)}`;
+  return `kody_${createHash11("sha256").update(id).digest("hex").slice(0, 32)}`;
 }
 function stateEvent(session) {
   return {

package/dist/implementations/types.ts

@@ -600,7 +600,7 @@ export interface Job {
 }
 
 export interface WorkflowRunState {
-  status: "running" | "blocked" | "failed" | "done"
+  status: "running" | "waiting-approval" | "blocked" | "failed" | "done"
   /** Immutable input supplied when this workflow run started. */
   input?: Record<string, unknown>
   /** Hash of the workflow definition used by this run. */
@@ -608,6 +608,14 @@ export interface WorkflowRunState {
   currentStepId?: string
   completedStepIds: string[]
   transitionCounts: Record<string, number>
+  approval?: {
+    stepId: string
+    action: string
+    contextHash: string
+    status: "pending" | "approved" | "consumed"
+    approvedAt?: string
+    approvedBy?: string
+  }
   /** Exact per-step handoffs for audit, resume, and debugging. */
   steps?: Record<
     string,

package/package.json

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