@kody-ade/kody-engine 0.2.20 → 0.2.22

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.20",
+  version: "0.2.22",
   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;
@@ -2384,6 +2479,28 @@ function postWith(type, n, body, cwd) {
   }
 }
 
+// src/scripts/postPlanComment.ts
+var postPlanComment = async (ctx) => {
+  if (!ctx.data.agentDone) return;
+  const targetType = ctx.data.commentTargetType;
+  const targetNumber = Number(ctx.data.commentTargetNumber ?? 0);
+  const plan = ctx.data.prSummary?.trim();
+  if (targetType !== "issue" || !targetNumber || !plan) return;
+  const body = renderPlanComment(targetNumber, plan);
+  try {
+    postIssueComment(targetNumber, body, ctx.cwd);
+  } catch {
+  }
+};
+function renderPlanComment(issueNumber, plan) {
+  return `## Plan for issue #${issueNumber}
+
+${plan}
+
+---
+Comment \`@kody2 run\` to execute this plan.`;
+}
+
 // src/scripts/postReviewResult.ts
 function detectVerdict(body) {
   const m = body.match(/##\s*Verdict\s*:\s*(PASS|CONCERNS|FAIL)\b/i);
@@ -2735,6 +2852,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;
@@ -3208,6 +3348,7 @@ var preflightScripts = {
   loadConventions,
   loadCoverageRules,
   buildSyntheticPlugin,
+  resolveArtifacts,
   composePrompt
 };
 var postflightScripts = {
@@ -3217,7 +3358,9 @@ var postflightScripts = {
   commitAndPush: commitAndPush2,
   ensurePr: ensurePr2,
   postIssueComment: postIssueComment2,
+  postPlanComment,
   postReviewResult,
+  persistArtifacts,
   writeRunSummary,
   saveTaskState
 };

package/dist/executables/plan/profile.json

@@ -48,6 +48,12 @@
       {
         "script": "parseAgentResult"
       },
+      {
+        "script": "persistArtifacts"
+      },
+      {
+        "script": "postPlanComment"
+      },
       {
         "script": "writeRunSummary"
       },
@@ -60,6 +66,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/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.20",
+  "version": "0.2.22",
   "description": "kody2 — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",