@wrenautomation/birdwatch 0.0.0-stage → 0.30.0

package/dist/engine/agent.d.ts

@@ -0,0 +1,475 @@
+/**
+ * The engine driven by an agent: each step as one call over a run's ledger. Claude Code (or any
+ * agent) plans, triages, reviews and stops in its own head; the engine does the fixed work
+ * (search, open, extract through the quote gate, check) and keeps the records. Every record the
+ * agent writes carries its id and, on a decision, a why; the person's words come through it
+ * marked `from: human`. The budget is a guard rail: the brief shows it, nothing cuts a query or
+ * stops a round by it.
+ */
+import { type DocumentRecord, type DraftRecord, type FollowAs, type From, type HitRecord, LedgerRecord, type SourceClass, type Step } from "../ledger/records.js";
+import { costOf } from "./cost.js";
+import { type JudgeStats } from "./judge.js";
+import { type PersonView, type Unfollowed } from "./people.js";
+import { type AskKind, type Criterion, type Edge, PlanFile, QueryTree, type TreeGuide, type YieldRow } from "./plan.js";
+import type { Deps } from "./ports.js";
+import { type Pointer, type RunState } from "./state.js";
+import { type ChildView } from "./tree.js";
+/** Who a record is from: the agent (`ai`, its id) or the person through it (`human`, their name). */
+export interface Who {
+    from: From;
+    by: string;
+}
+/** What one command did: the step's word and every record it wrote, in order. */
+export interface Did {
+    run: string;
+    round: number;
+    step: Step;
+    ok: boolean;
+    note?: string;
+    wrote: Shown[];
+}
+/** A record as a command prints it: a document's text replaced by its length. */
+export type Shown = LedgerRecord | (Omit<DocumentRecord, "text"> & {
+    chars: number;
+});
+export declare const shown: (r: LedgerRecord) => Shown;
+export interface AskInput {
+    text: string;
+    kind: AskKind;
+    known?: readonly string[];
+    /** What the ask takes as given: the tree tests each in a `premise` facet. */
+    premises?: readonly string[];
+    /** The person's tests of a good source: the judge asks each on every hit and page. */
+    criteria?: readonly Criterion[];
+    site?: string;
+}
+export interface PlanInput {
+    /** Absent: a new run. Present: the next round of it, after an edge that said again. */
+    run?: string;
+    /** A new run's ask; a later round takes the last snapshot's. */
+    ask?: AskInput;
+    /** Its `sources` are the run's allow-list, every name one this machine has. */
+    planFile: PlanFile;
+    /** Openers let in only to open and follow, never to search. Absent: the last snapshot's. */
+    opens?: readonly string[];
+    /** The model id the extract will use, for the snapshot; null when none. */
+    model: string | null;
+    /** A new run's parent, and why this child. */
+    parent?: {
+        run: string;
+        why: string;
+    };
+}
+/**
+ * Opens a round: writes its snapshot (the ask, with what is known and what the last round left
+ * open, the allow-list, the budget) and the plan step's `done`. No queries: the agent's come
+ * through `search`, never capped.
+ */
+export declare function planRound(deps: Deps, input: PlanInput): Promise<Did>;
+export interface QueryInput {
+    terms: string;
+    why: string;
+    site?: string;
+    /** The tree's facet it serves, when the agent adds one more leaf by hand. */
+    facet?: string;
+}
+/** Writes the agent's queries, then runs the fetch step: every searcher on every unsearched query of the round. */
+export declare function search(deps: Deps, run: string, queries: readonly QueryInput[], who: Who): Promise<Did>;
+export interface FollowInput {
+    as: FollowAs;
+    why: string;
+    /** Where to start: a page or a profile. Absent: the document's URL. */
+    url?: string;
+    /** The read page that led here. */
+    document?: string;
+    /** Follow sources this machine has that the run lacks: they join to follow, never to search. */
+    with?: readonly string[];
+}
+/**
+ * What a person does after a good page: its channel's or author's own posts, or pages like it.
+ * Writes a query with `follow`, then runs the fetch step: its hits go through the same calls,
+ * reads and checks, and the tree's read cap bounds them.
+ */
+export declare function follow(deps: Deps, run: string, input: FollowInput, who: Who): Promise<Did>;
+/** One try of a facet as the brief shows it: its queries, each with the hits it wrote and the known ones it found again. */
+export interface TryView {
+    tier: number;
+    queries: {
+        id: string;
+        terms: string;
+        hits: number;
+        again: number;
+    }[];
+    /** New hits the try wrote, summed. */
+    hits: number;
+}
+export interface FacetView {
+    name: string;
+    tries: TryView[];
+    /** New hits over every try. */
+    hits: number;
+    /** Hits a query of this facet found (written or found again) that triage kept. */
+    kept: number;
+    /** Hits of this facet no call has named yet: the next try waits on them. */
+    uncalled: number;
+    /** The facet reached the guide's `thin` in kept hits: no more tries. */
+    enough: boolean;
+    /** The source classes it needs, as its queries say. */
+    needs: string[];
+    /** Kept hits whose class (the agent's, else the judge's guess) is one it needs. */
+    fit: number;
+    /** Kept hits with any class known or guessed: `fit` counts only when one is. */
+    guessed: number;
+    /** Read pages with a kept finding, per class. */
+    classes: Partial<Record<SourceClass | "unclassed", number>>;
+    /** It needs classes; pages were read and none is of one. */
+    lacks: boolean;
+}
+export interface TreeView {
+    thin: number;
+    facets: FacetView[];
+    /** Facets the guide names that no query of the round served, dead ones left out. */
+    uncovered: string[];
+    /** Facets the agent gave up on: no try runs for them again. */
+    dead: string[];
+}
+/** The round's queries by facet and try, with what each wrote and what triage kept: rebuilt from the records. */
+export declare function treeView(state: RunState, round: number, guide: TreeGuide): TreeView;
+export interface TreeDid extends Did {
+    tree: TreeView;
+}
+export interface TreeOptions {
+    /** The next try of every facet that has one, whatever triage kept: no thin rule, no wait. */
+    all?: boolean;
+}
+/**
+ * One tier of the round's query tree: for each facet in the tree, its next try, in one fetch.
+ * A facet with no query yet this round runs its first try. A facet that ran one waits for
+ * triage (a call on each of its hits); then, under the guide's `thin` in kept hits, it runs the
+ * next try; at `thin` it is done; out of tries, it is a gap. So the agent runs the same tree
+ * again after each triage, and the tree falls through on what the agent kept, never on what a
+ * searcher returned (every searcher returns a page). `all` runs every facet's next try at once.
+ * A page two facets reached is a `found` on the first facet's hit, and the brief ranks it above
+ * one facet's. Never capped: the agent wrote the tree.
+ */
+export declare function searchTree(deps: Deps, run: string, tree: QueryTree, who: Who, options?: TreeOptions): Promise<TreeDid>;
+export interface OpenInput {
+    /** Hits to keep (a call in the agent's name) and read. */
+    hits?: readonly string[];
+    /** Pages the agent names itself: a hit each, kept and read. */
+    urls?: readonly string[];
+    /** Why these: required with `hits` or `urls`. */
+    why?: string;
+    /**
+     * Open sources this machine has that the run's allow-list lacks (a ladder that came after the
+     * plan). Written as a new snapshot in the agent's name, so the ledger says when the list grew.
+     */
+    with?: readonly string[];
+}
+/** Kept hits of any round with no document yet. */
+export declare const unread: (state: RunState) => HitRecord[];
+/**
+ * Keeps the hits named (and writes a hit per URL named), then runs the read step over every
+ * kept hit of the run that has no document. No names: the reads alone.
+ */
+export declare function open(deps: Deps, run: string, input: OpenInput, who: Who): Promise<Did>;
+/** Documents of any round the extractor has no verdict on. */
+export declare const unjudged: (state: RunState) => DocumentRecord[];
+/** The extract step over the documents named, else every one of the run without a verdict. */
+export declare function extract(deps: Deps, run: string, documents?: readonly string[]): Promise<Did>;
+/** Kept findings the run's patterns rest on that no check has read. */
+export declare const uncheckedOf: (state: RunState, ids: readonly string[]) => string[];
+/** Findings the judge says credit another named source. */
+export declare const citesOf: (state: RunState, ids: readonly string[]) => string[];
+/**
+ * The check over the findings named; else, with `patterns`, every unchecked finding a pattern
+ * rests on; else a sample spread over documents: `n`, or the budget's `checks` or a tenth of
+ * the kept findings, whichever is more.
+ */
+export declare function check(deps: Deps, run: string, input?: {
+    findings?: readonly string[];
+    n?: number;
+    patterns?: boolean;
+}): Promise<Did>;
+/** What the agent or the person adds by hand. */
+export type Addition = {
+    type: "query";
+    terms: string;
+    why: string;
+    site?: string;
+    facet?: string;
+} | {
+    type: "finding";
+    document: string;
+    text: string;
+    quote: string;
+} | {
+    type: "check";
+    on: string;
+    ok: boolean;
+    why: string;
+} | {
+    type: "call";
+    on: string;
+    verdict: "keep" | "drop";
+    why: string;
+} | {
+    type: "edge";
+    next: Edge["next"];
+    to?: Edge["to"];
+    why: string;
+} | {
+    type: "steer";
+    text: string;
+} | {
+    type: "gap";
+    note: string;
+    on?: string;
+} | {
+    type: "pattern";
+    text: string;
+    findings: string[];
+} | {
+    type: "draft";
+    for: string;
+    items: DraftInput[];
+} | {
+    type: "class";
+    on: string;
+    class: SourceClass;
+    why: string;
+} | {
+    type: "dead";
+    facet: string;
+    why: string;
+} | {
+    type: "person";
+    name: string;
+    profiles: string[];
+    aka: string[];
+    why: string;
+};
+/** One item of a draft as the agent writes it: cites are finding or pattern ids. */
+export interface DraftInput {
+    title?: string | null;
+    body?: string | null;
+    cites?: string[] | null;
+}
+export interface Added {
+    record: Shown;
+    /** What the agent should know: an edge past the budget, a finding on a dropped document. */
+    warnings: string[];
+}
+/**
+ * One record in the agent's or the person's name. A query, finding or pattern lands in the
+ * current round; a call, edge, steer or gap in the round it is about (the one just reviewed,
+ * between rounds). A finding goes through the quote gate: its quote must be on the document,
+ * word for word, or the add fails with the gate's why. A pattern names kept findings; its
+ * source count is counted here, never claimed. No `step`: a hand-written record has none.
+ */
+export declare function add(deps: Deps, run: string, a: Addition, who: Who): Promise<Added>;
+/** What the agent takes from the judge in bulk: classes over a bar, or calls on uncalled hits. */
+export type Acceptance = {
+    take: "class";
+    min: number;
+    why: string;
+} | {
+    take: "keep";
+    over: number;
+    why: string;
+} | {
+    take: "drop";
+    under: number;
+    why: string;
+};
+/**
+ * The judge's guesses over a bar, written in the agent's name with its why and the judge's
+ * number: a class on each document with none, or a keep or drop on each uncalled hit by how
+ * likely it serves the ask. The agent sets the bar and owns the records; the judge decides none.
+ */
+export declare function accept(deps: Deps, run: string, a: Acceptance, who: Who): Promise<{
+    wrote: Shown[];
+    skipped: number;
+}>;
+/** What `learn` changes on a plan file. Every field is optional; the version always moves. */
+export interface PlanChanges {
+    sources?: string[];
+    budget?: Partial<PlanFile["budget"]>;
+    age?: string;
+    rules?: string[];
+    tree?: TreeGuide;
+    runs?: PlanFile["runs"];
+}
+/**
+ * The next version of a plan file: the current one with the changes, version plus one. Pure:
+ * the ledger writes it (`birdwatch learn`), at the end of a run the agent and the person agreed
+ * was good. The sources stay an allow-list a run narrows, never widens; `learn` is how it widens.
+ */
+export declare function tunePlan(current: PlanFile, changes: PlanChanges): PlanFile;
+/** A hit as the brief shows it: the view, its id, round and queries. */
+export type HitBrief = Omit<HitRecord, "type" | "run" | "step" | "at" | "from" | "by" | "key"> & {
+    /** The facets whose queries found it. */
+    facets: string[];
+    /**
+     * The judge's hint: how likely it serves the ask, whose side wrote it, its class. The brief
+     * lists hits by facets plus `serves`, most first. A hint: the agent calls each.
+     */
+    judge?: {
+        serves: number;
+        side: string;
+        class: string;
+        criteria?: Record<string, number>;
+    };
+};
+export interface Brief {
+    run: string;
+    round: number;
+    /** The next step the fold points at; null when an edge said stop. */
+    next: Pointer | null;
+    /** The last edge's why, or the step that gave up. */
+    note: string | null;
+    ask: NonNullable<RunState["snapshot"]>["ask"] | null;
+    budget: NonNullable<RunState["snapshot"]>["budget"] | null;
+    sources: string[];
+    planFile: NonNullable<RunState["snapshot"]>["planFile"] | null;
+    /** The kind's word for the agent, from its plan file: how much a source's age counts, and the rules to heed when it plans and triages. */
+    guide: {
+        age: string | null;
+        rules: string[];
+    } | null;
+    /** What the person said, oldest first. */
+    steer: string[];
+    /** What the last round left open: its edge's why, its gaps, the person's calls. */
+    open: string[];
+    /** This round's gaps, as lines. */
+    gaps: string[];
+    findings: {
+        kept: {
+            id: string;
+            round: number;
+            text: string;
+            quote?: string;
+            url: string;
+            date?: string;
+            /** The failed finding this one narrows. */
+            fixes?: string;
+        }[];
+        dropped: number;
+    };
+    checks: {
+        on: string;
+        ok: boolean;
+        why: string;
+    }[];
+    /** What the agent says several findings say together, its sources counted now over kept findings. */
+    patterns: {
+        id: string;
+        round: number;
+        text: string;
+        findings: string[];
+        /** Distinct sites over its kept findings; each forum thread counts on its own. */
+        sources: number;
+        /** Sources per class; `unclassed` counts the sites with none. */
+        classes: Partial<Record<SourceClass | "unclassed", number>>;
+        /** Every classed source is a vendor. */
+        echo: boolean;
+        /** Kept findings it rests on that no check has read. */
+        unchecked: string[];
+        /** Findings the judge says credit another source (a survey, a report): read that one. */
+        cites: string[];
+    }[];
+    /** The run this one is a child of. */
+    parent: {
+        run: string;
+        round: number;
+        why: string;
+    } | null;
+    /** The runs that name this one as parent, and what the tree under it read and cost. */
+    children: ChildView[];
+    treeCost: ReturnType<typeof costOf> | null;
+    /** The asks from the root down to this run's parent, each with why it began: to see drift. */
+    lineage: {
+        run: string;
+        ask: string;
+        why?: string;
+    }[];
+    /** Pages the whole tree may still read: the one hard stop. Null on a run with no cap. */
+    treeRoom: {
+        root: string;
+        cap: number;
+        read: number;
+        left: number;
+    } | null;
+    /** Facets given up on, with why. */
+    dead: {
+        facet: string;
+        why: string;
+    }[];
+    /** People across platforms, most kept findings first. */
+    people: PersonView[];
+    /** Kept pages no follow started from and no person owns: `follow` their author's posts or pages like them; a paper's refs or citers. */
+    unfollowed: Unfollowed[];
+    /** The latest rough draft, or null: never the final. */
+    draft: {
+        id: string;
+        round: number;
+        for: string;
+        items: DraftRecord["items"];
+    } | null;
+    verdicts: {
+        document: string;
+        url: string;
+        quality: string;
+        gap?: string;
+    }[];
+    /** This round's query tree with what each try wrote; null when the round's queries are flat. */
+    tree: TreeView | null;
+    hits: {
+        uncalled: HitBrief[];
+        toRead: {
+            id: string;
+            url: string;
+        }[];
+        read: number;
+        total: number;
+    };
+    documents: {
+        /**
+         * Best first by the judge: the mean of its criteria yeses when the ask has criteria, else
+         * `worth` (its trial score); pages it has not judged last. A hint only: the agent picks.
+         */
+        toExtract: {
+            id: string;
+            url: string;
+            worth?: number;
+            criteria?: Record<string, number>;
+        }[];
+        /**
+         * Documents with a kept finding and no class: class them before the patterns count. `guess`
+         * is the judge's; `accept <run> class` takes every guess over a bar.
+         */
+        unclassed: {
+            id: string;
+            url: string;
+            guess?: {
+                class: string;
+                p: number;
+            };
+        }[];
+        total: number;
+    };
+    edges: {
+        round: number;
+        next: string;
+        to?: string;
+        why: string;
+        by: string;
+    }[];
+    /** What the allow-list's sources yielded over every run. */
+    yield: YieldRow[];
+    /** What the judge did and how often the agent and the check agreed with it. */
+    judge: JudgeStats;
+    cost: ReturnType<typeof costOf>;
+}
+/** The brief, as JSON: everything the agent needs to plan, triage, review and stop. */
+export declare function brief(deps: Deps, run: string): Promise<Brief>;