@kody-ade/kody-engine 0.4.304 → 0.4.306

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.304",
+      version: "0.4.306",
       description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
       license: "MIT",
       type: "module",
@@ -1914,6 +1914,7 @@ function parseCapabilityConfig(raw) {
     mentions: stringList(raw.mentions).map((m) => m.replace(/^@/, "")),
     tools,
     capabilityTools: tools,
+    capabilityToolMode: parseCapabilityToolMode(raw.capabilityToolMode),
     implementations,
     executables: stringList(raw.executables),
     role: stringField(raw.role),
@@ -1924,6 +1925,11 @@ function parseCapabilityConfig(raw) {
     workflow: parseWorkflow(raw.workflow)
   };
 }
+function parseCapabilityToolMode(raw) {
+  if (raw === void 0 || raw === null || raw === "") return void 0;
+  if (raw === "lock" || raw === "append") return raw;
+  return void 0;
+}
 function parseCapabilityBody(raw, slug2) {
   const trimmed = raw.trim();
   const firstLine2 = trimmed.split("\n", 1)[0] ?? "";
@@ -2414,7 +2420,8 @@ __export(capabilityMcp_exports, {
   parseCapabilityTrustMode: () => parseCapabilityTrustMode,
   readCapabilityTrustMode: () => readCapabilityTrustMode,
   readCheckRuns: () => readCheckRuns,
-  readThread: () => readThread
+  readThread: () => readThread,
+  startCapability: () => startCapability
 });
 import { createSdkMcpServer as createSdkMcpServer4, tool as tool4 } from "@anthropic-ai/claude-agent-sdk";
 import { z as z3 } from "zod";
@@ -2663,6 +2670,9 @@ function dispatchWorkflow(workflowFile, capability, issueNumber, repoSlug) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }
 }
+function startCapability(workflowFile, name, issue, repoSlug) {
+  return dispatchWorkflow(workflowFile, name, issue, repoSlug);
+}
 function expectedDispatchTarget(capability) {
   const route = resolveCapabilityAction(capability);
   if (!route) return null;
@@ -2835,9 +2845,31 @@ function capabilityToolDefinitions(opts) {
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   };
+  const startCapabilityTool = {
+    name: "start_capability",
+    description: "Start a known Kody capability on an issue or PR through workflow_dispatch. Use this instead of shelling out to `gh workflow run` or posting bot-authored `@kody` command comments. E.g. start_capability({name:'qa-engineer', issue:<n>}). Returns {ok} or {ok:false,error}.",
+    inputSchema: {
+      name: z3.string().min(1).describe("Capability action to start (e.g. 'qa-engineer', 'run', 'sync')."),
+      issue: z3.number().int().positive().optional().describe("Issue or PR number forwarded as issue_number."),
+      issueNumber: z3.number().int().positive().optional().describe("Deprecated alias for issue.")
+    },
+    handler: async (args) => {
+      const name = String(args.name ?? "");
+      const issue = Number(args.issue ?? args.issueNumber);
+      if (!Number.isFinite(issue) || issue <= 0) {
+        return { content: [{ type: "text", text: "Start failed: `issue` is required and must be a positive number." }] };
+      }
+      if (isDispatchGated(name, readCapabilityTrustMode(opts.state, opts.repoSlug, opts.capabilitySlug))) {
+        return { content: [{ type: "text", text: trustRefusal(opts.capabilitySlug) }] };
+      }
+      const result = startCapability(workflowFile, name, issue, opts.repoSlug);
+      const text = result.ok ? `Started capability \`${name}\` on #${issue} via workflow_dispatch.` : `Start failed for capability \`${name}\` on #${issue}: ${result.error}`;
+      return { content: [{ type: "text", text }] };
+    }
+  };
   const dispatchTool = {
     name: "dispatch_workflow",
-    description: "Dispatch a kody.yml workflow_dispatch run for a capability action against an issue (the cross-run bot\u2192engine path; a bot `@kody` comment would be dropped). E.g. dispatch_workflow({capability:'run', issueNumber:<n>}) opens a fix PR from a tracking issue. Returns {ok} or {ok:false,error}.",
+    description: "Legacy alias for start_capability. Dispatches a kody.yml workflow_dispatch run for a capability action against an issue. Prefer start_capability({name:'run', issue:<n>}). Returns {ok} or {ok:false,error}.",
     inputSchema: {
       capability: z3.string().min(1).optional().describe("Capability action to run (e.g. 'run')."),
       executable: z3.string().min(1).optional().describe("Deprecated alias for capability."),
@@ -2849,7 +2881,7 @@ function capabilityToolDefinitions(opts) {
       if (isDispatchGated(capability, readCapabilityTrustMode(opts.state, opts.repoSlug, opts.capabilitySlug))) {
         return { content: [{ type: "text", text: trustRefusal(opts.capabilitySlug) }] };
       }
-      const result = dispatchWorkflow(workflowFile, capability, issueNumber, opts.repoSlug);
+      const result = startCapability(workflowFile, capability, issueNumber, opts.repoSlug);
       const text = result.ok ? `Dispatched capability \`${capability}\` on #${issueNumber} via workflow_dispatch.` : `Dispatch failed for capability \`${capability}\` on #${issueNumber}: ${result.error}`;
       return { content: [{ type: "text", text }] };
     }
@@ -2869,6 +2901,7 @@ function capabilityToolDefinitions(opts) {
     readThreadTool,
     ensureIssueTool,
     ensureCommentTool,
+    startCapabilityTool,
     dispatchTool,
     ...cmsTools
   ];
@@ -2918,6 +2951,7 @@ var init_capabilityMcp = __esm({
       "read_thread",
       "ensure_issue",
       "ensure_comment",
+      "start_capability",
       "dispatch_workflow",
       ...DASHBOARD_CMS_MCP_TOOL_NAMES
     ];
@@ -4264,6 +4298,7 @@ function loadProfile(profilePath) {
         describe: typeof r.describe === "string" ? r.describe : base.describe,
         agent: typeof r.agent === "string" && r.agent.trim() ? r.agent.trim() : base.agent,
         capabilityTools: parseStringArray2(r.capabilityTools ?? r.capabilityTools ?? r.tools) ?? base.capabilityTools,
+        capabilityToolMode: parseCapabilityToolMode2(profilePath, r.capabilityToolMode) ?? base.capabilityToolMode,
         mentions: Array.isArray(r.mentions) ? r.mentions.map((m) => String(m).trim()).filter(Boolean) : base.mentions
       };
     }
@@ -4319,6 +4354,7 @@ function loadProfile(profilePath) {
     agent: typeof r.agent === "string" && r.agent.trim() ? r.agent.trim() : void 0,
     // Locked-toolbox palette + mentions from folder-capability profile metadata.
     capabilityTools: parseStringArray2(r.capabilityTools ?? r.capabilityTools ?? r.tools),
+    capabilityToolMode: parseCapabilityToolMode2(profilePath, r.capabilityToolMode),
     mentions: Array.isArray(r.mentions) ? r.mentions.map((m) => String(m).trim()).filter(Boolean) : void 0,
     role,
     kind,
@@ -4360,12 +4396,7 @@ function loadProfile(profilePath) {
   const preNames = new Set(profile.scripts.preflight.map((e) => e.script).filter(Boolean));
   const postNames = profile.scripts.postflight.map((e) => e.script).filter(Boolean);
   const needsState = postNames.includes("writeJobStateFile") || postNames.includes("parseJobStateFromAgentResult");
-  const STATE_LOADERS = [
-    "loadCapabilityState",
-    "loadJobFromFile",
-    "runTickScript",
-    "runScheduledExecutableTick"
-  ];
+  const STATE_LOADERS = ["loadCapabilityState", "loadJobFromFile", "runTickScript", "runScheduledExecutableTick"];
   if (needsState && !STATE_LOADERS.some((s) => preNames.has(s))) {
     throw new ProfileError(
       profilePath,
@@ -4375,6 +4406,11 @@ function loadProfile(profilePath) {
   profile.subagentTemplates = captureSubagentTemplates(profile);
   return profile;
 }
+function parseCapabilityToolMode2(profilePath, raw) {
+  if (raw === void 0 || raw === null || raw === "") return void 0;
+  if (raw === "lock" || raw === "append") return raw;
+  throw new ProfileError(profilePath, `"capabilityToolMode" must be "lock" or "append"`);
+}
 function readPromptTemplates(dir) {
   const out = {};
   const read = (p) => {
@@ -4694,6 +4730,7 @@ var init_profile = __esm({
       "capabilityTools",
       "capabilityTools",
       "tools",
+      "capabilityToolMode",
       "mentions",
       "stage",
       "readsFrom",
@@ -13074,10 +13111,16 @@ var init_loadCapabilityState = __esm({
             `loadCapabilityState: capability '${slug2}' declared capabilityTools not in the kody-capability palette: ${unknown.join(", ")}. Available: ${[...CAPABILITY_MCP_TOOL_NAMES].join(", ")}`
           );
         }
+        const mode = profile.capabilityToolMode ?? "lock";
         ctx.data.capabilityTools = declaredTools;
+        ctx.data.capabilityToolMode = mode;
         ctx.data.capabilityToolsList = declaredTools.map((name) => `- \`${name}\``).join("\n");
         ctx.data.capabilityOperatorMention = mentions;
         const mcpToolNames = declaredTools.map((name) => `mcp__kody-capability__${name}`);
+        if (mode === "append") {
+          profile.claudeCode.tools = [.../* @__PURE__ */ new Set([...profile.claudeCode.tools ?? [], ...mcpToolNames])];
+          return;
+        }
         profile.claudeCode.tools = [...mcpToolNames, "mcp__kody-submit__submit_state"];
         profile.claudeCode.enableSubmitTool = true;
       }
@@ -13289,8 +13332,8 @@ var CAPABILITY_TOOL_PALETTE2, loadJobFromFile;
 var init_loadJobFromFile = __esm({
   "src/scripts/loadJobFromFile.ts"() {
     "use strict";
-    init_capabilityMcp();
     init_agents();
+    init_capabilityMcp();
     init_registry();
     init_jobState();
     CAPABILITY_TOOL_PALETTE2 = new Set(CAPABILITY_MCP_TOOL_NAMES);
@@ -13304,9 +13347,7 @@ var init_loadJobFromFile = __esm({
       }
       const capability = resolveCapabilityFolder(slug2, path33.join(ctx.cwd, jobsDir));
       if (!capability) {
-        throw new Error(
-          `loadJobFromFile: capability folder not found or incomplete: ${path33.join(ctx.cwd, jobsDir, slug2)}`
-        );
+        throw new Error(`loadJobFromFile: capability folder not found or incomplete: ${path33.join(ctx.cwd, jobsDir, slug2)}`);
       }
       const { title, body, config } = capability;
       const mentions = (config.mentions ?? []).map((login) => `@${login}`).join(" ");
@@ -13351,10 +13392,16 @@ var init_loadJobFromFile = __esm({
           );
         }
         const mcpToolNames = declaredTools.map((name) => `mcp__kody-capability__${name}`);
-        profile.claudeCode.tools = [...mcpToolNames, "mcp__kody-submit__submit_state"];
+        const mode = config.capabilityToolMode ?? "lock";
+        if (mode === "append") {
+          profile.claudeCode.tools = [.../* @__PURE__ */ new Set([...profile.claudeCode.tools ?? [], ...mcpToolNames])];
+        } else {
+          profile.claudeCode.tools = [...mcpToolNames, "mcp__kody-submit__submit_state"];
+          ctx.data.promptTemplate = "prompts/locked.md";
+        }
         ctx.data.capabilityTools = declaredTools;
+        ctx.data.capabilityToolMode = mode;
         ctx.data.capabilityOperatorMention = mentions;
-        ctx.data.promptTemplate = "prompts/locked.md";
         ctx.data.capabilityToolsList = declaredTools.map((name) => `- \`${name}\``).join("\n");
       }
     };
@@ -15826,165 +15873,6 @@ var init_runFlow = __esm({
   }
 });
 
-// src/scripts/previewBuildHelpers.ts
-import { createDecipheriv, createHash as createHash3 } from "crypto";
-function shortHash(s) {
-  return createHash3("sha256").update(s).digest("hex").slice(0, 6);
-}
-function previewAppName(repo, pr) {
-  const [owner, name] = repo.split("/");
-  if (!owner || !name) {
-    throw new Error(`invalid repo "${repo}", expected "owner/name"`);
-  }
-  return `kp-${shortHash(owner)}-${shortHash(name)}-pr-${pr}`;
-}
-function basePreviewAppName(repo) {
-  const [owner, name] = repo.split("/");
-  if (!owner || !name) {
-    throw new Error(`invalid repo "${repo}", expected "owner/name"`);
-  }
-  return `kp-${shortHash(owner)}-${shortHash(name)}-base`;
-}
-function decryptVaultPayload(payload, keyRaw) {
-  const parts = payload.split(":");
-  if (parts.length !== 4 || parts[0] !== "v1") {
-    throw new Error("invalid vault payload format");
-  }
-  const [, ivB64, ctB64, tagB64] = parts;
-  const key = /^[0-9a-fA-F]{64}$/.test(keyRaw) ? Buffer.from(keyRaw, "hex") : Buffer.from(keyRaw, "base64");
-  if (key.length !== 32) {
-    throw new Error("KODY_MASTER_KEY must decode to 32 bytes");
-  }
-  const iv = Buffer.from(ivB64, "base64");
-  const ct = Buffer.from(ctB64, "base64");
-  const tag = Buffer.from(tagB64, "base64");
-  const decipher = createDecipheriv("aes-256-gcm", key, iv);
-  decipher.setAuthTag(tag);
-  return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
-}
-function buildEnvFromVault(doc) {
-  const buildEnv = {};
-  for (const [name, entry] of Object.entries(doc.secrets ?? {})) {
-    if (!entry?.value) continue;
-    if (NEVER_PASS_TO_BUILD.has(name)) continue;
-    buildEnv[name] = entry.value;
-  }
-  const raw = doc.secrets?.KODY_PREVIEW_BUILD_MODE?.value;
-  const buildMode = raw?.toLowerCase().trim() === "dev" ? "dev" : "prod";
-  return { buildEnv, buildMode };
-}
-function formatPreviewComment(args) {
-  const url = `https://${args.appName}.fly.dev`;
-  return [
-    "<!-- kody-fly-preview -->",
-    `\u2705 **Preview ready:** ${url}`,
-    "",
-    `<sub>App: \`${args.appName}\` \xB7 Commit: \`${args.ref.slice(0, 7)}\` \xB7 Updated: ${args.nowIso}</sub>`
-  ].join("\n");
-}
-function defaultImageTag(repo, ref) {
-  return createHash3("sha256").update(`${repo}@${ref}`).digest("hex").slice(0, 12);
-}
-var NEVER_PASS_TO_BUILD;
-var init_previewBuildHelpers = __esm({
-  "src/scripts/previewBuildHelpers.ts"() {
-    "use strict";
-    NEVER_PASS_TO_BUILD = /* @__PURE__ */ new Set([
-      "FLY_API_TOKEN",
-      "FLY_ORG_SLUG",
-      "FLY_DEFAULT_REGION",
-      "KODY_MASTER_KEY",
-      // Preview-config knob; consumed by the dispatcher before spawn.
-      "KODY_PREVIEW_BUILD_MODE"
-    ]);
-  }
-});
-
-// src/scripts/previewBuildRun.ts
-import { spawn as spawn4 } from "child_process";
-async function runCmd(cmd, args, opts = {}) {
-  await new Promise((resolve10, reject) => {
-    const child = spawn4(cmd, args, {
-      cwd: opts.cwd,
-      env: { ...process.env, ...opts.env ?? {} },
-      stdio: opts.input ? ["pipe", "inherit", "inherit"] : "inherit"
-    });
-    if (opts.input && child.stdin) {
-      child.stdin.write(opts.input);
-      child.stdin.end();
-    }
-    child.on("error", reject);
-    child.on("close", (code) => {
-      if (code === 0) resolve10();
-      else reject(new Error(`${cmd} ${args.join(" ")} exited ${code}`));
-    });
-  });
-}
-var init_previewBuildRun = __esm({
-  "src/scripts/previewBuildRun.ts"() {
-    "use strict";
-  }
-});
-
-// src/scripts/previewBuildNamespace.ts
-async function fetchGithubOidcToken(audience) {
-  const url = process.env.ACTIONS_ID_TOKEN_REQUEST_URL?.trim();
-  const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN?.trim();
-  if (!url || !requestToken) return null;
-  const res = await fetch(`${url}&audience=${encodeURIComponent(audience)}`, {
-    headers: { Authorization: `Bearer ${requestToken}` },
-    signal: AbortSignal.timeout(REQ_TIMEOUT_MS)
-  });
-  if (!res.ok) {
-    throw new Error(`OIDC token request failed: ${res.status} ${res.statusText}`);
-  }
-  const data = await res.json();
-  if (!data.value) throw new Error("OIDC token response missing `value`");
-  return data.value;
-}
-async function setupNamespaceBuilder(opts) {
-  try {
-    await runCmd("bash", ["-c", NSC_INSTALL]);
-    const jwt = await fetchGithubOidcToken(NSC_OIDC_AUDIENCE);
-    if (!jwt) {
-      console.warn("[preview-build] no GitHub OIDC token (id-token: write missing?) \u2014 local docker build");
-      return null;
-    }
-    await runCmd("nsc", ["auth", "exchange-oidc-token", "--tenant_id", opts.tenantId, "--token", jwt]);
-    await runCmd("nsc", ["docker", "buildx", "setup", "--name", opts.builderName]);
-    console.log(`[preview-build] Namespace remote builder ready (${opts.builderName})`);
-    return opts.builderName;
-  } catch (err) {
-    console.warn(
-      "[preview-build] Namespace setup failed \u2014 falling back to local docker:",
-      err instanceof Error ? err.message : String(err)
-    );
-    return null;
-  }
-}
-var NSC_OIDC_AUDIENCE, REQ_TIMEOUT_MS, NSC_INSTALL;
-var init_previewBuildNamespace = __esm({
-  "src/scripts/previewBuildNamespace.ts"() {
-    "use strict";
-    init_previewBuildRun();
-    NSC_OIDC_AUDIENCE = "https://namespace.so";
-    REQ_TIMEOUT_MS = 15e3;
-    NSC_INSTALL = `
-set -euo pipefail
-if [ ! -x /usr/local/bin/nsc ]; then
-  ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
-  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
-  curl -fsSL "https://get.namespace.so/packages/nsc/latest?arch=\${ARCH}&os=\${OS}" -o /tmp/nsc.tar.gz
-  mkdir -p /tmp/nsc-extract
-  tar -xzf /tmp/nsc.tar.gz -C /tmp/nsc-extract
-  NSC_BIN=$(find /tmp/nsc-extract -type f -name nsc | head -1)
-  sudo install -m 0755 "$NSC_BIN" /usr/local/bin/nsc
-fi
-/usr/local/bin/nsc version
-`;
-  }
-});
-
 // src/stateRepoGithub.ts
 import * as fs39 from "fs";
 import * as path37 from "path";
@@ -16004,7 +15892,7 @@ async function githubContentsFile(opts) {
       "X-GitHub-Api-Version": "2022-11-28",
       "User-Agent": "kody-engine"
     },
-    signal: AbortSignal.timeout(REQ_TIMEOUT_MS2)
+    signal: AbortSignal.timeout(REQ_TIMEOUT_MS)
   });
   if (res.status === 404) return null;
   if (!res.ok) {
@@ -16103,7 +15991,7 @@ async function writeGithubStateTextWithConfig(opts) {
       "User-Agent": "kody-engine"
     },
     body: JSON.stringify(payload),
-    signal: AbortSignal.timeout(REQ_TIMEOUT_MS2)
+    signal: AbortSignal.timeout(REQ_TIMEOUT_MS)
   });
   if (!res.ok) {
     throw new Error(
@@ -16157,13 +16045,196 @@ async function persistJsonlFileToGithubState(opts) {
     }
   }
 }
-var GITHUB_API, REQ_TIMEOUT_MS2;
+var GITHUB_API, REQ_TIMEOUT_MS;
 var init_stateRepoGithub = __esm({
   "src/stateRepoGithub.ts"() {
     "use strict";
     init_stateRepo();
     GITHUB_API = "https://api.github.com";
-    REQ_TIMEOUT_MS2 = 3e4;
+    REQ_TIMEOUT_MS = 3e4;
+  }
+});
+
+// src/scripts/previewBuildHelpers.ts
+import { createDecipheriv, createHash as createHash3, hkdfSync } from "crypto";
+function shortHash(s) {
+  return createHash3("sha256").update(s).digest("hex").slice(0, 6);
+}
+function previewAppName(repo, pr) {
+  const [owner, name] = repo.split("/");
+  if (!owner || !name) {
+    throw new Error(`invalid repo "${repo}", expected "owner/name"`);
+  }
+  return `kp-${shortHash(owner)}-${shortHash(name)}-pr-${pr}`;
+}
+function basePreviewAppName(repo) {
+  const [owner, name] = repo.split("/");
+  if (!owner || !name) {
+    throw new Error(`invalid repo "${repo}", expected "owner/name"`);
+  }
+  return `kp-${shortHash(owner)}-${shortHash(name)}-base`;
+}
+function decryptVaultPayload(payload, keyRaw) {
+  const parts = payload.split(":");
+  if (parts.length !== 4 || parts[0] !== "v1") {
+    throw new Error("invalid vault payload format");
+  }
+  const [, ivB64, ctB64, tagB64] = parts;
+  const key = decodeMasterKey(keyRaw);
+  if (key.length !== 32) {
+    throw new Error("KODY_MASTER_KEY must decode to 32 bytes");
+  }
+  const iv = Buffer.from(ivB64, "base64");
+  const ct = Buffer.from(ctB64, "base64");
+  const tag = Buffer.from(tagB64, "base64");
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+}
+function decodeMasterKey(keyRaw) {
+  if (/^[0-9a-fA-F]{64}$/.test(keyRaw)) return Buffer.from(keyRaw, "hex");
+  return Buffer.from(keyRaw.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+function derivePreviewVerifyKey(masterKeyRaw) {
+  const masterKey = decodeMasterKey(masterKeyRaw);
+  if (masterKey.length !== 32) {
+    throw new Error("KODY_MASTER_KEY must decode to 32 bytes");
+  }
+  return Buffer.from(hkdfSync("sha256", masterKey, Buffer.alloc(0), PREVIEW_KEY_INFO, 32)).toString("hex");
+}
+function previewRuntimeEnv(args) {
+  return {
+    ...args.buildEnv,
+    KODY_PREVIEW_VERIFY_KEY: derivePreviewVerifyKey(args.masterKey),
+    KODY_REPO_CONTEXT: args.repo,
+    KODY_PR: String(args.pr)
+  };
+}
+function buildEnvFromVault(doc) {
+  const buildEnv = {};
+  for (const [name, entry] of Object.entries(doc.secrets ?? {})) {
+    if (!entry?.value) continue;
+    if (NEVER_PASS_TO_BUILD.has(name)) continue;
+    buildEnv[name] = entry.value;
+  }
+  const raw = doc.secrets?.KODY_PREVIEW_BUILD_MODE?.value;
+  const buildMode = raw?.toLowerCase().trim() === "dev" ? "dev" : "prod";
+  return { buildEnv, buildMode };
+}
+function formatPreviewComment(args) {
+  const url = `https://${args.appName}.fly.dev`;
+  return [
+    "<!-- kody-fly-preview -->",
+    `\u2705 **Preview ready:** ${url}`,
+    "",
+    `<sub>App: \`${args.appName}\` \xB7 Commit: \`${args.ref.slice(0, 7)}\` \xB7 Updated: ${args.nowIso}</sub>`
+  ].join("\n");
+}
+function defaultImageTag(repo, ref) {
+  return createHash3("sha256").update(`${repo}@${ref}`).digest("hex").slice(0, 12);
+}
+var NEVER_PASS_TO_BUILD, PREVIEW_KEY_INFO;
+var init_previewBuildHelpers = __esm({
+  "src/scripts/previewBuildHelpers.ts"() {
+    "use strict";
+    NEVER_PASS_TO_BUILD = /* @__PURE__ */ new Set([
+      "FLY_API_TOKEN",
+      "FLY_ORG_SLUG",
+      "FLY_DEFAULT_REGION",
+      "KODY_MASTER_KEY",
+      // Preview-config knob; consumed by the dispatcher before spawn.
+      "KODY_PREVIEW_BUILD_MODE",
+      "KODY_PREVIEW_VERIFY_KEY",
+      "KODY_REPO_CONTEXT",
+      "KODY_PR",
+      "KODY_BRANCH"
+    ]);
+    PREVIEW_KEY_INFO = "kody-preview:v1";
+  }
+});
+
+// src/scripts/previewBuildRun.ts
+import { spawn as spawn4 } from "child_process";
+async function runCmd(cmd, args, opts = {}) {
+  await new Promise((resolve10, reject) => {
+    const child = spawn4(cmd, args, {
+      cwd: opts.cwd,
+      env: { ...process.env, ...opts.env ?? {} },
+      stdio: opts.input ? ["pipe", "inherit", "inherit"] : "inherit"
+    });
+    if (opts.input && child.stdin) {
+      child.stdin.write(opts.input);
+      child.stdin.end();
+    }
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve10();
+      else reject(new Error(`${cmd} ${args.join(" ")} exited ${code}`));
+    });
+  });
+}
+var init_previewBuildRun = __esm({
+  "src/scripts/previewBuildRun.ts"() {
+    "use strict";
+  }
+});
+
+// src/scripts/previewBuildNamespace.ts
+async function fetchGithubOidcToken(audience) {
+  const url = process.env.ACTIONS_ID_TOKEN_REQUEST_URL?.trim();
+  const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN?.trim();
+  if (!url || !requestToken) return null;
+  const res = await fetch(`${url}&audience=${encodeURIComponent(audience)}`, {
+    headers: { Authorization: `Bearer ${requestToken}` },
+    signal: AbortSignal.timeout(REQ_TIMEOUT_MS2)
+  });
+  if (!res.ok) {
+    throw new Error(`OIDC token request failed: ${res.status} ${res.statusText}`);
+  }
+  const data = await res.json();
+  if (!data.value) throw new Error("OIDC token response missing `value`");
+  return data.value;
+}
+async function setupNamespaceBuilder(opts) {
+  try {
+    await runCmd("bash", ["-c", NSC_INSTALL]);
+    const jwt = await fetchGithubOidcToken(NSC_OIDC_AUDIENCE);
+    if (!jwt) {
+      console.warn("[preview-build] no GitHub OIDC token (id-token: write missing?) \u2014 local docker build");
+      return null;
+    }
+    await runCmd("nsc", ["auth", "exchange-oidc-token", "--tenant_id", opts.tenantId, "--token", jwt]);
+    await runCmd("nsc", ["docker", "buildx", "setup", "--name", opts.builderName]);
+    console.log(`[preview-build] Namespace remote builder ready (${opts.builderName})`);
+    return opts.builderName;
+  } catch (err) {
+    console.warn(
+      "[preview-build] Namespace setup failed \u2014 falling back to local docker:",
+      err instanceof Error ? err.message : String(err)
+    );
+    return null;
+  }
+}
+var NSC_OIDC_AUDIENCE, REQ_TIMEOUT_MS2, NSC_INSTALL;
+var init_previewBuildNamespace = __esm({
+  "src/scripts/previewBuildNamespace.ts"() {
+    "use strict";
+    init_previewBuildRun();
+    NSC_OIDC_AUDIENCE = "https://namespace.so";
+    REQ_TIMEOUT_MS2 = 15e3;
+    NSC_INSTALL = `
+set -euo pipefail
+if [ ! -x /usr/local/bin/nsc ]; then
+  ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
+  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+  curl -fsSL "https://get.namespace.so/packages/nsc/latest?arch=\${ARCH}&os=\${OS}" -o /tmp/nsc.tar.gz
+  mkdir -p /tmp/nsc-extract
+  tar -xzf /tmp/nsc.tar.gz -C /tmp/nsc-extract
+  NSC_BIN=$(find /tmp/nsc-extract -type f -name nsc | head -1)
+  sudo install -m 0755 "$NSC_BIN" /usr/local/bin/nsc
+fi
+/usr/local/bin/nsc version
+`;
   }
 });
 
@@ -16375,10 +16446,10 @@ var FLY_MACHINES, FLY_GRAPHQL, REQ_TIMEOUT_MS3, runPreviewBuild;
 var init_runPreviewBuild = __esm({
   "src/scripts/runPreviewBuild.ts"() {
     "use strict";
+    init_stateRepoGithub();
     init_previewBuildHelpers();
     init_previewBuildNamespace();
     init_previewBuildRun();
-    init_stateRepoGithub();
     FLY_MACHINES = "https://api.machines.dev/v1";
     FLY_GRAPHQL = "https://api.fly.io/graphql";
     REQ_TIMEOUT_MS3 = 3e4;
@@ -16503,7 +16574,7 @@ var init_runPreviewBuild = __esm({
             appName,
             region,
             image: `registry.fly.io/${appName}:${tag}`,
-            env: buildEnv
+            env: previewRuntimeEnv({ buildEnv, masterKey, pr, repo })
           },
           flyToken
         );
@@ -23060,7 +23131,7 @@ async function runCapabilityFallbackTick(deps) {
 }
 
 // src/pool/keys.ts
-import { hkdfSync } from "crypto";
+import { hkdfSync as hkdfSync2 } from "crypto";
 var POOL_API_KEY_INFO = "kody-pool-api:v1";
 var RUNNER_API_KEY_INFO = "kody-runner-api:v1";
 function masterKeyBytes(raw) {
@@ -23072,7 +23143,7 @@ function masterKeyBytes(raw) {
   return Buffer.from(v.replace(/-/g, "+").replace(/_/g, "/"), "base64");
 }
 function deriveKey(master, info, length = 32) {
-  return Buffer.from(hkdfSync("sha256", master, Buffer.alloc(0), info, length)).toString("hex");
+  return Buffer.from(hkdfSync2("sha256", master, Buffer.alloc(0), info, length)).toString("hex");
 }
 function derivePoolApiKey(master) {
   return deriveKey(master, POOL_API_KEY_INFO);

package/dist/executables/types.ts

@@ -76,13 +76,20 @@ export interface Profile {
    */
   kind: "oneshot" | "scheduled"
   /**
-   * Locked-toolbox palette (unified successor to a markdown capability's `tools:`
+   * Capability MCP palette (unified successor to a markdown capability's `tools:`
    * metadata). When non-empty, loadCapabilityState sets ctx.data.capabilityTools so the
-   * executor spins up the in-process kody-capability MCP server and the agent runs
-   * MCP-only (Bash/Read revoked unless also in claudeCode.tools). Absent →
-   * normal SDK tools.
+   * executor spins up the in-process kody-capability MCP server. By default this
+   * is locked mode: Bash/Read are revoked and only the declared MCP tools plus
+   * submit_state remain.
    */
   capabilityTools?: string[]
+  /**
+   * `lock` (default) replaces the normal toolbox with capability MCP tools.
+   * `append` keeps the normal toolbox and adds the declared MCP tools. Use append
+   * only for coordinator capabilities that still own repo state edits but must use
+   * an engine primitive for a narrow side effect such as starting another capability.
+   */
+  capabilityToolMode?: "lock" | "append"
   /**
    * GitHub logins (no leading `@`) this capability's output should mention. Rendered
    * to `@a @b` and exposed to the prompt as {{mentions}} (and as the capability-MCP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.304",
+  "version": "0.4.306",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,28 @@
     "templates",
     "kody.config.schema.json"
   ],
+  "scripts": {
+    "kody:run": "tsx bin/kody.ts",
+    "serve": "tsx bin/kody.ts serve",
+    "serve:vscode": "tsx bin/kody.ts serve vscode",
+    "serve:claude": "tsx bin/kody.ts serve claude",
+    "clean:dist": "node scripts/clean-dist.cjs",
+    "build": "pnpm clean:dist && tsup && node scripts/copy-assets.cjs",
+    "check:modularity": "tsx scripts/check-script-modularity.ts",
+    "pretest": "pnpm check:modularity",
+    "test": "vitest run tests/unit tests/int --coverage",
+    "posttest": "tsx scripts/check-coverage-floor.ts",
+    "test:smoke": "vitest run tests/smoke --no-coverage",
+    "test:e2e": "vitest run tests/e2e --no-coverage",
+    "test:all": "vitest run tests --no-coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "verify:package": "node scripts/verify-package-tarball.cjs",
+    "brain:publish": "docker buildx build --platform linux/amd64 -f runner/Dockerfile.brain -t ghcr.io/${KODY_BRAIN_GHCR_OWNER:-aharonyaircohen}/kody-brain:latest --push runner",
+    "prepublishOnly": "pnpm typecheck && vitest run tests/unit tests/int --no-coverage && pnpm build && pnpm verify:package"
+  },
   "dependencies": {
     "@actions/cache": "^6.0.0",
     "@anthropic-ai/claude-agent-sdk": "0.2.119",
@@ -35,26 +57,5 @@
     "url": "git+https://github.com/aharonyaircohen/kody-engine.git"
   },
   "homepage": "https://github.com/aharonyaircohen/kody-engine",
-  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues",
-  "scripts": {
-    "kody:run": "tsx bin/kody.ts",
-    "serve": "tsx bin/kody.ts serve",
-    "serve:vscode": "tsx bin/kody.ts serve vscode",
-    "serve:claude": "tsx bin/kody.ts serve claude",
-    "clean:dist": "node scripts/clean-dist.cjs",
-    "build": "pnpm clean:dist && tsup && node scripts/copy-assets.cjs",
-    "check:modularity": "tsx scripts/check-script-modularity.ts",
-    "pretest": "pnpm check:modularity",
-    "test": "vitest run tests/unit tests/int --coverage",
-    "posttest": "tsx scripts/check-coverage-floor.ts",
-    "test:smoke": "vitest run tests/smoke --no-coverage",
-    "test:e2e": "vitest run tests/e2e --no-coverage",
-    "test:all": "vitest run tests --no-coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check",
-    "lint:fix": "biome check --write",
-    "format": "biome format --write",
-    "verify:package": "node scripts/verify-package-tarball.cjs",
-    "brain:publish": "docker buildx build --platform linux/amd64 -f runner/Dockerfile.brain -t ghcr.io/${KODY_BRAIN_GHCR_OWNER:-aharonyaircohen}/kody-brain:latest --push runner"
-  }
-}
+  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues"
+}