@kody-ade/kody-engine 0.2.19 → 0.2.21

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.19",
+  version: "0.2.21",
   description: "kody2 \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -488,6 +488,8 @@ function loadProfile(profilePath) {
     cliTools: parseCliTools(profilePath, r.cliTools),
     scripts: parseScripts(profilePath, r.scripts),
     outputContract: r.outputContract,
+    inputArtifacts: parseInputArtifacts(profilePath, r.input),
+    outputArtifacts: parseOutputArtifacts(profilePath, r.output),
     dir: path4.dirname(profilePath)
   };
   return profile;
@@ -601,6 +603,51 @@ function parseScripts(p, raw) {
     postflight: parseScriptList(p, "postflight", r.postflight)
   };
 }
+function parseInputArtifacts(p, raw) {
+  if (raw === void 0 || raw === null) return [];
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new ProfileError(p, `"input" must be an object with an "artifacts" array`);
+  }
+  const list = raw.artifacts;
+  if (list === void 0 || list === null) return [];
+  if (!Array.isArray(list)) throw new ProfileError(p, `"input.artifacts" must be an array`);
+  const out = [];
+  for (const [i, item] of list.entries()) {
+    if (typeof item === "string") {
+      out.push({ name: item });
+      continue;
+    }
+    if (!item || typeof item !== "object") {
+      throw new ProfileError(p, `input.artifacts[${i}] must be a string or object`);
+    }
+    const r = item;
+    const name = requireString(p, r, "name");
+    const spec = { name };
+    if (typeof r.required === "boolean") spec.required = r.required;
+    out.push(spec);
+  }
+  return out;
+}
+function parseOutputArtifacts(p, raw) {
+  if (raw === void 0 || raw === null) return [];
+  if (typeof raw !== "object" || Array.isArray(raw)) return [];
+  const list = raw.artifacts;
+  if (list === void 0 || list === null) return [];
+  if (!Array.isArray(list)) throw new ProfileError(p, `"output.artifacts" must be an array`);
+  const out = [];
+  for (const [i, item] of list.entries()) {
+    if (!item || typeof item !== "object") {
+      throw new ProfileError(p, `output.artifacts[${i}] must be an object`);
+    }
+    const r = item;
+    out.push({
+      name: requireString(p, r, "name"),
+      format: typeof r.format === "string" ? r.format : "text",
+      from: requireString(p, r, "from")
+    });
+  }
+  return out;
+}
 function parseScriptList(p, key, raw) {
   if (!Array.isArray(raw)) {
     throw new ProfileError(p, `scripts.${key} must be an array`);
@@ -2126,6 +2173,7 @@ function emptyState() {
       attempts: {}
     },
     executables: {},
+    artifacts: {},
     history: []
   };
 }
@@ -2172,6 +2220,7 @@ function parseStateComment(body) {
       schemaVersion: 1,
       core: { ...emptyState().core, ...parsed.core },
       executables: parsed.executables ?? {},
+      artifacts: parsed.artifacts && typeof parsed.artifacts === "object" ? parsed.artifacts : {},
       history: Array.isArray(parsed.history) ? parsed.history : []
     };
   } catch {
@@ -2200,6 +2249,7 @@ function reduce(state, executable, action) {
       phase: phaseFromAction(executable, action)
     },
     executables: newExecutables,
+    artifacts: { ...state.artifacts ?? {} },
     history: newHistory
   };
 }
@@ -2228,7 +2278,13 @@ function renderStateComment(state) {
   lines.push("");
   lines.push("```json");
   lines.push(JSON.stringify(
-    { schemaVersion: state.schemaVersion, core: state.core, executables: state.executables, history: state.history },
+    {
+      schemaVersion: state.schemaVersion,
+      core: state.core,
+      artifacts: state.artifacts ?? {},
+      executables: state.executables,
+      history: state.history
+    },
     null,
     2
   ));
@@ -2249,6 +2305,10 @@ function renderStateComment(state) {
   if (attempts) lines.push(`- **Attempts:** ${attempts}`);
   if (state.core.prUrl) lines.push(`- **PR:** ${state.core.prUrl}`);
   if (state.core.runUrl) lines.push(`- **Run:** ${state.core.runUrl}`);
+  const artifactNames = Object.keys(state.artifacts ?? {});
+  if (artifactNames.length > 0) {
+    lines.push(`- **Artifacts:** ${artifactNames.map((n) => `\`${n}\``).join(", ")}`);
+  }
   lines.push("");
   if (state.history.length > 0) {
     lines.push("### Recent history");
@@ -2266,6 +2326,12 @@ function readTaskState(target, number, cwd) {
   const existing = findStateComment(target, number, cwd);
   return existing ? parseStateComment(existing.body) : emptyState();
 }
+function setArtifact(state, name, artifact) {
+  return {
+    ...state,
+    artifacts: { ...state.artifacts ?? {}, [name]: artifact }
+  };
+}
 function writeTaskState(target, number, state, cwd) {
   const body = renderStateComment(state);
   const existing = findStateComment(target, number, cwd);
@@ -2329,6 +2395,35 @@ function makeAction(type, payload) {
   return { type, payload, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
 }
 
+// src/scripts/persistArtifacts.ts
+var persistArtifacts = async (ctx, profile) => {
+  if (profile.outputArtifacts.length === 0) return;
+  let state = ctx.data.taskState ?? emptyState();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const spec of profile.outputArtifacts) {
+    const content = readDottedString(ctx.data, spec.from);
+    if (!content) continue;
+    state = setArtifact(state, spec.name, {
+      format: spec.format,
+      producedBy: profile.name,
+      createdAt: now,
+      content
+    });
+  }
+  ctx.data.taskState = state;
+};
+function readDottedString(source, dotted) {
+  const parts = dotted.split(".");
+  let cur = source;
+  for (const p of parts) {
+    if (cur === null || cur === void 0) return "";
+    cur = cur[p];
+  }
+  if (typeof cur === "string") return cur;
+  if (cur === null || cur === void 0) return "";
+  return String(cur);
+}
+
 // src/scripts/postIssueComment.ts
 var postIssueComment2 = async (ctx) => {
   if (ctx.skipAgent && ctx.output.exitCode !== void 0) return;
@@ -2735,6 +2830,29 @@ ${truncate2(r.stderr, 2e3)}
 `);
 }
 
+// src/scripts/resolveArtifacts.ts
+var resolveArtifacts = async (ctx, profile) => {
+  if (profile.inputArtifacts.length === 0) return;
+  const state = ctx.data.taskState;
+  const available = state?.artifacts ?? {};
+  const resolved = {};
+  const missing = [];
+  for (const spec of profile.inputArtifacts) {
+    const found = available[spec.name];
+    if (found && typeof found.content === "string") {
+      resolved[spec.name] = found.content;
+    } else if (spec.required) {
+      missing.push(spec.name);
+    }
+  }
+  ctx.data.artifacts = resolved;
+  if (missing.length > 0) {
+    ctx.skipAgent = true;
+    ctx.output.exitCode = 64;
+    ctx.output.reason = `required input artifacts missing from task state: ${missing.join(", ")}`;
+  }
+};
+
 // src/scripts/resolveFlow.ts
 import { execFileSync as execFileSync12 } from "child_process";
 var CONFLICT_DIFF_MAX_BYTES = 4e4;
@@ -2912,6 +3030,94 @@ function synthesizeAction(ctx) {
   };
 }
 
+// src/scripts/syncFlow.ts
+import { execFileSync as execFileSync13 } from "child_process";
+var syncFlow = async (ctx) => {
+  ctx.skipAgent = true;
+  const prNumber = ctx.args.pr;
+  const pr = getPr(prNumber, ctx.cwd);
+  if (pr.state !== "OPEN") {
+    bail2(ctx, prNumber, `PR #${prNumber} is not OPEN (state: ${pr.state})`);
+    return;
+  }
+  ctx.data.pr = pr;
+  ctx.data.commentTargetType = "pr";
+  ctx.data.commentTargetNumber = prNumber;
+  checkoutPrBranch(prNumber, ctx.cwd);
+  ctx.data.branch = getCurrentBranch(ctx.cwd);
+  const baseBranch = pr.baseRefName || ctx.config.git.defaultBranch;
+  ctx.data.baseBranch = baseBranch;
+  const headBefore = revParseHead(ctx.cwd);
+  const mergeStatus = mergeBase(baseBranch, ctx.cwd);
+  if (mergeStatus === "error") {
+    bail2(ctx, prNumber, `failed to merge origin/${baseBranch} (non-conflict error); see runner log`);
+    return;
+  }
+  if (mergeStatus === "conflict") {
+    bail2(
+      ctx,
+      prNumber,
+      `merge from origin/${baseBranch} produced conflicts \u2014 run \`@kody2 resolve\` to let kody2 resolve them`
+    );
+    return;
+  }
+  const headAfter = revParseHead(ctx.cwd);
+  if (headAfter === headBefore) {
+    ctx.output.exitCode = 0;
+    ctx.output.reason = `already up to date with origin/${baseBranch}`;
+    tryPostPr5(prNumber, `\u2139\uFE0F kody2 sync: already up to date with origin/${baseBranch}`, ctx.cwd);
+    return;
+  }
+  try {
+    pushBranch(ctx.data.branch, ctx.cwd);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    bail2(ctx, prNumber, `merge succeeded but push failed: ${msg}`);
+    return;
+  }
+  ctx.output.exitCode = 0;
+  ctx.output.reason = `merged origin/${baseBranch} into ${ctx.data.branch}`;
+  const runUrl = getRunUrl();
+  const runSuffix = runUrl ? ` ([logs](${runUrl}))` : "";
+  tryPostPr5(
+    prNumber,
+    `\u2705 kody2 sync: merged \`origin/${baseBranch}\` into \`${ctx.data.branch}\`${runSuffix}`,
+    ctx.cwd
+  );
+};
+function bail2(ctx, prNumber, reason) {
+  ctx.output.exitCode = 1;
+  ctx.output.reason = reason;
+  const runUrl = getRunUrl();
+  const runSuffix = runUrl ? ` ([logs](${runUrl}))` : "";
+  tryPostPr5(prNumber, `\u274C kody2 sync could not complete${runSuffix}: ${reason}`, ctx.cwd);
+}
+function revParseHead(cwd) {
+  try {
+    return execFileSync13("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
+  } catch {
+    return "";
+  }
+}
+function pushBranch(branch, cwd) {
+  const env = { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" };
+  try {
+    execFileSync13("git", ["push", "-u", "origin", branch], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+  } catch {
+    execFileSync13("git", ["push", "--force-with-lease", "-u", "origin", branch], {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  }
+}
+function tryPostPr5(prNumber, body, cwd) {
+  try {
+    postPrReviewComment(prNumber, body, cwd);
+  } catch {
+  }
+}
+
 // src/verify.ts
 import { spawn as spawn2 } from "child_process";
 var TAIL_CHARS = 4e3;
@@ -3111,6 +3317,7 @@ var preflightScripts = {
   fixCiFlow,
   resolveFlow,
   reviewFlow,
+  syncFlow,
   initFlow,
   releaseFlow,
   watchStalePrsFlow,
@@ -3119,6 +3326,7 @@ var preflightScripts = {
   loadConventions,
   loadCoverageRules,
   buildSyntheticPlugin,
+  resolveArtifacts,
   composePrompt
 };
 var postflightScripts = {
@@ -3129,6 +3337,7 @@ var postflightScripts = {
   ensurePr: ensurePr2,
   postIssueComment: postIssueComment2,
   postReviewResult,
+  persistArtifacts,
   writeRunSummary,
   saveTaskState
 };
@@ -3138,7 +3347,7 @@ var allScriptNames = /* @__PURE__ */ new Set([
 ]);
 
 // src/tools.ts
-import { execFileSync as execFileSync13 } from "child_process";
+import { execFileSync as execFileSync14 } from "child_process";
 function verifyCliTools(tools, cwd) {
   const out = [];
   for (const t of tools) out.push(verifyOne(t, cwd));
@@ -3171,7 +3380,7 @@ function verifyOne(tool, cwd) {
 }
 function runShell2(cmd, cwd, timeoutMs = 3e4) {
   try {
-    execFileSync13("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
+    execFileSync14("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
     return true;
   } catch {
     return false;
@@ -3409,7 +3618,7 @@ function finish(out) {
 }
 
 // src/kody2-cli.ts
-import { execFileSync as execFileSync14 } from "child_process";
+import { execFileSync as execFileSync15 } from "child_process";
 import * as fs16 from "fs";
 import * as path13 from "path";
 
@@ -3456,6 +3665,9 @@ function autoDispatch(opts) {
     if (/\breview\b/.test(afterTag)) {
       return { executable: "review", cliArgs: { pr: targetNum }, target: targetNum };
     }
+    if (/\bsync\b/.test(afterTag)) {
+      return { executable: "sync", cliArgs: { pr: targetNum }, target: targetNum };
+    }
     const feedback = extractFeedback(afterTag);
     return {
       executable: "fix",
@@ -3586,7 +3798,7 @@ function detectPackageManager2(cwd) {
 }
 function shellOut(cmd, args, cwd, stream = true) {
   try {
-    execFileSync14(cmd, args, {
+    execFileSync15(cmd, args, {
       cwd,
       stdio: stream ? "inherit" : "pipe",
       env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1", CI: process.env.CI ?? "1" }
@@ -3599,7 +3811,7 @@ function shellOut(cmd, args, cwd, stream = true) {
 }
 function isOnPath(bin) {
   try {
-    execFileSync14("which", [bin], { stdio: "pipe" });
+    execFileSync15("which", [bin], { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -3633,7 +3845,7 @@ function installLitellmIfNeeded(cwd) {
   } catch {
   }
   try {
-    execFileSync14("python3", ["-c", "import litellm"], { stdio: "pipe" });
+    execFileSync15("python3", ["-c", "import litellm"], { stdio: "pipe" });
     process.stdout.write("\u2192 kody2: litellm already installed\n");
     return 0;
   } catch {
@@ -3643,16 +3855,16 @@ function installLitellmIfNeeded(cwd) {
 }
 function configureGitIdentity(cwd) {
   try {
-    const name = execFileSync14("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
+    const name = execFileSync15("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
     if (name) return;
   } catch {
   }
   try {
-    execFileSync14("git", ["config", "user.name", "github-actions[bot]"], { cwd, stdio: "pipe" });
+    execFileSync15("git", ["config", "user.name", "github-actions[bot]"], { cwd, stdio: "pipe" });
   } catch {
   }
   try {
-    execFileSync14("git", ["config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com"], {
+    execFileSync15("git", ["config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com"], {
       cwd,
       stdio: "pipe"
     });

package/dist/executables/plan/profile.json

@@ -48,6 +48,9 @@
       {
         "script": "parseAgentResult"
       },
+      {
+        "script": "persistArtifacts"
+      },
       {
         "script": "writeRunSummary"
       },
@@ -60,6 +63,13 @@
     "actionTypes": [
       "PLAN_COMPLETED",
       "PLAN_FAILED"
+    ],
+    "artifacts": [
+      {
+        "name": "plan",
+        "format": "markdown",
+        "from": "prSummary"
+      }
     ]
   }
 }

package/dist/executables/run/profile.json

@@ -39,6 +39,9 @@
       {
         "script": "loadTaskState"
       },
+      {
+        "script": "resolveArtifacts"
+      },
       {
         "script": "loadConventions"
       },
@@ -76,6 +79,11 @@
       }
     ]
   },
+  "input": {
+    "artifacts": [
+      { "name": "plan", "required": false }
+    ]
+  },
   "output": {
     "actionTypes": [
       "RUN_COMPLETED",

package/dist/executables/run/prompt.md

@@ -7,6 +7,11 @@ You are Kody, an autonomous engineer. Take a GitHub issue from spec to a tested
 {{conventionsBlock}}{{coverageBlock}}{{toolsUsage}}# Issue #{{issue.number}}: {{issue.title}}
 {{issue.body}}
 
+# Existing plan (produced by `@kody2 plan`, if present)
+{{artifacts.plan}}
+
+If the plan above is non-empty, TREAT IT AS AUTHORITATIVE — follow its file list and approach rather than inventing your own. Deviate only if the plan is wrong; if you do, say so explicitly. If the plan is empty, proceed from first principles.
+
 # Required steps (all in this one session — no handoff)
 1. **Research** — read the issue carefully. Use Grep/Glob/Read to investigate the codebase: locate relevant files, understand existing patterns, check related tests, identify constraints. Do not edit anything yet.
 2. **Plan** — before any Edit/Write, output a short plan (5–10 lines): what files you'll change, the approach, what could go wrong. No fluff.

package/dist/executables/sync/profile.json

@@ -0,0 +1,35 @@
+{
+  "name": "sync",
+  "describe": "Merge the default (base) branch into a PR branch and push. No agent.",
+  "inputs": [
+    {
+      "name": "pr",
+      "flag": "--pr",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub PR number to update from its base branch."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "syncFlow"
+      }
+    ],
+    "postflight": []
+  }
+}

package/dist/executables/types.ts

@@ -33,10 +33,39 @@ export interface Profile {
     postflight: ScriptEntry[]
   }
   outputContract?: OutputContract
+  /**
+   * Declared artifacts consumed by this executable. The resolveArtifacts
+   * preflight loads each into ctx.data.artifacts[name] from the task-state
+   * comment. If `required: true` and the artifact is absent, the executable
+   * fails fast.
+   */
+  inputArtifacts: InputArtifactSpec[]
+  /**
+   * Declared artifacts produced by this executable. The persistArtifacts
+   * postflight reads the named source field from ctx.data and writes an
+   * Artifact entry into the task-state comment's `artifacts` map.
+   */
+  outputArtifacts: OutputArtifactSpec[]
   /** Absolute directory the profile was loaded from. Used to resolve prompt.md. */
   dir: string
 }
 
+export interface InputArtifactSpec {
+  /** Artifact name (the key in state.artifacts). */
+  name: string
+  /** If true, the executable fails when this artifact is missing from state. */
+  required?: boolean
+}
+
+export interface OutputArtifactSpec {
+  /** Artifact name (the key in state.artifacts). */
+  name: string
+  /** Informational format tag ("markdown", "text", …). */
+  format: string
+  /** Dotted path into ctx.data to read the payload from (e.g. "prSummary"). */
+  from: string
+}
+
 export interface InputSpec {
   name: string
   flag: string

package/package.json

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