@kody-ade/kody-engine 0.3.13 → 0.3.14

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.3.13",
+  version: "0.3.14",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -2732,6 +2732,70 @@ function postPrReviewComment(prNumber, body, cwd) {
   }
 }
 
+// src/scripts/dispatchManagerTicks.ts
+var dispatchManagerTicks = async (ctx, _profile, args) => {
+  ctx.skipAgent = true;
+  const label = String(args?.label ?? "");
+  const targetExecutable = String(args?.targetExecutable ?? "");
+  if (!label) throw new Error("dispatchManagerTicks: `with.label` is required");
+  if (!targetExecutable) throw new Error("dispatchManagerTicks: `with.targetExecutable` is required");
+  const issueArg = String(args?.issueArg ?? "issue");
+  const issues = listIssuesByLabel(label, ctx.cwd);
+  ctx.data.managerIssueCount = issues.length;
+  if (issues.length === 0) {
+    process.stdout.write(`[manager] no open issues with label "${label}"
+`);
+    return;
+  }
+  process.stdout.write(`[manager] ticking ${issues.length} issue(s) via ${targetExecutable}
+`);
+  const results = [];
+  for (const issue of issues) {
+    process.stdout.write(`[manager] \u2192 tick #${issue.number}: ${issue.title}
+`);
+    try {
+      const out = await runExecutable(targetExecutable, {
+        cliArgs: { [issueArg]: issue.number },
+        cwd: ctx.cwd,
+        config: ctx.config,
+        verbose: ctx.verbose,
+        quiet: ctx.quiet
+      });
+      results.push({ issue: issue.number, exitCode: out.exitCode, reason: out.reason });
+      if (out.exitCode !== 0) {
+        process.stderr.write(`[manager] tick #${issue.number} failed (exit ${out.exitCode}): ${out.reason ?? ""}
+`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[manager] tick #${issue.number} crashed: ${msg}
+`);
+      results.push({ issue: issue.number, exitCode: 99, reason: msg });
+    }
+  }
+  ctx.data.managerTickResults = results;
+  ctx.output.exitCode = 0;
+};
+function listIssuesByLabel(label, cwd) {
+  let raw = "";
+  try {
+    raw = gh2(
+      ["issue", "list", "--state", "open", "--label", label, "--limit", "100", "--json", "number,title"],
+      { cwd }
+    );
+  } catch {
+    return [];
+  }
+  let list;
+  try {
+    list = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(list)) return [];
+  return list.filter((x) => typeof x.number === "number" && typeof x.title === "string").map((x) => ({ number: x.number, title: x.title }));
+}
+
 // src/pr.ts
 var TITLE_MAX = 72;
 function stripTitlePrefixes(raw) {
@@ -3744,6 +3808,112 @@ var loadIssueContext = async (ctx) => {
   ctx.data.commentTargetNumber = issueNumber;
 };
 
+// src/scripts/issueStateComment.ts
+function isStateEnvelope(x) {
+  if (x === null || typeof x !== "object") return false;
+  const o = x;
+  return o.version === 1 && typeof o.rev === "number" && Number.isInteger(o.rev) && o.rev >= 0 && typeof o.cursor === "string" && typeof o.done === "boolean" && o.data !== null && typeof o.data === "object" && !Array.isArray(o.data);
+}
+function formatStateCommentBody(marker, state) {
+  return `<!-- ${marker} -->
+
+\`\`\`json
+${JSON.stringify(state, null, 2)}
+\`\`\`
+`;
+}
+function parseStateCommentBody(marker, body) {
+  const markerLine = `<!-- ${marker} -->`;
+  if (!body.trimStart().startsWith(markerLine)) return null;
+  const fenceOpen = body.indexOf("```json");
+  if (fenceOpen === -1) return null;
+  const after = body.slice(fenceOpen + "```json".length);
+  const fenceClose = after.indexOf("```");
+  if (fenceClose === -1) return null;
+  const jsonText = after.slice(0, fenceClose).trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch {
+    return null;
+  }
+  return isStateEnvelope(parsed) ? parsed : null;
+}
+function listIssueComments(owner, repo, issueNumber, cwd) {
+  const raw = gh2(["api", "--paginate", `repos/${owner}/${repo}/issues/${issueNumber}/comments`], { cwd });
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((c) => typeof c.id === "number" && typeof c.node_id === "string" && typeof c.body === "string").map((c) => ({ id: c.id, node_id: c.node_id, body: c.body }));
+}
+function findStateComment2(owner, repo, issueNumber, marker, cwd) {
+  const comments = listIssueComments(owner, repo, issueNumber, cwd);
+  for (const c of comments) {
+    const state = parseStateCommentBody(marker, c.body);
+    if (!state) continue;
+    return { commentId: c.id, commentNodeId: c.node_id, state };
+  }
+  return null;
+}
+function createStateComment(owner, repo, issueNumber, marker, state, cwd) {
+  const body = formatStateCommentBody(marker, state);
+  const raw = gh2(
+    ["api", "--method", "POST", `repos/${owner}/${repo}/issues/${issueNumber}/comments`, "--input", "-"],
+    { cwd, input: JSON.stringify({ body }) }
+  );
+  const parsed = JSON.parse(raw);
+  try {
+    minimizeComment(parsed.node_id, cwd);
+  } catch {
+  }
+  return { commentId: parsed.id, commentNodeId: parsed.node_id, state };
+}
+function updateStateComment(owner, repo, commentId, commentNodeId, marker, state, cwd) {
+  const body = formatStateCommentBody(marker, state);
+  gh2(
+    ["api", "--method", "PATCH", `repos/${owner}/${repo}/issues/comments/${commentId}`, "--input", "-"],
+    { cwd, input: JSON.stringify({ body }) }
+  );
+  try {
+    minimizeComment(commentNodeId, cwd);
+  } catch {
+  }
+}
+function minimizeComment(nodeId, cwd) {
+  const mutation = "mutation($id: ID!) { minimizeComment(input: { classifier: OUTDATED, subjectId: $id }) { minimizedComment { isMinimized } } }";
+  gh2(["api", "graphql", "-f", `query=${mutation}`, "-f", `id=${nodeId}`], { cwd });
+}
+
+// src/scripts/loadIssueStateComment.ts
+var loadIssueStateComment = async (ctx, _profile, args) => {
+  const marker = String(args?.marker ?? "");
+  if (!marker) {
+    throw new Error("loadIssueStateComment: `with.marker` is required");
+  }
+  const issueArg = String(args?.issueArg ?? "issue");
+  const issueNumber = Number(ctx.args[issueArg]);
+  if (!Number.isFinite(issueNumber) || issueNumber <= 0) {
+    throw new Error(`loadIssueStateComment: ctx.args.${issueArg} must be a positive integer`);
+  }
+  const owner = ctx.config.github.owner;
+  const repo = ctx.config.github.repo;
+  if (!owner || !repo) {
+    throw new Error("loadIssueStateComment: ctx.config.github.owner/repo must be set");
+  }
+  const issue = getIssue(issueNumber, ctx.cwd);
+  const loaded = findStateComment2(owner, repo, issueNumber, marker, ctx.cwd);
+  ctx.data.stateMarker = marker;
+  ctx.data.issueIntent = issue.body;
+  ctx.data.issueTitle = issue.title;
+  ctx.data.issueNumber = String(issueNumber);
+  ctx.data.issueStateComment = loaded;
+  ctx.data.issueStateJson = loaded ? JSON.stringify(loaded.state, null, 2) : "null";
+};
+
 // src/scripts/loadPriorArt.ts
 var PER_PR_DIFF_MAX_BYTES = 8e3;
 var TOTAL_MAX_BYTES = 3e4;
@@ -3911,6 +4081,53 @@ function makeAction(type, payload) {
   return { type, payload, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
 }
 
+// src/scripts/parseIssueStateFromAgentResult.ts
+function isPartialEnvelope(x) {
+  if (x === null || typeof x !== "object") return false;
+  const o = x;
+  return typeof o.cursor === "string" && o.cursor.length > 0 && typeof o.done === "boolean" && o.data !== null && typeof o.data === "object" && !Array.isArray(o.data);
+}
+var parseIssueStateFromAgentResult = async (ctx, _profile, agentResult, args) => {
+  const fenceLabel = String(args?.fenceLabel ?? "");
+  if (!fenceLabel) {
+    throw new Error("parseIssueStateFromAgentResult: `with.fenceLabel` is required");
+  }
+  if (!agentResult) {
+    ctx.data.nextStateParseError = "agent did not run";
+    return;
+  }
+  const fenceRegex = new RegExp("```" + escapeRegex(fenceLabel) + "\\s*\\n([\\s\\S]*?)\\n```", "m");
+  const match = fenceRegex.exec(agentResult.finalText);
+  if (!match) {
+    ctx.data.nextStateParseError = `agent did not emit a \`${fenceLabel}\` fenced block`;
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(match[1].trim());
+  } catch (err) {
+    ctx.data.nextStateParseError = `state JSON parse error: ${err instanceof Error ? err.message : String(err)}`;
+    return;
+  }
+  if (!isPartialEnvelope(parsed)) {
+    ctx.data.nextStateParseError = "state must be an object with string `cursor`, object `data`, and boolean `done`";
+    return;
+  }
+  const loaded = ctx.data.issueStateComment;
+  const prevRev = loaded?.state.rev ?? 0;
+  const next = {
+    version: 1,
+    rev: prevRev + 1,
+    cursor: parsed.cursor,
+    data: parsed.data,
+    done: parsed.done
+  };
+  ctx.data.nextIssueState = next;
+};
+function escapeRegex(s) {
+  return s.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+}
+
 // src/scripts/persistArtifacts.ts
 var persistArtifacts = async (ctx, profile) => {
   if (profile.outputArtifacts.length === 0) return;
@@ -5232,6 +5449,42 @@ var watchStalePrsFlow = async (ctx) => {
   ctx.data.staleCount = stale.length;
 };
 
+// src/scripts/writeIssueStateComment.ts
+var writeIssueStateComment = async (ctx, _profile, _agentResult, args) => {
+  const marker = String(args?.marker ?? "");
+  if (!marker) {
+    throw new Error("writeIssueStateComment: `with.marker` is required");
+  }
+  const issueArg = String(args?.issueArg ?? "issue");
+  const issueNumber = Number(ctx.args[issueArg]);
+  if (!Number.isFinite(issueNumber) || issueNumber <= 0) {
+    throw new Error(`writeIssueStateComment: ctx.args.${issueArg} must be a positive integer`);
+  }
+  const parseError = ctx.data.nextStateParseError;
+  if (parseError) {
+    process.stderr.write(`[kody] state write skipped: ${parseError}
+`);
+    if (ctx.output.exitCode === 0) ctx.output.exitCode = 1;
+    if (!ctx.output.reason) ctx.output.reason = `next-state parse failed: ${parseError}`;
+    return;
+  }
+  const next = ctx.data.nextIssueState;
+  if (!next) {
+    return;
+  }
+  const owner = ctx.config.github.owner;
+  const repo = ctx.config.github.repo;
+  if (!owner || !repo) {
+    throw new Error("writeIssueStateComment: ctx.config.github.owner/repo must be set");
+  }
+  const loaded = ctx.data.issueStateComment;
+  if (loaded) {
+    updateStateComment(owner, repo, loaded.commentId, loaded.commentNodeId, marker, next, ctx.cwd);
+  } else {
+    createStateComment(owner, repo, issueNumber, marker, next, ctx.cwd);
+  }
+};
+
 // src/scripts/writeRunSummary.ts
 import * as fs20 from "fs";
 var writeRunSummary = async (ctx, profile) => {
@@ -5274,6 +5527,7 @@ var preflightScripts = {
   watchStalePrsFlow,
   loadTaskState,
   loadIssueContext,
+  loadIssueStateComment,
   loadConventions,
   loadCoverageRules,
   loadPriorArt,
@@ -5286,10 +5540,13 @@ var preflightScripts = {
   setLifecycleLabel,
   skipAgent,
   classifyByLabel,
-  diagMcp
+  diagMcp,
+  dispatchManagerTicks
 };
 var postflightScripts = {
   parseAgentResult: parseAgentResult2,
+  parseIssueStateFromAgentResult,
+  writeIssueStateComment,
   requireFeedbackActions,
   requirePlanDeviations,
   verify,

package/dist/executables/manager/profile.json

@@ -0,0 +1,51 @@
+{
+  "name": "manager",
+  "role": "watch",
+  "describe": "Scheduled: for every open issue labeled kody:manager, invoke manager-tick once. No agent on the scheduler itself.",
+  "kind": "scheduled",
+  "schedule": "*/5 * * * *",
+  "inputs": [],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": null,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "gh",
+      "install": {
+        "required": true,
+        "checkCommand": "command -v gh"
+      },
+      "verify": "gh auth status",
+      "usage": "",
+      "allowedUses": ["issue"]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "dispatchManagerTicks",
+        "with": {
+          "label": "kody:manager",
+          "color": "1d76db",
+          "description": "kody: issue is a manager mission — scheduler will tick it on every cron wake",
+          "targetExecutable": "manager-tick",
+          "issueArg": "issue"
+        }
+      }
+    ],
+    "postflight": []
+  }
+}

package/dist/executables/manager-tick/profile.json

@@ -0,0 +1,72 @@
+{
+  "name": "manager-tick",
+  "role": "primitive",
+  "describe": "One classifier tick for one manager issue: read intent + state, decide and execute via gh, emit next state.",
+  "kind": "oneshot",
+  "inputs": [
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub issue number that owns this manager mission."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 20,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": ["Bash", "Read"],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "gh",
+      "install": {
+        "required": true,
+        "checkCommand": "command -v gh"
+      },
+      "verify": "gh auth status",
+      "usage": "Use `gh` for all GitHub actions: `gh workflow run <workflow> -f <key>=<val>` to spawn a child run, `gh run view <id> --json status,conclusion` to check status, `gh issue comment <n> --body \"...\"` to post narration. NEVER edit files in the working tree.",
+      "allowedUses": ["workflow", "run", "issue", "pr", "api"]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "loadIssueStateComment",
+        "with": {
+          "marker": "kody-manager-state",
+          "issueArg": "issue"
+        }
+      },
+      {
+        "script": "composePrompt"
+      }
+    ],
+    "postflight": [
+      {
+        "script": "parseIssueStateFromAgentResult",
+        "with": {
+          "fenceLabel": "kody-manager-next-state"
+        }
+      },
+      {
+        "script": "writeIssueStateComment",
+        "with": {
+          "marker": "kody-manager-state",
+          "issueArg": "issue"
+        }
+      }
+    ]
+  }
+}

package/dist/executables/manager-tick/prompt.md

@@ -0,0 +1,54 @@
+You are **kody manager-tick**, the coordinator for one GitHub-issue-scoped mission. You do **not** touch code, do **not** commit, and do **not** edit files. You coordinate other kody executables by dispatching their workflows, observing their runs, and writing back state.
+
+## The mission
+
+Issue **#{{issueNumber}}** — *{{issueTitle}}* — owns this mission. The issue description below is authoritative: it states what success looks like, constraints, deadlines, budget, or anything else a human operator has written. Re-read it every tick — the human may have edited it to steer you.
+
+### Mission (issue description)
+
+{{issueIntent}}
+
+## Current state
+
+This is the state you wrote at the end of the previous tick (or `null` if this is the first tick):
+
+```json
+{{issueStateJson}}
+```
+
+`cursor` is *your* enum — pick whatever labels map cleanly to your mission's phases (e.g. `seed`, `spawn-release`, `waiting-release`, `merge-to-dev`, `finalize`, `done`). `data` is where you stash anything you need on the next tick (run IDs, SHAs, child issue numbers, budget counters). `done: true` tells the scheduler to stop calling you.
+
+## What to do on this tick
+
+1. **Re-read the mission.** If the human has edited the description in a way that changes what "on track" means, adapt.
+2. **Decide the single next step** based on (cursor, data, mission).
+   - If `cursor` is `null`/first-run, initialize: plan the pipeline, pick an initial cursor, record any baseline info in `data`.
+   - If you're waiting on a child run, check its status via `gh run view <id> --json status,conclusion`. If still running, just update cursor/data minimally and exit — the next cron wake will check again. If succeeded, advance. If failed, record the failure and either spawn a remediation child or mark `done: true` with an error.
+   - If it's time to spawn a child executable, use `gh workflow run kody.yml -f issue_number=<N>` (or the appropriate workflow + inputs for the consumer repo). Capture the dispatched run's ID via `gh run list --workflow=kody.yml --limit 1 --json databaseId --jq '.[0].databaseId'` and stash it in `data`.
+   - If the mission is complete, set `done: true` and a terminal cursor like `done`.
+3. **Optionally post a human-readable narration comment** on the issue summarizing what you just did (spawned run #12345, waiting on CI, etc.). Keep it short. Use `gh issue comment {{issueNumber}} --body "..."`.
+4. **Emit the new state** at the very end of your response using the fenced block below. Do not include `version` or `rev` — the postflight script manages those.
+
+## Output contract (MANDATORY, exactly once, at the end)
+
+End your response with a single fenced block using the `kody-manager-next-state` language tag:
+
+````
+```kody-manager-next-state
+{
+  "cursor": "<your-next-cursor>",
+  "data": { ... },
+  "done": <true|false>
+}
+```
+````
+
+If you fail to emit this block, or the JSON is invalid, the tick fails and the state comment is NOT updated. On the next wake you'll see the same prior state and can retry.
+
+## Rules
+
+- Never edit, create, or delete files in the working tree.
+- Never commit or push.
+- Only shell calls allowed: `gh` (for workflows, runs, issues, PRs, API). Everything must go through it.
+- Keep each tick focused: do one thing per wake. The cron will call you again.
+- If the state says you're waiting on something, just check and re-emit — don't spawn a duplicate.

package/package.json

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