@wrenautomation/birdwatch 0.0.0-stage → 0.29.0

package/dist/app/engine-cli.js

@@ -0,0 +1,738 @@
+/**
+ * The engine from a shell: `run` an ask, `trace` a run, `keep` or `drop` a finding by hand, `steer`
+ * a run, say a `gap`, send it `back` to a step,
+ * `yield` per source, `sources` on this machine. Every command prints JSON, so Claude Code
+ * can drive it. The ledger is a folder (`--ledger`, BIRDWATCH_LEDGER, default `./ledger`); a
+ * writer names this terminal's file in it (`--writer`, BIRDWATCH_WRITER, default the user name).
+ * The model is a `@wrenautomation/models` spec: `anthropic` by default (Claude Haiku direct,
+ * ANTHROPIC_API_KEY), `gateway[:alias]`, `gemini`, `claude-code`, `command:<cmd>` and the rest
+ * of its grammar. A host with its own ledger, sources or
+ * model passes them in `EngineCliDeps`; wren's `research` command is these commands over
+ * Postgres. A run that stops on a transient failure (a 429, a 5xx, a dropped connection) is
+ * resumed by `run` itself after a pause, up to RESUMES times.
+ */
+import { mkdir, readFile } from "node:fs/promises";
+import { userInfo } from "node:os";
+import { serve } from "@hono/node-server";
+import { isTransient } from "@wrenautomation/models";
+import { judgeFromSpec } from "@wrenautomation/models/judge";
+import { modelFromSpec } from "@wrenautomation/models/spec";
+import { PoliteFetcher, userAgent } from "@wrenautomation/read/fetch";
+import { geminiVideo } from "@wrenautomation/read/video";
+import { claimExtractor } from "../document/index.js";
+import { accept, add, brief, check, costOf, extract, fold, follow, joined, open, planRound, RESERVED, recall, registry, run, search, searchTree, tunePlan, } from "../engine/index.js";
+import { FilesLedger, FollowAs, SOURCE_CLASSES, SourceClass, ulids, } from "../ledger/index.js";
+import { Criterion, defaultPlanFile, PLAN_KINDS, Step as PlanStep, QueryTree, TreeGuide, treeOf, } from "../plan/index.js";
+import { accountsFrom, arxivSource, exa, facebookSource, fetcherSource, googleSource, httpLadderClient, ingressLadderClient, ladderSource, ledgerSource, paste, redditSource, searxng, ytdlpSource, } from "../sources/index.js";
+import { SERVE_ORIGINS, SERVE_PORT, serveApp, watchRuns } from "./serve.js";
+const DEFAULT_MODEL = "anthropic";
+/** Resumes `run` makes on its own after a transient failure. */
+export const RESUMES = 5;
+/** The longest pause before a resume, whatever `retry-after` said. */
+const MAX_RESUME_WAIT_MS = 300_000;
+export { costOf };
+/** The pause before a resume: to `retryAfter` (five minutes at most), else 15 s per resume so far. */
+export function resumeWaitMs(n, retryAfter, now = Date.now()) {
+    if (retryAfter) {
+        const until = Date.parse(retryAfter) - now;
+        if (!Number.isNaN(until))
+            return Math.max(0, Math.min(until, MAX_RESUME_WAIT_MS));
+    }
+    return 15_000 * n;
+}
+/** `NAME`, then `NAME_1`, `NAME_2`, ... in order: a fleet of keys for one vendor. */
+export function keys(printed, name) {
+    const out = [];
+    const one = printed[name];
+    if (one)
+        out.push(one);
+    for (let i = 1;; i++) {
+        const k = printed[`${name}_${i}`];
+        if (!k)
+            break;
+        out.push(k);
+    }
+    return out;
+}
+/** `name=question` lines as criteria; a name the judge already asks, or a repeat, fails. */
+export function criteriaOf(lines) {
+    const out = [];
+    for (const line of lines ?? []) {
+        const at = line.indexOf("=");
+        const c = Criterion.safeParse({
+            name: line.slice(0, at).trim(),
+            question: line.slice(at + 1).trim(),
+        });
+        if (at < 1 || !c.success)
+            throw new Error(`--criterion ${line}: want name=question, name in a-z0-9_`);
+        if (RESERVED.has(c.data.name) || out.some((x) => x.name === c.data.name))
+            throw new Error(`--criterion ${c.data.name}: the name is taken`);
+        out.push(c.data);
+    }
+    return out;
+}
+const filesLedger = (o) => new FilesLedger(o.ledger, o.writer);
+/** The sources this machine can run, from the environment. */
+export function sourcesHere(printed, ledger, ytDlp, warn = (l) => console.error(l)) {
+    const out = [];
+    if (printed.SEARXNG_URL)
+        out.push(searxng({
+            url: printed.SEARXNG_URL,
+            ...(printed.SEARXNG_TOKEN ? { token: printed.SEARXNG_TOKEN } : {}),
+        }));
+    const exaKeys = keys(printed, "EXA_API_KEY");
+    if (exaKeys.length)
+        out.push(exa({ keys: exaKeys }));
+    const geminiKeys = keys(printed, "GEMINI_API_KEY");
+    out.push(ytdlpSource({
+        ytDlp,
+        ...(geminiKeys.length ? { video: () => geminiVideo(geminiKeys) } : {}),
+    }));
+    if (printed.BIRDWATCH_CONTACT) {
+        out.push(fetcherSource({ fetcher: new PoliteFetcher(userAgent(printed.BIRDWATCH_CONTACT)) }));
+        const categories = (printed.BIRDWATCH_ARXIV_CATEGORIES ?? "")
+            .split(",")
+            .map((c) => c.trim())
+            .filter(Boolean);
+        out.push(arxivSource({
+            agent: userAgent(printed.BIRDWATCH_CONTACT),
+            categories,
+            ...(printed.OPENALEX_API_KEY ? { openalexKey: printed.OPENALEX_API_KEY } : {}),
+            ...(printed.SEMANTIC_SCHOLAR_API_KEY ? { s2Key: printed.SEMANTIC_SCHOLAR_API_KEY } : {}),
+        }));
+    }
+    else
+        warn("no BIRDWATCH_CONTACT (an email address or URL for site operators): pages stay unopened");
+    const sites = printed.AUTOBROWSE_URL
+        ? httpLadderClient({ url: printed.AUTOBROWSE_URL, token: printed.AUTOBROWSE_TOKEN ?? null })
+        : printed.RESTATE_INGRESS_URL
+            ? ingressLadderClient({
+                url: printed.RESTATE_INGRESS_URL,
+                token: printed.RESTATE_AUTH_TOKEN ?? null,
+                ...(printed.AUTOBROWSE_SERVICE ? { service: printed.AUTOBROWSE_SERVICE } : {}),
+                caller: `birdwatch:${printed.BIRDWATCH_AGENT ?? "runner"}`,
+            })
+            : null;
+    if (sites) {
+        // The account each site reader signs in as: the caller's choice, never a default here.
+        const accounts = accountsFrom(printed.BIRDWATCH_ACCOUNTS);
+        const reddit = accounts.get("reddit");
+        out.push(ladderSource({ sites }), redditSource({ sites, ...(reddit ? { account: reddit } : {}) }), facebookSource({ sites }), googleSource({ sites }));
+    }
+    out.push(ledgerSource(ledger));
+    return registry(...out);
+}
+/**
+ * The run's allow-list: the names wanted that exist here. `opens`: unless the list was given by
+ * hand, every other opener here, let in to open and follow, never to search (arxiv searched every
+ * web run when it joined the list). A name wanted that this machine lacks is dropped with a line on stderr.
+ */
+export function allowList(sources, wanted, byHand, warn = (l) => console.error(l)) {
+    const out = [];
+    for (const name of wanted) {
+        if (sources.has(name))
+            out.push(name);
+        else
+            warn(`no source named ${name} here: skipped`);
+    }
+    const opens = byHand
+        ? []
+        : [...sources.values()].filter((s) => s.open && !out.includes(s.name)).map((s) => s.name);
+    return { sources: out, opens };
+}
+const progress = (e) => console.error(`${e.run} ${e.round}.${e.step} ${e.ok ? "ok" : "gave up"} ${e.ms}ms${e.note ? `: ${e.note}` : ""}`);
+/** A kind the engine plans for; anything else is the caller's mistake, said in words. */
+export const kindOf = (kind) => {
+    const k = PLAN_KINDS.find((p) => p === kind);
+    if (!k)
+        throw new Error(`no kind "${kind}": the kinds are ${PLAN_KINDS.join(", ")}`);
+    return k;
+};
+/** Prints what a command did as JSON; a step that gave up exits 2, like `run`. */
+function printDid(did) {
+    console.error(`${did.run} ${did.round}.${did.step} ${did.ok ? "ok" : "gave up"}${did.note ? `: ${did.note}` : ""}`);
+    console.log(JSON.stringify(did, null, 2));
+    if (!did.ok)
+        process.exitCode = 2;
+}
+/** Whole stdin, for a batch of queries as JSON. */
+async function stdinText() {
+    let text = "";
+    for await (const chunk of process.stdin)
+        text += chunk;
+    return text;
+}
+export function addEngineCommands(program, deps = {}) {
+    const ledgerOf = deps.ledger ?? filesLedger;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const common = (c) => c
+        .option("--ledger <dir>", "the ledger folder", process.env.BIRDWATCH_LEDGER ?? "./ledger")
+        .option("--writer <name>", "this terminal's file in the ledger", process.env.BIRDWATCH_WRITER ?? userInfo().username);
+    const machine = (c) => c
+        .option("--model <spec>", "a models spec: anthropic[:haiku|sonnet|opus], gateway[:alias], gemini[:id], claude-code, command:<cmd>, ...", process.env.BIRDWATCH_MODEL ?? DEFAULT_MODEL)
+        .option("--no-model", "no model: nothing extracted or checked")
+        .option("--decider <spec>", "the model for the steps that decide what comes next (plan, triage, review); default: anthropic:sonnet when --model is Haiku, else --model", process.env.BIRDWATCH_DECIDER)
+        .option("--judge <spec>", "cheap typed answers on every hit, page and finding (a hint and a router): jev[:model], fake, off", process.env.BIRDWATCH_JUDGE ?? (process.env.TYPESAFE_API_KEY ? "jev" : "off"))
+        .option("--no-judge", "no judge")
+        .option("--yt-dlp <cmd>", "the yt-dlp command", process.env.BIRDWATCH_YTDLP ?? "yt-dlp");
+    const agent = (c) => c
+        .option("--by <agent>", "the agent's id on what it writes", process.env.BIRDWATCH_AGENT)
+        .option("--human [name]", "the record is the person's word, relayed: from human, by their name (default: the writer)");
+    /** The ledger, this machine's sources and the model, from the options. */
+    const setup = (o) => {
+        const ledger = ledgerOf(o);
+        const sources = deps.sources
+            ? deps.sources(o, ledger)
+            : sourcesHere(process.env, ledger, o.ytDlp);
+        const model = o.model === false ? null : (deps.model ?? modelFromSpec)(o.model, process.env);
+        // Haiku restates, Sonnet decides: a few cents a run.
+        const deciderSpec = o.decider ??
+            (o.model === "anthropic" || o.model === "anthropic:haiku" ? "anthropic:sonnet" : null);
+        const decider = model && deciderSpec ? (deps.model ?? modelFromSpec)(deciderSpec, process.env) : null;
+        const judge = o.judge === false ? null : (deps.judge ?? judgeFromSpec)(o.judge, process.env);
+        return { ledger, sources, model, judge, ...(decider ? { decider } : {}) };
+    };
+    /**
+     * The ledger's tuned plan file for the kind (the stock one when none), its sources the run's
+     * allow-list: the names given by hand, else `first` then the plan file's, as far as this
+     * machine has them. `opens`: the other openers, let in to open and follow only.
+     */
+    const planFileOf = async (ledger, sources, kind, byHand, first = []) => {
+        const stock = defaultPlanFile(kind);
+        const tuned = (await ledger.readPlan?.(kind)) ?? stock;
+        if (tuned.version < stock.version)
+            console.error(`plan file ${kind} is version ${tuned.version}; birdwatch ships ${stock.version}: delete it to take the new one`);
+        const wanted = byHand ?? [...first, ...tuned.sources];
+        // The planner narrows to the plan file's sources, so the run's allow-list goes in as the plan file's.
+        const { sources: list, opens } = allowList(sources, wanted, !!byHand);
+        return { planFile: { ...tuned, sources: list }, opens };
+    };
+    const depsOf = (s, runner) => ({
+        ...s,
+        extractor: deps.extractor ?? claimExtractor,
+        clock: () => new Date(),
+        ids: ulids(),
+        runner,
+    });
+    /** The agent's id: `--by` or BIRDWATCH_AGENT. Every record it writes names it. */
+    const agentOf = (o) => {
+        if (!o.by)
+            throw new Error("name the agent: --by <id> or BIRDWATCH_AGENT");
+        return o.by;
+    };
+    /** Who a record is from: the person through the agent (`--human`), else the agent. */
+    const whoOf = (o) => o.human
+        ? { from: "human", by: o.human === true ? o.writer : o.human }
+        : { from: "ai", by: agentOf(o) };
+    machine(common(program.command("run [ask]")))
+        .description("run an ask through plan, fetch, triage, read, extract, check and review; prints the run as JSON")
+        .option("--kind <kind>", `one of ${PLAN_KINDS.join(", ")}`, "web")
+        .option("--known <line...>", "what is known already, one line each, with its URL or ledger id; a line without one is a premise")
+        .option("--premise <line...>", "what the ask takes as given (a buyer, an offer, a price): the tree tests each")
+        .option("--criterion <name=question...>", 'a yes-or-no test of a good source (code="Is code released?"): the judge asks it on every hit and every page read whole, a hint only')
+        .option("--steer <line...>", "what you say to the model, first in every prompt")
+        .option("--site <host>", "the site the ask is about")
+        .option("--sources <name...>", "the allow-list for this run (default: the plan file's, as far as this machine has them)")
+        .option("--propose <terms...>", "queries from you, merged with the model's in round 1")
+        .option("--url <url...>", "pages you want read: a paste source, first in the allow-list")
+        .option("--by <who>", "who proposes or pastes", process.env.BIRDWATCH_WRITER ?? userInfo().username)
+        .option("--resume <run>", "continue an earlier run from the step it stopped on")
+        .option("--run <id>", "the new run's id")
+        .option("--pause", "stop after each round's review: `birdwatch steer`, then --resume")
+        .option("--parent <run>", "a new run's parent: this run is a child of it (one niche of a wide run)")
+        .option("--why <why>", "with --parent: why this child")
+        .action(async (ask, o) => {
+        if (!ask && !o.resume)
+            throw new Error("run needs an ask, or --resume <run>");
+        const kind = kindOf(o.kind);
+        const s = setup(o);
+        const { ledger, sources } = s;
+        if (o.url?.length)
+            sources.set("paste", paste(o.url.map((url) => ({ url })), o.by));
+        const { planFile, opens } = await planFileOf(ledger, sources, kind, o.sources, o.url?.length ? ["paste"] : []);
+        const byHand = [
+            ...(o.propose ?? []).map((terms) => ({ kind, terms, why: "proposed by hand" })),
+            // The paste answers the first query it sees: this one, when nothing else is proposed.
+            ...(o.url?.length && !o.propose?.length && ask
+                ? [{ kind, terms: ask, why: "the pasted pages" }]
+                : []),
+        ];
+        const proposals = byHand.length
+            ? [{ from: "human", by: o.by, queries: byHand }]
+            : [];
+        const id = o.resume ?? o.run ?? ulids()();
+        const engineDeps = depsOf(s, o.writer);
+        const options = {
+            ...(ask
+                ? {
+                    ask: {
+                        text: ask,
+                        kind,
+                        known: o.known ?? [],
+                        premises: o.premise ?? [],
+                        criteria: criteriaOf(o.criterion),
+                        steer: o.steer ?? [],
+                        ...(o.site ? { site: o.site } : {}),
+                    },
+                }
+                : {}),
+            planFile,
+            opens,
+            proposals,
+            onStep: progress,
+            ...(o.pause ? { pause: true } : {}),
+            ...(o.parent ? { parent: { run: o.parent, why: o.why ?? "" } } : {}),
+        };
+        let result = null;
+        for (let n = 0; result === null; n++) {
+            try {
+                result = await run(engineDeps, {
+                    ...options,
+                    ...(n === 0 && !o.resume ? { run: id } : { resume: id }),
+                });
+            }
+            catch (err) {
+                if (!isTransient(err))
+                    throw err;
+                if (n >= RESUMES) {
+                    console.error(`${id}: ${err.message}; stopped after ${RESUMES} resumes`);
+                    break;
+                }
+                const ms = resumeWaitMs(n + 1, err.retryAfter);
+                console.error(`${id}: ${err.message}; resume ${n + 1} of ${RESUMES} in ${Math.round(ms / 1000)}s`);
+                await sleep(ms);
+            }
+        }
+        const state = result?.state ?? fold(id, await ledger.trace(id));
+        if (result?.paused)
+            console.error(`${id}: paused after round ${state.edges.length}; birdwatch add steer ${id} "<their words>" --human, then birdwatch run --resume ${id} --pause`);
+        if (result?.parked)
+            console.error(`${id}: ${result.parked}; birdwatch run --resume ${id} goes one more round, birdwatch plan --run ${id} opens it by hand`);
+        const cost = costOf(state.spends);
+        // The last review's word: what the ask still lacks, or that it is answered.
+        const last = state.edges.at(-1);
+        if (last)
+            console.error(`${id}: ${last.next}: ${last.why}`);
+        console.error(`${id}: ${cost.line}`);
+        console.log(JSON.stringify({
+            run: id,
+            rounds: state.round,
+            cost: cost.total,
+            finished: result?.finished ?? false,
+            ...(result?.paused ? { paused: true } : {}),
+            ...(result?.parked ? { parked: result.parked } : {}),
+            note: result ? result.note : "stopped on a transient failure: --resume to go on",
+            ...(last ? { edge: { next: last.next, why: last.why } } : {}),
+            hits: state.hits.length,
+            documents: state.documents.length,
+            findings: state.findings.filter((f) => state.called.get(f.id) !== "drop"),
+            spends: state.spends.map(({ source, op, about, ok, cost, ms, usd, tokens }) => ({
+                source,
+                op,
+                about,
+                ok,
+                cost,
+                ms,
+                ...(usd !== undefined ? { usd } : {}),
+                ...(tokens ? { tokens } : {}),
+            })),
+            problems: ledger.problems ?? [],
+        }, null, 2));
+        if (!result?.finished && !result?.paused && !result?.parked)
+            process.exitCode = 2;
+    });
+    agent(machine(common(program.command("plan [ask]"))))
+        .description("open a round: a new run from an ask, or the next round of --run after an edge that said again. Prints the run id")
+        .option("--run <id>", "the run whose next round to open")
+        .option("--kind <kind>", `one of ${PLAN_KINDS.join(", ")}`, "web")
+        .option("--known <line...>", "what is known already, one line each, with its URL or ledger id; a line without one is a premise")
+        .option("--premise <line...>", "what the ask takes as given (a buyer, an offer, a price): the tree tests each")
+        .option("--criterion <name=question...>", 'a yes-or-no test of a good source (code="Is code released?"): the judge asks it on every hit and every page read whole, a hint only')
+        .option("--site <host>", "the site the ask is about")
+        .option("--sources <name...>", "the allow-list for this run (default: the plan file's, as far as this machine has them)")
+        .option("--parent <run>", "a new run's parent: this run is a child of it (one niche of a wide run)")
+        .option("--why <why>", "with --parent: why this child")
+        .action(async (ask, o) => {
+        if (!ask && !o.run)
+            throw new Error("plan needs an ask, or --run <run>");
+        const s = setup(o);
+        const kind = o.run
+            ? (fold(o.run, await s.ledger.trace(o.run)).snapshot?.ask.kind ?? kindOf(o.kind))
+            : kindOf(o.kind);
+        const { planFile, opens } = await planFileOf(s.ledger, s.sources, kind, o.sources);
+        printDid(await planRound(depsOf(s, agentOf(o)), {
+            ...(o.run ? { run: o.run } : {}),
+            ...(ask
+                ? {
+                    ask: {
+                        text: ask,
+                        kind,
+                        known: o.known ?? [],
+                        premises: o.premise ?? [],
+                        criteria: criteriaOf(o.criterion),
+                        ...(o.site ? { site: o.site } : {}),
+                    },
+                }
+                : {}),
+            planFile,
+            opens,
+            model: s.model?.id ?? null,
+            ...(o.parent ? { parent: { run: o.parent, why: o.why ?? "" } } : {}),
+        }));
+    });
+    agent(machine(common(program.command("search <run> [terms]"))))
+        .description("one query in the agent's name, then every searcher on every unsearched query of the round; the new hits as JSON. No terms: on stdin, a JSON array of {terms, why, site?}, or a tree {facets: [{name, why, tries: [[{terms, why, site?}]]}]}: one tier. First call: every facet's first try. After triage, the same tree again: the next try of each facet under the guide's thin in kept hits; a facet with uncalled hits waits")
+        .option("--why <why>", "why this query serves the ask")
+        .option("--site <host>", "keep the query on one host")
+        .option("--facet <name>", "the tree's facet this query serves")
+        .option("--all", "tree: the next try of every facet that has one, whatever triage kept")
+        .action(async (runId, terms, o) => {
+        if (!terms && process.stdin.isTTY)
+            throw new Error("search: terms, or a JSON array of {terms, why} or a tree on stdin");
+        const s = setup(o);
+        const deps = depsOf(s, agentOf(o));
+        if (terms) {
+            const q = {
+                terms,
+                why: o.why ?? "",
+                ...(o.site ? { site: o.site } : {}),
+                ...(o.facet ? { facet: o.facet } : {}),
+            };
+            printDid(await search(deps, runId, [q], whoOf(o)));
+            return;
+        }
+        const input = JSON.parse(await stdinText());
+        if (Array.isArray(input)) {
+            if (!input.length)
+                throw new Error("search: no queries");
+            printDid(await search(deps, runId, input, whoOf(o)));
+            return;
+        }
+        const did = await searchTree(deps, runId, QueryTree.parse(input), whoOf(o), {
+            all: o.all ?? false,
+        });
+        printDid(did);
+    });
+    common(program.command("show <run> <document>"))
+        .description("a document's text as the run stored it, for the agent to read itself")
+        .option("--head <chars>", "only the first N characters", Number)
+        .action(async (runId, document, o) => {
+        const ledger = ledgerOf(o);
+        const state = fold(runId, await ledger.trace(runId));
+        const d = state.documents.find((x) => x.id === document);
+        if (!d)
+            throw new Error(`run ${runId}: no document ${document}`);
+        console.error(`${d.id} ${d.url}${d.title ? ` | ${d.title}` : ""}${d.date ? ` | ${d.date}` : ""} | ${d.text.length} chars`);
+        console.log(o.head ? d.text.slice(0, o.head) : d.text);
+    });
+    agent(machine(common(program.command("open <run> [hit...]"))))
+        .description("keep the hits named (and a hit per --url), then read every kept hit of the run that has no document yet")
+        .option("--url <url...>", "pages the agent names itself")
+        .option("--why <why>", "why read these (with hits or --url)")
+        .option("--with <source...>", "open sources this machine has that the run's allow-list lacks (`sources` lists them)")
+        .action(async (runId, hits, o) => {
+        const s = setup(o);
+        printDid(await open(depsOf(s, agentOf(o)), runId, {
+            hits,
+            ...(o.url ? { urls: o.url } : {}),
+            ...(o.why ? { why: o.why } : {}),
+            ...(o.with ? { with: o.with } : {}),
+        }, whoOf(o)));
+    });
+    agent(machine(common(program.command("follow <run> [url]"))))
+        .description(`what a person does after a good page: --as posts (its channel's or author's own posts: a YouTube channel or video, a TikTok profile, a Reddit user), similar (pages like it), refs (what a paper cites) or citers (what cites it, most cited first); the hits go through the same calls and reads.`)
+        .requiredOption("--as <as>", "posts, similar, refs or citers")
+        .requiredOption("--why <why>", "why this page's neighbors may answer the ask")
+        .option("--from <document>", "the read page that led here (its URL when no url is given)")
+        .option("--with <source...>", "follow sources this machine has that the run's allow-list lacks")
+        .action(async (runId, url, o) => {
+        const s = setup(o);
+        printDid(await follow(depsOf(s, agentOf(o)), runId, {
+            as: FollowAs.parse(o.as),
+            why: o.why,
+            ...(url ? { url } : {}),
+            ...(o.from ? { document: o.from } : {}),
+            ...(o.with ? { with: o.with } : {}),
+        }, whoOf(o)));
+    });
+    agent(machine(common(program.command("extract <run> [document...]"))))
+        .description("the extractor (a model behind the quote gate) over the documents named, else every one without a verdict; findings as JSON")
+        .action(async (runId, documents, o) => {
+        const s = setup(o);
+        printDid(await extract(depsOf(s, agentOf(o)), runId, documents.length ? documents : undefined));
+    });
+    agent(machine(common(program.command("check <run> [finding...]"))))
+        .description("a model reads each finding against its document: the findings named, else with --patterns every unchecked finding a pattern rests on, else a sample spread across documents. The judge first reads every kept finding; each one it doubts joins the sample. One that fails gets a drop call")
+        .option("-n <n>", "the sample's size (default: the budget's checks or a tenth of the kept findings, whichever is more)", (v) => Number(v))
+        .option("--patterns", "every unchecked finding a pattern rests on")
+        .action(async (runId, findings, o) => {
+        const s = setup(o);
+        printDid(await check(depsOf(s, agentOf(o)), runId, {
+            ...(findings.length ? { findings } : {}),
+            ...(o.n !== undefined ? { n: o.n } : {}),
+            ...(o.patterns ? { patterns: true } : {}),
+        }));
+    });
+    const added = async (o, runId, a) => {
+        const s = { ledger: ledgerOf(o), sources: registry(), model: null, judge: null };
+        const { record, warnings } = await add(depsOf(s, agentOf(o)), runId, a, whoOf(o));
+        for (const w of warnings)
+            console.error(`${runId}: ${w}`);
+        console.log(JSON.stringify(record));
+    };
+    const adds = program
+        .command("add")
+        .description("one record by hand, in the agent's name or (--human) the person's");
+    agent(common(adds.command("query <run> <terms>")))
+        .description("a query for the next search")
+        .requiredOption("--why <why>", "why it serves the ask")
+        .option("--site <host>")
+        .option("--facet <name>", "the tree's facet it serves")
+        .action((runId, terms, o) => added(o, runId, {
+        type: "query",
+        terms,
+        why: o.why,
+        ...(o.site ? { site: o.site } : {}),
+        ...(o.facet ? { facet: o.facet } : {}),
+    }));
+    agent(common(adds.command("check <run> <finding>")))
+        .description("the agent's own check of a finding against its document: --ok or --fail (a fail also drops it)")
+        .option("--ok", "the quote backs the sentence")
+        .option("--fail", "it does not")
+        .requiredOption("--why <why>")
+        .action((runId, finding, o) => {
+        if (o.ok === o.fail)
+            throw new Error("check: --ok or --fail");
+        return added(o, runId, { type: "check", on: finding, ok: !!o.ok, why: o.why });
+    });
+    agent(common(adds.command("finding <run> <document>")))
+        .description("a finding the agent read itself: the sentence and its quote, which must be on the document word for word")
+        .requiredOption("--text <sentence>", "one plain sentence")
+        .requiredOption("--quote <quote>", "copied from the document")
+        .action((runId, document, o) => added(o, runId, { type: "finding", document, text: o.text, quote: o.quote }));
+    agent(common(adds.command("call <run> <on> <verdict>")))
+        .description("keep or drop a hit (read it or not) or a finding, with why")
+        .requiredOption("--why <why>")
+        .action((runId, on, verdict, o) => {
+        if (verdict !== "keep" && verdict !== "drop")
+            throw new Error("verdict: keep or drop");
+        return added(o, runId, { type: "call", on, verdict, why: o.why });
+    });
+    agent(common(adds.command("edge <run> <next>")))
+        .description("the round's edge: again (a new round), stop, or back --to <step>")
+        .requiredOption("--why <why>")
+        .option("--to <step>", "with back: plan, fetch, triage, read or extract")
+        .action((runId, next, o) => {
+        if (next !== "again" && next !== "stop" && next !== "back")
+            throw new Error("next: again, stop or back");
+        return added(o, runId, {
+            type: "edge",
+            next,
+            ...(o.to ? { to: PlanStep.parse(o.to) } : {}),
+            why: o.why,
+        });
+    });
+    agent(common(adds.command("steer <run> <text>")))
+        .description("what the person says to the run: first in every prompt after it (always --human)")
+        .action((runId, text, o) => added({ ...o, human: o.human ?? true }, runId, { type: "steer", text }));
+    agent(common(adds.command("gap <run> <text>")))
+        .description("what the round still lacks")
+        .option("--on <id>", "the query or hit it is about")
+        .action((runId, text, o) => added(o, runId, { type: "gap", note: text, ...(o.on ? { on: o.on } : {}) }));
+    agent(common(adds.command("pattern <run> <text>")))
+        .description("what several kept findings say together: one sentence; the count of distinct sites is computed")
+        .requiredOption("--on <finding...>", "the findings it rests on")
+        .action((runId, text, o) => added(o, runId, { type: "pattern", text, findings: o.on }));
+    agent(common(adds.command("dead <run> <facet>")))
+        .description("give up on a facet, with why: later tries and rounds skip it, and a parent's next plan reads it as a dead end")
+        .requiredOption("--why <why>")
+        .action((runId, facet, o) => added(o, runId, { type: "dead", facet, why: o.why }));
+    agent(common(adds.command("person <run> <name>")))
+        .description("one person across platforms: their profile URLs and the names they post under. The brief counts kept findings per person; follow each profile's posts")
+        .option("--profile <url...>", "a channel, a Substack, an X account, a blog")
+        .option("--aka <name...>", "a channel name or handle they post under")
+        .requiredOption("--why <why>")
+        .action((runId, name, o) => added(o, runId, {
+        type: "person",
+        name,
+        profiles: o.profile ?? [],
+        aka: o.aka ?? [],
+        why: o.why,
+    }));
+    agent(common(adds.command("class <run> <on> <class>")))
+        .description(`what kind of source a document is (its findings take it), or one finding when it differs: ${SOURCE_CLASSES.join(", ")}. Patterns count sites per class`)
+        .requiredOption("--why <why>")
+        .action((runId, on, cls, o) => added(o, runId, { type: "class", on, class: SourceClass.parse(cls), why: o.why }));
+    agent(common(program.command("accept <run> <take>")))
+        .description("take the judge's guesses over a bar, in your name with your why: `class --min p` classes every unclassed document whose guess is at least p; `keep --over p` and `drop --under p` call every uncalled hit by how likely it serves the ask")
+        .requiredOption("--why <why>", "why this bar")
+        .option("--min <p>", "class: the guess's least probability", (v) => Number(v))
+        .option("--over <p>", "keep: serves the ask over p", (v) => Number(v))
+        .option("--under <p>", "drop: serves the ask under p", (v) => Number(v))
+        .action(async (runId, take, o) => {
+        const bar = (v, flag) => {
+            if (v === undefined)
+                throw new Error(`accept ${take}: ${flag} <p>`);
+            return v;
+        };
+        const a = take === "class"
+            ? { take, min: bar(o.min, "--min"), why: o.why }
+            : take === "keep"
+                ? { take, over: bar(o.over, "--over"), why: o.why }
+                : take === "drop"
+                    ? { take, under: bar(o.under, "--under"), why: o.why }
+                    : (() => {
+                        throw new Error(`accept: class, keep or drop; got ${take}`);
+                    })();
+        const s = { ledger: ledgerOf(o), sources: registry(), model: null, judge: null };
+        const out = await accept(depsOf(s, agentOf(o)), runId, a, whoOf(o));
+        console.error(`${runId}: ${out.wrote.length} taken, ${out.skipped} under the bar`);
+        console.log(JSON.stringify(out, null, 2));
+    });
+    agent(common(adds.command("draft <run>")))
+        .description("a rough draft over the run's kept findings and patterns, on stdin as JSON [{title, body, cites: [finding or pattern id...]}]: an item that cites nothing kept, or has a number no cited finding has, is dropped. A draft, never the final")
+        .requiredOption("--for <what>", "what it is for: a decision memo, an SOP outline")
+        .action(async (runId, o) => {
+        const parsed = JSON.parse(await stdinText());
+        const items = Array.isArray(parsed) ? parsed : parsed?.items;
+        if (!Array.isArray(items))
+            throw new Error("draft: stdin is a JSON array of items, or {items}");
+        return added(o, runId, { type: "draft", for: o.for, items: items });
+    });
+    common(program.command("learn <kind>"))
+        .description("the next version of a kind's plan file, from what a run taught: sources, budget, age, a prompt; --show prints the current one")
+        .option("--show", "print the current plan file, write nothing")
+        .option("--sources <name...>", "the allow-list, in order of preference")
+        .option("--queries <n>", "queries per round", Number)
+        .option("--reads <n>", "reads per round", Number)
+        .option("--rounds <n>", "rounds before the runner parks", Number)
+        .option("--checks <n>", "findings checked per round", Number)
+        .option("--age <sentence>", "how much a source's age counts")
+        .option("--propose <file>", "the propose prompt, from a file")
+        .option("--triage <file>", "the triage prompt, from a file")
+        .option("--review <file>", "the review prompt, from a file")
+        .option("--thin <n>", "new hits under which a tree's try is thin, so the next try runs", Number)
+        .option("--tree <file>", "the query tree's guide, as JSON {facets: [{name, why}], thin}")
+        .action(async (kind, o) => {
+        const k = kindOf(kind);
+        const ledger = ledgerOf(o);
+        const current = (await ledger.readPlan?.(k)) ?? defaultPlanFile(k);
+        if (o.show) {
+            console.log(JSON.stringify(current, null, 2));
+            return;
+        }
+        if (!ledger.writePlan)
+            throw new Error("this ledger keeps no plan files");
+        const text = (file) => readFile(file, "utf8");
+        const budget = {
+            ...(o.queries !== undefined ? { queries: o.queries } : {}),
+            ...(o.reads !== undefined ? { reads: o.reads } : {}),
+            ...(o.rounds !== undefined ? { rounds: o.rounds } : {}),
+            ...(o.checks !== undefined ? { checks: o.checks } : {}),
+        };
+        const next = tunePlan(current, {
+            ...(o.sources ? { sources: o.sources } : {}),
+            budget,
+            ...(o.age !== undefined ? { age: o.age } : {}),
+            ...(o.propose ? { propose: await text(o.propose) } : {}),
+            ...(o.triage ? { triage: await text(o.triage) } : {}),
+            ...(o.review ? { review: await text(o.review) } : {}),
+            ...(o.tree
+                ? { tree: TreeGuide.parse(JSON.parse(await text(o.tree))) }
+                : o.thin !== undefined
+                    ? { tree: { ...treeOf(current), thin: o.thin } }
+                    : {}),
+        });
+        const path = await ledger.writePlan(next);
+        console.error(`${k}: plan file version ${next.version} at ${path}`);
+        console.log(JSON.stringify(next, null, 2));
+    });
+    common(program.command("brief <run>"))
+        .description("the run as the agent needs it: the ask, what is known, what the last round left open, hits to call, documents to extract, findings, checks, edges, yield, cost")
+        .action(async (runId, o) => {
+        const s = { ledger: ledgerOf(o), sources: registry(), model: null, judge: null };
+        console.log(JSON.stringify(await brief(depsOf(s, o.writer), runId), null, 2));
+    });
+    common(program.command("recall <terms...>"))
+        .description("what earlier runs found on these terms: each finding with its quote, URL, source date and run, best match first; dropped findings left out")
+        .option("-n <n>", "at most this many (default 20)", Number)
+        .option("--not <run>", "leave out this run (the one asking)")
+        .option("--kind <kind>", "only runs of this ask kind")
+        .option("--also <dir...>", "more ledger folders to read with --ledger (one per day)")
+        .action(async (terms, o) => {
+        const ledgers = [
+            ledgerOf(o),
+            ...(o.also ?? []).map((dir) => ledgerOf({ ...o, ledger: dir })),
+        ];
+        const found = await recall(joined(ledgers), terms.join(" "), {
+            ...(o.n !== undefined ? { n: o.n } : {}),
+            ...(o.not ? { not: o.not } : {}),
+            ...(o.kind ? { kind: kindOf(o.kind) } : {}),
+        });
+        console.log(JSON.stringify(found, null, 2));
+    });
+    common(program.command("trace <run>"))
+        .description("every record of a run, in time order, as JSON lines")
+        .option("--type <type...>", "only these record types")
+        .action(async (id, o) => {
+        const ledger = ledgerOf(o);
+        const records = await ledger.trace(id);
+        if (!records.length)
+            throw new Error(`run ${id}: no records`);
+        for (const r of records)
+            if (!o.type || o.type.includes(r.type))
+                console.log(JSON.stringify(r));
+        for (const p of ledger.problems ?? [])
+            console.error(`${p.file}:${p.line}: ${p.why}`);
+    });
+    common(program.command("serve"))
+        .description("the ledger over HTTP for a viewer, read only: GET /runs, /runs/:run, /runs/:run/documents/:doc, and /events (one event per changed run)")
+        .option("--port <n>", "the port", (v) => Number(v), SERVE_PORT)
+        .option("--host <host>", "the address to bind", "127.0.0.1")
+        .option("--origin <url...>", "the pages that may read it, besides any localhost", SERVE_ORIGINS)
+        .action(async (o) => {
+        const ledger = new FilesLedger(o.ledger, o.writer);
+        await mkdir(`${o.ledger}/runs`, { recursive: true });
+        const s = { ledger, sources: registry(), model: null, judge: null };
+        const app = serveApp({
+            deps: depsOf(s, o.writer),
+            runs: () => ledger.runs(),
+            changes: watchRuns(o.ledger),
+            origins: o.origin,
+        });
+        serve({ fetch: app.fetch, port: o.port, hostname: o.host }, (a) => console.error(`birdwatch serve: http://${a.address}:${a.port} over ${o.ledger}`));
+        await new Promise(() => { });
+    });
+    common(program.command("yield"))
+        .description("hits, reads, proposed and kept per source, by, channel and kind, over every run")
+        .option("--source <name>")
+        .option("--by <who>")
+        .option("--channel <name>")
+        .option("--kind <kind>")
+        .action(async (o) => {
+        const rows = await ledgerOf(o).yield({
+            ...(o.source ? { source: o.source } : {}),
+            ...(o.by ? { by: o.by } : {}),
+            ...(o.channel ? { channel: o.channel } : {}),
+            ...(o.kind ? { kind: defaultPlanFile(o.kind).kind } : {}),
+        });
+        console.log(JSON.stringify(rows, null, 2));
+    });
+    common(program.command("sources"))
+        .description("the sources this machine can run, from the environment")
+        .option("--yt-dlp <cmd>", "the yt-dlp command", process.env.BIRDWATCH_YTDLP ?? "yt-dlp")
+        .action(async (o) => {
+        const ledger = ledgerOf(o);
+        const sources = deps.sources
+            ? deps.sources(o, ledger)
+            : sourcesHere(process.env, ledger, o.ytDlp);
+        const rows = [...sources.values()].map(({ name, kind, cost, from }) => ({
+            name,
+            kind,
+            cost,
+            from: from ?? "tool",
+        }));
+        console.log(JSON.stringify(rows, null, 2));
+    });
+}
+//# sourceMappingURL=engine-cli.js.map