@kody-ade/kody-engine 0.4.203 → 0.4.204-next.0

package/dist/bin/kody.js

@@ -551,9 +551,11 @@ __export(dutyMcp_exports, {
   dispatchWorkflow: () => dispatchWorkflow,
   ensureComment: () => ensureComment,
   ensureIssue: () => ensureIssue,
+  isDispatchGated: () => isDispatchGated,
   parseDutyTrustMode: () => parseDutyTrustMode,
   readCheckRuns: () => readCheckRuns,
-  readDutyTrustMode: () => readDutyTrustMode
+  readDutyTrustMode: () => readDutyTrustMode,
+  readThread: () => readThread
 });
 import { createSdkMcpServer as createSdkMcpServer3, tool as tool3 } from "@anthropic-ai/claude-agent-sdk";
 import { z as z3 } from "zod";
@@ -665,6 +667,24 @@ function readDutyTrustMode(repoSlug, dutySlug) {
     return "ask";
   }
 }
+function readThread(repoSlug, number, limit = 10) {
+  const meta = JSON.parse(gh(["api", `repos/${repoSlug}/issues/${number}`]));
+  const rawComments = JSON.parse(
+    gh(["api", `repos/${repoSlug}/issues/${number}/comments?per_page=100`])
+  );
+  const comments = rawComments.slice(-Math.max(1, limit)).map((c) => ({
+    author: c.user?.login ?? "?",
+    createdAt: c.created_at ?? "",
+    body: (c.body ?? "").slice(0, THREAD_BODY_MAX)
+  }));
+  return {
+    number,
+    title: meta.title ?? "",
+    state: meta.state ?? "",
+    labels: (meta.labels ?? []).map((l) => l.name ?? "").filter(Boolean),
+    comments
+  };
+}
 function readCheckRuns(repoSlug, ref, ignoreNames) {
   const sha = gh(["api", `repos/${repoSlug}/commits/${ref}`, "--jq", ".sha"]).trim();
   const raw = gh([
@@ -723,6 +743,11 @@ function dispatchWorkflow(workflowFile, executable, issueNumber) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }
 }
+function isDispatchGated(executable, mode) {
+  if (mode === "auto") return false;
+  if (executable && GATE_EXEMPT_EXECUTABLES.has(executable)) return false;
+  return true;
+}
 function trustRefusal(dutySlug) {
   return `Not dispatched: duty \`${dutySlug ?? "?"}\` is in ASK mode (not trusted for autonomy). Do NOT retry the dispatch. Instead notify the operator (use recommend_to_operator, or rely on the tracking issue that already @-mentions them), then submit_state. To let this duty act on its own, grant it Auto on the dashboard Trust page.`;
 }
@@ -751,7 +776,7 @@ function buildDutyMcpServer(opts) {
       pr: z3.number().int().positive().describe("PR number to repair.")
     },
     async (args) => {
-      if (readDutyTrustMode(opts.repoSlug, opts.dutySlug) !== "auto") {
+      if (isDispatchGated(verb, readDutyTrustMode(opts.repoSlug, opts.dutySlug))) {
         return { content: [{ type: "text", text: trustRefusal(opts.dutySlug) }] };
       }
       const result = dispatchVerb(workflowFile, verb, args.pr);
@@ -818,6 +843,18 @@ function buildDutyMcpServer(opts) {
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
+  const readThreadTool = tool3(
+    "read_thread",
+    "Read an issue or PR's recent comments + labels + title/state. Returns {number, title, state, labels:[...], comments:[{author, createdAt, body}]} (newest last, body truncated). Use this to read a verdict a dispatched check posted back \u2014 e.g. qa-engineer's report or ui-review's PASS/CONCERNS/FAIL \u2014 on a later tick. Read-only; works for both issues and PRs.",
+    {
+      number: z3.number().int().positive().describe("Issue or PR number to read."),
+      limit: z3.number().int().positive().optional().describe("Max recent comments to return (default 10).")
+    },
+    async (args) => {
+      const result = readThread(opts.repoSlug, args.number, args.limit ?? 10);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
   const ensureIssueTool = tool3(
     "ensure_issue",
     "Idempotently ensure ONE open tracking issue exists for `key`. Searches OPEN issues (issues API, not the laggy search index) for `key`'s hidden marker; if found, returns {created:false, number} and creates NOTHING; otherwise creates the issue (title + body, marker appended) and returns {created:true, number}. This is the anti-duplication primitive: use one stable `key` per recurring finding so re-ticks reuse the same issue. Only take follow-up actions (dispatch/comment) when created===true.",
@@ -856,7 +893,7 @@ function buildDutyMcpServer(opts) {
       issueNumber: z3.number().int().positive().describe("Issue (or PR) number forwarded as issue_number.")
     },
     async (args) => {
-      if (readDutyTrustMode(opts.repoSlug, opts.dutySlug) !== "auto") {
+      if (isDispatchGated(args.executable, readDutyTrustMode(opts.repoSlug, opts.dutySlug))) {
         return { content: [{ type: "text", text: trustRefusal(opts.dutySlug) }] };
       }
       const result = dispatchWorkflow(workflowFile, args.executable, args.issueNumber);
@@ -875,6 +912,7 @@ function buildDutyMcpServer(opts) {
       recommendTool,
       ledgerTool,
       checkRunsTool,
+      readThreadTool,
       ensureIssueTool,
       ensureCommentTool,
       dispatchTool
@@ -882,7 +920,7 @@ function buildDutyMcpServer(opts) {
   });
   return { server };
 }
-var FAIL_CONCLUSIONS, RUNNING_STATUSES, TRUST_FILE_PATH, TRUST_STATE_BRANCH, CHECK_FAIL_CONCLUSIONS, DEFAULT_IGNORE_CHECKS, trackMarker, commentMarker, DUTY_MCP_TOOL_NAMES;
+var FAIL_CONCLUSIONS, RUNNING_STATUSES, TRUST_FILE_PATH, TRUST_STATE_BRANCH, THREAD_BODY_MAX, CHECK_FAIL_CONCLUSIONS, DEFAULT_IGNORE_CHECKS, trackMarker, commentMarker, GATE_EXEMPT_EXECUTABLES, DUTY_MCP_TOOL_NAMES;
 var init_dutyMcp = __esm({
   "src/dutyMcp.ts"() {
     "use strict";
@@ -891,10 +929,12 @@ var init_dutyMcp = __esm({
     RUNNING_STATUSES = /* @__PURE__ */ new Set(["IN_PROGRESS", "QUEUED", "PENDING", "WAITING", "REQUESTED"]);
     TRUST_FILE_PATH = ".kody/state/trust.json";
     TRUST_STATE_BRANCH = "kody-state";
+    THREAD_BODY_MAX = 4e3;
     CHECK_FAIL_CONCLUSIONS = /* @__PURE__ */ new Set(["FAILURE", "TIMED_OUT", "STARTUP_FAILURE", "ACTION_REQUIRED"]);
     DEFAULT_IGNORE_CHECKS = ["run", "kody", "job-tick", "goal-tick", "worker-ask", "chat"];
     trackMarker = (key) => `<!-- kody-track:${key} -->`;
     commentMarker = (key) => `<!-- kody-track-comment:${key} -->`;
+    GATE_EXEMPT_EXECUTABLES = /* @__PURE__ */ new Set(["qa-engineer", "ui-review"]);
     DUTY_MCP_TOOL_NAMES = [
       "list_prs_to_repair",
       "sync_pr",
@@ -903,6 +943,7 @@ var init_dutyMcp = __esm({
       "recommend_to_operator",
       "read_ledger",
       "read_check_runs",
+      "read_thread",
       "ensure_issue",
       "ensure_comment",
       "dispatch_workflow"
@@ -1442,7 +1483,7 @@ var init_loadCoverageRules = __esm({
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.203",
+  version: "0.4.204-next.0",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -1500,8 +1541,8 @@ var package_default = {
 
 // src/chat-cli.ts
 import { execFileSync as execFileSync29 } from "child_process";
-import * as fs44 from "fs";
-import * as path40 from "path";
+import * as fs45 from "fs";
+import * as path41 from "path";
 
 // src/chat/events.ts
 import * as fs from "fs";
@@ -3249,8 +3290,8 @@ async function emit2(sink, type, sessionId, suffix, payload) {
 
 // src/kody-cli.ts
 import { execFileSync as execFileSync28 } from "child_process";
-import * as fs43 from "fs";
-import * as path39 from "path";
+import * as fs44 from "fs";
+import * as path40 from "path";
 
 // src/app-auth.ts
 import { createSign } from "crypto";
@@ -3676,8 +3717,8 @@ function coerceBare(spec, value) {
 
 // src/executor.ts
 import { spawn as spawn10 } from "child_process";
-import * as fs42 from "fs";
-import * as path38 from "path";
+import * as fs43 from "fs";
+import * as path39 from "path";
 
 // src/container.ts
 init_events();
@@ -3913,6 +3954,8 @@ function loadProfile(profilePath) {
   const profile = {
     name: requireString(profilePath, r, "name"),
     describe: typeof r.describe === "string" ? r.describe : "",
+    // Optional persona to run as. Empty/blank string → undefined (no persona).
+    staff: typeof r.staff === "string" && r.staff.trim() ? r.staff.trim() : void 0,
     role,
     kind,
     schedule: typeof r.schedule === "string" ? r.schedule : void 0,
@@ -6342,10 +6385,10 @@ import * as fs25 from "fs";
 import * as path22 from "path";
 var VALID_STATES = /* @__PURE__ */ new Set(["active", "abandoned", "closed", "awaiting-merge", "done"]);
 var GoalStateError = class extends Error {
-  constructor(path41, message) {
-    super(`Invalid goal state at ${path41}:
+  constructor(path42, message) {
+    super(`Invalid goal state at ${path42}:
   ${message}`);
-    this.path = path41;
+    this.path = path42;
     this.name = "GoalStateError";
   }
   path;
@@ -10993,8 +11036,8 @@ var FlyClient = class {
   get fetch() {
     return this.opts.fetchImpl ?? fetch;
   }
-  async call(path41, init = {}) {
-    const res = await this.fetch(`${FLY_API_BASE}${path41}`, {
+  async call(path42, init = {}) {
+    const res = await this.fetch(`${FLY_API_BASE}${path42}`, {
       method: init.method ?? "GET",
       headers: {
         Authorization: `Bearer ${this.opts.token}`,
@@ -11005,7 +11048,7 @@ var FlyClient = class {
     if (res.status === 404 && init.allow404) return null;
     if (!res.ok) {
       const text = await res.text().catch(() => "");
-      throw new Error(`Fly API ${res.status} on ${path41}: ${text.slice(0, 200) || res.statusText}`);
+      throw new Error(`Fly API ${res.status} on ${path42}: ${text.slice(0, 200) || res.statusText}`);
     }
     if (res.status === 204) return null;
     const raw = await res.text();
@@ -14501,9 +14544,41 @@ var allScriptNames = /* @__PURE__ */ new Set([
   ...Object.keys(postflightScripts)
 ]);
 
-// src/subagents.ts
+// src/staff.ts
 import * as fs41 from "fs";
 import * as path37 from "path";
+var DEFAULT_STAFF_DIR = ".kody/staff";
+function stripFrontmatter(raw) {
+  const match = /^---\n[\s\S]*?\n---\n?([\s\S]*)$/.exec(raw);
+  return (match ? match[1] : raw).trim();
+}
+function loadStaffPersona(cwd, slug, staffDir = DEFAULT_STAFF_DIR) {
+  const trimmed = slug.trim();
+  if (!trimmed) throw new Error("loadStaffPersona: empty staff slug");
+  const staffPath = path37.join(cwd, staffDir, `${trimmed}.md`);
+  if (!fs41.existsSync(staffPath)) {
+    throw new Error(`loadStaffPersona: staff '${trimmed}' declared but ${staffPath} does not exist`);
+  }
+  const body = stripFrontmatter(fs41.readFileSync(staffPath, "utf-8"));
+  if (!body) throw new Error(`loadStaffPersona: staff '${trimmed}' persona body is empty (${staffPath})`);
+  return body;
+}
+function framePersona(slug, persona) {
+  return [
+    `## Who you are \u2014 staff persona (authoritative identity)`,
+    ``,
+    `You are operating as staff member \`${slug}\`. This persona defines *who* you are:`,
+    `your authority, doctrine, voice, and hard limits. Honour it exactly. Where the`,
+    `persona's restrictions are stricter than the task, **the persona wins** \u2014 a task`,
+    `can never grant you authority your persona withholds.`,
+    ``,
+    persona
+  ].join("\n");
+}
+
+// src/subagents.ts
+import * as fs42 from "fs";
+import * as path38 from "path";
 function splitFrontmatter2(raw) {
   const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw);
   if (!match) return { fm: {}, body: raw.trim() };
@@ -14516,10 +14591,10 @@ function splitFrontmatter2(raw) {
   return { fm, body: (match[2] ?? "").trim() };
 }
 function resolveAgentFile(profileDir, name) {
-  const local = path37.join(profileDir, "agents", `${name}.md`);
-  if (fs41.existsSync(local)) return local;
-  const central = path37.join(getPluginsCatalogRoot(), "agents", `${name}.md`);
-  if (fs41.existsSync(central)) return central;
+  const local = path38.join(profileDir, "agents", `${name}.md`);
+  if (fs42.existsSync(local)) return local;
+  const central = path38.join(getPluginsCatalogRoot(), "agents", `${name}.md`);
+  if (fs42.existsSync(central)) return central;
   throw new Error(`loadSubagents: agent '${name}' not found in ${profileDir}/agents/ or shared catalog`);
 }
 function loadSubagents(profile) {
@@ -14527,7 +14602,7 @@ function loadSubagents(profile) {
   if (!names || names.length === 0) return void 0;
   const agents = {};
   for (const name of names) {
-    const { fm, body } = splitFrontmatter2(fs41.readFileSync(resolveAgentFile(profile.dir, name), "utf-8"));
+    const { fm, body } = splitFrontmatter2(fs42.readFileSync(resolveAgentFile(profile.dir, name), "utf-8"));
     if (!body) throw new Error(`loadSubagents: agent '${name}' has an empty prompt body`);
     const def = {
       description: fm.description ?? `Subagent ${name}`,
@@ -14715,9 +14790,10 @@ async function runExecutable(profileName, input) {
       })
     };
   })() : null;
-  const ndjsonDir = path38.join(input.cwd, ".kody");
+  const ndjsonDir = path39.join(input.cwd, ".kody");
+  const staffPersona = typeof profile.staff === "string" && profile.staff.length > 0 ? framePersona(profile.staff, loadStaffPersona(input.cwd, profile.staff)) : null;
   const invokeAgent = async (prompt) => {
-    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path38.isAbsolute(p) ? p : path38.resolve(profile.dir, p)).filter((p) => p.length > 0);
+    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path39.isAbsolute(p) ? p : path39.resolve(profile.dir, p)).filter((p) => p.length > 0);
     const syntheticPath = ctx.data.syntheticPluginPath;
     const pluginPaths = [...externalPlugins, ...syntheticPath ? [syntheticPath] : []];
     const agents = loadSubagents(profile);
@@ -14746,7 +14822,7 @@ async function runExecutable(profileName, input) {
       maxTurnTimeoutMs: typeof profile.claudeCode.maxTurnTimeoutSec === "number" ? Math.floor(profile.claudeCode.maxTurnTimeoutSec * 1e3) : void 0,
       // DISCIPLINE leads so the stable, role-agnostic block sits at the front
       // of the cacheable system-prompt prefix; profile/task appends follow.
-      systemPromptAppend: [DISCIPLINE, profile.claudeCode.systemPromptAppend, taskArtifacts?.promptAddendum].filter((s) => typeof s === "string" && s.length > 0).join("\n\n") || void 0,
+      systemPromptAppend: [DISCIPLINE, staffPersona, profile.claudeCode.systemPromptAppend, taskArtifacts?.promptAddendum].filter((s) => typeof s === "string" && s.length > 0).join("\n\n") || void 0,
       cacheable: profile.claudeCode.cacheable,
       enableVerifyTool: profile.claudeCode.enableVerifyTool,
       enableSubmitTool: profile.claudeCode.enableSubmitTool,
@@ -14986,17 +15062,17 @@ function clearStampedLifecycleLabels(profile, ctx) {
 function resolveProfilePath(profileName) {
   const found = resolveExecutable(profileName);
   if (found) return found;
-  const here = path38.dirname(new URL(import.meta.url).pathname);
+  const here = path39.dirname(new URL(import.meta.url).pathname);
   const candidates = [
-    path38.join(here, "executables", profileName, "profile.json"),
+    path39.join(here, "executables", profileName, "profile.json"),
     // same-dir sibling (dev)
-    path38.join(here, "..", "executables", profileName, "profile.json"),
+    path39.join(here, "..", "executables", profileName, "profile.json"),
     // up one (prod: dist/bin → dist/executables)
-    path38.join(here, "..", "src", "executables", profileName, "profile.json")
+    path39.join(here, "..", "src", "executables", profileName, "profile.json")
     // fallback
   ];
   for (const c of candidates) {
-    if (fs42.existsSync(c)) return c;
+    if (fs43.existsSync(c)) return c;
   }
   return candidates[0];
 }
@@ -15096,8 +15172,8 @@ function resolveShellTimeoutMs(entry) {
 var SIGKILL_GRACE_MS = 5e3;
 async function runShellEntry(entry, ctx, profile) {
   const shellName = entry.shell;
-  const shellPath = path38.join(profile.dir, shellName);
-  if (!fs42.existsSync(shellPath)) {
+  const shellPath = path39.join(profile.dir, shellName);
+  if (!fs43.existsSync(shellPath)) {
     ctx.skipAgent = true;
     ctx.output.exitCode = 99;
     ctx.output.reason = `shell script not found: ${shellName} (looked in ${profile.dir})`;
@@ -15332,9 +15408,9 @@ async function resolveAuthToken(env = process.env) {
   return void 0;
 }
 function detectPackageManager2(cwd) {
-  if (fs43.existsSync(path39.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs43.existsSync(path39.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs43.existsSync(path39.join(cwd, "bun.lockb"))) return "bun";
+  if (fs44.existsSync(path40.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs44.existsSync(path40.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs44.existsSync(path40.join(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function shellOut(cmd, args, cwd, stream = true) {
@@ -15421,11 +15497,11 @@ function configureGitIdentity(cwd) {
 }
 function postFailureTail(issueNumber, cwd, reason) {
   if (!issueNumber) return;
-  const logPath = path39.join(cwd, ".kody", "last-run.jsonl");
+  const logPath = path40.join(cwd, ".kody", "last-run.jsonl");
   let tail = "";
   try {
-    if (fs43.existsSync(logPath)) {
-      const content = fs43.readFileSync(logPath, "utf-8");
+    if (fs44.existsSync(logPath)) {
+      const content = fs44.readFileSync(logPath, "utf-8");
       tail = content.slice(-3e3);
     }
   } catch {
@@ -15450,7 +15526,7 @@ async function runCi(argv) {
     return 0;
   }
   const args = parseCiArgs(argv);
-  const cwd = args.cwd ? path39.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path40.resolve(args.cwd) : process.cwd();
   let earlyConfig;
   try {
     earlyConfig = loadConfig(cwd);
@@ -15460,9 +15536,9 @@ async function runCi(argv) {
   const eventName = process.env.GITHUB_EVENT_NAME;
   const dispatchEventPath = process.env.GITHUB_EVENT_PATH;
   let manualWorkflowDispatch = false;
-  if (!args.issueNumber && !autoFallback && eventName === "workflow_dispatch" && dispatchEventPath && fs43.existsSync(dispatchEventPath)) {
+  if (!args.issueNumber && !autoFallback && eventName === "workflow_dispatch" && dispatchEventPath && fs44.existsSync(dispatchEventPath)) {
     try {
-      const evt = JSON.parse(fs43.readFileSync(dispatchEventPath, "utf-8"));
+      const evt = JSON.parse(fs44.readFileSync(dispatchEventPath, "utf-8"));
       const issueInput = parseInt(String(evt?.inputs?.issue_number ?? ""), 10);
       const sessionInput = String(evt?.inputs?.sessionId ?? "");
       manualWorkflowDispatch = !sessionInput && !(Number.isFinite(issueInput) && issueInput > 0);
@@ -15728,12 +15804,12 @@ function parseChatArgs(argv, env = process.env) {
   return result;
 }
 function commitChatFiles(cwd, sessionId, verbose) {
-  const sessionFile = path40.relative(cwd, sessionFilePath(cwd, sessionId));
-  const eventsFile = path40.relative(cwd, eventsFilePath(cwd, sessionId));
+  const sessionFile = path41.relative(cwd, sessionFilePath(cwd, sessionId));
+  const eventsFile = path41.relative(cwd, eventsFilePath(cwd, sessionId));
   const safeSession = sessionId.replace(/[^a-zA-Z0-9._-]/g, "_");
-  const tasksDir = path40.join(".kody", "tasks", safeSession);
+  const tasksDir = path41.join(".kody", "tasks", safeSession);
   const candidatePaths = [sessionFile, eventsFile, tasksDir];
-  const paths = candidatePaths.filter((p) => fs44.existsSync(path40.join(cwd, p)));
+  const paths = candidatePaths.filter((p) => fs45.existsSync(path41.join(cwd, p)));
   if (paths.length === 0) return;
   const opts = { cwd, stdio: verbose ? "inherit" : "pipe" };
   try {
@@ -15777,7 +15853,7 @@ async function runChat(argv) {
 ${CHAT_HELP}`);
     return 64;
   }
-  const cwd = args.cwd ? path40.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path41.resolve(args.cwd) : process.cwd();
   const sessionId = args.sessionId;
   const unpackedSecrets = unpackAllSecrets();
   if (unpackedSecrets > 0) {
@@ -15829,7 +15905,7 @@ ${CHAT_HELP}`);
   const sink = buildSink(cwd, sessionId, args.dashboardUrl);
   const meta = readMeta(sessionFile);
   process.stdout.write(
-    `\u2192 kody:chat: session file=${sessionFile} exists=${fs44.existsSync(sessionFile)} meta=${meta ? meta.mode : "none"}
+    `\u2192 kody:chat: session file=${sessionFile} exists=${fs45.existsSync(sessionFile)} meta=${meta ? meta.mode : "none"}
 `
   );
   try {

package/dist/executables/types.ts

@@ -17,6 +17,15 @@ import type { Phase } from "../state.js"
 
 export interface Profile {
   name: string
+  /**
+   * Optional staff member this executable runs *as*. When set, the executor
+   * loads `.kody/staff/<staff>.md` and injects that persona (authoritative
+   * identity) ahead of the executable's own system-prompt append. This is the
+   * unification hook: a "duty" is just an executable + a staff member. Absent →
+   * runs with no persona (unchanged legacy behaviour). A declared-but-missing
+   * staff file is fatal at run time (see src/staff.ts).
+   */
+  staff?: string
   describe: string
   /**
    * Semantic role — what this executable IS, not when it runs.

package/package.json

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