@kody-ade/kody-engine 0.4.72 → 0.4.73

package/dist/bin/kody.js

@@ -864,7 +864,7 @@ var init_loadPriorArt = __esm({
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.72",
+  version: "0.4.73",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -919,8 +919,8 @@ var package_default = {
 
 // src/chat-cli.ts
 import { execFileSync as execFileSync31 } from "child_process";
-import * as fs33 from "fs";
-import * as path31 from "path";
+import * as fs34 from "fs";
+import * as path32 from "path";
 
 // src/chat/events.ts
 import * as fs from "fs";
@@ -2013,8 +2013,8 @@ async function emit2(sink, type, sessionId, suffix, payload) {
 
 // src/kody-cli.ts
 import { execFileSync as execFileSync30 } from "child_process";
-import * as fs32 from "fs";
-import * as path30 from "path";
+import * as fs33 from "fs";
+import * as path31 from "path";
 
 // src/dispatch.ts
 import * as fs8 from "fs";
@@ -2455,8 +2455,8 @@ init_issue();
 
 // src/executor.ts
 import { execFileSync as execFileSync29, spawn as spawn6 } from "child_process";
-import * as fs31 from "fs";
-import * as path29 from "path";
+import * as fs32 from "fs";
+import * as path30 from "path";
 init_events();
 
 // src/lifecycleLabels.ts
@@ -6659,6 +6659,19 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch2, cwd, baseBranch
       git2(["pull", "origin", branchName], cwd);
     } catch {
     }
+    if (!baseBranch || baseBranch === defaultBranch2) {
+      try {
+        git2(["merge", "--no-edit", `origin/${defaultBranch2}`], cwd);
+      } catch {
+        try {
+          git2(["merge", "--abort"], cwd);
+        } catch {
+        }
+        throw new Error(
+          `Branch '${branchName}' has merge conflicts with 'origin/${defaultBranch2}'. Resolve manually or delete the branch to start fresh.`
+        );
+      }
+    }
     return { branch: branchName, created: false };
   }
   try {
@@ -7277,10 +7290,10 @@ import * as fs25 from "fs";
 import * as path24 from "path";
 var VALID_STATES = /* @__PURE__ */ new Set(["active", "abandoned", "closed", "done"]);
 var GoalStateError = class extends Error {
-  constructor(path32, message) {
-    super(`Invalid goal state at ${path32}:
+  constructor(path33, message) {
+    super(`Invalid goal state at ${path33}:
   ${message}`);
-    this.path = path32;
+    this.path = path33;
     this.name = "GoalStateError";
   }
   path;
@@ -9002,6 +9015,240 @@ function buildChildEnv(parent, force) {
   return out;
 }
 
+// src/scripts/brainServe.ts
+import { createServer } from "http";
+import * as fs30 from "fs";
+import * as path29 from "path";
+var DEFAULT_PORT = 8080;
+function getApiKey() {
+  const key = (process.env.BRAIN_API_KEY ?? "").trim();
+  if (!key) {
+    throw new Error(
+      "BRAIN_API_KEY env var is required \u2014 set it on the Fly machine before boot."
+    );
+  }
+  return key;
+}
+function authOk(req, expected) {
+  const xApiKey = req.headers["x-api-key"]?.trim();
+  if (xApiKey && xApiKey === expected) return true;
+  const auth = req.headers["authorization"]?.trim();
+  if (auth && auth.toLowerCase().startsWith("bearer ")) {
+    return auth.slice(7).trim() === expected;
+  }
+  return false;
+}
+function readJsonBody(req) {
+  return new Promise((resolve4, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf-8");
+      if (!raw.trim()) {
+        resolve4({});
+        return;
+      }
+      try {
+        resolve4(JSON.parse(raw));
+      } catch (err) {
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function sendJson(res, status, body) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+function writeSseHeaders(res) {
+  res.writeHead(200, {
+    "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-cache, no-transform",
+    connection: "keep-alive",
+    "x-accel-buffering": "no"
+  });
+}
+function emitSse(res, event) {
+  res.write(`data: ${JSON.stringify(event)}
+
+`);
+}
+var BrainSseSink = class {
+  constructor(res, chatId) {
+    this.res = res;
+    this.chatId = chatId;
+  }
+  res;
+  chatId;
+  async emit(event) {
+    switch (event.event) {
+      case "chat.message": {
+        const content = String(event.payload.content ?? "");
+        if (content.length > 0) {
+          emitSse(this.res, { type: "text", text: content, chatId: this.chatId });
+        }
+        return;
+      }
+      case "chat.tool": {
+        if (event.payload.phase !== "use") return;
+        emitSse(this.res, {
+          type: "tool_use",
+          name: typeof event.payload.name === "string" ? event.payload.name : "tool",
+          input: event.payload.input ?? {},
+          chatId: this.chatId
+        });
+        return;
+      }
+      case "chat.done": {
+        emitSse(this.res, { type: "done", chatId: this.chatId });
+        return;
+      }
+      case "chat.error": {
+        const errMsg2 = typeof event.payload.error === "string" ? event.payload.error : "agent error";
+        emitSse(this.res, { type: "error", error: errMsg2, chatId: this.chatId });
+        return;
+      }
+      // chat.thinking / chat.ready / chat.exit — not part of the Brain protocol.
+      default:
+        return;
+    }
+  }
+};
+async function handleChatTurn(req, res, chatId, opts) {
+  let body;
+  try {
+    body = await readJsonBody(req);
+  } catch {
+    sendJson(res, 400, { error: "invalid JSON body" });
+    return;
+  }
+  const message = typeof body === "object" && body !== null && "message" in body ? body.message : void 0;
+  if (typeof message !== "string" || !message.trim()) {
+    sendJson(res, 400, { error: "message required" });
+    return;
+  }
+  const sessionFile = sessionFilePath(opts.cwd, chatId);
+  fs30.mkdirSync(path29.dirname(sessionFile), { recursive: true });
+  appendTurn(sessionFile, {
+    role: "user",
+    content: message,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  writeSseHeaders(res);
+  emitSse(res, { type: "chat", chatId });
+  const sink = new BrainSseSink(res, chatId);
+  try {
+    await opts.runTurn({
+      sessionId: chatId,
+      sessionFile,
+      cwd: opts.cwd,
+      model: opts.model,
+      litellmUrl: opts.litellmUrl,
+      sink
+    });
+  } catch (err) {
+    const errMsg2 = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[brain-serve] chat turn failed: ${errMsg2}
+`);
+    try {
+      emitSse(res, { type: "error", error: errMsg2, chatId });
+    } catch {
+    }
+  } finally {
+    try {
+      res.end();
+    } catch {
+    }
+  }
+}
+function buildServer(opts) {
+  const runTurn = opts.runTurn ?? runChatTurn;
+  return createServer(async (req, res) => {
+    if (!req.method || !req.url) {
+      sendJson(res, 400, { error: "bad request" });
+      return;
+    }
+    const url = new URL(req.url, `http://localhost`);
+    if (req.method === "GET" && url.pathname === "/healthz") {
+      sendJson(res, 200, { ok: true });
+      return;
+    }
+    if (!authOk(req, opts.apiKey)) {
+      sendJson(res, 401, { error: "unauthorized" });
+      return;
+    }
+    const m = url.pathname.match(/^\/chats\/([^/]+)\/messages\/?$/);
+    if (req.method === "POST" && m) {
+      const chatId = decodeURIComponent(m[1] ?? "");
+      if (!chatId) {
+        sendJson(res, 400, { error: "chatId required" });
+        return;
+      }
+      await handleChatTurn(req, res, chatId, {
+        cwd: opts.cwd,
+        model: opts.model,
+        litellmUrl: opts.litellmUrl,
+        runTurn
+      });
+      return;
+    }
+    sendJson(res, 404, { error: "not found" });
+  });
+}
+var brainServe = async (ctx) => {
+  ctx.skipAgent = true;
+  const apiKey = getApiKey();
+  const port = Number(process.env.PORT ?? DEFAULT_PORT);
+  const model = parseProviderModel(ctx.config.agent.model);
+  const usesProxy = needsLitellmProxy(model);
+  let handle = null;
+  if (usesProxy) {
+    process.stdout.write(
+      `[brain-serve] starting LiteLLM proxy for ${model.provider}/${model.model}...
+`
+    );
+    handle = await startLitellmIfNeeded(model, ctx.cwd);
+    process.stdout.write(
+      `[brain-serve] LiteLLM ready at ${handle?.url ?? LITELLM_DEFAULT_URL}
+`
+    );
+  }
+  const litellmUrl = usesProxy ? handle?.url ?? LITELLM_DEFAULT_URL : null;
+  const server = buildServer({
+    apiKey,
+    cwd: ctx.cwd,
+    model,
+    litellmUrl
+  });
+  await new Promise((resolve4) => {
+    server.listen(port, "0.0.0.0", () => {
+      process.stdout.write(
+        `[brain-serve] listening on 0.0.0.0:${port} (cwd=${ctx.cwd})
+`
+      );
+      resolve4();
+    });
+  });
+  const shutdown = (signal) => {
+    process.stdout.write(`[brain-serve] ${signal} \u2014 shutting down
+`);
+    server.close(() => {
+      if (handle) {
+        try {
+          handle.kill();
+        } catch {
+        }
+      }
+      process.exit(0);
+    });
+  };
+  process.once("SIGINT", () => shutdown("SIGINT"));
+  process.once("SIGTERM", () => shutdown("SIGTERM"));
+  await new Promise(() => {
+  });
+};
+
 // src/scripts/serveFlow.ts
 import { spawn as spawn3 } from "child_process";
 function parseTarget(positional) {
@@ -9841,7 +10088,7 @@ var writeJobStateFile = async (ctx, _profile, _agentResult, args) => {
 };
 
 // src/scripts/writeRunSummary.ts
-import * as fs30 from "fs";
+import * as fs31 from "fs";
 var writeRunSummary = async (ctx, profile) => {
   const summaryPath = process.env.GITHUB_STEP_SUMMARY;
   if (!summaryPath) return;
@@ -9863,7 +10110,7 @@ var writeRunSummary = async (ctx, profile) => {
   if (reason) lines.push(`- **Reason:** ${reason}`);
   lines.push("");
   try {
-    fs30.appendFileSync(summaryPath, `${lines.join("\n")}
+    fs31.appendFileSync(summaryPath, `${lines.join("\n")}
 `);
   } catch {
   }
@@ -9905,6 +10152,7 @@ var preflightScripts = {
   dispatchJobFileTicks,
   runTickScript,
   serveFlow,
+  brainServe,
   loadGoalState,
   handleAbandonedGoal,
   deriveGoalPhase,
@@ -10085,9 +10333,9 @@ async function runExecutable(profileName, input) {
     data: { ...input.preloadedData ?? {} },
     output: { exitCode: 0 }
   };
-  const ndjsonDir = path29.join(input.cwd, ".kody");
+  const ndjsonDir = path30.join(input.cwd, ".kody");
   const invokeAgent = async (prompt) => {
-    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path29.isAbsolute(p) ? p : path29.resolve(profile.dir, p)).filter((p) => p.length > 0);
+    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path30.isAbsolute(p) ? p : path30.resolve(profile.dir, p)).filter((p) => p.length > 0);
     const syntheticPath = ctx.data.syntheticPluginPath;
     const pluginPaths = [...externalPlugins, ...syntheticPath ? [syntheticPath] : []];
     return runAgent({
@@ -10282,7 +10530,7 @@ function clearStampedLifecycleLabels(profile, ctx) {
 function getProfileInputsForChild(profileName, _cwd) {
   try {
     const profilePath = resolveProfilePath(profileName);
-    if (!fs31.existsSync(profilePath)) return null;
+    if (!fs32.existsSync(profilePath)) return null;
     return loadProfile(profilePath).inputs;
   } catch {
     return null;
@@ -10291,17 +10539,17 @@ function getProfileInputsForChild(profileName, _cwd) {
 function resolveProfilePath(profileName) {
   const found = resolveExecutable(profileName);
   if (found) return found;
-  const here = path29.dirname(new URL(import.meta.url).pathname);
+  const here = path30.dirname(new URL(import.meta.url).pathname);
   const candidates = [
-    path29.join(here, "executables", profileName, "profile.json"),
+    path30.join(here, "executables", profileName, "profile.json"),
     // same-dir sibling (dev)
-    path29.join(here, "..", "executables", profileName, "profile.json"),
+    path30.join(here, "..", "executables", profileName, "profile.json"),
     // up one (prod: dist/bin → dist/executables)
-    path29.join(here, "..", "src", "executables", profileName, "profile.json")
+    path30.join(here, "..", "src", "executables", profileName, "profile.json")
     // fallback
   ];
   for (const c of candidates) {
-    if (fs31.existsSync(c)) return c;
+    if (fs32.existsSync(c)) return c;
   }
   return candidates[0];
 }
@@ -10401,8 +10649,8 @@ function resolveShellTimeoutMs(entry) {
 var SIGKILL_GRACE_MS = 5e3;
 async function runShellEntry(entry, ctx, profile) {
   const shellName = entry.shell;
-  const shellPath = path29.join(profile.dir, shellName);
-  if (!fs31.existsSync(shellPath)) {
+  const shellPath = path30.join(profile.dir, shellName);
+  if (!fs32.existsSync(shellPath)) {
     ctx.skipAgent = true;
     ctx.output.exitCode = 99;
     ctx.output.reason = `shell script not found: ${shellName} (looked in ${profile.dir})`;
@@ -10881,9 +11129,9 @@ function resolveAuthToken(env = process.env) {
   return token;
 }
 function detectPackageManager2(cwd) {
-  if (fs32.existsSync(path30.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs32.existsSync(path30.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs32.existsSync(path30.join(cwd, "bun.lockb"))) return "bun";
+  if (fs33.existsSync(path31.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs33.existsSync(path31.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs33.existsSync(path31.join(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function shellOut(cmd, args, cwd, stream = true) {
@@ -10970,11 +11218,11 @@ function configureGitIdentity(cwd) {
 }
 function postFailureTail(issueNumber, cwd, reason) {
   if (!issueNumber) return;
-  const logPath = path30.join(cwd, ".kody", "last-run.jsonl");
+  const logPath = path31.join(cwd, ".kody", "last-run.jsonl");
   let tail = "";
   try {
-    if (fs32.existsSync(logPath)) {
-      const content = fs32.readFileSync(logPath, "utf-8");
+    if (fs33.existsSync(logPath)) {
+      const content = fs33.readFileSync(logPath, "utf-8");
       tail = content.slice(-3e3);
     }
   } catch {
@@ -10999,7 +11247,7 @@ async function runCi(argv) {
     return 0;
   }
   const args = parseCiArgs(argv);
-  const cwd = args.cwd ? path30.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path31.resolve(args.cwd) : process.cwd();
   let earlyConfig;
   try {
     earlyConfig = loadConfig(cwd);
@@ -11009,9 +11257,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 && fs32.existsSync(dispatchEventPath)) {
+  if (!args.issueNumber && !autoFallback && eventName === "workflow_dispatch" && dispatchEventPath && fs33.existsSync(dispatchEventPath)) {
     try {
-      const evt = JSON.parse(fs32.readFileSync(dispatchEventPath, "utf-8"));
+      const evt = JSON.parse(fs33.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);
@@ -11270,9 +11518,9 @@ function parseChatArgs(argv, env = process.env) {
   return result;
 }
 function commitChatFiles(cwd, sessionId, verbose) {
-  const sessionFile = path31.relative(cwd, sessionFilePath(cwd, sessionId));
-  const eventsFile = path31.relative(cwd, eventsFilePath(cwd, sessionId));
-  const paths = [sessionFile, eventsFile].filter((p) => fs33.existsSync(path31.join(cwd, p)));
+  const sessionFile = path32.relative(cwd, sessionFilePath(cwd, sessionId));
+  const eventsFile = path32.relative(cwd, eventsFilePath(cwd, sessionId));
+  const paths = [sessionFile, eventsFile].filter((p) => fs34.existsSync(path32.join(cwd, p)));
   if (paths.length === 0) return;
   const opts = { cwd, stdio: verbose ? "inherit" : "pipe" };
   try {
@@ -11310,7 +11558,7 @@ async function runChat(argv) {
 ${CHAT_HELP}`);
     return 64;
   }
-  const cwd = args.cwd ? path31.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path32.resolve(args.cwd) : process.cwd();
   const sessionId = args.sessionId;
   const unpackedSecrets = unpackAllSecrets();
   if (unpackedSecrets > 0) {
@@ -11362,7 +11610,7 @@ ${CHAT_HELP}`);
   const sink = buildSink(cwd, sessionId, args.dashboardUrl);
   const meta = readMeta(sessionFile);
   process.stdout.write(
-    `\u2192 kody:chat: session file=${sessionFile} exists=${fs33.existsSync(sessionFile)} meta=${meta ? meta.mode : "none"}
+    `\u2192 kody:chat: session file=${sessionFile} exists=${fs34.existsSync(sessionFile)} meta=${meta ? meta.mode : "none"}
 `
   );
   try {

package/dist/executables/brain-serve/profile.json

@@ -0,0 +1,28 @@
+{
+  "name": "brain-serve",
+  "role": "utility",
+  "describe": "Long-lived HTTP server that wraps the Kody chat loop and speaks the Brain SSE protocol. Listens on $PORT (default 8080); auth via $BRAIN_API_KEY. Pairs with the Kody-Dashboard /api/kody/chat/brain proxy. Usage: `kody brain-serve` (runs until SIGINT/SIGTERM).",
+  "inputs": [],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "brainServe"
+      }
+    ],
+    "postflight": []
+  }
+}

package/dist/executables/plan/prompt.md

@@ -89,7 +89,19 @@ For EACH file you will change or create, include:
  - Target state — what will be there after the change, at the same level of specificity.
  - Exact locations of edits (function name, line range if stable, or anchor like "after the `meta` group field, before the closing `fields: []`").
  - For new files: rough shape including exports, key functions with signatures, and top-level module comment. **Do not paste full function bodies** — signatures and 1–2 sentence intent per export are enough for an implementer to write the body. Single-line type/interface declarations and short config snippets are fine.
- - Dependencies touched (imports added/removed, new packages) — call out if anything needs installing.
+ - Dependencies touched (imports added/removed) — call out per file; list any new third-party packages here AND aggregate them in the `## Dependencies to install` section below.
+
+## Dependencies to install
+REQUIRED if the plan introduces any third-party import not already present in
+the repo's manifest (`package.json` / `requirements.txt` / `go.mod` / etc).
+One line per dep with the exact install command the implementer should run,
+picked from the repo's lockfile (`pnpm-lock.yaml` → pnpm, `package-lock.json`
+→ npm, `yarn.lock` → yarn, `bun.lockb` → bun):
+ - `pnpm add <pkg>` — runtime dep, used by `<file>`
+ - `pnpm add -D <pkg>` — dev/types-only dep (`@types/*`, test tooling)
+If no new deps are needed, write the single line `- none`. Omitting this
+section when new deps ARE needed is a planning failure — the implementer will
+hit a `Cannot find module` typecheck error and have to recover blind.
 
 ## Algorithms & pseudocode
 REQUIRED for any non-trivial logic (sorting, diffing, state transitions, concurrency, batching, caching, conflict resolution).

package/dist/executables/run/prompt.md

@@ -41,6 +41,8 @@ If a prior-art block is present above, READ THE DIFFS — those are failed or su
 3. **Build** — Edit/Write to implement the change. Stay within the plan; if you discover the plan was wrong, briefly say so and adjust.
 4. **Test** — for every new module you added and every behavior you changed, write or update tests. If the plan above contains a "Test plan" section, treat it as authoritative: every item there must produce a corresponding test. Before writing a test, open the newest existing file in the same test directory (`tests/int/`, `tests/unit/`, `tests/e2e/`, or sibling `*.test.ts`) and copy its imports, setup hooks, and auth pattern **verbatim**. Do NOT introduce a new test infrastructure (own testcontainers, `fetch` against relative URLs, alternate auth headers) when a working pattern already exists in that directory — divergence from the established pattern is a hard failure even if the test passes locally. Cover at least one happy path and one failure path per change. Skipping tests is a hard failure. A change may only be declared untestable if you can name the specific blocker (e.g., "no fake exists for the X SDK and stubbing it would mock the entire call surface"); vague "this is just config" claims are rejected. Untestable changes go in `PLAN_DEVIATIONS:` with the named blocker.
 5. **Verify** — before declaring DONE, call the `verify` tool (mcp__kody-verify__verify). It runs typecheck/lint/tests with the project's configured commands and returns `{ ok, failures, attemptsRemaining }`. If `ok: true`, you may proceed to DONE. If `ok: false`, read the truncated `failures` list, fix the root cause, commit-equivalent edits, and call `verify` again. You have up to 4 total attempts; the tool will return `locked: true` after that and you must wrap up with FAILED. The postflight verifier runs again after this session ends and is the final ratifier — but it's also the gate that downgrades a self-reported DONE to FAILED if you skipped this step, so calling the tool is strictly cheaper than not.
+
+   **Allowed fixes between attempts** include installing missing third-party dependencies. If `failures` contains `Cannot find module 'X'` / `Cannot find package 'X'` / `error TS2307` for a NON-relative import (i.e. not `./` or `../`), the fix is to install it with the repo's package manager before the next verify call — `pnpm add X` (runtime) or `pnpm add -D X` (types-only, `@types/*`, dev tooling). Pick the package manager from the repo's lockfile: `pnpm-lock.yaml` → pnpm, `package-lock.json` → npm, `yarn.lock` → yarn, `bun.lockb` → bun. If the plan provided a `## Dependencies to install` section, prefer the exact command it specifies. Do NOT install a dep just to silence a relative-path resolution error — that's a code bug, fix the import path instead.
 6. Your FINAL message must use this exact format (or a single `FAILED: <reason>` line on failure). The `PLAN_DEVIATIONS:` block is REQUIRED whenever a plan was provided.
 
    ```

package/package.json

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