atabey 0.0.37 → 0.1.0

package/dist/atabey/src/modules/runtime/adapters/headless-cli.js

@@ -0,0 +1,115 @@
+import { spawn } from "child_process";
+import fs from "fs";
+import path from "path";
+/**
+ * Built-in headless CLI presets — all non-interactive ("print" mode).
+ * Overridable per project via `.atabey/config.json` (`runtime.cli`) or by
+ * passing a custom `CliPreset` to the constructor.
+ */
+export const CLI_PRESETS = {
+    claude: { command: "claude", buildArgs: (p) => ["-p", p, "--output-format", "text"] },
+    gemini: { command: "gemini", buildArgs: (p) => ["-p", p] },
+    codex: { command: "codex", buildArgs: (p) => ["exec", p] },
+    opencode: { command: "opencode", buildArgs: (p) => ["run", "--standalone", "--auto", p] },
+};
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_OUTPUT_CHARS = 200_000;
+/**
+ * Drives a single headless CLI invocation as one agent "turn".
+ *
+ * Safety: `shell: false` (no shell interpolation), hard timeout with SIGKILL,
+ * output capping, and never-throws result contract.
+ */
+export class HeadlessCliAdapter {
+    id;
+    preset;
+    constructor(cliId, preset) {
+        this.id = cliId;
+        const resolved = preset ?? CLI_PRESETS[cliId];
+        if (!resolved)
+            throw new Error(`Unknown CLI adapter: ${cliId}`);
+        this.preset = resolved;
+    }
+    /** Resolve the command on PATH (or as an absolute path). */
+    async isAvailable() {
+        const { command } = this.preset;
+        if (path.isAbsolute(command))
+            return fs.existsSync(command);
+        const pathEnv = process.env.PATH || "";
+        const exts = process.platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+        return pathEnv.split(path.delimiter).some((dir) => exts.some((ext) => dir && fs.existsSync(path.join(dir, command + ext))));
+    }
+    /** Expose the resolved command + argv (used by the sandbox runtime). */
+    buildCommand(prompt) {
+        return { command: this.preset.command, args: this.preset.buildArgs(prompt), useStdin: this.preset.useStdin };
+    }
+    runTurn(req) {
+        const started = Date.now();
+        const timeoutMs = req.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const maxChars = req.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+        const composed = req.systemPrompt ? `${req.systemPrompt}\n\n${req.prompt}` : req.prompt;
+        const args = this.preset.buildArgs(composed);
+        return new Promise((resolve) => {
+            let stdout = "";
+            let stderr = "";
+            let timedOut = false;
+            let settled = false;
+            const child = spawn(this.preset.command, args, {
+                cwd: req.cwd,
+                // Keep PWD in sync with cwd — some CLIs (e.g. opencode) resolve
+                // their project root from PWD, not the real process cwd.
+                env: { ...process.env, PWD: req.cwd, ...(req.env || {}) },
+                stdio: [this.preset.useStdin ? "pipe" : "ignore", "pipe", "pipe"],
+                shell: false,
+            });
+            const timer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* already dead */
+                }
+            }, timeoutMs);
+            const finish = (exitCode, error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                let output = stdout.trim();
+                if (output.length > maxChars) {
+                    output = output.slice(0, maxChars) + `\n[... truncated ${stdout.length - maxChars} chars]`;
+                }
+                const ok = !timedOut && exitCode === 0;
+                let reason = error;
+                if (!ok && !reason) {
+                    reason = timedOut
+                        ? `Timeout after ${timeoutMs}ms`
+                        : stderr.trim().slice(0, 2000) || `Process exited with code ${exitCode}`;
+                }
+                resolve({
+                    ok,
+                    output,
+                    exitCode,
+                    durationMs: Date.now() - started,
+                    timedOut,
+                    adapterId: this.id,
+                    error: ok ? undefined : reason,
+                });
+            };
+            child.stdout?.on("data", (d) => {
+                stdout += d.toString();
+            });
+            child.stderr?.on("data", (d) => {
+                stderr += d.toString();
+            });
+            child.on("error", (err) => finish(null, `spawn failed: ${err.message}`));
+            child.on("close", (code) => finish(code));
+            if (this.preset.useStdin && child.stdin) {
+                child.stdin.write(composed);
+                child.stdin.end();
+            }
+        });
+    }
+}
+//# sourceMappingURL=headless-cli.js.map

package/dist/atabey/src/modules/runtime/adapters/headless-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-cli.js","sourceRoot":"","sources":["../../../../../../src/modules/runtime/adapters/headless-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAYxB;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAA8B;IAClD,MAAM,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE;IACrF,MAAM,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE;IAC1D,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE;IAC1D,QAAQ,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE;CAC5F,CAAC;AAEF,MAAM,kBAAkB,GAAG,OAAO,CAAC;AACnC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IACX,EAAE,CAAS;IACV,MAAM,CAAY;IAEnC,YAAY,KAAa,EAAE,MAAkB;QACzC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC;QAChB,MAAM,QAAQ,GAAG,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,KAAK,EAAE,CAAC,CAAC;QAChE,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,4DAA4D;IACrD,KAAK,CAAC,WAAW;QACpB,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QAChC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChF,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAC9C,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAC1E,CAAC;IACN,CAAC;IAED,wEAAwE;IACjE,YAAY,CAAC,MAAc;QAC9B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;IACjH,CAAC;IAEM,OAAO,CAAC,GAAqB;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,IAAI,kBAAkB,CAAC;QACtD,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,IAAI,wBAAwB,CAAC;QAEhE,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,YAAY,OAAO,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QACxF,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAE7C,OAAO,IAAI,OAAO,CAAkB,CAAC,OAAO,EAAE,EAAE;YAC5C,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,IAAI,OAAO,GAAG,KAAK,CAAC;YAEpB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE;gBAC3C,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,gEAAgE;gBAChE,yDAAyD;gBACzD,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE;gBACzD,KAAK,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;gBACjE,KAAK,EAAE,KAAK;aACf,CAAC,CAAC;YAEH,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC1B,QAAQ,GAAG,IAAI,CAAC;gBAChB,IAAI,CAAC;oBACD,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC1B,CAAC;gBAAC,MAAM,CAAC;oBACL,kBAAkB;gBACtB,CAAC;YACL,CAAC,EAAE,SAAS,CAAC,CAAC;YAEd,MAAM,MAAM,GAAG,CAAC,QAAuB,EAAE,KAAc,EAAQ,EAAE;gBAC7D,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,YAAY,CAAC,KAAK,CAAC,CAAC;gBAEpB,IAAI,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC3B,IAAI,MAAM,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;oBAC3B,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,oBAAoB,MAAM,CAAC,MAAM,GAAG,QAAQ,SAAS,CAAC;gBAC/F,CAAC;gBAED,MAAM,EAAE,GAAG,CAAC,QAAQ,IAAI,QAAQ,KAAK,CAAC,CAAC;gBACvC,IAAI,MAAM,GAAG,KAAK,CAAC;gBACnB,IAAI,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;oBACjB,MAAM,GAAG,QAAQ;wBACb,CAAC,CAAC,iBAAiB,SAAS,IAAI;wBAChC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,4BAA4B,QAAQ,EAAE,CAAC;gBACjF,CAAC;gBAED,OAAO,CAAC;oBACJ,EAAE;oBACF,MAAM;oBACN,QAAQ;oBACR,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;oBAChC,QAAQ;oBACR,SAAS,EAAE,IAAI,CAAC,EAAE;oBAClB,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM;iBACjC,CAAC,CAAC;YACP,CAAC,CAAC;YAEF,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE;gBACnC,MAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC3B,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE;gBACnC,MAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC3B,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAChF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAmB,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YAEzD,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBACtC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC5B,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YACtB,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;CACJ"}

package/dist/atabey/src/modules/runtime/adapters/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export { HeadlessCliAdapter, CLI_PRESETS, type CliPreset } from "./headless-cli.js";

package/dist/atabey/src/modules/runtime/adapters/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export { HeadlessCliAdapter, CLI_PRESETS } from "./headless-cli.js";
+//# sourceMappingURL=index.js.map

package/dist/atabey/src/modules/runtime/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/modules/runtime/adapters/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAkB,MAAM,mBAAmB,CAAC"}

package/dist/atabey/src/modules/runtime/adapters/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ─── AGENT ADAPTER INTERFACE ─────────────────────────────────────────
+ *
+ * An AgentAdapter turns a single task prompt into real work by driving an
+ * external non-interactive runtime (a headless AI CLI, or a local model).
+ *
+ * Atabey itself does NOT call an LLM API directly — it orchestrates headless
+ * CLIs (Claude / Gemini / Codex / Aider / Ollama). This preserves the project
+ * identity: "we do not write code, we coordinate."
+ */
+export interface AgentTurnRequest {
+    /** Target agent, e.g. "@backend". */
+    agentName: string;
+    /** The task / instruction to execute. */
+    prompt: string;
+    /** Optional role/system context prepended to the prompt. */
+    systemPrompt?: string;
+    /** Working directory (typically a per-agent git worktree). */
+    cwd: string;
+    /** Hard wall-clock timeout in ms (default 120000). */
+    timeoutMs?: number;
+    /** Cap on captured output characters (default 200000). */
+    maxOutputChars?: number;
+    /** Extra environment variables for the child process. */
+    env?: Record<string, string>;
+}
+export interface AgentTurnResult {
+    ok: boolean;
+    output: string;
+    exitCode: number | null;
+    durationMs: number;
+    timedOut: boolean;
+    adapterId: string;
+    error?: string;
+}
+export interface AgentAdapter {
+    readonly id: string;
+    /** Whether the underlying CLI/runtime can be resolved on this machine. */
+    isAvailable(): Promise<boolean>;
+    /** Execute exactly one non-interactive turn and return its output. */
+    runTurn(req: AgentTurnRequest): Promise<AgentTurnResult>;
+    /** Optional: expose the command + argv so a caller (e.g. the sandbox runtime) can spawn it. */
+    buildCommand?(prompt: string): {
+        command: string;
+        args: string[];
+        useStdin?: boolean;
+    };
+}

package/dist/atabey/src/modules/runtime/adapters/types.js

@@ -0,0 +1,12 @@
+/**
+ * ─── AGENT ADAPTER INTERFACE ─────────────────────────────────────────
+ *
+ * An AgentAdapter turns a single task prompt into real work by driving an
+ * external non-interactive runtime (a headless AI CLI, or a local model).
+ *
+ * Atabey itself does NOT call an LLM API directly — it orchestrates headless
+ * CLIs (Claude / Gemini / Codex / Aider / Ollama). This preserves the project
+ * identity: "we do not write code, we coordinate."
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/atabey/src/modules/runtime/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../src/modules/runtime/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/atabey/src/modules/runtime/agent-runtime.d.ts

@@ -0,0 +1,54 @@
+import { type AgentAdapter, type AgentTurnResult } from "./adapters/index.js";
+export interface RunTurnOptions {
+    /** Hard wall-clock timeout in ms. */
+    timeoutMs?: number;
+    /** Advisory output-token cap; exceeding it is reported, not fatal. */
+    tokenBudget?: number;
+    /** Optional role/system context prepended to the prompt. */
+    systemPrompt?: string;
+    /** Working directory. Defaults to cwd. */
+    cwd?: string;
+    /** Extra environment variables for the child process. */
+    env?: Record<string, string>;
+    /** Explicit CLI id override (else resolved from env/config/default). */
+    cliId?: string;
+    /** Pre-built adapter (dependency injection — used by tests). */
+    adapter?: AgentAdapter;
+    /** Run in an isolated git worktree (`.atabey/worktrees/<agent>`). */
+    worktree?: boolean;
+    /** Route the spawn through the sandbox runtime (fail-closed if required). */
+    sandbox?: boolean;
+    /** Run the QualityGate on the turn output. */
+    qualityGate?: boolean;
+    /** Inject a targeted context bundle (CodeGraph + ContextAssembler) into the prompt. */
+    context?: boolean;
+}
+export interface AgentTurnReport extends AgentTurnResult {
+    agent: string;
+    inputTokens: number;
+    outputTokens: number;
+    isolation: "worktree" | "main-tree";
+    sandbox: string;
+    quality?: {
+        passed: boolean;
+        reason: string;
+    };
+}
+/**
+ * Resolve which headless CLI backs a given agent.
+ *
+ * Priority: explicit → ATABEY_AGENT_CLI → ATABEY_CLI_<AGENT> → default "claude".
+ */
+export declare function resolveAgentCli(agentName: string, explicit?: string): string;
+/**
+ * ─── AGENT RUNTIME ───────────────────────────────────────────────────
+ *
+ * Drives real, non-interactive work for a single agent by orchestrating a
+ * headless AI CLI. Optionally isolates the turn in a git worktree, routes it
+ * through the sandbox runtime, and runs the QualityGate + emits an OTel span.
+ *
+ * Never throws for runtime failures — always returns a report.
+ */
+export declare class AgentRuntime {
+    static runTurn(agentName: string, prompt: string, options?: RunTurnOptions): Promise<AgentTurnReport>;
+}

package/dist/atabey/src/modules/runtime/agent-runtime.js

@@ -0,0 +1,203 @@
+import { countTokens } from "atabey-shared/tokenizer.js";
+import { emitSpan, newSpanId, newTraceId } from "atabey-shared/otel.js";
+import { logger } from "../../shared/logger.js";
+import { HeadlessCliAdapter } from "./adapters/index.js";
+import { ensureAgentWorktree } from "./worktree.js";
+function envFlag(key) {
+    return ["1", "true", "yes", "on"].includes((process.env[key] || "").toLowerCase());
+}
+/**
+ * Resolve which headless CLI backs a given agent.
+ *
+ * Priority: explicit → ATABEY_AGENT_CLI → ATABEY_CLI_<AGENT> → default "claude".
+ */
+export function resolveAgentCli(agentName, explicit) {
+    if (explicit)
+        return explicit;
+    if (process.env.ATABEY_AGENT_CLI)
+        return process.env.ATABEY_AGENT_CLI;
+    const perAgent = `ATABEY_CLI_${agentName.replace("@", "").toUpperCase()}`;
+    if (process.env[perAgent])
+        return process.env[perAgent];
+    return "claude";
+}
+/**
+ * ─── AGENT RUNTIME ───────────────────────────────────────────────────
+ *
+ * Drives real, non-interactive work for a single agent by orchestrating a
+ * headless AI CLI. Optionally isolates the turn in a git worktree, routes it
+ * through the sandbox runtime, and runs the QualityGate + emits an OTel span.
+ *
+ * Never throws for runtime failures — always returns a report.
+ */
+export class AgentRuntime {
+    static async runTurn(agentName, prompt, options = {}) {
+        const started = Date.now();
+        const telemetryRoot = options.cwd || process.cwd();
+        const traceId = newTraceId();
+        const spanId = newSpanId();
+        const cliId = options.cliId || (options.adapter ? options.adapter.id : resolveAgentCli(agentName));
+        let composed = options.systemPrompt ? `${options.systemPrompt}\n\n${prompt}` : prompt;
+        let inputTokens = countTokens(composed);
+        const wantWorktree = options.worktree ?? envFlag("ATABEY_AGENT_WORKTREE");
+        const wantSandbox = options.sandbox ?? envFlag("ATABEY_AGENT_SANDBOX");
+        const wantQuality = options.qualityGate ?? envFlag("ATABEY_AGENT_QUALITY_GATE");
+        const report = (base, extra = {}) => ({
+            ...base,
+            agent: agentName,
+            inputTokens,
+            outputTokens: countTokens(base.output),
+            isolation: extra.isolation ?? "main-tree",
+            sandbox: extra.sandbox ?? "off",
+            quality: extra.quality,
+        });
+        const emit = (r) => {
+            emitSpan(telemetryRoot, {
+                name: `agent.turn ${agentName}`,
+                traceId,
+                spanId,
+                startMs: started,
+                endMs: Date.now(),
+                status: r.ok ? "OK" : "ERROR",
+                attributes: {
+                    agent: agentName,
+                    cli: cliId,
+                    isolation: r.isolation,
+                    sandbox: r.sandbox,
+                    inputTokens: r.inputTokens,
+                    outputTokens: r.outputTokens,
+                    durationMs: r.durationMs,
+                },
+            });
+            return r;
+        };
+        const failResult = (error) => ({
+            ok: false,
+            output: "",
+            exitCode: null,
+            durationMs: Date.now() - started,
+            timedOut: false,
+            adapterId: cliId,
+            error,
+        });
+        // ─── Working directory isolation (worktree) ───────────────────────
+        let cwd = options.cwd || process.cwd();
+        let isolation = "main-tree";
+        if (wantWorktree) {
+            try {
+                const wt = ensureAgentWorktree(cwd, agentName, wantSandbox);
+                if (wt !== cwd) {
+                    cwd = wt;
+                    isolation = "worktree";
+                }
+            }
+            catch (e) {
+                return emit(report(failResult(`[WORKTREE] ${e.message}`), { isolation: "main-tree" }));
+            }
+        }
+        // ─── Targeted context injection (no repo re-scan) ─────────────────
+        let effectiveSystem = options.systemPrompt;
+        if ((options.context ?? envFlag("ATABEY_AGENT_CONTEXT")) && !effectiveSystem) {
+            try {
+                const { ContextAssembler, formatContextBundle } = await import("../memory/context-assembler.js");
+                const bundle = ContextAssembler.assemble(cwd, prompt, { maxSymbols: 8, maxSnippetLines: 40 });
+                if (bundle.symbols.length > 0) {
+                    effectiveSystem =
+                        "You are working on an existing codebase. Do NOT re-scan the repository; use the targeted context below.\n\n" +
+                            formatContextBundle(bundle);
+                    composed = `${effectiveSystem}\n\n${prompt}`;
+                    inputTokens = countTokens(composed);
+                    logger.info(`[RUNTIME] Context injected for ${agentName}: ${bundle.symbols.length} symbols, ~${bundle.bundleTokens} tokens (saved ~${bundle.savingsPercent}%)`);
+                }
+            }
+            catch (e) {
+                logger.warn(`[RUNTIME] Context assembly skipped: ${e.message}`);
+            }
+        }
+        // ─── Resolve adapter ──────────────────────────────────────────────
+        let adapter;
+        if (options.adapter) {
+            adapter = options.adapter;
+        }
+        else {
+            try {
+                adapter = new HeadlessCliAdapter(cliId);
+            }
+            catch (e) {
+                return emit(report(failResult(`[RUNTIME] ${e.message}`), { isolation }));
+            }
+        }
+        if (!(await adapter.isAvailable())) {
+            return emit(report(failResult(`[RUNTIME] CLI "${cliId}" not found on PATH. Install it or set ATABEY_AGENT_CLI.`), { isolation }));
+        }
+        logger.info(`[RUNTIME] ${agentName} → ${cliId} (cwd: ${cwd}, isolation: ${isolation}, ~${inputTokens} input tokens)`);
+        // ─── Execute (sandboxed when requested) ───────────────────────────
+        let result;
+        let sandboxLabel = "off";
+        if (wantSandbox && typeof adapter.buildCommand === "function") {
+            try {
+                const { runInSandbox } = await import("atabey-shared/sandbox-runtime.js");
+                const { command, args, useStdin } = adapter.buildCommand(composed);
+                const t0 = Date.now();
+                const r = await runInSandbox({
+                    command,
+                    args,
+                    projectRoot: cwd,
+                    timeoutMs: options.timeoutMs,
+                    stdin: useStdin ? composed : undefined,
+                    env: { ...process.env, PWD: cwd, ...(options.env || {}) },
+                });
+                sandboxLabel = r.runtime;
+                const out = r.stdout.trim();
+                result = {
+                    ok: r.code === 0,
+                    output: out,
+                    exitCode: r.code,
+                    durationMs: Date.now() - t0,
+                    timedOut: false,
+                    adapterId: `${cliId}@${r.runtime}`,
+                    error: r.code === 0 ? undefined : r.stderr.trim().slice(0, 2000) || `exit ${r.code}`,
+                };
+            }
+            catch (e) {
+                // Fail-closed: sandbox required but unavailable, or spawn error.
+                sandboxLabel = "failed";
+                return emit(report(failResult(`[SANDBOX] ${e.message}`), { isolation, sandbox: sandboxLabel }));
+            }
+        }
+        else {
+            if (wantSandbox)
+                sandboxLabel = "unavailable";
+            result = await adapter.runTurn({
+                agentName,
+                prompt,
+                systemPrompt: effectiveSystem,
+                cwd,
+                timeoutMs: options.timeoutMs,
+                env: options.env,
+            });
+        }
+        const outputTokens = countTokens(result.output);
+        if (options.tokenBudget && outputTokens > options.tokenBudget) {
+            logger.warn(`[RUNTIME] ${agentName} output ~${outputTokens} tokens exceeds budget ${options.tokenBudget}.`);
+        }
+        // ─── QualityGate (P0.5) ───────────────────────────────────────────
+        let quality;
+        if (wantQuality && result.ok) {
+            try {
+                const { QualityGate } = await import("../engines/quality-gate.js");
+                const q = await QualityGate.check(agentName, result.output, prompt);
+                quality = { passed: q.passed, reason: q.reason };
+                if (!q.passed) {
+                    result = { ...result, ok: false, error: `[QUALITY_GATE] ${q.reason}` };
+                }
+            }
+            catch (e) {
+                logger.warn(`[RUNTIME] QualityGate error for ${agentName}: ${e.message}`);
+            }
+        }
+        logger.info(`[RUNTIME] ${agentName} ${result.ok ? "OK" : "FAIL"} in ${result.durationMs}ms (~${outputTokens} output tokens, sandbox: ${sandboxLabel})`);
+        return emit(report(result, { isolation, sandbox: sandboxLabel, quality }));
+    }
+}
+//# sourceMappingURL=agent-runtime.js.map

package/dist/atabey/src/modules/runtime/agent-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime.js","sourceRoot":"","sources":["../../../../../src/modules/runtime/agent-runtime.ts"],"names":[],"mappings":"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"}

package/dist/atabey/src/modules/runtime/dispatcher.d.ts

@@ -0,0 +1,75 @@
+import type { Plan, PlanTask } from "../engines/types.js";
+import { type AgentTurnReport, type RunTurnOptions } from "./agent-runtime.js";
+import { type EvidenceBundle } from "./evidence.js";
+export interface DispatchOptions {
+    /** Base working directory for turns (default: cwd). */
+    projectRoot?: string;
+    /** Global concurrency cap (default: min(cpus, 8)). */
+    maxConcurrency?: number;
+    /** Isolate each agent in its own git worktree (default: true). */
+    worktree?: boolean;
+    /** Route turns through the sandbox runtime. */
+    sandbox?: boolean;
+    /** Run the QualityGate on each turn. */
+    qualityGate?: boolean;
+    /** Inject a targeted context bundle into each turn's prompt. */
+    context?: boolean;
+    /** Advisory per-agent token ceiling; tasks beyond it are skipped. */
+    perAgentTokenBudget?: number;
+    /** Max retries on transient crash/timeout before marking task failed (default: 0). */
+    maxRetries?: number;
+    /** Fallback agent name or per-agent fallback map if primary worker fails. */
+    fallbackAgent?: string | Record<string, string>;
+    /** Collect signed evidence bundles + collision check after execution (default: true). */
+    collectEvidence?: boolean;
+    /** Automatically apply non-conflicting worktree changes back to `projectRoot` when `ok` and zero collisions. */
+    mergeChanges?: boolean;
+    /** Injectable runner (tests). Defaults to `AgentRuntime.runTurn`. */
+    runner?: (agent: string, task: string, opts: RunTurnOptions) => Promise<AgentTurnReport>;
+}
+export interface TaskResult {
+    id: string;
+    agent: string;
+    ok: boolean;
+    skipped: boolean;
+    output: string;
+    error?: string;
+    durationMs: number;
+    tokens: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface DispatchReport {
+    planId: string;
+    ok: boolean;
+    results: TaskResult[];
+    /** Execution waves (task ids) — for observability / the run graph. */
+    waves: string[][];
+    totalTokens: number;
+    /** Files touched by more than one agent (must be resolved before merge). */
+    conflicts: string[];
+    /** Files applied back to `projectRoot` when `mergeChanges` is enabled and zero conflicts exist. */
+    mergedFiles: string[];
+    /** Signed proof-of-work per executed task. */
+    evidence: EvidenceBundle[];
+    errors: string[];
+}
+/** Kahn-style level decomposition. Detects cycles / unresolved deps. */
+export declare function computeWaves(tasks: PlanTask[]): {
+    waves: PlanTask[][];
+    errors: string[];
+};
+/**
+ * ─── AGENT DISPATCHER ────────────────────────────────────────────────
+ *
+ * Executes a plan DAG of tasks across agents:
+ *   - Independent tasks run in parallel (bounded by `maxConcurrency`).
+ *   - Dependent tasks wait for their dependencies (Kahn waves).
+ *   - Tasks for the SAME agent are serialized (they share one worktree),
+ *     preventing write collisions while different agents run concurrently.
+ *   - A per-agent token ceiling stops runaway spend.
+ *   - After execution: collision detection + signed evidence bundles.
+ */
+export declare class AgentDispatcher {
+    static dispatch(plan: Plan, options?: DispatchOptions): Promise<DispatchReport>;
+}