@gr8ful/spf 0.1.0

package/dist/core/data_types.d.ts

@@ -0,0 +1,562 @@
+/**
+ * Concrete data types for the SPF ADW system.
+ *
+ * RULE (four-param rule): any function that takes more than 4 parameters takes
+ * ONE of these objects instead. AgentCall and PhaseParams are the pattern.
+ *
+ * Every agent call declares a concrete output type — an envelope built with
+ * envelopeType() — that its final JSON response is parsed against. No untyped
+ * handoffs. Validation is Valibot's job here (zod's/Python's pydantic
+ * equivalent) — chosen because Flue's own structured-output wiring is built
+ * on Valibot, so an envelope type doubles as the tool schema handed to it
+ * with no second definition.
+ */
+import * as v from "valibot";
+export type PhaseKind = "engineer" | "agent" | "code";
+export type PhaseStatus = "queued" | "running" | "success" | "fail";
+/** Everything run.phase() needs. Passed as one object, never loose params. */
+declare const PhaseParamsShape: v.ObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly kind: v.PicklistSchema<["engineer", "agent", "code"], undefined>;
+    readonly owner: v.StringSchema<undefined>;
+    readonly description: v.StringSchema<undefined>;
+    readonly retries: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>, 0>;
+}, undefined>;
+/**
+ * A phase name identifies; a description explains. Both are required.
+ *
+ * The description is the only sentence the trace, the console, and the
+ * phase block in the UI ever show about intent — everything else is ids,
+ * statuses, and timings. `commit_plan: "Commit the plan"` tells a reader
+ * nothing they could not already see, so an echo is rejected the same way
+ * a blank one is. This is a construction-time error on purpose: it fires
+ * before the phase opens, not after a run is already in the trace.
+ */
+export declare const PhaseParamsSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly kind: v.PicklistSchema<["engineer", "agent", "code"], undefined>;
+    readonly owner: v.StringSchema<undefined>;
+    readonly description: v.StringSchema<undefined>;
+    readonly retries: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>, 0>;
+}, undefined>, v.RawTransformAction<{
+    name: string;
+    kind: "agent" | "code" | "engineer";
+    owner: string;
+    description: string;
+    retries: number;
+}, {
+    name: string;
+    kind: "agent" | "code" | "engineer";
+    owner: string;
+    retries: number;
+    description: string;
+}>]>;
+export type PhaseParams = v.InferOutput<typeof PhaseParamsSchema>;
+export declare function makePhaseParams(input: v.InferInput<typeof PhaseParamsShape>): PhaseParams;
+/** The persisted phase record — PhaseParams plus lifecycle. */
+export interface Phase {
+    phase_id: string;
+    adw_id: string;
+    seq: number;
+    params: PhaseParams;
+    status: PhaseStatus;
+    attempt: number;
+    error?: string | null;
+    started_at?: string | null;
+    ended_at?: string | null;
+}
+export declare const EnvelopeBaseSchema: v.ObjectSchema<{
+    status: v.PicklistSchema<["success", "fail"], undefined>;
+    summary: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    artifacts: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    notes_for_next_agent: v.OptionalSchema<v.StringSchema<undefined>, "">;
+}, undefined>;
+export type EnvelopeBase = v.InferOutput<typeof EnvelopeBaseSchema>;
+export interface EnvelopeType<T> {
+    name: string;
+    schema: v.GenericSchema<Record<string, unknown>, T>;
+    fields: string[];
+}
+export declare const GenericOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+}>;
+export type GenericOutputT = v.InferOutput<typeof GenericOutput.schema>;
+export declare const PlanOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    commit_message: string;
+}>;
+export type PlanOutputT = v.InferOutput<typeof PlanOutput.schema>;
+export declare const BuildOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    changed_files: string[];
+    commit_message: string;
+}>;
+export type BuildOutputT = v.InferOutput<typeof BuildOutput.schema>;
+export declare const ScoutFindingSchema: v.ObjectSchema<{
+    readonly file: v.StringSchema<undefined>;
+    readonly note: v.OptionalSchema<v.StringSchema<undefined>, "">;
+}, undefined>;
+export type ScoutFinding = v.InferOutput<typeof ScoutFindingSchema>;
+export declare const ScoutOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    findings: {
+        file: string;
+        note: string;
+    }[];
+}>;
+export type ScoutOutputT = v.InferOutput<typeof ScoutOutput.schema>;
+/** One thing the request (or plan) asked for, and whether it is there. */
+export declare const ReviewFindingSchema: v.ObjectSchema<{
+    readonly requirement: v.StringSchema<undefined>;
+    readonly met: v.BooleanSchema<undefined>;
+    readonly evidence: v.OptionalSchema<v.StringSchema<undefined>, "">;
+}, undefined>;
+export type ReviewFinding = v.InferOutput<typeof ReviewFindingSchema>;
+/** Confirmation that what was built is what was asked for — not a test run. */
+export declare const ReviewOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    approved: boolean;
+    findings: {
+        requirement: string;
+        met: boolean;
+        evidence: string;
+    }[];
+    blocking: string[];
+}>;
+export type ReviewOutputT = v.InferOutput<typeof ReviewOutput.schema>;
+/** Where the write-up of a completed change landed. */
+export declare const DocumentOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    document_path: string;
+    documented_files: string[];
+    commit_message: string;
+}>;
+export type DocumentOutputT = v.InferOutput<typeof DocumentOutput.schema>;
+export declare const QualityAreaSchema: v.PicklistSchema<["frontend", "backend"], undefined>;
+export type QualityArea = v.InferOutput<typeof QualityAreaSchema>;
+export declare const QualityOperationSchema: v.PicklistSchema<["lint", "typecheck", "build"], undefined>;
+export type QualityOperation = v.InferOutput<typeof QualityOperationSchema>;
+/** One deterministic quality command, as configured in spf.config.yaml's `quality.checks`. */
+export declare const QualityCheckSpecSchema: v.ObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly area: v.OptionalSchema<v.PicklistSchema<["frontend", "backend"], undefined>, "backend">;
+    readonly operation: v.PicklistSchema<["lint", "typecheck", "build"], undefined>;
+    readonly argv: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MinLengthAction<string[], 1, "argv must name at least the binary to run">]>;
+    readonly timeout_seconds: v.OptionalSchema<v.NumberSchema<undefined>, 120>;
+}, undefined>;
+export type QualityCheckSpec = v.InferOutput<typeof QualityCheckSpecSchema>;
+/**
+ * `quality.checks` names the deterministic commands; `quality.suites` groups
+ * them into what a chain actually runs (`test`, `all`, ...). An unconfigured
+ * suite is a hard error at validate() time — see agents.validate() — not a
+ * silent placeholder that reports green. There is deliberately no packaged
+ * default suite: "no quality commands configured yet" must fail loudly on
+ * the first quality-gated chain, not quietly pass one.
+ */
+export declare const QualityConfigSchema: v.ObjectSchema<{
+    readonly checks: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly name: v.StringSchema<undefined>;
+        readonly area: v.OptionalSchema<v.PicklistSchema<["frontend", "backend"], undefined>, "backend">;
+        readonly operation: v.PicklistSchema<["lint", "typecheck", "build"], undefined>;
+        readonly argv: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MinLengthAction<string[], 1, "argv must name at least the binary to run">]>;
+        readonly timeout_seconds: v.OptionalSchema<v.NumberSchema<undefined>, 120>;
+    }, undefined>, undefined>, () => never[]>;
+    readonly suites: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, () => {}>;
+}, undefined>;
+export type QualityConfig = v.InferOutput<typeof QualityConfigSchema>;
+/** Captured evidence from one quality command. */
+export interface QualityCheckResult {
+    name: string;
+    area: QualityArea;
+    operation: QualityOperation;
+    command: string;
+    returncode: number;
+    passed: boolean;
+    duration_seconds: number;
+    output_artifact: string;
+    output_tail: string;
+}
+/** Aggregate result from a quality block: every check it ran, and the verdict. */
+export interface QualityResult {
+    passed: boolean;
+    checks: QualityCheckResult[];
+    failures: string[];
+    artifacts: string[];
+}
+/** Everything changes.capture() needs. One object, never loose params. */
+export interface ChangeCapture {
+    base: string;
+    max_diff_lines: number;
+    include_untracked: boolean;
+}
+export declare function makeChangeCapture(input: Partial<ChangeCapture> & {
+    base?: string;
+}): ChangeCapture;
+/**
+ * The commit a change is measured from, and why that one.
+ *
+ * `reason` is the line the trace shows. A diff is only as trustworthy as the
+ * thing it was taken against, so the ADW records that choice instead of
+ * leaving the reader to infer it.
+ */
+export declare class BaseRef {
+    ref: string;
+    commit: string;
+    reason: string;
+    constructor(ref: string, commit: string, reason?: string);
+    /** Display form — a named ref as itself, a pinned raw sha shortened. */
+    get label(): string;
+}
+/** What changed since the base commit — pure git facts, no judgement. */
+export declare class ChangeSet {
+    base: BaseRef;
+    files: string[];
+    untracked: string[];
+    insertions: number;
+    deletions: number;
+    stat: string;
+    diff_path: string;
+    truncated: boolean;
+    constructor(base: BaseRef, files?: string[], untracked?: string[], insertions?: number, deletions?: number, stat?: string, diff_path?: string, // the full diff, written into context_handoff/
+    truncated?: boolean);
+    get empty(): boolean;
+}
+/**
+ * A ChangeSet shaped as an envelope so an agent can be handed it directly.
+ *
+ * Same adapter idea as VerifyOutput: code computes the diff, the documenter
+ * consumes it through the one door every agent handoff uses.
+ */
+export declare const ChangesOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    base: string;
+    changed_files: string[];
+    insertions: number;
+    deletions: number;
+    stat: string;
+    diff_path: string;
+}>;
+export type ChangesOutputT = v.InferOutput<typeof ChangesOutput.schema>;
+/**
+ * A deterministic result, shaped as an envelope so an agent can consume it.
+ *
+ * Agents hand each other typed envelopes; code blocks return QualityResult.
+ * This is the adapter, so a failing lint or test run flows back into the
+ * builder through exactly the same door a tester agent's report used to —
+ * the ADW script is the only thing that knows the difference.
+ */
+export declare const VerifyOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    passed: boolean;
+    failures: string[];
+}>;
+export type VerifyOutputT = v.InferOutput<typeof VerifyOutput.schema>;
+/**
+ * One thing a gate looked at, and what it found.
+ *
+ * `note` is the evidence — "exists, 2.1KB", "exit 0", "not in the diff". On a
+ * failed check it doubles as the reason, so it is what the agent is told.
+ */
+export interface GateCheck {
+    item: string;
+    ok: boolean;
+    note: string;
+}
+/**
+ * What every gate returns: the checks it ran. Violations are derived.
+ *
+ * Authoring stays a one-liner per item — `report.check(...)` appends and
+ * returns self, so a gate is a loop and a return.
+ */
+export declare class GateReport {
+    checks: GateCheck[];
+    check(item: string, ok: boolean, note?: string): GateReport;
+    get violations(): string[];
+    get passed(): boolean;
+}
+/** The minimal shape a gate needs from a run — avoids a circular import with runner.ts. */
+export interface RunContext {
+    repo_root: string;
+}
+export type GateFn = (envelope: EnvelopeBase, run: RunContext) => GateReport | string[];
+/** One agent invocation: prompt in, typed envelope out, gates verified. */
+export interface AgentCall<T extends EnvelopeBase = EnvelopeBase> {
+    output_type: EnvelopeType<T>;
+    prompt: string;
+    previous?: EnvelopeBase | null;
+    gates?: GateFn[];
+}
+export declare function makeAgentCall<T extends EnvelopeBase>(input: {
+    output_type: EnvelopeType<T>;
+    prompt: string;
+    previous?: EnvelopeBase | null;
+    gates?: GateFn[];
+}): AgentCall<T>;
+export declare const PromptEngineeringSchema: v.ObjectSchema<{
+    readonly system: v.StringSchema<undefined>;
+    readonly user: v.StringSchema<undefined>;
+}, undefined>;
+export type PromptEngineering = v.InferOutput<typeof PromptEngineeringSchema>;
+export declare const ThinkingLevelSchema: v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>;
+export type ThinkingLevel = v.InferOutput<typeof ThinkingLevelSchema>;
+export declare const AgentConfigSchema: v.ObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+    readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
+    readonly thinking: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>, "medium">;
+    readonly color: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly purpose: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly prompt_engineering: v.ObjectSchema<{
+        readonly system: v.StringSchema<undefined>;
+        readonly user: v.StringSchema<undefined>;
+    }, undefined>;
+    readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+    readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+}, undefined>;
+export type AgentConfig = v.InferOutput<typeof AgentConfigSchema>;
+export declare const ConfigDefaultsSchema: v.ObjectSchema<{
+    readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+    readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
+    readonly thinking: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>, "medium">;
+    readonly color: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+    readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+    readonly protected_files: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
+    readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
+}, undefined>;
+export type ConfigDefaults = v.InferOutput<typeof ConfigDefaultsSchema>;
+export declare const ObservabilityConfigSchema: v.ObjectSchema<{
+    readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
+    readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 500>;
+}, undefined>;
+export type ObservabilityConfig = v.InferOutput<typeof ObservabilityConfigSchema>;
+/**
+ * `spf watch`'s configuration. `provider` is a small enum today (just
+ * `"github"`) by design — adding Jira/Linear later is a new provider
+ * module (`core/issues/*_provider.ts`) implementing `IssueProvider` plus
+ * one more enum entry here, not a rewrite of the poll loop.
+ *
+ * `repo` has no sensible default and is validated as required at `spf
+ * watch` startup, not here — an empty string parses fine (this schema has
+ * no opinion on whether watch is even configured), matching the same
+ * "fails loudly before anything spawns, not eagerly at parse time" pattern
+ * `quality:` already uses.
+ */
+export declare const WatchProviderSchema: v.PicklistSchema<["github"], undefined>;
+export type WatchProvider = v.InferOutput<typeof WatchProviderSchema>;
+export declare const WatchConfigSchema: v.ObjectSchema<{
+    readonly provider: v.OptionalSchema<v.PicklistSchema<["github"], undefined>, "github">;
+    readonly repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly label_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+    readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "plan-build-test">;
+    readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
+    readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 60000>;
+    readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+}, undefined>;
+export type WatchConfig = v.InferOutput<typeof WatchConfigSchema>;
+export declare const SFConfigSchema: v.ObjectSchema<{
+    readonly defaults: v.OptionalSchema<v.ObjectSchema<{
+        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+        readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
+        readonly thinking: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>, "medium">;
+        readonly color: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+        readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+        readonly protected_files: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => string[]>;
+        readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
+    }, undefined>, () => {
+        coding_agent: "claude_code" | "flue";
+        model: string;
+        thinking: "high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh";
+        color: string;
+        harness_engineering: string[];
+        tools?: string[] | null | undefined;
+        protected_files: string[];
+        data_dir: string;
+    }>;
+    readonly observability: v.OptionalSchema<v.ObjectSchema<{
+        readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
+        readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 500>;
+    }, undefined>, () => {
+        db: string;
+        poll_ms: number;
+    }>;
+    readonly agents: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly name: v.StringSchema<undefined>;
+        readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
+        readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;
+        readonly thinking: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh", "max"], undefined>, "medium">;
+        readonly color: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly purpose: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly prompt_engineering: v.ObjectSchema<{
+            readonly system: v.StringSchema<undefined>;
+            readonly user: v.StringSchema<undefined>;
+        }, undefined>;
+        readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+        readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+        readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+    }, undefined>, undefined>, () => never[]>;
+    readonly quality: v.OptionalSchema<v.ObjectSchema<{
+        readonly checks: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.StringSchema<undefined>;
+            readonly area: v.OptionalSchema<v.PicklistSchema<["frontend", "backend"], undefined>, "backend">;
+            readonly operation: v.PicklistSchema<["lint", "typecheck", "build"], undefined>;
+            readonly argv: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MinLengthAction<string[], 1, "argv must name at least the binary to run">]>;
+            readonly timeout_seconds: v.OptionalSchema<v.NumberSchema<undefined>, 120>;
+        }, undefined>, undefined>, () => never[]>;
+        readonly suites: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, () => {}>;
+    }, undefined>, () => {
+        checks: {
+            name: string;
+            area: "backend" | "frontend";
+            operation: "build" | "lint" | "typecheck";
+            argv: string[];
+            timeout_seconds: number;
+        }[];
+        suites: {
+            [x: string]: string[];
+        };
+    }>;
+    readonly watch: v.OptionalSchema<v.ObjectSchema<{
+        readonly provider: v.OptionalSchema<v.PicklistSchema<["github"], undefined>, "github">;
+        readonly repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly label_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+        readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "plan-build-test">;
+        readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
+        readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 60000>;
+        readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+    }, undefined>, () => {
+        provider: "github";
+        repo: string;
+        label_prefix: string;
+        chain: string;
+        base_branch: string;
+        poll_ms: number;
+        concurrency: number;
+    }>;
+}, undefined>;
+export type SFConfig = v.InferOutput<typeof SFConfigSchema>;
+/** One traced event, always logged against adw_id + phase. */
+export interface EventRecord {
+    adw_id: string;
+    phase_id: string;
+    type: string;
+    name: string;
+    payload: Record<string, unknown>;
+    parent_id: string;
+    tokens?: number | null;
+    started_at?: string | null;
+    ended_at?: string | null;
+}
+export declare function makeEventRecord(input: Partial<EventRecord> & {
+    adw_id: string;
+    type: string;
+}): EventRecord;
+/**
+ * Everything one coding-agent dispatch+read turn needs, whichever backend
+ * (`coding_agent:` in config) actually runs it — Flue today, others later.
+ * Each backend module (`agent_flue.ts`, ...) is free to ignore fields it has
+ * no use for (a subprocess-based backend has no use for `flue_db_path`) and
+ * to interpret `model` in its own vocabulary (Flue: `provider/model-id`;
+ * others may take a bare alias) — `agents.validate()` already branches its
+ * model-shape check on `coding_agent` for exactly this reason.
+ *
+ * No `session_dir`/`raw_output_path` (Flue's own persistence is the durable
+ * record for Flue; a subprocess backend owns its own equivalent) and no
+ * `extensions` (harness_engineering has no analogue on any current backend —
+ * see agents.validate()). `output_schema`/`output_type_name` is the one
+ * contract every backend must honor somehow — Flue via an injected
+ * `sf_report` tool, a CLI-shaped backend via its own structured-output flag —
+ * so a Valibot envelope type becomes that backend's schema-validated output
+ * with no second definition anywhere.
+ */
+export interface AgentRequest {
+    prompt: string;
+    system_prompt: string;
+    model: string;
+    thinking: ThinkingLevel;
+    session_id: string;
+    resume: boolean;
+    tools?: string[] | null;
+    output_schema: v.GenericSchema<Record<string, unknown>, unknown>;
+    output_type_name: string;
+    cwd: string;
+    flue_db_path: string;
+}
+/**
+ * Tokens and the dollars they cost, per component, summed over a call.
+ *
+ * Mirrors pi's `usage` shape one-for-one so the numbers reconcile with what
+ * pi itself reports: `input` EXCLUDES cache reads, which bill at their own
+ * (cheaper) rate — add them to learn the size of the prompt that was sent.
+ */
+export declare class UsageBreakdown {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+    reasoning_tokens: number;
+    total_tokens: number;
+    input_cost: number;
+    output_cost: number;
+    cache_read_cost: number;
+    cache_write_cost: number;
+    total_cost: number;
+    /**
+     * Fold in one pi `message_end` usage object.
+     *
+     * `totalTokens` is passed in rather than re-derived: the caller already
+     * computes it pi's way (totalTokens, else the sum of the parts).
+     */
+    add_turn(usage: Record<string, any>, totalTokens: number): void;
+    /** Add another call's usage — a phase that retries spends more than once. */
+    merge(other: UsageBreakdown): void;
+    toJSON(): Record<string, number>;
+}
+export interface AgentResult {
+    text: string;
+    /**
+     * The validated structured output, however this backend produced it —
+     * Flue's injected `sf_report` tool call, or another backend's own
+     * schema-validated result field. Present whenever the backend captured
+     * one, regardless of whether it also produced JSON in `text`. `null`
+     * means it never validated, so the caller falls back to extracting JSON
+     * from `text` directly.
+     */
+    report: unknown | null;
+    session_id: string;
+    tokens: number;
+    cost: number;
+    usage: UsageBreakdown;
+    context_tokens: number;
+    context_window: number;
+}
+export declare function makeAgentResult(input: Partial<AgentResult> & {
+    session_id: string;
+}): AgentResult;
+export {};