ai-foreman 1.0.0 → 1.0.2

package/dist/adapters/claude.d.ts

@@ -0,0 +1,34 @@
+/** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
+export declare function requireClaudeSDK(): Promise<typeof import("@anthropic-ai/claude-agent-sdk")>;
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, TurnResult } from "./types.js";
+/**
+ * Pure function: build the `options` object passed to `query()`.
+ * Extracted so tests can assert on the shape without making a live SDK call.
+ * `canUseTool` is omitted here — it's a closure that the constructor adds.
+ */
+export declare function buildClaudeQueryOptions(opts: Omit<BuilderAdapterOptions, "permission">): Record<string, unknown>;
+/**
+ * Drives Claude Code through the Claude Agent SDK in streaming-input mode:
+ * one persistent session, follow-up turns pushed as user messages, permission
+ * requests routed to the foreman's handler via `canUseTool`.
+ */
+export declare class ClaudeAdapter implements BuilderAdapter {
+    readonly agent: "claude";
+    private readonly inbox;
+    private readonly eventQueue;
+    private readonly query;
+    private readonly abort;
+    private readonly pumpDone;
+    private _sessionId?;
+    private pending?;
+    private closed;
+    static create(opts: BuilderAdapterOptions): Promise<ClaudeAdapter>;
+    private constructor();
+    /** Background loop: consume the SDK message stream until it ends. */
+    private pump;
+    private handle;
+    sendTurn(text: string): Promise<TurnResult>;
+    sessionId(): string | undefined;
+    events(): AsyncIterable<BuilderEvent>;
+    close(): Promise<void>;
+}

package/dist/adapters/claude.js

@@ -1,4 +1,15 @@
-import { query } from "@anthropic-ai/claude-agent-sdk";
+/** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
+export async function requireClaudeSDK() {
+    try {
+        return await import("@anthropic-ai/claude-agent-sdk");
+    }
+    catch {
+        throw new Error("Claude Agent SDK not installed.\n" +
+            "To use Claude Code as your agent runtime, run:\n" +
+            "  npm install @anthropic-ai/claude-agent-sdk\n" +
+            "Or use Codex only: ai-foreman start --agent codex");
+    }
+}
 import { AsyncQueue } from "../util/asyncQueue.js";
 /**
  * Pure function: build the `options` object passed to `query()`.
@@ -38,7 +49,12 @@ export class ClaudeAdapter {
     _sessionId;
     pending;
     closed = false;
-    constructor(opts) {
+    static async create(opts) {
+        const { query } = await requireClaudeSDK();
+        return new ClaudeAdapter(opts, query);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(opts, query) {
         this.query = query({
             prompt: this.inbox,
             options: {

package/dist/adapters/codex.d.ts

@@ -0,0 +1,46 @@
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, TurnResult } from "./types.js";
+/** Result of parsing one JSONL line from `codex exec --json` output. */
+export interface CodexLineResult {
+    /** Events to emit to the BuilderEvent stream. */
+    events: BuilderEvent[];
+    /** If set, update the stored session ID to this value. */
+    sessionId?: string;
+    /** If set, append this to the turn's accumulated text. */
+    text?: string;
+}
+/**
+ * Pure function: parse one JSONL event from `codex exec --json` output into
+ * structured actions. Exported for unit testing; production code calls this
+ * via handleEvent().
+ */
+export declare function parseCodexLine(raw: Record<string, unknown>): CodexLineResult;
+/**
+ * Drives Codex CLI as a subprocess. Each sendTurn() spawns `codex exec --json`
+ * and reads JSONL from stdout. Session continuity is maintained via the
+ * thread_id captured from the first run and passed as `resume <id>` on
+ * subsequent turns.
+ *
+ * NOTE: opts.permission is accepted for interface conformance but is not
+ * invoked. Codex manages its own tool sandboxing via --sandbox workspace-write.
+ */
+export declare class CodexAdapter implements BuilderAdapter {
+    private readonly opts;
+    readonly agent: "codex";
+    private readonly eventQueue;
+    private _sessionId?;
+    private _closed;
+    private _activeProc?;
+    constructor(opts: BuilderAdapterOptions);
+    /**
+     * Prepend role system text to a turn instruction when `systemPromptAppend` is
+     * set. Codex reads everything from the prompt (no persistent system prompt), so
+     * role guidance must ride along with each turn.
+     */
+    buildInstruction(instruction: string): string;
+    /** Build the `codex exec` argument list for the given instruction. */
+    buildArgs(instruction: string): string[];
+    sendTurn(instruction: string): Promise<TurnResult>;
+    sessionId(): string | undefined;
+    events(): AsyncIterable<BuilderEvent>;
+    close(): Promise<void>;
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Agent-agnostic interface over a coding agent ("builder").
+ */
+/** A permission request surfaced by a builder before it runs a tool. */
+export interface PermissionRequest {
+    toolName: string;
+    input: Record<string, unknown>;
+    /** Human-readable prompt from the agent, when available. */
+    title?: string;
+}
+/** The foreman's verdict on a permission request. */
+export type PermissionDecision = {
+    behavior: "allow";
+} | {
+    behavior: "deny";
+    message: string;
+};
+/** Decides each permission request. Supplied by the foreman, called by the adapter. */
+export type PermissionHandler = (req: PermissionRequest) => Promise<PermissionDecision>;
+/** Result of a single completed turn. */
+export interface TurnResult {
+    /** Final assistant message text — where the STEP_STATUS marker lives. */
+    text: string;
+    isError: boolean;
+    numTurns: number;
+    costUsd: number;
+}
+/** Observability events emitted while a builder works. */
+export type BuilderEvent = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "tool";
+    name: string;
+    input: unknown;
+} | {
+    kind: "turn-complete";
+    result: TurnResult;
+} | {
+    kind: "error";
+    message: string;
+};
+export type EffortLevel = "low" | "medium" | "high" | "xhigh";
+export interface BuilderAdapterOptions {
+    /** Working directory the builder operates in. */
+    cwd: string;
+    /** Permission decision callback. */
+    permission: PermissionHandler;
+    /** Resume a prior session instead of starting fresh. */
+    resumeSessionId?: string;
+    /** Override the model; omit for the agent's default. */
+    model?: string;
+    /** Reasoning effort level. Claude also accepts "max"; Codex supports up to "xhigh". */
+    effort?: EffortLevel;
+    /** Fast mode: lower latency at the cost of some quality. */
+    fast?: boolean;
+    /** Role system text to append to the harness system prompt (from .rafi/compiled or library). */
+    systemPromptAppend?: string;
+    /** Skill names to preload for this session (Claude: lazy-loaded; Codex: flattened). */
+    skills?: string[];
+}
+export interface BuilderAdapter {
+    readonly agent: "claude" | "codex";
+    /** Send one instruction; resolves when that turn completes. */
+    sendTurn(text: string): Promise<TurnResult>;
+    /** Current session id, once known — used for resume. */
+    sessionId(): string | undefined;
+    /** Stream of observability events. Iterate to drive a live view. */
+    events(): AsyncIterable<BuilderEvent>;
+    /** Shut the builder down and release resources. */
+    close(): Promise<void>;
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function buildDoctorCommand(): Command;

package/dist/cli/doctor.js

@@ -0,0 +1,71 @@
+import { Command } from "commander";
+import { resolve, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { loadConfig } from "../config.js";
+import { isTicketsInitialized } from "../tickets/config.js";
+import { cmdValidate } from "../tickets/commands.js";
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))?.version;
+function commandVersion(command) {
+    const result = spawnSync(command, ["--version"], {
+        encoding: "utf8",
+        timeout: 3000,
+    });
+    if (result.error)
+        return { ok: false, detail: result.error.message };
+    if (result.status !== 0)
+        return { ok: false, detail: result.stderr.trim() };
+    return { ok: true, detail: (result.stdout.trim() || result.stderr.trim()).slice(0, 120) };
+}
+export function buildDoctorCommand() {
+    return new Command("doctor")
+        .description("Check Foreman, agent CLIs, config, and optional ticket tracker readiness.")
+        .argument("[project]", "path to the project directory", ".")
+        .action((project) => {
+        const cwd = resolve(project);
+        let errors = 0;
+        const report = (ok, label, detail) => {
+            console.log(`${ok ? "ok" : "!!"} ${label}${detail ? ` — ${detail}` : ""}`);
+            if (!ok)
+                errors++;
+        };
+        const warn = (label, detail) => {
+            console.log(`-- ${label}${detail ? ` — ${detail}` : ""}`);
+        };
+        report(Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10) >= 20, "node >=20", process.version);
+        report(Boolean(PACKAGE_VERSION), "foreman package version", PACKAGE_VERSION);
+        report(existsSync(cwd), "project directory exists", cwd);
+        if (!existsSync(cwd))
+            process.exit(1);
+        try {
+            loadConfig(join(cwd, "foreman.yaml"));
+            report(true, "foreman.yaml", existsSync(join(cwd, "foreman.yaml")) ? "valid" : "not present, using defaults");
+        }
+        catch (err) {
+            report(false, "foreman.yaml", err instanceof Error ? err.message : String(err));
+        }
+        const claude = commandVersion("claude");
+        if (claude.ok)
+            warn("claude CLI found", claude.detail);
+        else
+            warn("claude CLI not found", "Claude adapter may still work through the SDK if credentials are configured");
+        const codex = commandVersion("codex");
+        if (codex.ok)
+            warn("codex CLI found", codex.detail);
+        else
+            warn("codex CLI not found", "required only for --agent codex");
+        if (isTicketsInitialized(cwd)) {
+            try {
+                const result = cmdValidate(cwd);
+                report(result.clean, ".tickets validation", result.clean ? "clean" : `${result.issues.length} issue(s)`);
+            }
+            catch (err) {
+                report(false, ".tickets validation", err instanceof Error ? err.message : String(err));
+            }
+        }
+        else {
+            warn(".tickets", "not initialized; start will run in plain mode");
+        }
+        process.exit(errors === 0 ? 0 : 1);
+    });
+}

package/dist/cli/events.d.ts

@@ -0,0 +1,3 @@
+import type { BuilderEvent } from "../adapters/types.js";
+/** Print a compact live feed of builder activity. */
+export declare function printEvents(events: AsyncIterable<BuilderEvent>): Promise<void>;

package/dist/cli/start.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function buildStartCommand(): Command;

package/dist/cli/start.js

@@ -0,0 +1,181 @@
+import { Command } from "commander";
+import { resolve, join, relative } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { select, text, isCancel } from "@clack/prompts";
+import { loadConfig } from "../config.js";
+import { Log } from "../log.js";
+import { PermissionPolicy } from "../permissions/policy.js";
+import { ClaudeAdapter } from "../adapters/claude.js";
+import { CodexAdapter } from "../adapters/codex.js";
+import { Foreman, createPermissionHandler } from "../foreman.js";
+import { printEvents } from "./events.js";
+import { loadRoleBundle } from "../roles.js";
+function fail(message) {
+    console.error(`foreman: ${message}`);
+    process.exit(1);
+}
+function findLastSessionId(dir) {
+    if (!existsSync(dir))
+        return undefined;
+    const logs = readdirSync(dir).filter((f) => f.endsWith(".jsonl")).sort();
+    if (logs.length === 0)
+        return undefined;
+    const lines = readFileSync(join(dir, logs[logs.length - 1]), "utf8")
+        .split("\n")
+        .filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const r = JSON.parse(lines[i]);
+        if (r.event === "batch-end" && typeof r.sessionId === "string") {
+            return r.sessionId;
+        }
+    }
+    return undefined;
+}
+export function buildStartCommand() {
+    return new Command("start")
+        .description("Enlist a builder and drive it through a batch of N steps.")
+        .argument("<project>", "path to the project directory the builder works in")
+        .requiredOption("-s, --steps <n>", "number of steps to drive")
+        .option("-a, --agent <agent>", "builder agent (claude | codex)", "claude")
+        .option("-m, --model <model>", "override the builder's model")
+        .option("-r, --resume <sessionId>", "resume a prior builder session")
+        .option("--continue", "resume the most recent logged session for this project")
+        .option("-t, --tickets <path>", "path to ticket file (.md, .txt, .yaml, …) — passed to the builder as context")
+        .option("-y, --yes", "skip pre-flight confirmation prompt")
+        .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
+        .option("--fast", "fast mode — lower latency (maps to effort=low for codex)")
+        .option("--no-qa", "disable per-ticket QA review (enabled by default)")
+        .action(async (project, opts) => {
+        const steps = Number.parseInt(opts.steps, 10);
+        if (!Number.isInteger(steps) || steps < 1) {
+            fail("--steps must be a positive integer");
+        }
+        const VALID_AGENTS = ["claude", "codex"];
+        if (!VALID_AGENTS.includes(opts.agent)) {
+            fail(`unknown agent "${opts.agent}" — choose: ${VALID_AGENTS.join(" | ")}`);
+        }
+        const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
+        if (opts.effort && !VALID_EFFORT.includes(opts.effort)) {
+            fail(`unknown effort "${opts.effort}" — choose: ${VALID_EFFORT.join(" | ")}`);
+        }
+        const cwd = resolve(project);
+        if (!existsSync(cwd))
+            fail(`project directory not found: ${cwd}`);
+        const TRACKER_SEARCH_PATHS = ["docs/ticket-progress.md", "ticket-progress.md"];
+        let ticketsContent;
+        let trackerRelPath;
+        if (opts.tickets) {
+            const ticketPath = resolve(opts.tickets);
+            if (!existsSync(ticketPath))
+                fail(`ticket file not found: ${ticketPath}`);
+            ticketsContent = readFileSync(ticketPath, "utf8");
+            trackerRelPath = relative(cwd, ticketPath);
+        }
+        else {
+            for (const rel of TRACKER_SEARCH_PATHS) {
+                const abs = join(cwd, rel);
+                if (existsSync(abs)) {
+                    ticketsContent = readFileSync(abs, "utf8");
+                    trackerRelPath = rel;
+                    break;
+                }
+            }
+        }
+        if (opts.resume && opts.continue) {
+            fail("choose either --resume <sessionId> or --continue, not both");
+        }
+        const resumeSessionId = opts.resume ??
+            (opts.continue ? findLastSessionId(join(cwd, ".foreman")) : undefined);
+        if (opts.continue && !resumeSessionId) {
+            fail(`no previous session id found under ${join(cwd, ".foreman")}`);
+        }
+        const config = loadConfig(join(cwd, "foreman.yaml"));
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
+        const log = new Log(logPath);
+        const policy = new PermissionPolicy(config.permissions, cwd);
+        const roleBundle = loadRoleBundle("builder", { projectDir: cwd });
+        const adapterOpts = {
+            cwd,
+            model: opts.model,
+            resumeSessionId,
+            permission: createPermissionHandler(policy, log),
+            effort: opts.effort,
+            fast: opts.fast,
+            systemPromptAppend: roleBundle.system || undefined,
+            skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
+        };
+        const builder = opts.agent === "codex"
+            ? new CodexAdapter(adapterOpts)
+            : await ClaudeAdapter.create(adapterOpts);
+        const qaEnabled = opts.qa !== false && config.qa.enabled !== false;
+        const foreman = new Foreman(builder, log, config.notifications.enabled, qaEnabled, 3, cwd);
+        const modifiers = [
+            opts.model ? `model=${opts.model}` : null,
+            opts.effort ? `effort=${opts.effort}` : null,
+            opts.fast ? "fast" : null,
+            qaEnabled ? null : "qa=off",
+        ].filter(Boolean).join(" ");
+        console.log(`foreman: driving a ${opts.agent} builder through ${steps} step(s)${modifiers ? ` [${modifiers}]` : ""}`);
+        console.log(`foreman: project ${cwd}`);
+        if (trackerRelPath)
+            console.log(`foreman: tracker ${trackerRelPath}`);
+        console.log(`foreman: log ${logPath}\n`);
+        const viewer = printEvents(builder.events());
+        try {
+            console.log("ai-foreman: asking builder to plan the next tickets or steps...\n");
+            await foreman.runPreflight(steps, ticketsContent);
+            if (!opts.yes) {
+                while (true) {
+                    console.log();
+                    const action = await select({
+                        message: "How does this plan look?",
+                        options: [
+                            { value: "proceed", label: "Proceed — start implementing" },
+                            { value: "feedback", label: "Give feedback — revise the plan" },
+                            { value: "cancel", label: "Cancel" },
+                        ],
+                    });
+                    if (isCancel(action) || action === "cancel") {
+                        console.log("ai-foreman: cancelled");
+                        await builder.close();
+                        await viewer;
+                        process.exit(0);
+                    }
+                    if (action === "proceed") {
+                        console.log();
+                        break;
+                    }
+                    const fb = await text({
+                        message: "Your feedback:",
+                        validate: (v) => (v?.trim() ? undefined : "Please enter some feedback"),
+                    });
+                    if (isCancel(fb)) {
+                        console.log("ai-foreman: cancelled");
+                        await builder.close();
+                        await viewer;
+                        process.exit(0);
+                    }
+                    console.log();
+                    await foreman.sendPreflightFeedback(String(fb));
+                }
+            }
+            const result = await foreman.runBatch(steps, trackerRelPath);
+            await builder.close();
+            await viewer;
+            console.log(`\nforeman: ${result.completed}/${result.requested} step(s) completed`);
+            console.log(`foreman: outcome — ${result.outcome}`);
+            if (result.detail)
+                console.log(`foreman: ${result.detail}`);
+            const sid = builder.sessionId();
+            if (sid)
+                console.log(`foreman: resume this builder with  --resume ${sid}`);
+            process.exit(result.outcome === "needs-human" ? 2 : 0);
+        }
+        catch (err) {
+            await builder.close().catch(() => { });
+            log.write("error", { message: String(err) });
+            fail(`run failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}

package/dist/cli/status.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function buildStatusCommand(): Command;

package/dist/cli/status.js

@@ -0,0 +1,43 @@
+import { Command } from "commander";
+import { resolve, join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+function fail(message) {
+    console.error(`foreman: ${message}`);
+    process.exit(1);
+}
+export function buildStatusCommand() {
+    return new Command("status")
+        .description("Summarize the most recent foreman run for a project.")
+        .argument("<project>", "path to the project directory")
+        .action((project) => {
+        const dir = join(resolve(project), ".foreman");
+        if (!existsSync(dir))
+            fail(`no foreman runs found under ${dir}`);
+        const logs = readdirSync(dir)
+            .filter((f) => f.endsWith(".jsonl"))
+            .sort();
+        if (logs.length === 0)
+            fail(`no foreman runs found under ${dir}`);
+        const latest = join(dir, logs[logs.length - 1]);
+        const records = readFileSync(latest, "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+        const steps = records.filter((r) => r.event === "step");
+        const escalations = records.filter((r) => r.event === "escalation");
+        const batchEnd = records.reverse().find((r) => r.event === "batch-end");
+        console.log(`foreman: latest run ${logs[logs.length - 1]}`);
+        console.log(`foreman: ${steps.length} step record(s), ${escalations.length} escalation(s)`);
+        if (batchEnd) {
+            console.log(`foreman: outcome — ${batchEnd.outcome} (${batchEnd.completed}/${batchEnd.requested})`);
+            if (batchEnd.detail)
+                console.log(`foreman: ${batchEnd.detail}`);
+        }
+        else {
+            console.log("ai-foreman: run is still in progress or did not finish");
+        }
+        for (const esc of escalations) {
+            console.log(`  escalated: ${esc.tool} — ${esc.reason}`);
+        }
+    });
+}

package/dist/cli/tickets.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function buildPopulateInstruction(): string;
+export declare function buildTicketsCommand(): Command;

package/dist/cli/tickets.js

@@ -144,7 +144,7 @@ export function buildTicketsCommand() {
         };
         const builder = agent === "codex"
             ? new CodexAdapter(adapterOpts)
-            : new ClaudeAdapter(adapterOpts);
+            : await ClaudeAdapter.create(adapterOpts);
         const viewer = printEvents(builder.events());
         const foreman = new Foreman(builder, log, config.notifications.enabled, false, 3, dir);
         console.log(`foreman tickets: populating tickets with ${agent}`);

package/dist/config.d.ts

@@ -0,0 +1,27 @@
+export interface PermissionConfig {
+    /** Bash command prefixes that are auto-approved when every segment matches. */
+    allowBash: string[];
+    /** Bash command substrings that always escalate (checked first). */
+    escalateBash: string[];
+    /** Tool names auto-approved when their target stays inside the worktree. */
+    allowTools: string[];
+    /** Tool names that always escalate. */
+    escalateTools: string[];
+}
+export interface NotificationsConfig {
+    /** Fire a desktop notification when the builder needs user input. Default: false. */
+    enabled: boolean;
+}
+export interface QaConfig {
+    /** Run a QA review pass after each completed ticket or step. Default: true. */
+    enabled: boolean;
+}
+export interface ForemanConfig {
+    permissions: PermissionConfig;
+    notifications: NotificationsConfig;
+    qa: QaConfig;
+}
+/** Built-in defaults; foreman.yaml overrides any field present. */
+export declare const DEFAULT_CONFIG: ForemanConfig;
+/** Load foreman.yaml if present and deep-merge it over the defaults. */
+export declare function loadConfig(path?: string): ForemanConfig;

package/dist/foreman.d.ts

@@ -0,0 +1,74 @@
+import type { BuilderAdapter, PermissionHandler, TurnResult } from "./adapters/types.js";
+import type { PermissionPolicy } from "./permissions/policy.js";
+import type { Log } from "./log.js";
+/** Parsed STEP_STATUS marker from a builder's turn. */
+export interface StepStatus {
+    kind: "done" | "blocked" | "plan_complete" | "needs_input" | "qa_pass" | "qa_fail" | "unknown";
+    summary?: string;
+    next?: string;
+    reason?: string;
+    question?: string;
+    choices?: string[];
+    issues?: string;
+    ticket?: string;
+    error?: string;
+}
+/**
+ * Pull the STEP_STATUS marker out of a turn's final text.
+ * Format: `STEP_STATUS: <kind> | key="value" key="value"`.
+ */
+export declare function parseStepStatus(text: string): StepStatus;
+/** Heuristic: did a marker-less turn end by asking the human something? */
+export declare function looksLikeQuestion(text: string): boolean;
+export { MARKER_SPEC } from "./markers.js";
+export { QA_MARKER_SPEC } from "./markers.js";
+/** Instruction sent on the first turn of a batch. */
+export declare function buildPrimer(n: number, trackerPath?: string, ticketsEnabled?: boolean): string;
+/** Instruction sent on turns 2–N. */
+export declare function buildNextStepInstruction(i: number, n: number): string;
+/** QA review turn: ask the builder to triple-check the ticket or step it just completed. */
+export declare function buildQaInstruction(): string;
+/** Follow-up turn after qa_fail: have the builder implement the listed fixes. */
+export declare function buildQaFixInstruction(issues: string): string;
+/** Pre-flight planning turn: ask the builder to list its next N steps without implementing anything. */
+export declare function buildPlanningTurn(n: number, ticketsContent?: string): string;
+/** Builds the permission callback: classify, log, allow or escalate. */
+export declare function createPermissionHandler(policy: PermissionPolicy, log: Log): PermissionHandler;
+export interface BatchResult {
+    completed: number;
+    requested: number;
+    outcome: "all-done" | "plan-complete" | "blocked" | "needs-human";
+    detail?: string;
+}
+/** Drives one builder through a batch of N steps via the STEP_STATUS protocol. */
+export declare class Foreman {
+    private readonly builder;
+    private readonly log;
+    private readonly notificationsEnabled;
+    private readonly qaEnabled;
+    private readonly qaMaxCycles;
+    private readonly projectDir?;
+    private readonly ticketsEnabled;
+    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined);
+    /**
+     * Send one instruction and resolve any needs_input exchanges before returning.
+     * The returned result and status always reflect the final (non-needs_input) turn.
+     */
+    private doTurn;
+    /** Send a planning turn and return the builder's response text. Does not count toward steps. */
+    runPreflight(n: number, ticketsContent?: string): Promise<string>;
+    /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */
+    sendPreflightFeedback(feedback: string): Promise<void>;
+    /** Send one custom instruction through the same needs_input loop as a batch turn. */
+    runInstruction(instruction: string): Promise<{
+        result: TurnResult;
+        status: StepStatus;
+    }>;
+    /**
+     * Run a QA review pass on the ticket the builder just completed.
+     * Loops on qa_fail → fix → re-QA until qa_pass or the cycle cap is reached.
+     * QA turns are free — they do not advance the step counter.
+     */
+    private runQa;
+    runBatch(n: number, trackerPath?: string): Promise<BatchResult>;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};