beflow 0.1.0

package/src/config/load.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { z } from "zod";
+
+import { configSchema, fileSchema, registrySchema } from "./schema.ts";
+import type { Config, ConfigFile, Registry } from "./schema.ts";
+
+function loadFile<T>(path: string, schema: z.ZodType<T, z.ZodTypeDef, unknown>): T {
+    let raw: string;
+    try {
+        raw = readFileSync(path, "utf8");
+    } catch {
+        throw new Error(`beflow: cannot read config file at ${path}`);
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`beflow: ${path} is not valid JSON: ${reason}`, { cause: err });
+    }
+
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
+        throw new Error(`beflow: ${path} failed validation:\n${issues}`);
+    }
+    return result.data;
+}
+
+function loadConfigFile(dir: string): ConfigFile {
+    return loadFile(join(dir, "config.json"), fileSchema);
+}
+
+export function loadConfig(dir: string = process.cwd()): Config {
+    const file = loadConfigFile(dir);
+    return configSchema.parse({ ...file, agents: file.agents ?? {} });
+}
+
+export function loadRegistry(dir: string = process.cwd()): Registry {
+    const file = loadConfigFile(dir);
+    return registrySchema.parse(file);
+}

package/src/config/persist.ts

@@ -0,0 +1,58 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { z } from "zod";
+
+import { fileSchema } from "./schema.ts";
+import type { Project } from "./schema.ts";
+
+export interface PersistDeps {
+    read?: (path: string) => string;
+    write?: (path: string, data: string) => void;
+}
+
+const projectsExtractSchema = z.object({ projects: z.record(z.string(), z.unknown()).optional() });
+
+export function addProject(dir: string, key: string, project: Project, deps?: PersistDeps): void {
+    const path = join(dir, "config.json");
+
+    function read(p: string): string {
+        return deps?.read ? deps.read(p) : readFileSync(p, "utf8");
+    }
+
+    function write(p: string, data: string): void {
+        if (deps?.write) {
+            deps.write(p, data);
+        } else {
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, data, "utf8");
+        }
+    }
+
+    const raw = read(path);
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`beflow: ${path} is not valid JSON: ${reason}`, { cause: err });
+    }
+
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`beflow: ${path} must be a JSON object`);
+    }
+
+    const { projects: existingProjects } = projectsExtractSchema.parse(parsed);
+
+    if (existingProjects?.[key] !== undefined) {
+        throw new Error(`beflow: project "${key}" already exists in config.json`);
+    }
+
+    const projects: Record<string, unknown> = { ...existingProjects, [key]: project };
+    const merged = Object.assign({}, parsed, { projects });
+
+    fileSchema.parse(merged);
+
+    write(path, `${JSON.stringify(merged, null, 2)}\n`);
+}

package/src/config/schema.ts

@@ -0,0 +1,181 @@
+import { z } from "zod";
+
+export const runModeSchema = z.enum(["autonomous", "supervised"]);
+export const jobKindSchema = z.enum(["triage", "spec", "implement"]);
+
+export const projectDefaultsSchema = z
+    .object({
+        agent: z.string().optional(),
+        runMode: runModeSchema.optional(),
+    })
+    .optional();
+
+export const routingSchema = z
+    .object({
+        implement: z.string().optional(),
+        spec: z.string().optional(),
+        triage: z.string().optional(),
+    })
+    .optional();
+
+export const projectSchema = z.object({
+    default_repo: z.string(),
+    defaults: projectDefaultsSchema,
+    ci: z.object({ autoReworkOnRed: z.boolean().optional() }).optional(),
+    deadLetter: z.object({ maxAttempts: z.number().optional() }).optional(),
+    inputQuality: z.object({ minBodyChars: z.number().optional() }).optional(),
+    limits: z
+        .object({
+            inReview: z.number().optional(),
+            inProgress: z.number().optional(),
+            maxRunMinutes: z.number().optional(),
+        })
+        .optional(),
+    module_repo_map: z.record(z.string(), z.string()),
+    name: z.string(),
+    plane_project_id: z.string().optional(),
+    qualityGate: z.object({ commands: z.array(z.string()).optional() }).optional(),
+    repos: z.record(z.string(), z.string()),
+    review: z.object({ enabled: z.boolean().optional(), postToPr: z.boolean().optional() }).optional(),
+    root: z.string(),
+    routing: routingSchema,
+    scheduling: z.object({ activeCycleOnly: z.boolean().optional() }).optional(),
+    sla: z.object({ inReviewMinutes: z.number().optional(), needsInputMinutes: z.number().optional() }).optional(),
+    telemetry: z.object({ inComment: z.boolean().optional() }).optional(),
+});
+
+export type Project = z.infer<typeof projectSchema>;
+
+export const agentConfigSchema = z.object({
+    // Interactive CLI binary used by the `--open` direct spawn. REQUIRED.
+    command: z.string(),
+    // Extra args appended to the `--open` direct spawn (before the task).
+    args: z.array(z.string()).optional(),
+    // ACP-server binary used by acpx `--auto`/`--attend`; defaults to `command`.
+    acpCommand: z.string().optional(),
+    // Args for the ACP server; beflow passes acpx
+    // `--agent "<acpCommand ?? command> <acpArgs...>"` for --auto/--attend.
+    acpArgs: z.array(z.string()).optional(),
+    // Acpx `--model` for `--auto`/`--attend`.
+    model: z.string().optional(),
+    permissionPolicy: z.unknown().optional(),
+});
+
+export type AgentConfig = z.infer<typeof agentConfigSchema>;
+
+export const agentsMapSchema = z.record(z.string(), agentConfigSchema);
+
+export const workspaceSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+});
+
+// The single on-disk shape of config.json: tracker settings + registry
+// (workspace + projects) + the per-agent map, all in one file.
+export const fileSchema = z.object({
+    $schema: z.string().optional(),
+    _comment: z.string().optional(),
+    tracker: z.enum(["plane", "linear"]),
+    trackers: z.object({
+        linear: z
+            .object({
+                apiKeyEnv: z.string(),
+            })
+            .optional(),
+        plane: z
+            .object({
+                baseUrl: z.string(),
+                workspaceSlug: z.string(),
+                apiKeyEnv: z.string(),
+            })
+            .optional(),
+    }),
+    defaults: z.object({
+        agent: z.string(),
+        runMode: runModeSchema,
+        // Optional tracker user id; when set, beflow assigns the issue to this user
+        // As it picks it up (moves it to In Progress), for both --auto and --attend.
+        assignee: z.string().optional(),
+        // Unified dead-letter cap: how many accumulated failed attempts (across crash
+        // Resume + CI rework) before beflow quarantines the item to Needs Input.
+        // Per-project `projects.<KEY>.deadLetter` overrides this global; default 3.
+        deadLetter: z.object({ maxAttempts: z.number().optional() }).optional(),
+        // Opt-in input-quality gate. When `minBodyChars` > 0, a fresh autonomous
+        // Dispatch of a too-thin issue is parked to Needs Input instead of burning an
+        // Agent run. Per-project `projects.<KEY>.inputQuality` overrides this global.
+        inputQuality: z.object({ minBodyChars: z.number().optional() }).optional(),
+        // Inline parent-epic + attachment context into the agent task. Default on; set false to disable.
+        linkedContext: z.boolean().optional(),
+        // How beflow reacts when a human moves a card out of beflow's hands (out of
+        // The started group) while a run is live. `yield` lets the run finish but
+        // Skips writeback so the human's move stands; `abort` additionally cancels
+        // The agent mid-run. Always present after parse thanks to the default.
+        onManualMove: z.enum(["yield", "abort"]).default("yield"),
+        // Opt-in quality gate: project check command(s) run in the worktree before an
+        // Implement `done` report opens a PR / advances to In Review. On RED beflow
+        // Auto-reworks the live agent session once, then re-checks; still-red is failed.
+        // Per-project `projects.<KEY>.qualityGate` overrides this global.
+        qualityGate: z.object({ commands: z.array(z.string()).optional() }).optional(),
+        // Opt-in PR review assist. When `enabled`, watch dispatches a reviewer agent over
+        // In-Review items and posts its findings as an issue comment; `postToPr` also posts
+        // Them on the PR. Per-project `projects.<KEY>.review` overrides this global.
+        review: z.object({ enabled: z.boolean().optional(), postToPr: z.boolean().optional() }).optional(),
+        // Opt-in agent routing by jobkind. Keys are jobkind names; values are agent names
+        // From config.agents. Per-project `projects.<KEY>.routing` overrides this global.
+        routing: routingSchema,
+        // Opt-in SLA aging: minutes an item may sit in Needs Input / In Review before
+        // Beflow re-pings the escalation channel. Per-project `projects.<KEY>.sla`
+        // Overrides this global.
+        sla: z.object({ inReviewMinutes: z.number().optional(), needsInputMinutes: z.number().optional() }).optional(),
+        // Opt-in run telemetry: when `inComment`, beflow appends a compact token/cost
+        // Line to its writeback comment on the issue. Default off. Per-project
+        // `projects.<KEY>.telemetry` overrides this global.
+        telemetry: z.object({ inComment: z.boolean().optional() }).optional(),
+    }),
+    // Where `--auto` runs create their per-issue git worktrees. `~` expands to the
+    // Home dir; defaults to ~/.beflow/worktrees (outside any repo).
+    worktrees: z
+        .object({
+            dir: z.string(),
+        })
+        .optional(),
+    // When enabled, beflow reads a user `.mcp.json` cascade and injects the
+    // Translated servers as a managed `.acpxrc.json` into the agent cwd for
+    // Acpx-driven runs (`--auto`/`watch`/`--attend`). Disabled by default.
+    mcp: z.object({ enabled: z.boolean().default(false) }).optional(),
+    // Where `--auto` runs persist their per-issue run-records so an interrupted
+    // Run can resume. `~` expands to home; defaults to ~/.beflow/runs.
+    runs: z.object({ dir: z.string() }).optional(),
+    // External tool launchers. `acpx` is the command array beflow spawns to run
+    // Acpx (command + leading args); defaults to `["bunx", "acpx"]` (bun-first).
+    tools: z.object({ acpx: z.array(z.string()).optional() }).optional(),
+    // Directory of user-editable prompt templates that override the compiled-in
+    // Defaults. `~` expands to home; each `<name>.md` overrides that prompt.
+    prompts: z.object({ dir: z.string() }).optional(),
+    workspace: workspaceSchema,
+    projects: z.record(z.string(), projectSchema),
+    agents: agentsMapSchema.optional(),
+});
+
+export type ConfigFile = z.infer<typeof fileSchema>;
+
+// The Config slice consumed by tracker/run/doctor code. `agents` is always
+// Present (loaders default it to {}), so downstream may read config.agents
+// Without an undefined guard.
+export const configSchema = fileSchema
+    .omit({
+        _comment: true,
+        projects: true,
+        workspace: true,
+    })
+    .extend({ agents: agentsMapSchema });
+
+export type Config = z.infer<typeof configSchema>;
+
+// The Registry slice: workspace + projects.
+export const registrySchema = z.object({
+    projects: z.record(z.string(), projectSchema),
+    workspace: workspaceSchema,
+});
+
+export type Registry = z.infer<typeof registrySchema>;

package/src/config/store.ts

@@ -0,0 +1,119 @@
+import { watch as fsWatch } from "node:fs";
+import { join } from "node:path";
+
+import { loadConfig, loadRegistry } from "./load.ts";
+import type { Config, Registry } from "./schema.ts";
+
+export interface ConfigSnapshot {
+    config: Config;
+    registry: Registry;
+}
+
+// Injectable file-watcher seam so ConfigStore is testable without real fs.
+export interface ConfigWatcher {
+    // Returns an unwatch fn that stops the watcher.
+    watch(filePath: string, onChange: () => void): () => void;
+}
+
+const WATCH_DEBOUNCE_MS = 100;
+
+export const nodeConfigWatcher: ConfigWatcher = {
+    watch(filePath, onChange) {
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const watcher = fsWatch(filePath, () => {
+            // Editors fire multiple events per save; debounce to a single reload.
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            timer = setTimeout(onChange, WATCH_DEBOUNCE_MS);
+        });
+        return () => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            watcher.close();
+        };
+    },
+};
+
+export interface ConfigStoreOpts {
+    log?: (m: string) => void;
+    loadConfig?: (dir: string) => Config;
+    loadRegistry?: (dir: string) => Registry;
+    watcher?: ConfigWatcher;
+}
+
+export class ConfigStore {
+    private readonly dir: string;
+    private readonly log: (m: string) => void;
+    private readonly loadConfig: (dir: string) => Config;
+    private readonly loadRegistry: (dir: string) => Registry;
+    private readonly watcher: ConfigWatcher;
+    private snapshot: ConfigSnapshot | undefined;
+    private unwatch: (() => void) | undefined;
+
+    public constructor(dir: string, opts: ConfigStoreOpts = {}) {
+        this.dir = dir;
+        this.log =
+            opts.log ??
+            ((): void => {
+                /* no-op: logging disabled */
+            });
+        this.loadConfig = opts.loadConfig ?? loadConfig;
+        this.loadRegistry = opts.loadRegistry ?? loadRegistry;
+        this.watcher = opts.watcher ?? nodeConfigWatcher;
+    }
+
+    // Eager initial load; a failure here is fatal (the app cannot start without
+    // A valid config) so it rethrows.
+    public init(): void {
+        this.snapshot = this.read();
+    }
+
+    public get(): ConfigSnapshot {
+        if (this.snapshot === undefined) {
+            throw new Error("beflow: ConfigStore.get() called before init()");
+        }
+        return this.snapshot;
+    }
+
+    // Re-run the loaders; validate-before-swap. Never throws: a bad save keeps
+    // The last-good snapshot and logs a warning.
+    public reload(): void {
+        let next: ConfigSnapshot;
+        try {
+            next = this.read();
+        } catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.log(`beflow: config reload failed: ${reason}; keeping previous config`);
+            return;
+        }
+        this.snapshot = next;
+        this.log("beflow: config reloaded");
+    }
+
+    public start(): void {
+        if (this.unwatch !== undefined) {
+            return;
+        }
+        const filePath = join(this.dir, "config.json");
+        this.unwatch = this.watcher.watch(filePath, () => {
+            this.reload();
+        });
+    }
+
+    public stop(): void {
+        if (this.unwatch === undefined) {
+            return;
+        }
+        this.unwatch();
+        this.unwatch = undefined;
+    }
+
+    private read(): ConfigSnapshot {
+        return {
+            config: this.loadConfig(this.dir),
+            registry: this.loadRegistry(this.dir),
+        };
+    }
+}

package/src/core/accept.ts

@@ -0,0 +1,25 @@
+import type { IntakeItem, Tracker } from "../trackers/tracker.ts";
+import type { Logger } from "./run.ts";
+
+export interface AcceptDeps {
+    tracker: Tracker;
+    log?: Logger;
+}
+
+export async function acceptIntake(projectKey: string, intakeId: string, deps: AcceptDeps): Promise<IntakeItem> {
+    const log =
+        deps.log ??
+        ((): void => {
+            /* no-op: logging disabled */
+        });
+    const inbox = await deps.tracker.listInbox(projectKey);
+    const item = inbox.find((i) => i.id === intakeId);
+    if (item === undefined) {
+        const available = inbox.map((i) => i.id).join(", ");
+        throw new Error(`beflow: unknown intake id "${intakeId}" in ${projectKey} (available: ${available})`);
+    }
+
+    await deps.tracker.acceptInbox(projectKey, item);
+    log(`beflow: accepted intake ${intakeId} ("${item.title}") in ${projectKey}`);
+    return item;
+}

package/src/core/continuation.ts

@@ -0,0 +1,57 @@
+import type { Report } from "../agent/report.ts";
+import type { Issue } from "../model/types.ts";
+import type { Comment, Tracker } from "../trackers/tracker.ts";
+import type { PromptSet } from "./prompts.ts";
+import { renderTemplate } from "./prompts.ts";
+import type { RunRecord } from "./runstore.ts";
+
+export interface ContinuationContext {
+    newComments: Comment[];
+    prUrl?: string;
+    priorReport?: Report;
+}
+
+export interface AssembleOptions {
+    since?: string;
+    record?: RunRecord | null;
+}
+
+export async function assembleContinuation(
+    tracker: Tracker,
+    issue: Issue,
+    opts: AssembleOptions = {},
+): Promise<ContinuationContext> {
+    const all = await tracker.listComments(issue);
+
+    const newComments = all.filter((c) => {
+        if (c.isBot) {
+            return false;
+        }
+        if (opts.since !== undefined) {
+            if (!c.createdAt) {
+                return false;
+            }
+            return c.createdAt > opts.since;
+        }
+        return true;
+    });
+
+    return {
+        newComments,
+        ...(opts.record?.prUrl !== undefined ? { prUrl: opts.record.prUrl } : {}),
+        ...(opts.record?.report !== undefined ? { priorReport: opts.record.report } : {}),
+    };
+}
+
+export function renderContinuation(prompts: PromptSet, ctx: ContinuationContext): string {
+    const priorReport =
+        ctx.priorReport !== undefined ? `${ctx.priorReport.status} — ${ctx.priorReport.summary}` : "(none)";
+    const prUrl = ctx.prUrl ?? "(none)";
+    const reviewComments =
+        ctx.newComments.length > 0 ? ctx.newComments.map((c) => `- ${c.body}`).join("\n") : "No new comments.";
+    return renderTemplate("continuation", prompts.continuation, {
+        pr_url: prUrl,
+        prior_report: priorReport,
+        review_comments: reviewComments,
+    });
+}

package/src/core/deadletter.ts

@@ -0,0 +1,55 @@
+import type { Config, Registry } from "../config/schema.ts";
+import type { Issue } from "../model/types.ts";
+import type { Tracker } from "../trackers/tracker.ts";
+import { notifyEscalation } from "./notify.ts";
+import type { Notifier } from "./notify.ts";
+import type { Clock, RunRecord, RunStoreFs } from "./runstore.ts";
+import { saveRecord } from "./runstore.ts";
+
+export const QUARANTINED_LABEL = "quarantined";
+
+const NEEDS_INPUT_STATE = "Needs Input";
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+/** Universal failure cap: quarantine once the accumulated attempt count reaches the threshold. */
+export function shouldQuarantine(attempts: number, threshold: number): boolean {
+    return attempts >= threshold;
+}
+
+/** Project-over-default-over-3 resolution of the unified dead-letter threshold. */
+export function resolveDeadLetterThreshold(config: Config, registry: Registry, projectKey: string): number {
+    const projectMax = registry.projects[projectKey]?.deadLetter?.maxAttempts;
+    const globalMax = config.defaults.deadLetter?.maxAttempts;
+    return projectMax ?? globalMax ?? DEFAULT_MAX_ATTEMPTS;
+}
+
+export interface QuarantineDeps {
+    clock: Clock;
+    notify?: Notifier;
+    record: RunRecord;
+    runsDir: string;
+    runsFs?: RunStoreFs;
+    tracker: Tracker;
+}
+
+/**
+ * Shared dead-letter: label the issue `quarantined`, park it in Needs Input, notify the
+ * Escalation channel, and persist the run record as a quarantine hold. Degrade-safe — a
+ * Tracker/notify failure must not throw out and halt the watch tick.
+ */
+export async function quarantine(issue: Issue, detail: string, deps: QuarantineDeps): Promise<void> {
+    try {
+        await deps.tracker.addProperty(issue, QUARANTINED_LABEL);
+        await deps.tracker.updateState(issue, NEEDS_INPUT_STATE);
+        await deps.tracker.comment(issue, detail);
+        await notifyEscalation(deps.notify, issue, "failed", detail);
+    } catch {
+        // Best-effort escalation: a transient tracker/notify error must not crash the tick.
+    }
+    saveRecord(
+        deps.runsDir,
+        { ...deps.record, heldReason: "quarantine", status: "failed", updatedAt: deps.clock() },
+        deps.runsFs,
+    );
+}

package/src/core/decision.ts

@@ -0,0 +1,8 @@
+export const NEEDS_DECISION_LABEL = "needs-decision";
+
+export const DECISION_HOLD_MESSAGE =
+    "This work item is held for a human decision (it carries the `needs-decision` label). Make the call and REMOVE the `needs-decision` label — beflow will then release it back to Todo and proceed. (Leave the rationale as a comment if useful.)";
+
+export function isDecisionHeld(labels: string[]): boolean {
+    return labels.includes(NEEDS_DECISION_LABEL);
+}