@kody-ade/kody-engine-lite 0.1.25 → 0.1.26

package/README.md

@@ -265,6 +265,43 @@ npm publish --access public  # Publish
 
 Only GitHub collaborators (COLLABORATOR, MEMBER, OWNER) can trigger `@kody`. External contributors cannot.
 
+## Branching Convention (Recommended)
+
+Give Kody a dedicated unprotected branch so it can push freely, while keeping your default branch protected for human review.
+
+```
+main (protected — require PR + review + status checks)
+  └── kody/develop (unprotected — Kody's integration branch)
+       ├── kody/task-123  (per-task, short-lived)
+       └── kody/task-456
+```
+
+### Workflow
+
+1. **Task start** — Kody creates `kody/task-<id>` from `kody/develop`
+2. **Work** — Kody pushes freely (commits, quality gates, iterations)
+3. **Task done** — Kody merges task branch into `kody/develop` (squash or fast-forward)
+4. **Ship batch** — PR from `kody/develop` → `main` (human reviews accumulated features)
+5. **After merge** — Rebase `kody/develop` onto updated `main`
+
+### GitHub Setup
+
+Configure via **Settings → Rules → Rulesets**:
+
+| Branch pattern | Protection |
+|---|---|
+| `main` | Require PR, require review, require status checks |
+| `kody/**` | No protection (optionally require status checks for CI) |
+
+Add your GitHub Actions bot as a **bypass actor** so Kody can push to `kody/*` branches even under org-wide rules.
+
+### Guidelines
+
+- **Keep `kody/develop` fresh** — rebase onto `main` after each merge to avoid drift
+- **Always branch from HEAD** — task branches should come from current `kody/develop`
+- **Critical fixes bypass** — for urgent fixes, Kody can branch directly from `main` and PR to `main`, skipping `kody/develop`
+- **Batch size** — PR to `main` after 2-3 related tasks, or on a regular cadence
+
 ## License
 
 MIT

package/dist/agent-runner.d.ts

@@ -0,0 +1,4 @@
+import type { AgentRunner } from "./types.js";
+import type { KodyConfig } from "./config.js";
+export declare function createClaudeCodeRunner(): AgentRunner;
+export declare function createRunners(config: KodyConfig): Record<string, AgentRunner>;

package/dist/agent-runner.js

@@ -0,0 +1,122 @@
+import { spawn, execFileSync } from "child_process";
+const SIGKILL_GRACE_MS = 5000;
+const STDERR_TAIL_CHARS = 500;
+function writeStdin(child, prompt) {
+    return new Promise((resolve, reject) => {
+        if (!child.stdin) {
+            resolve();
+            return;
+        }
+        child.stdin.write(prompt, (err) => {
+            if (err)
+                reject(err);
+            else {
+                child.stdin.end();
+                resolve();
+            }
+        });
+    });
+}
+function waitForProcess(child, timeout) {
+    return new Promise((resolve) => {
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!child.killed)
+                    child.kill("SIGKILL");
+            }, SIGKILL_GRACE_MS);
+        }, timeout);
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            resolve({
+                code,
+                stdout: Buffer.concat(stdoutChunks).toString(),
+                stderr: Buffer.concat(stderrChunks).toString(),
+            });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: -1, stdout: "", stderr: err.message });
+        });
+    });
+}
+async function runSubprocess(command, args, prompt, timeout, options) {
+    const child = spawn(command, args, {
+        cwd: options?.cwd ?? process.cwd(),
+        env: {
+            ...process.env,
+            SKIP_BUILD: "1",
+            SKIP_HOOKS: "1",
+            ...options?.env,
+        },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    try {
+        await writeStdin(child, prompt);
+    }
+    catch (err) {
+        return {
+            outcome: "failed",
+            error: `Failed to send prompt: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const { code, stdout, stderr } = await waitForProcess(child, timeout);
+    if (code === 0) {
+        return { outcome: "completed", output: stdout };
+    }
+    return {
+        outcome: code === null ? "timed_out" : "failed",
+        error: `Exit code ${code}\n${stderr.slice(-STDERR_TAIL_CHARS)}`,
+    };
+}
+function checkCommand(command, args) {
+    try {
+        execFileSync(command, args, { timeout: 10_000, stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Claude Code Runner ──────────────────────────────────────────────────────
+export function createClaudeCodeRunner() {
+    return {
+        async run(_stageName, prompt, model, timeout, _taskDir, options) {
+            return runSubprocess("claude", [
+                "--print",
+                "--model", model,
+                "--dangerously-skip-permissions",
+                "--allowedTools", "Bash,Edit,Read,Write,Glob,Grep",
+            ], prompt, timeout, options);
+        },
+        async healthCheck() {
+            return checkCommand("claude", ["--version"]);
+        },
+    };
+}
+// ─── Runner Factory ──────────────────────────────────────────────────────────
+const RUNNER_FACTORIES = {
+    "claude-code": createClaudeCodeRunner,
+};
+export function createRunners(config) {
+    // New multi-runner config
+    if (config.agent.runners && Object.keys(config.agent.runners).length > 0) {
+        const runners = {};
+        for (const [name, runnerConfig] of Object.entries(config.agent.runners)) {
+            const factory = RUNNER_FACTORIES[runnerConfig.type];
+            if (factory) {
+                runners[name] = factory();
+            }
+        }
+        return runners;
+    }
+    // Legacy single-runner fallback
+    const runnerType = config.agent.runner ?? "claude-code";
+    const factory = RUNNER_FACTORIES[runnerType];
+    const defaultName = config.agent.defaultRunner ?? "claude";
+    return { [defaultName]: factory ? factory() : createClaudeCodeRunner() };
+}