@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/dist/src/include.d.ts

@@ -0,0 +1,435 @@
+import { splitModelSpec, type ScanDepth, type NitPolicy, type MemoryDelivery } from "./reviewconfig.js";
+import type { PassTier } from "./types.js";
+import type { EcosystemName } from "./ecosystem.js";
+import type { LensTuningMap } from "./lenstuning.js";
+/** The `{{name}}` grammar the agent build and the prompt renderer
+ * (packages/pi-plugin/src/templates.ts) share: bare word, no `:` — include directives
+ * (`{{include:path}}`) never match. */
+export declare const VARIABLE_RE: RegExp;
+/** Substitute every `{{name}}` in `text` from `vars` — the strict core of
+ * `expandVariables` and the renderer's `render`, each throwing its own error
+ * on `unknown`. A name `vars` does not itself hold is unknown, so an
+ * inherited property (`{{constructor}}`) never substitutes function text. */
+export declare function substituteVariables(text: string, vars: Readonly<Record<string, string>>): {
+    out: string;
+    unknown: string[];
+};
+/**
+ * The neutral fallback values: empty config values degrade to role wording,
+ * never to a hardcoded personal name.
+ */
+export declare const NEUTRAL_IDENTITY_VARS: Readonly<Record<string, string>>;
+/** The identity variable map from config ([owner] + [github]).
+ * Structural and tolerant of partial configs (hand-rolled test configs omit
+ * whole sections): every missing or empty value degrades to role wording. */
+export declare function identityVars(cfg: {
+    owner?: {
+        name?: string;
+    };
+    github?: {
+        repo?: string;
+        bot_login?: string;
+    };
+}): Record<string, string>;
+/**
+ * Expand `{{name}}` variables in `text`. An unknown name throws — the build
+ * must fail loudly rather than ship a literal `{{…}}` to a session.
+ */
+export declare function expandVariables(text: string, vars: Readonly<Record<string, string>>): string;
+export interface IncludeOptions {
+    /** Sandbox root every include path is resolved against. */
+    root: string;
+    /** Injected for tests; defaults to the real fs. */
+    readFile?: (path: string) => string;
+    /** Max nesting depth — a runaway include chain fails loudly. */
+    maxDepth?: number;
+}
+/** Expand every `{{include:…}}` directive in `text`, recursively. */
+export declare function expandIncludes(text: string, opts: IncludeOptions): string;
+export interface AgentDoc {
+    /** Raw frontmatter block *without* the `---` fences (may be ""). */
+    frontmatter: string;
+    /** Everything after the closing fence. */
+    body: string;
+    /** True when the source actually carried a frontmatter block. */
+    hasFrontmatter: boolean;
+}
+export declare function splitFrontmatter(text: string): AgentDoc;
+export declare function joinFrontmatter(doc: AgentDoc): string;
+/** Read the `name:` field of an agent's frontmatter (falls back to null). */
+export declare function frontmatterName(frontmatter: string): string | null;
+/** Rewrite the `model:` frontmatter field. Adds it when absent. */
+export declare function applyModelOverride(frontmatter: string, model: string): string;
+/** Rewrite the `name:` frontmatter field. Adds it when absent. */
+export declare function applyNameOverride(frontmatter: string, name: string): string;
+/** Rewrite the `thinking:` frontmatter field. Adds it when absent. */
+export declare function applyThinkingOverride(frontmatter: string, thinking: string): string;
+/**
+ * Strip agent-spawning tools from a built variant's `tools:` list.
+ *
+ * The seeds under `agents/` are canonical (AGENTS.md invariant 3) and list only
+ * read-only tools — this is the enforcement that keeps that true no
+ * matter what a future seed says, applied to the files agent discovery
+ * actually reads. A `tools:` line that names nothing else is dropped entirely
+ * rather than left empty (an empty list is not the same statement as no list).
+ */
+export declare function stripAgentSpawnTools(frontmatter: string): string;
+/**
+ * The memory tools a lens pass would hold if its leaf loaded the memory
+ * extension — exactly two, both read-only. No leaf does today
+ * (`LENS_LEAVES_LOAD_MEMORY` below), so no build grants them by default.
+ *
+ * A pass is a blank-slate evaluator of a diff; being able to look something up
+ * ("was this settled before?", "what does the reviewer's memory say about this
+ * subsystem?") would be a deliberate, narrow widening of that slate. Writing is
+ * not: everything durable a review produces is authored by the PR's one main
+ * session and the EOD curator, so a leaf that could write would be a second
+ * author of the reviewer's memory with none of the accounting.
+ *
+ * The frontmatter `tools:` line becomes the leaf session's tool allowlist
+ * (runLens hands it to PiHost.makeSession), so it decides which memory tools a
+ * leaf could ever activate; pi ignores an allowlisted name nothing registers.
+ * The inner layer is the vendored fork's own PATCH 2, which withholds
+ * `viking_write` in any leaf process regardless of what the frontmatter says.
+ */
+export declare const LEAF_MEMORY_TOOLS: readonly string[];
+/**
+ * Whether a lens leaf session loads the OpenViking memory extension. It does
+ * not, on any route: runLens (packages/pi-plugin/src/engine/lens/runlens.ts) gives a leaf the
+ * bash guard and, in a cache group, the leaf cache — nothing else — and that
+ * runner hosts every lens the built agents feed (a worker round, a debug round,
+ * the `qcr review` route, the bench). The memory extension goes only to a PR's
+ * main and answer sessions (src/engine/botsdk.ts). So a build grants a leaf no
+ * memory tool and no rule describing one unless its caller says the leaf has
+ * them (`BuildAgentsOptions.memory`). tests/lens-runner.test.ts holds this to
+ * the runner: every tool a default-built lens names exists in its session.
+ * Wire the extension into the leaves and this flips with it, in one change.
+ */
+export declare const LENS_LEAVES_LOAD_MEMORY = false;
+/** Drop `NOT_PI_TOOLS` from a built variant's `tools:` line. A line left
+ * as it was when it names none of them. */
+export declare function dropNonPiTools(frontmatter: string): string;
+/**
+ * Put exactly `tools` — `LEAF_MEMORY_TOOLS` by default, none for a leaf
+ * without memory — on a built variant's `tools:` line.
+ *
+ * Any other `viking_*` tool a seed might name is dropped first, so a future
+ * seed carrying `viking_write` cannot smuggle a write surface into a leaf —
+ * same enforcement stance as `stripAgentSpawnTools`, applied to the files
+ * agent discovery actually reads.
+ *
+ * A pass with no `tools:` line is left alone. An absent list means "whatever
+ * the harness gives you" while a present one is an allowlist, so adding the
+ * line would silently narrow that pass to two tools — a much bigger change
+ * than the one being made here. (Every seeded pass carries a tools line.)
+ */
+export declare function applyMemoryTools(frontmatter: string, tools?: readonly string[]): string;
+/** Split a "provider/model:thinking" spec into its model and thinking halves
+ * (config.ts owns the parse). Only a recognized thinking level after the last
+ * colon is treated as a suffix. The built `model:` field keeps the whole spec
+ * (pi's --model accepts the suffix); the split feeds the `thinking:` field and
+ * the BuiltAgent record. */
+export { splitModelSpec };
+/** All pass tiers, ascending. */
+export declare const PASS_TIERS: readonly PassTier[];
+/** The single pass that consumes findings instead of producing them. */
+export declare const VALIDATE_PASS = "pass-validate";
+/** Scan stage 1's lens (agents/scan/pass-scan.md) — built only into the
+ * companion's scan build. */
+export declare const SCAN_PASS = "pass-scan";
+/** No path predicate: added mid-round by the session, or planned by its
+ * content trigger when the diff touches synchronisation or the PR text says
+ * race/lock/thread-safe (heuristics.ts SUBLENS_TRIGGERS; the
+ * `concurrency-planned` addendum below). */
+export declare const CONCURRENCY_PASS = "pass-concurrency";
+/** Addable only: the ask-your-human lens. Same reason as
+ * pass-concurrency and a stronger one — no path predicate finds "code whose
+ * intent is not written down anywhere", and the deciding fact (is the answer
+ * in the repo at all?) is only visible after the diff has been read. */
+export declare const ASK_HUMAN_PASS = "pass-ask-human";
+/**
+ * Who an addendum binds:
+ *  - `"all"`    — every built pass, `pass-validate` included.
+ *  - `"lenses"` — every pass that PRODUCES findings, i.e. all but
+ *                 `pass-validate`. New lenses are covered automatically;
+ *                 the validator gets its own entry with its own wording.
+ *  - a list     — exactly the named passes (lens-specific rules).
+ */
+export type PassAddendumScope = "all" | "lenses" | readonly string[];
+export interface PassAddendum {
+    /** Stable id — what tests and commit messages refer to. */
+    id: string;
+    scope: PassAddendumScope;
+    /** Rendered verbatim into the built body, in registry order. */
+    text: string;
+    /**
+     * Composed only when the build's ecosystem is this one. Absent ⇒ every
+     * ecosystem. The gate keeps the entry at its registry position, so a
+     * Django build composes the same bytes with or without the gate, and a
+     * `none` build carries no framework rule and no claim about a pre-check that
+     * never runs.
+     */
+    ecosystem?: EcosystemName;
+    /**
+     * Composed only in a build of this mode. Absent ⇒ every build.
+     * `"scan"` entries redefine what a PR build takes for granted (a diff, a
+     * changed-line anchor), so they reach the companion's scan agent build and
+     * never a PR round's — the daemon's build is a `"pr"` build, always.
+     */
+    mode?: BuildMode;
+    /**
+     * Composed only in a scan build of this depth (`[scan] depth`). Absent ⇒
+     * every depth. Only a `mode: "scan"` entry carries one; a PR build is
+     * always `"standard"`, so a `"deep"` entry never reaches it.
+     */
+    depth?: ScanDepth;
+}
+/** What an agent build is for: a PR round (the daemon, the bench,
+ * the replay — the default) or the companion's whole-repo scan. */
+export type BuildMode = "pr" | "scan";
+/** Does `addendum` compose into a build for `ecosystem`? */
+export declare function addendumInEcosystem(addendum: PassAddendum, ecosystem: EcosystemName): boolean;
+/** Does `addendum` compose into a build of `mode`? */
+export declare function addendumInMode(addendum: PassAddendum, mode: BuildMode): boolean;
+/** Does `addendum` compose into a build of `depth`? */
+export declare function addendumInDepth(addendum: PassAddendum, depth: ScanDepth): boolean;
+/** Does `scope` bind `pass`? */
+export declare function addendumApplies(scope: PassAddendumScope, pass: string): boolean;
+/**
+ * The "Allowed commands: …" clause of the execution policy, rendered from the
+ * bash guard's own allowlist. The two halves of the no-exec policy are the
+ * prompt (what a pass is told it may run) and `packages/pi-plugin/extensions/bash-guard.ts` (what
+ * `checkBashCommand` lets through); deriving one from the other keeps the
+ * prompt from advertising a command the guard refuses, which costs a turn and
+ * reads to the model as a malfunction. `gh` is named last and qualified,
+ * because the guard admits only its read verbs.
+ */
+export declare const ALLOWED_COMMANDS_CLAUSE: string;
+/** The execution-policy + leaf rules — the registry's first entry; only its
+ * allowlist clause is derived. */
+export declare const EXECUTION_POLICY_ADDENDUM: string;
+/** Addenda that exist only when the config asks for them — composed after the
+ * registry by both agent builds (src/wire.ts, src/bench/runner.ts). */
+export declare function configAddenda(review: {
+    nits?: NitPolicy;
+    validate_demote?: boolean;
+    validate_consequence_rule?: boolean;
+    dedup_merge?: boolean;
+    validate_compact?: boolean;
+}): PassAddendum[];
+export declare const LESSON_VALIDATE_ADDENDUM_ID = "lesson-validate";
+/** The id of the same-day `[feedback]` validator addendum
+ * (`feedbackDayAddendum`, src/feedback.ts), composed beside the lesson one —
+ * reserved against profile packs by the same name (packages/pi-plugin/src/profiles.ts). */
+export declare const FEEDBACK_DAY_ADDENDUM_ID = "feedback-day-validate";
+/** The one downgrade word a dont-raise lesson licenses (packages/pi-plugin/src/findingsrecord.ts
+ * DOWNGRADE_WORDS). */
+export declare const LESSON_SHAPE_WORD = "lesson-shape";
+export declare const LESSON_VALIDATE_ADDENDUM: string;
+/**
+ * The lesson addenda: the validator's `lesson-validate`,
+ * composed only when `[memory] delivery = "on"` and the operator's kill
+ * switch is on. Anything else — `shadow`, `off`, the kill switch off, the
+ * bench (which never calls this) — is no addendum at all, so the build is
+ * byte-identical.
+ */
+export declare function lessonAddenda(opts: {
+    delivery: MemoryDelivery;
+    lessonsOff: boolean;
+}): PassAddendum[];
+/**
+ * The lesson addenda for the production agents build (wire.ts), from
+ * `[memory] delivery` and the operator's kill switch as the ledger holds it
+ * now (src/lessonledger.ts `lessonsOff`) — so `qcr lessons off` takes the
+ * validator's lesson authority away at the rebuild it triggers. No ledger yet,
+ * or one that cannot be read, reads as the switch on: the authority alone
+ * changes nothing without a round's `Lessons file:` line, and a ledger that
+ * cannot be read selects nothing for any round.
+ */
+export declare function lessonAddendaFor(delivery: MemoryDelivery, killSwitch: {
+    lessonsOff(): boolean;
+} | null | undefined): PassAddendum[];
+/** Composed only where the leaves hold the memory tools (BuildAgentsOptions.memory). */
+export declare const MEMORY_ADDENDUM_ID = "memory-read-only";
+export declare const CONSISTENCY_IDENTIFIERS_ADDENDUM: string;
+export declare const VALIDATE_EXTERNAL_SEMANTICS_ADDENDUM = "\n## External and documented semantics (sandbox rule)\nFor a candidate resting on what a library, tool, service or platform does:\n\n1. **Read the dependency sources first** \u2014 the *Third-party sources* block's package at the PR's locked version, citing `path:line` \u2014 and the repository's own usage (call sites, wrappers, tests, docs). What you read settles it: `refuted`, or it survives.\n2. **Documented core semantics and published standards are evidence, not assumptions**: the language, its runtime and standard library; SQL and the database engine in use (constraints, isolation, locking, bind-parameter and identifier limits); the datastore's commands and type errors; HTTP and other protocols; the operating system and process model; an RFC, a file-format or codec specification, a published grammar. Name the behaviour and where it is specified, and keep the candidate's severity and reachability.\n3. **Behaviour specific to one third-party tool that its sources and documentation do not settle**, when the mechanism IN THIS CODE is real, is a question, never a doubt: demote it to `P3` with the downgrade word `external-assumption`, its text naming the assumption (\"if `<tool>` treats `<input>` as `<X>`, then `<consequence>`\"); its reachability stays how often the path runs.\n4. **A missing source lowers `confidence`, never `reachability`** \u2014 reachability is how often the path runs. `unverifiable` is only for a mechanism you could not establish IN THIS CODE.\n\nNone of this lifts a candidate whose in-repo mechanism is wrong or that is below the bar; a claim one read of the repository could settle is still yours to settle.\n";
+export declare const VALIDATE_INTERFACE_CONTRACT_ADDENDUM: string;
+export declare const VALIDATE_MASKED_DEFECT_ADDENDUM: string;
+export declare const TESTS_LOOSENED_IS_BEHAVIOUR_ADDENDUM: string;
+export declare const TESTS_CANNOT_OBSERVE_ADDENDUM: string;
+export declare const TESTS_CANNOT_OBSERVE_VALIDATE_ADDENDUM: string;
+export declare const CONCURRENCY_DUPLICATE_INIT_ADDENDUM: string;
+export declare const WRITE_PREDICATE_SCOPE_ADDENDUM: string;
+export declare const PERSISTENCE_BYPASSES_CALLBACKS_ADDENDUM: string;
+export declare const REORDERED_STATEMENTS_ADDENDUM: string;
+export declare const ANCHOR_AT_CAUSE_ADDENDUM: string;
+export declare const VALIDATE_ANCHOR_AT_CAUSE_ADDENDUM: string;
+export declare const LINE_LOCAL_SLIPS_ADDENDUM: string;
+export declare const EXHAUST_THE_SITE_ADDENDUM = "\n## Exhaust the site before you move on (sandbox rule)\nWhen you CONFIRM a defect's mechanism, check before moving on: its **siblings** \u2014 the other overrides, fields, keys, branches, enum arms, registry entries or parallel methods the PR touches the same way, and the other readers of a shared value, callers of a shared helper or copies of a shared pattern; its **twin** \u2014 add/remove, setter/getter, the error path beside the success path, setup/cleanup, encode/decode; **every consequence** of an early return, a reorder, a bypass or a swallowed error (a refresh not fired, an event not sent, a counter not updated, a resource not freed); and the **other calls** in the same loop or chain that can fail. A site or consequence that needs its OWN fix is its own finding with its `path:line`; sites one fix covers are one finding with every site listed. Stay inside what this PR changed or newly exposes.\n";
+export declare const SWEEP_MECHANICAL_CHECKLIST_ADDENDUM: string;
+export declare const SWEEP_DOCS_AND_MOVES_ADDENDUM: string;
+export declare const REMOVED_RULE_OTHER_CONSUMERS_ADDENDUM: string;
+export declare const CONTRACT_VALUES_RENUMBERED_ADDENDUM: string;
+export declare const CONCURRENCY_PLANNED_ADDENDUM: string;
+export declare const CONCURRENCY_SCAN_ADDENDUM: string;
+export declare const SCAN_MODE_ANCHOR_ADDENDUM: string;
+export declare const SCAN_DELIVERY_ADDENDUM: string;
+/** Suggestions a deep scan's stage 1 may make per case (the cheap pass's
+ * own cap is five): enough for every focus file of a full case to be named. */
+export declare const SCAN_DEEP_MAX_SUGGESTIONS = 20;
+export declare const SCAN_DEEP_SUGGEST_ADDENDUM: string;
+export declare const SCAN_DEEP_DIG_ADDENDUM: string;
+export declare const SCAN_DEEP_RECALL_ADDENDUM: string;
+export declare const SCAN_DEEP_CONSISTENCY_ADDENDUM: string;
+export declare const SCAN_DEEP_DUPLICATION_ADDENDUM: string;
+export declare const SCAN_DEEP_MAINTAINABILITY_ADDENDUM: string;
+export declare const SCAN_PRECISION_LENSES: readonly ["pass-scan", "pass-contracts", "pass-data-safety", "pass-security", "pass-concurrency"];
+export interface ScanFalsePositiveClass {
+    slug: string;
+    name: string;
+    text: string;
+}
+export declare const SCAN_FALSE_POSITIVE_CLASSES: readonly ScanFalsePositiveClass[];
+export declare const SCAN_PRECISION_ADDENDUM: string;
+export declare const SCAN_SKEPTIC_ADDENDUM: string;
+export declare const NO_BUDGET_ADDENDUM: string;
+export declare const REPEATED_COPY_ADDENDUM: string;
+export declare const REPEATED_COPY_VALIDATE_ADDENDUM: string;
+export declare const REGRESSION_TEST_ASK_ADDENDUM: string;
+export declare const REGRESSION_TEST_ASK_VALIDATE_ADDENDUM: string;
+/**
+ * The composed addendum set, in composition order.
+ *
+ * Order is the declaration order below and nothing else — deterministic by
+ * construction, so a rebuild of an unchanged tree produces byte-identical
+ * bodies. Execution policy stays first (the most operational rule).
+ */
+export declare const PASS_ADDENDA: readonly PassAddendum[];
+/** The addenda binding `pass`, in composition order. `ecosystem` defaults to
+ * Django, as everywhere on the ecosystem seam; `depth` to `"standard"`, which
+ * is every PR build's. */
+export declare function addendaForPass(pass: string, registry?: readonly PassAddendum[], ecosystem?: EcosystemName, mode?: BuildMode, depth?: ScanDepth): PassAddendum[];
+/** The text appended to `pass`'s BUILT body (never to its seed). */
+export declare function composeAddendum(pass: string, registry?: readonly PassAddendum[], ecosystem?: EcosystemName, mode?: BuildMode, depth?: ScanDepth): string;
+export interface BuildAgentsOptions {
+    /** Sandbox root for include resolution. Defaults to `srcDir`'s parent. */
+    root?: string;
+    /** config.models.tiers — PassTier → model spec ("provider/model:thinking"). */
+    tiers?: Record<PassTier, string>;
+    /** config.models.risk_passes — build only the sol-high variant. */
+    riskPasses?: string[];
+    /** config.models.validate_tier — pass-validate's lowest built tier: the
+     * validator is built at it and every tier above (`tiersForPass`). */
+    validateTier?: PassTier;
+    /** Addendum registry to compose from — injected for tests; defaults to
+     * `PASS_ADDENDA`. Composition order is the registry's own order. */
+    addenda?: readonly PassAddendum[];
+    /** The profile's ecosystem — decides which ecosystem-gated
+     * addenda compose. Defaults to Django;
+     * wire.ts and the bench always pass the profile's selection. */
+    ecosystem?: EcosystemName;
+    /** Per-VARIANT model-spec overrides, keyed by variant name
+     * (`<pass>--<tier>`) — wins over the tier's spec; same splitting rules. */
+    models?: Record<string, string>;
+    /** Identity variable map — `identityVars(cfg)` in production
+     * (threaded from wire.ts). Defaults to the neutral role wording so a
+     * config-less build never ships a literal `{{…}}`. */
+    vars?: Readonly<Record<string, string>>;
+    /** What the build is for. `"pr"` (the default) is every PR
+     * round's build. `"scan"` is the companion's: it composes the `mode: "scan"`
+     * addenda (the scan-mode anchor rule), builds `extraSrcDirs` beside
+     * `srcDir`, and gives every variant exactly `SCAN_LEAF_TOOLS` — a scan leaf
+     * runs with no extensions, so no bash guard stands between it and a shell,
+     * and none of the memory tools exists in it. */
+    mode?: BuildMode;
+    /** A scan build's depth (`[scan] depth`): a `"deep"` build also composes
+     * the `depth: "deep"` addenda. Default `"standard"`; a `"pr"` build is
+     * always `"standard"`, whatever this says. */
+    scanDepth?: ScanDepth;
+    /** A `"pr"` build whose leaves the companion's case runner runs (the
+     * profile replay): composed exactly as a PR round's build — no
+     * scan-mode addendum — but every variant's tools are `SCAN_LEAF_TOOLS`,
+     * for the scan build's reason: such a leaf loads no extensions, so no bash
+     * guard stands between it and a shell, and no memory tool exists in it.
+     * Implied by `mode: "scan"`. */
+    readOnlyLeaves?: boolean;
+    /** Whether the leaves run with the memory extension (the two read-only
+     * memory tools and their rule). Default `LENS_LEAVES_LOAD_MEMORY` — false:
+     * no route's lens leaf loads it, so the tools and the rule would describe
+     * nothing. Never for a scan or `readOnlyLeaves` build, whatever this says.
+     * The bench passes `false` explicitly. */
+    memory?: boolean;
+    /** More source directories of `pass-*.md` agents, built exactly like
+     * `srcDir`'s — the scan build's `agents/scan/` (`pass-scan`), which no PR
+     * build ever reads. A name in two directories is refused. */
+    extraSrcDirs?: string[];
+    /** Narrow a pass's fan-out to these tiers (intersected with
+     * `tiersForPass`), keyed by pass name. The scan build's `pass-scan` runs at
+     * `[scan] tier` alone, so that is the only variant it builds. A pass not
+     * named keeps every tier `tiersForPass` gives it. */
+    onlyTiers?: Readonly<Record<string, readonly PassTier[]>>;
+    readFile?: (path: string) => string;
+}
+/** The tools a scan leaf holds: read-only, pi's own names, the
+ * same set the companion's other read-only leaves carry. No `bash` — the
+ * bash guard is an extension and a scan leaf loads none — and no memory. */
+export declare const SCAN_LEAF_TOOLS: readonly string[];
+/** Put exactly `SCAN_LEAF_TOOLS` on a variant's `tools:` line, adding the
+ * line when absent (a scan leaf's allowlist is never "whatever the harness
+ * gives you"). */
+export declare function applyScanLeafTools(frontmatter: string): string;
+export interface BuiltAgent {
+    /** Variant agent name: `<pass>--<tier>`. */
+    name: string;
+    /** The seeded pass this variant was built from. */
+    pass: string;
+    tier: PassTier;
+    source: string;
+    output: string;
+    /** Model id with the thinking suffix split off (the frontmatter's `model:`
+     * carries the whole spec). */
+    model: string | null;
+    /** Thinking level written to frontmatter, when the spec carried one. */
+    thinking: string | null;
+}
+/**
+ * `[models.pass_tiers]` as the per-VARIANT model map `buildAgents` takes
+ * (`BuildAgentsOptions.models`): every variant of a pinned pass carries its
+ * pinned tier's spec, so whichever variant name a session calls, the lens runs
+ * at that tier. Dispatch plans the pinned tier by name too (buildPassPlan).
+ * `overrides` is the per-variant map the rest of the config already asks for
+ * (the profile's per-lens `effort`): it is kept, and a pinned pass
+ * takes ITS pinned tier's entry from it when there is one — a pin moves the
+ * tier, the profile still sets the effort. Empty pins ⇒ `overrides` unchanged.
+ * `lenses` is the profile's tuning: its `min_tier` floors a pin exactly as
+ * dispatch's plan floors it (`flooredTier`), so the variant the plan names
+ * runs at the tier the plan records, never at the pin below the floor.
+ */
+export declare function passTierModels(passTiers: Readonly<Record<string, PassTier>> | undefined, tiers: Readonly<Record<PassTier, string>>, overrides?: Readonly<Record<string, string>>, passModels?: Readonly<Record<string, string>>, 
+/** Variants a pin leaves at their OWN tier's spec (`sweepLightVariants`). */
+unpinned?: readonly string[], lenses?: LensTuningMap): Record<string, string>;
+/** The pass-sweep variant `[review] sweep_light_tier` plans
+ * light rows at — exempt from the sweep's tier pin, so that variant runs at
+ * its own tier's spec. The light tier is floored by the profile's sweep
+ * `min_tier` as dispatch floors it, so the exempt variant is the one the plan
+ * names. Empty when the lever is off. */
+export declare function sweepLightVariants(review: {
+    sweep_light_tier?: "" | PassTier;
+}, lenses?: LensTuningMap): string[];
+/** The tiers a given pass fans out into.
+ *
+ * `validateTier` is the validator's configured tier. Dispatch never raises
+ * it to the round's highest lens, but a profile's `min_tier` for
+ * `pass-validate` can floor it upward, so every tier at or above it
+ * keeps a built variant on disk — a floored plan row never names an agent the
+ * subagent tool cannot find. */
+export declare function tiersForPass(pass: string, riskPasses: string[], validateTier: PassTier): PassTier[];
+/**
+ * Preprocess every `agents/pass-*.md` in `srcDir` into per-tier variant files
+ * `<pass>--<tier>.md` in `outDir` — the directory the native subagent
+ * extension discovers through its "user" scope (the container
+ * entrypoints symlink ~/.pi/agent/agents at outDir, so the built passes are
+ * exactly what a session's `subagent` tool can name).
+ */
+export declare function buildAgents(srcDir: string, outDir: string, opts?: BuildAgentsOptions): BuiltAgent[];
+//# sourceMappingURL=include.d.ts.map

package/dist/src/include.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"include.d.ts","sourceRoot":"","sources":["../../src/include.ts"],"names":[],"mappings":"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"}