beflow 0.1.0

package/src/agent/acpx.ts

@@ -0,0 +1,197 @@
+import { spawn } from "bun";
+
+import type { AgentConfig, Config } from "../config/schema.ts";
+import type { AgentDriver, AgentRunResult, RunOptions } from "./driver.ts";
+import { parseAcpLine, reduceAcpStream } from "./events.ts";
+import { extractReport } from "./report.ts";
+
+const DEFAULT_ACPX_COMMAND = ["bunx", "acpx"] as const;
+
+// Wall-clock grace added on top of acpx's own cooperative `--timeout`. acpx's
+// `--timeout` is the first line of defence (it asks the agent to stop); this
+// Grace is the window we give that cooperative stop before the driver's hard
+// Kill backstops a wedged acpx.
+const GRACE_SECONDS = 30;
+
+// The configured acpx launcher (command + leading args), default `bunx acpx`.
+export function resolveAcpxCommand(config: Config): string[] {
+    const configured = config.tools?.acpx;
+    return configured !== undefined && configured.length > 0 ? configured : [...DEFAULT_ACPX_COMMAND];
+}
+
+// Resolve the acpx `--agent` command string for an agent. beflow always fully
+// Specifies the agent in config.agents and never relies on acpx's built-in
+// Registry, so an unconfigured agent is an error.
+export function resolveAcpCommand(agentName: string, cfg: AgentConfig | undefined): string {
+    if (cfg === undefined) {
+        throw new Error(`beflow: agent "${agentName}" is not configured in config.agents (add it with a "command")`);
+    }
+    return [cfg.acpCommand ?? cfg.command, ...(cfg.acpArgs ?? [])].join(" ");
+}
+
+export function buildAcpxArgs(opts: RunOptions): string[] {
+    const args: string[] = ["--format", "json", "--json-strict", "--cwd", opts.cwd];
+
+    args.push(opts.runMode === "autonomous" ? "--approve-all" : "--approve-reads");
+
+    if (opts.nonInteractive !== undefined) {
+        args.push("--non-interactive-permissions", opts.nonInteractive);
+    }
+    if (opts.contract !== undefined) {
+        args.push("--append-system-prompt", opts.contract);
+    }
+    if (opts.model !== undefined) {
+        args.push("--model", opts.model);
+    }
+    args.push("--agent", opts.acpCommand);
+    if (opts.timeoutSeconds !== undefined) {
+        args.push("--timeout", String(opts.timeoutSeconds));
+    }
+    if (opts.suppressReads === true) {
+        args.push("--suppress-reads");
+    }
+
+    if (opts.oneShot === true) {
+        args.push("exec", opts.task);
+    } else {
+        args.push("prompt", "-s", opts.sessionKey, opts.task);
+    }
+
+    return args;
+}
+
+export function buildCancelArgs(sessionKey: string, cwd: string, acpCommand: string): string[] {
+    return ["--cwd", cwd, "--agent", acpCommand, "cancel", "-s", sessionKey];
+}
+
+export function buildEnsureSessionArgs(sessionName: string, cwd: string, acpCommand: string): string[] {
+    return ["--cwd", cwd, "--agent", acpCommand, "sessions", "ensure", "--name", sessionName];
+}
+
+export interface SpawnedProcess {
+    lines(): AsyncIterable<string>;
+    exit(): Promise<number>;
+    kill(): void;
+}
+
+export interface ProcessRunner {
+    spawn(args: string[], cwd: string): SpawnedProcess;
+}
+
+export class BunProcessRunner implements ProcessRunner {
+    public constructor(private readonly command: string[] = ["bunx", "acpx"]) {}
+
+    public spawn(args: string[], cwd: string): SpawnedProcess {
+        const proc = spawn([...this.command, ...args], {
+            cwd,
+            stderr: "inherit",
+            stdout: "pipe",
+        });
+
+        async function* lines(): AsyncIterable<string> {
+            const decoder = new TextDecoder();
+            let buffer = "";
+            for await (const chunk of proc.stdout) {
+                buffer += decoder.decode(chunk, { stream: true });
+                let newline = buffer.indexOf("\n");
+                while (newline !== -1) {
+                    yield buffer.slice(0, newline);
+                    buffer = buffer.slice(newline + 1);
+                    newline = buffer.indexOf("\n");
+                }
+            }
+            buffer += decoder.decode();
+            if (buffer !== "") {
+                yield buffer;
+            }
+        }
+
+        return {
+            exit: async () => proc.exited,
+            kill: () => {
+                proc.kill();
+            },
+            lines,
+        };
+    }
+}
+
+async function realDelay(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+
+const MS_PER_SECOND = 1000;
+
+export class AcpxDriver implements AgentDriver {
+    private readonly runner: ProcessRunner;
+    private readonly delay: (ms: number) => Promise<void>;
+
+    public constructor(
+        opts: { runner?: ProcessRunner; command?: string[]; delay?: (ms: number) => Promise<void> } = {},
+    ) {
+        this.runner = opts.runner ?? new BunProcessRunner(opts.command);
+        this.delay = opts.delay ?? realDelay;
+    }
+
+    public async run(opts: RunOptions, onEvent?: (evt: unknown) => void): Promise<AgentRunResult> {
+        const proc = this.runner.spawn(buildAcpxArgs(opts), opts.cwd);
+
+        const raw: string[] = [];
+        async function consume(): Promise<void> {
+            for await (const line of proc.lines()) {
+                raw.push(line);
+                if (onEvent !== undefined) {
+                    const evt = parseAcpLine(line);
+                    if (evt !== null) {
+                        onEvent(evt);
+                    }
+                }
+            }
+        }
+
+        let timedOut = false;
+        const consumed = consume();
+        if (opts.timeoutSeconds === undefined) {
+            await consumed;
+        } else {
+            const deadlineMs = (opts.timeoutSeconds + GRACE_SECONDS) * MS_PER_SECOND;
+            const deadline = Symbol("deadline");
+            const winner = await Promise.race([consumed, this.delay(deadlineMs).then(() => deadline)]);
+            if (winner === deadline) {
+                timedOut = true;
+                // Hard kill: ending stdout terminates the in-flight `consume()` line
+                // Iteration cleanly, so we await the SAME promise to drain it and avoid
+                // A dangling unhandled rejection.
+                proc.kill();
+                await consumed;
+            }
+        }
+
+        // OnEvent already fired live above; reduce the buffered lines for the result.
+        const stream = reduceAcpStream(raw);
+        const report = extractReport(stream.assistantText);
+        const exitCode = await proc.exit();
+
+        return { exitCode, raw, report, stream, timedOut };
+    }
+
+    public async cancel(sessionKey: string, cwd: string, acpCommand: string): Promise<void> {
+        const proc = this.runner.spawn(buildCancelArgs(sessionKey, cwd, acpCommand), cwd);
+        await proc.exit();
+    }
+
+    public async ensureSession(sessionName: string, cwd: string, acpCommand: string): Promise<void> {
+        const proc = this.runner.spawn(buildEnsureSessionArgs(sessionName, cwd, acpCommand), cwd);
+        for await (const line of proc.lines()) {
+            void line; // drain stdout
+        }
+        const exitCode = await proc.exit();
+        if (exitCode !== 0) {
+            throw new Error(
+                `beflow: acpx sessions ensure failed for session "${sessionName}" (exit ${String(exitCode)})`,
+            );
+        }
+    }
+}

package/src/agent/driver.ts

@@ -0,0 +1,38 @@
+import type { RunMode } from "../model/types.ts";
+import type { AcpStreamResult } from "./events.ts";
+import type { Report } from "./report.ts";
+
+// The agent-execution contract: the inputs, the result, and the surface that
+// consumers depend on. Kept separate from the concrete acpx driver so callers
+// and tests depend on the interface, not the implementation's private internals.
+
+export interface RunOptions {
+    sessionKey: string;
+    cwd: string;
+    runMode: RunMode;
+    task: string;
+    contract?: string;
+    model?: string;
+    // ACP-server command passed to acpx via `--agent`. Always set by beflow.
+    acpCommand: string;
+    oneShot?: boolean;
+    nonInteractive?: "deny" | "fail";
+    timeoutSeconds?: number;
+    suppressReads?: boolean;
+}
+
+export interface AgentRunResult {
+    exitCode: number;
+    stream: AcpStreamResult;
+    report: Report | null;
+    raw: string[];
+    // True when the driver hit its hard wall-clock deadline and killed the process
+    // before it completed. False on every normal completion.
+    timedOut: boolean;
+}
+
+export interface AgentDriver {
+    run: (opts: RunOptions, onEvent?: (evt: unknown) => void) => Promise<AgentRunResult>;
+    cancel: (sessionKey: string, cwd: string, acpCommand: string) => Promise<void>;
+    ensureSession: (sessionName: string, cwd: string, acpCommand: string) => Promise<void>;
+}

package/src/agent/events.ts

@@ -0,0 +1,228 @@
+export interface AcpToolCall {
+    id: string;
+    title?: string;
+    kind?: string;
+    status?: string;
+    toolName?: string;
+}
+
+export interface Usage {
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    costUsd?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+
+export interface AcpStreamResult {
+    assistantText: string;
+    toolCalls: AcpToolCall[];
+    stopReason?: string;
+    error?: { code?: number; message: string };
+    usage?: Usage;
+}
+
+export function parseAcpLine(line: string): unknown {
+    const trimmed = line.trim();
+    if (trimmed === "") {
+        return null;
+    }
+    try {
+        return JSON.parse(trimmed);
+    } catch {
+        return null;
+    }
+}
+
+interface ToolName {
+    _meta?: { claudeCode?: { toolName?: unknown } };
+}
+
+function readToolName(update: ToolName): string | undefined {
+    const name = update._meta?.claudeCode?.toolName;
+    return typeof name === "string" ? name : undefined;
+}
+
+function asString(value: unknown): string | undefined {
+    return typeof value === "string" ? value : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+    return isRecord(value) ? value : undefined;
+}
+
+function handleToolCall(toolCalls: AcpToolCall[], update: Record<string, unknown>): void {
+    const id = asString(update.toolCallId);
+    if (id === undefined) {
+        return;
+    }
+    toolCalls.push({
+        id,
+        kind: asString(update.kind),
+        status: asString(update.status),
+        title: asString(update.title),
+        toolName: readToolName(update as ToolName),
+    });
+}
+
+function handleToolCallUpdate(toolCalls: AcpToolCall[], update: Record<string, unknown>): void {
+    const id = asString(update.toolCallId);
+    if (id === undefined) {
+        return;
+    }
+
+    const status = asString(update.status);
+    const title = asString(update.title);
+    const toolName = readToolName(update as ToolName);
+
+    const existing = toolCalls.find((call) => call.id === id);
+    if (existing === undefined) {
+        toolCalls.push({ id, status, title, toolName });
+        return;
+    }
+    if (status !== undefined) {
+        existing.status = status;
+    }
+    if (title !== undefined) {
+        existing.title = title;
+    }
+    if (toolName !== undefined) {
+        existing.toolName = toolName;
+    }
+}
+
+// Lenient `usage_update` parse: the on-wire shape is unverified, so read token
+// Counts defensively from either a nested `usage` object or the top-level update,
+// Accepting camelCase AND snake_case. Any missing/non-numeric field is left
+// Undefined; this NEVER throws. Returns undefined when no field was readable.
+function parseUsage(update: Record<string, unknown>): Usage | undefined {
+    const src = asRecord(update.usage) ?? update;
+    const inputTokens = asNumber(src.inputTokens) ?? asNumber(src.input_tokens);
+    const outputTokens = asNumber(src.outputTokens) ?? asNumber(src.output_tokens);
+    const totalTokens = asNumber(src.totalTokens) ?? asNumber(src.total_tokens) ?? asNumber(src.used);
+    const cacheReadTokens =
+        asNumber(src.cachedReadTokens) ??
+        asNumber(src.cacheReadTokens) ??
+        asNumber(src.cache_read_tokens) ??
+        asNumber(src.cacheReadInputTokens) ??
+        asNumber(src.cache_read_input_tokens);
+    const cacheWriteTokens =
+        asNumber(src.cachedWriteTokens) ??
+        asNumber(src.cacheWriteTokens) ??
+        asNumber(src.cache_write_tokens) ??
+        asNumber(src.cacheCreationInputTokens) ??
+        asNumber(src.cache_creation_input_tokens);
+    const costUsd =
+        asNumber(src.costUsd) ??
+        asNumber(src.cost_usd) ??
+        asNumber(src.total_cost) ??
+        asNumber(src.cost) ??
+        asNumber(asRecord(src.cost)?.amount);
+
+    const usage: Usage = {
+        ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+        ...(cacheWriteTokens !== undefined ? { cacheWriteTokens } : {}),
+        ...(costUsd !== undefined ? { costUsd } : {}),
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        ...(totalTokens !== undefined ? { totalTokens } : {}),
+    };
+    return Object.keys(usage).length > 0 ? usage : undefined;
+}
+
+// Last-writer-wins merge: a later usage_update field overrides an earlier one,
+// But a field absent from the new event keeps its prior value.
+function mergeUsage(prior: Usage | undefined, next: Usage): Usage {
+    return { ...prior, ...next };
+}
+
+function handleSessionUpdate(result: AcpStreamResult, update: Record<string, unknown>): void {
+    switch (update.sessionUpdate) {
+        case "agent_message_chunk": {
+            const content = asRecord(update.content);
+            if (content?.type === "text" && typeof content.text === "string") {
+                result.assistantText += content.text;
+            }
+            return;
+        }
+        case "tool_call":
+            handleToolCall(result.toolCalls, update);
+            return;
+        case "tool_call_update":
+            handleToolCallUpdate(result.toolCalls, update);
+            return;
+        case "usage_update": {
+            const parsed = parseUsage(update);
+            if (parsed !== undefined) {
+                result.usage = mergeUsage(result.usage, parsed);
+            }
+            return;
+        }
+        // Unknown sessionUpdate types (agent_thought_chunk, plan,
+        // Available_commands_update, …) are ignored by design.
+        default:
+            return;
+    }
+}
+
+export function reduceAcpStream(lines: Iterable<string>, onEvent?: (evt: unknown) => void): AcpStreamResult {
+    const result: AcpStreamResult = { assistantText: "", toolCalls: [] };
+
+    for (const line of lines) {
+        const evt = parseAcpLine(line);
+        if (evt === null) {
+            continue;
+        }
+        onEvent?.(evt);
+
+        const obj = asRecord(evt);
+        if (obj === undefined) {
+            continue;
+        }
+
+        if (obj.method === "session/update") {
+            const update = asRecord(asRecord(obj.params)?.update);
+            if (update !== undefined) {
+                handleSessionUpdate(result, update);
+            }
+            continue;
+        }
+
+        const resultField = asRecord(obj.result);
+        if (resultField !== undefined && typeof resultField.stopReason === "string") {
+            result.stopReason = resultField.stopReason;
+        }
+        if (resultField !== undefined) {
+            const resultUsage = parseUsage(resultField);
+            if (resultUsage !== undefined) {
+                result.usage = mergeUsage(result.usage, resultUsage);
+            }
+        }
+
+        const errorField = asRecord(obj.error);
+        if (errorField !== undefined && typeof errorField.message === "string") {
+            result.error = {
+                message: errorField.message,
+                ...(typeof errorField.code === "number" ? { code: errorField.code } : {}),
+            };
+        }
+    }
+
+    return result;
+}

package/src/agent/issuefence.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+
+export interface IssueFence {
+    body: string;
+    title?: string;
+    type?: string;
+    priority?: string;
+    labels?: string[];
+}
+
+const issueFenceSchema = z.object({
+    body: z.string(),
+    labels: z.array(z.string()).optional(),
+    priority: z.enum(["urgent", "high", "medium", "low", "none"]).optional(),
+    title: z.string().optional(),
+    type: z.string().optional(),
+});
+
+// Matches a fenced block whose info string is exactly `beflow-issue` (tolerating
+// trailing whitespace after it and CRLF line endings). The `g` flag lets us take
+// the LAST block — the agent's final word.
+const blockPattern = /```beflow-issue[^\S\r\n]*\r?\n([\s\S]*?)```/g;
+
+export function extractIssueFence(text: string): IssueFence | null {
+    let inner: string | null = null;
+    for (const match of text.matchAll(blockPattern)) {
+        inner = match[1] ?? null;
+    }
+    if (inner === null) {
+        return null;
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(inner);
+    } catch {
+        return null;
+    }
+
+    const result = issueFenceSchema.safeParse(parsed);
+    return result.success ? result.data : null;
+}

package/src/agent/report.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+
+export type ReportStatus = "done" | "needs_input" | "blocked" | "failed";
+
+export interface Report {
+    status: ReportStatus;
+    summary: string;
+    prUrl?: string;
+    questions?: string[];
+    notes?: string;
+}
+
+const reportSchema = z.object({
+    notes: z.string().optional(),
+    prUrl: z.string().optional(),
+    questions: z.array(z.string()).optional(),
+    status: z.enum(["done", "needs_input", "blocked", "failed"]),
+    summary: z.string(),
+});
+
+// Matches a fenced block whose info string is exactly `beflow-report`
+// (tolerating trailing whitespace after it and CRLF line endings). The `g`
+// Flag lets us take the LAST block — the agent's final word.
+const blockPattern = /```beflow-report[^\S\r\n]*\r?\n([\s\S]*?)```/g;
+
+export function extractReport(text: string): Report | null {
+    let inner: string | null = null;
+    for (const match of text.matchAll(blockPattern)) {
+        inner = match[1] ?? null;
+    }
+    if (inner === null) {
+        return null;
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(inner);
+    } catch {
+        return null;
+    }
+
+    const result = reportSchema.safeParse(parsed);
+    return result.success ? result.data : null;
+}