infraweaver 0.1.0

package/dist/utils/packageManager.d.ts

@@ -0,0 +1,49 @@
+export type SupportedPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+export interface PackageManagerSpec {
+    name: SupportedPackageManager;
+    /**
+     * either a concrete semver (e.g. "11.1.1") or a range (e.g. "^11.0.0").
+     * `concrete` distinguishes — corepack only accepts concrete versions.
+     */
+    version: string;
+    concrete: boolean;
+    /** which package.json field this came from */
+    source: "devEngines" | "packageManager";
+}
+/**
+ * resolve the project's intended package manager from package.json. precedence
+ * matches pnpm 11+: `devEngines.packageManager` wins over `packageManager`.
+ * when both are present, a concrete `packageManager` that satisfies a
+ * `devEngines` range is preferred (we can pin it via corepack); otherwise
+ * we warn on disagreement and stick with `devEngines`.
+ */
+export declare function resolvePackageManagerSpec(cwd: string): Promise<PackageManagerSpec | null>;
+/** the per-run directory the corepack shim is installed into. deliberately
+ * NOT the node bin dir: that's npm's `-g` target, and a corepack shim sitting
+ * there makes a customer setup script's `npm i -g pnpm` abort with EEXIST
+ * (npm refuses to clobber a binary it doesn't own). lives under the run
+ * tmpdir so it's cleaned up with everything else. */
+export declare function packageManagerBinDir(tmpdir: string): string;
+export interface EnsurePackageManagerParams {
+    spec: PackageManagerSpec;
+    /** directory to install the corepack shim into (see `packageManagerBinDir`).
+     * prepended to PATH so the pinned binary resolves by name. */
+    binDir: string;
+}
+/**
+ * ensure the requested package manager is on PATH at the declared version,
+ * provisioning via corepack when applicable. returns true if PATH now
+ * resolves to that version, false if we couldn't pin it (in which case
+ * the caller should treat PATH as untrusted and may fall back to its
+ * legacy install path).
+ *
+ * the corepack shim is installed into `params.binDir` (prepended to PATH),
+ * not the node bin dir, so a later `npm i -g pnpm` in a setup hook can't
+ * collide with it. our dir wins the PATH lookup, so the pinned version is
+ * also what resolves even if that `npm i -g` succeeds into the node bin dir.
+ *
+ * never throws: network failure, missing corepack, range-only versions —
+ * all degrade to "log warning, return false". the existing PATH binary
+ * still works; we just don't get our version guarantee.
+ */
+export declare function ensurePackageManager(params: EnsurePackageManagerParams): Promise<boolean>;

package/dist/utils/patchWorkflowRunFields.d.ts

@@ -0,0 +1,29 @@
+import type { AgentUsage } from "#app/agents/shared";
+import type { CloudToolContext } from "#app/mcp/capabilityContext";
+/**
+ * Artifact tracking fields — one-off PATCHes from MCP tools as GitHub entities
+ * are created during the run. Strings only (GraphQL node IDs).
+ * Keep in sync with `STRING_FIELDS` in `app/api/workflow-run/[runId]/route.ts`.
+ */
+export type WorkflowRunArtifactPatchKey = "prNodeId" | "issueNodeId" | "reviewNodeId" | "planCommentNodeId" | "summarySnapshot";
+/**
+ * Usage fields — aggregated across all agent calls and PATCHed once at
+ * end-of-run. Token counts are Int4 on the DB side (ample for any realistic
+ * run); `costUsd` is a Decimal populated by provider-reported dollar amounts.
+ * Keep in sync with `INT_FIELDS` + `DECIMAL_FIELDS` in the server route.
+ */
+export type WorkflowRunUsagePatchKey = "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheWriteTokens" | "costUsd";
+export type WorkflowRunPatch = Partial<Record<WorkflowRunArtifactPatchKey, string>> & Partial<Record<WorkflowRunUsagePatchKey, number>>;
+/** PATCH workflow-run fields (Infraweaver JWT, not GitHub). */
+export declare function patchWorkflowRunFields(ctx: CloudToolContext, fields: WorkflowRunPatch): Promise<void>;
+/**
+ * Sum per-agent usage entries into a single WorkflowRunPatch payload.
+ * Returns an empty object when there's nothing to report, which causes
+ * `patchWorkflowRunFields` to no-op — safe to call unconditionally from
+ * end-of-run paths. Zero-valued fields are dropped so the DB only stores
+ * positive sums (and NULL means "not reported").
+ *
+ * Token sums are clamped to INT4_MAX to guarantee the payload the server
+ * sees is always self-consistent across all numeric columns.
+ */
+export declare function aggregateUsage(entries: AgentUsage[]): WorkflowRunPatch;

package/dist/utils/payload.d.ts

@@ -0,0 +1,249 @@
+import type { PayloadEvent } from "#app/external";
+import type { RepoSettings } from "#app/utils/runContext";
+export declare const JsonPayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    "~infraweaver": true;
+    version: string;
+    model?: string | undefined;
+    prompt: string;
+    triggerer?: string | undefined;
+    eventInstructions?: string;
+    previousRunsNote?: string;
+    event?: object;
+    timeout?: string | undefined;
+    progressComment?: {
+        id: string;
+        type: "issue" | "review";
+    } | undefined;
+    generateSummary?: boolean | undefined;
+}, {}>;
+export declare const Inputs: import("arktype/internal/variants/object.ts").ObjectType<{
+    prompt: string;
+    model?: string | undefined;
+    mode?: string | undefined;
+    timeout?: string | undefined;
+    push?: "disabled" | "enabled" | "restricted" | undefined;
+    shell?: "disabled" | "enabled" | "restricted" | undefined;
+    cwd?: string | undefined;
+    output_schema?: string | undefined;
+    scan_scope?: string | undefined;
+    iac_languages?: string | undefined;
+    language?: string | undefined;
+    severity_threshold?: string | undefined;
+    concern_ids?: string | undefined;
+    grouping?: string | undefined;
+    max_prs?: string | undefined;
+    max_run_tokens?: string | undefined;
+    pr_concurrent_limit?: string | undefined;
+    pr_hourly_limit?: string | undefined;
+    allowed_paths?: string | undefined;
+    base_branch?: string | undefined;
+    allow_replace?: string | undefined;
+    protected_paths?: string | undefined;
+    autonomy_threshold?: string | undefined;
+    required_controls?: string | undefined;
+    gitleaks?: string | undefined;
+    cost_increase_block_usd?: string | undefined;
+    module_catalogue?: string | undefined;
+    terratest?: string | undefined;
+    docs?: string | undefined;
+    terraform_mcp?: string | undefined;
+    opentofu_mcp?: string | undefined;
+    fix_memory?: string | undefined;
+    tools_enabled?: string | undefined;
+    tools_network?: string | undefined;
+    module_fetch_token?: string | undefined;
+    module_fetch_ssh_key?: string | undefined;
+    registry_token?: string | undefined;
+    registry_host?: string | undefined;
+    refactor_source?: string | undefined;
+    review_instructions?: string | undefined;
+    fp_filtering_instructions?: string | undefined;
+    remediation_instructions?: string | undefined;
+    refactor_instructions?: string | undefined;
+    api_token?: string | undefined;
+}, {}>;
+export type Inputs = typeof Inputs.infer;
+export type ResolvedPromptInput = string | typeof JsonPayload.infer;
+/**
+ * Built-in, VETTED prompts for the deterministic Terraform CI modes. When one of
+ * these modes is pinned via the action `mode:` input, the engine OWNS the prompt —
+ * a workflow-supplied prompt is ignored (see {@link resolveEffectivePrompt}) so a
+ * managed / Cloud-dispatched run can never be steered by free-form prompt text.
+ * Keyed by the canonical mode name returned by {@link parseMode}.
+ */
+export declare const VETTED_MODE_PROMPTS: Readonly<Record<string, string>>;
+export declare function resolvePromptInput(): ResolvedPromptInput;
+/**
+ * The prompt a run actually uses. For a pinned mode that ships a vetted standard
+ * (the Terraform CI modes in {@link VETTED_MODE_PROMPTS}), the engine owns the
+ * prompt: a FREE-FORM workflow prompt is IGNORED (and warned) so it can't steer a
+ * managed/CI run — this is the security boundary. Two things are deliberately NOT
+ * overridden: the internal JSON dispatch payload (trusted), and a recognised
+ * `@infraweaver fix …` command (`isRemediationCommand`) — the comment-driven flow
+ * needs the structured command to reach the agent. Otherwise the workflow prompt is
+ * used, and is required when no vetted mode supplies one.
+ */
+export declare function resolveEffectivePrompt(rawPrompt: string, fromJsonPayload: boolean, mode: string | undefined, isRemediationCommand: boolean): string;
+/**
+ * Canonicalize the `mode` input against the built-in mode names
+ * (case-insensitive), resolving any control-plane alias first. Returns the
+ * canonical name (e.g. "remediate" → "Remediate", "refresh" →
+ * "RefreshRemediation") when it matches a built-in mode, letting CI pin a mode
+ * deterministically. Unknown non-empty values warn and return undefined so the
+ * agent falls back to prompt-driven `select_mode` — mirroring how an unknown
+ * `model` slug degrades to auto-select rather than hard-failing the run.
+ */
+export declare function parseMode(raw: string | undefined): string | undefined;
+/** parse the comma-separated `concern_ids` focus list — the specific concern ids a
+ * dashboard "Remediate" dispatch targets. Structured scope (like severity/paths),
+ * NOT task text. undefined when unset. */
+export declare function parseConcernIds(raw: string | undefined): string[] | undefined;
+/**
+ * Append an engine-owned "fix exactly these concern ids" directive to a Remediate
+ * run's task when the dispatch targeted specific findings (the Cloud "Remediate"
+ * button). The task text stays engine-owned — only the id list comes from the
+ * trusted dispatch — so this narrows scope without letting a customer author the
+ * prompt. A no-op when there are no targeted ids.
+ */
+export declare function withConcernFocus(prompt: string, concernIds: string[] | undefined): string;
+/**
+ * The five module-source variants a Refactor run can be pinned to. `auto` (the
+ * default) lets the engine pick the lowest-risk BEHAVIOUR-PRESERVING source
+ * (b.2 → b.1 → b.3) and deliberately excludes the behaviour-altering b.4. The
+ * other four map 1:1 onto the spec's b-variants and let the operator force one:
+ *   - `same-repo`   → b.2 (a module already in this repo, `./modules/x`)
+ *   - `org-repo`    → b.1 (a module in a separate org repo, fetched read-only)
+ *   - `author`      → b.3 (mechanically extract a new module)
+ *   - `third-party` → b.4 (adopt a registry/community module — ALTERS behaviour)
+ * The value is structured SCOPE, never task text: the engine still owns the
+ * Refactor prompt (the security boundary), and this only narrows which source
+ * the agent may resolve to. See {@link withRefactorSource}.
+ */
+export type RefactorSource = "auto" | "same-repo" | "org-repo" | "author" | "third-party";
+/** parse the `refactor_source` input into a canonical {@link RefactorSource}.
+ * Unset → undefined (the consumer treats that as `auto`). An unknown value
+ * warns and falls back to `auto` rather than hard-failing the run (mirrors how
+ * an unknown `mode`/`model` degrades). */
+export declare function parseRefactorSource(raw: string | undefined): RefactorSource | undefined;
+/**
+ * Append the engine-owned module-source directive to a Refactor run's task when
+ * the operator pinned a `refactor_source` variant (the Cloud refactor picker, or
+ * the `refactor_source` action input). The task text stays engine-owned — only
+ * the enum comes from the trusted dispatch/input — so this narrows WHICH source
+ * the agent may resolve to without letting a customer author the prompt (the same
+ * boundary as {@link withConcernFocus}). A no-op when the variant is unset (the
+ * vetted prompt's own risk-ordered guidance applies).
+ */
+export declare function withRefactorSource(prompt: string, source: RefactorSource | undefined): string;
+/**
+ * The languages a run's user-facing PROSE can be written in. English is the
+ * source/default; the others are the L1 marketing languages (see
+ * `docs/I18N-AND-MULTI-REGION-PLAN.md` A.5). This governs LLM-authored
+ * explanations only — never the Terraform, the identifiers, or the evidence.
+ */
+export type UserFacingLanguage = "en" | "de" | "es" | "pl" | "ro";
+/** parse the `language:` input into a {@link UserFacingLanguage}. Unset → "en".
+ * Accepts a code (`de`), a regional tag (`de-DE`), or a name (`German`). An
+ * unknown value warns and falls back to "en" rather than hard-failing the run —
+ * mirroring how an unknown `mode`/`model`/`refactor_source` degrades. */
+export declare function parseLanguage(raw: string | undefined): UserFacingLanguage;
+/**
+ * Append the engine-owned "write user-facing prose in <language>" directive to a
+ * run's task. Structured enum input, never workflow prose — the engine still owns
+ * the prompt (the security boundary, same as {@link withConcernFocus} /
+ * {@link withRefactorSource}). A no-op for English (the default), so existing runs
+ * are byte-for-byte unchanged. The directive is glossary-aware: it localizes the
+ * EXPLANATIONS a human reads and holds every identifier, code block, path, rule
+ * id, control name, and the product terms verbatim in English — so a translated
+ * PR body never corrupts the Terraform it describes.
+ */
+export declare function withLanguageDirective(prompt: string, language: UserFacingLanguage): string;
+/** parse the base_branch override; trims and strips a leading `refs/heads/`,
+ * undefined when unset (downstream resolves the run-start branch / default). */
+export declare function parseBaseBranch(raw: string | undefined): string | undefined;
+/** parse the comma-separated allow_replace list — resource addresses (or globs,
+ * or `*`/`all`) permitted to be destroyed/replaced; undefined when unset. */
+export declare function parseAllowReplace(raw: string | undefined): string[] | undefined;
+/**
+ * true when `actor` is Infraweaver's own GitHub identity — the bot login
+ * (`infraweaver[bot]` / `infraweaverdev[bot]`) or the bare account. used to skip
+ * self-triggered events and to recognise Infraweaver-originated review threads
+ * (the never-approve-with-outstanding-findings gate). matches with or without
+ * the `[bot]` suffix since GraphQL and REST report the login differently.
+ */
+export declare const isInfraweaver: (actor: string | null | undefined) => boolean;
+export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput, repoSettings: RepoSettings, 
+/** The org's mandatory pack-control ids from the Cloud run-context (org-scoped).
+ *  Merged with the local `required_controls` so the dashboard policy gates CI. */
+orgRequiredControls?: string[], 
+/** Cloud-managed module credentials from the run-context (the dashboard Refactor
+ *  dialog). A FALLBACK only — an explicit `module_fetch_token` / `registry_token`
+ *  input always wins. undefined when none are stored for the repo. */
+managedCredentials?: {
+    moduleFetchToken?: string;
+    registryToken?: string;
+}): {
+    "~infraweaver": true;
+    version: string;
+    model: string | undefined;
+    mode: string | undefined;
+    prompt: string;
+    triggerer: string | undefined;
+    eventInstructions: string | undefined;
+    previousRunsNote: string | undefined;
+    event: PayloadEvent;
+    timeout: string | undefined;
+    cwd: string | undefined;
+    progressComment: {
+        id: string;
+        type: "issue" | "review";
+    } | undefined;
+    generateSummary: boolean | undefined;
+    push: import("#app/external").PushPermission;
+    shell: import("#app/external").ShellPermission;
+    scanScope: "diff" | "full" | undefined;
+    iacLanguages: string | undefined;
+    severityThreshold: string | undefined;
+    grouping: "file" | "rule" | undefined;
+    concernIds: string[] | undefined;
+    maxPrs: number | undefined;
+    maxRunTokens: number | undefined;
+    prConcurrentLimit: number | undefined;
+    prHourlyLimit: number | undefined;
+    allowedPaths: string[] | undefined;
+    protectedPaths: string[] | undefined;
+    autonomyThreshold: string | undefined;
+    requiredControls: string[] | undefined;
+    gitleaks: boolean;
+    costIncreaseBlockUsd: number | undefined;
+    moduleCatalogue: string | undefined;
+    terratest: boolean;
+    docs: boolean;
+    terraformMcp: boolean;
+    opentofuMcp: boolean;
+    language: UserFacingLanguage;
+    fixMemory: boolean;
+    toolsEnabled: import("#app/utils/toolSelection").ToolDirective | undefined;
+    toolsNetwork: import("#app/mcp/terraform/scannerEgress").ToolsNetworkDirective | undefined;
+    moduleFetchToken: string | undefined;
+    moduleFetchSshKey: string | undefined;
+    registryToken: string | undefined;
+    registryHost: string | undefined;
+    refactorSource: RefactorSource | undefined;
+    remediationCommand: import("#app/utils/remediationCommand").RemediationCommand | null;
+    baseBranch: string | undefined;
+    allowReplace: string[] | undefined;
+    reviewInstructions: string | undefined;
+    fpFilteringInstructions: string | undefined;
+    remediationInstructions: string | undefined;
+    refactorInstructions: string | undefined;
+    cloudApiToken: string | undefined;
+};
+export type ResolvedPayload = ReturnType<typeof resolvePayload>;
+/**
+ * Parse and validate the optional `output_schema` action input. Returns the
+ * parsed object when present, or `undefined` when absent. Throws on invalid
+ * JSON or non-object payloads — these are workflow-author errors that should
+ * surface immediately, not silently degrade to "no schema".
+ */
+export declare function resolveOutputSchema(): Record<string, unknown> | undefined;

package/dist/utils/prSummary.d.ts

@@ -0,0 +1,61 @@
+import type { ToolContext } from "#app/mcp/server";
+/**
+ * The PR-level summary snapshot is a markdown file the agent edits in place
+ * during a Review / IncrementalReview run. The server seeds the file with
+ * either the previous run's snapshot (incremental) or a stub scaffold (first
+ * run), lets the agent edit it with its native file-editing tools, then
+ * reads it back at end-of-run and persists it to `WorkflowRun.summarySnapshot`.
+ *
+ * The snapshot is an internal artifact — it is consumed by future agent runs
+ * as durable cross-run context, not surfaced to humans. User-visible summary
+ * content lives in the Review / IncrementalReview review bodies, governed by
+ * `src/modes/` (review.ts / incremental-review.ts).
+ *
+ * Edit-in-place avoids the output-token tax of a tool call that regurgitates
+ * the full snapshot, and gives incremental runs a clean surface that
+ * range-diffs cleanly across runs because the section headings are stable.
+ */
+export declare const SUMMARY_FILE_NAME = "infraweaver-summary.md";
+/**
+ * minimal seed for first-run PRs. just a header + a one-line note about
+ * what this file is for. structure is intentionally NOT prescribed —
+ * different PRs warrant different organization, and the agent should pick
+ * a shape that fits this PR. the agent's prompt (see selectMode.ts
+ * `buildSummaryAddendum`) carries the actual instructions for what to
+ * capture and how.
+ *
+ * keeping the seed short also makes the unchanged-from-seed gate more
+ * sensitive — any meaningful edit moves the file off the seed, so
+ * `persistSummary` can reliably skip the DB write when the agent didn't
+ * touch the file.
+ */
+export declare const SUMMARY_SCAFFOLD = "# PR summary\n\n<!-- durable cross-run context. edit in place; the next agent run reads this\n     before reviewing new commits. structure however serves the PR best. -->\n";
+export declare function summaryFilePath(tmpdir: string): string;
+/** seed the summary file with previous snapshot (incremental) or scaffold (first run). */
+export declare function seedSummaryFile(params: {
+    tmpdir: string;
+    previousSnapshot: string | null;
+}): Promise<string>;
+/** read + validate the summary file written by the agent.
+ * returns null when the file is missing or fails sanity checks. */
+export declare function readSummaryFile(path: string): Promise<string | null>;
+/**
+ * Fetch the most recent persisted PR summary snapshot for this PR.
+ * Returns null on first-time PRs, when summary is disabled, or on any error.
+ * Best-effort: a transient API failure should not block the run.
+ */
+export declare function fetchPreviousSnapshot(ctx: ToolContext, prNumber: number): Promise<string | null>;
+/**
+ * Read the agent-edited PR summary tmpfile and persist to
+ * `WorkflowRun.summarySnapshot`.
+ *
+ * Best-effort: any failure is logged and does not affect the run's success
+ * status. Skips the PATCH when the file is byte-identical to its seed —
+ * persisting the seed verbatim would either re-write what the DB already has
+ * (on incremental runs) or serialize the placeholder scaffold (on first
+ * runs), neither of which is useful.
+ *
+ * Funnels through both the success path and the SIGINT/SIGTERM handler;
+ * `summaryPersistAttempted` guards against double-execution.
+ */
+export declare function persistSummary(ctx: ToolContext): Promise<void>;

package/dist/utils/presets.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shareable config presets — the Renovate `extends:` analog.
+ *
+ * A repo can write `extends: [infraweaver:recommended]` (or `:strict`,
+ * `:ukCyberEssentials`) in `.infraweaver.yml`/`.infraweaver.json` instead of spelling
+ * out every policy knob. A preset is just a named bundle of the SAME repo-level
+ * keys the file already supports, so resolution is a plain merge with a strict
+ * precedence chain:
+ *
+ *   action input  >  the file's own keys  >  later preset  >  earlier preset
+ *
+ * i.e. an explicit value always wins over a preset, and a later entry in
+ * `extends` wins over an earlier one. Presets only RELAX/tune within the same
+ * structure the inputs validate — they can't introduce new keys or bypass the
+ * licence gate (a named non-permissive tool is still the repo owner's opt-in).
+ */
+import type { InfraweaverFileValues } from "#app/utils/infraweaverConfig";
+/** A preset is a partial bundle of the repo-level config keys. */
+export type Preset = InfraweaverFileValues;
+/**
+ * The built-in preset registry. Values are written in the SAME normalized string
+ * shape the file parser produces, so they feed the existing input parsers as-is.
+ */
+export declare const INFRAWEAVER_PRESETS: Readonly<Record<string, Preset>>;
+export interface ResolvedPresets {
+    values: InfraweaverFileValues;
+    warnings: string[];
+}
+/**
+ * Resolve an `extends` list into a merged set of config values. Unknown preset
+ * names are warned and skipped (degrade-green). Later presets override earlier
+ * ones; the caller then overlays the file's own explicit keys on top.
+ */
+export declare function resolvePresets(names: readonly string[]): ResolvedPresets;
+/** Normalize the raw `extends` value (string | string[]) into a clean name list. */
+export declare function normalizeExtends(value: unknown): string[];

package/dist/utils/progressComment.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Single source of truth for reading, updating, deleting, and creating "progress comments" —
+ * the GitHub comments Infraweaver uses to surface a run's status.
+ *
+ * A progress comment can be one of two distinct GitHub entities with non-overlapping IDs and
+ * distinct REST endpoints:
+ *   - "issue":  a top-level issue/PR timeline comment (octokit.rest.issues.*Comment)
+ *   - "review": an inline PR review-thread comment   (octokit.rest.pulls.*ReviewComment)
+ *
+ * Callers carry a `ProgressComment` (id + type) value end-to-end so the right endpoint is always
+ * picked. Adding a third comment type later means one new branch in this file, not six.
+ */
+export type ProgressCommentType = "issue" | "review";
+export type ProgressComment = {
+    id: number;
+    type: ProgressCommentType;
+};
+/**
+ * Parse the on-the-wire `{ id: string; type }` shape (the form carried in `JsonPayload`)
+ * into the in-memory `ProgressComment` shape. Returns undefined when the id isn't a
+ * positive integer so callers can short-circuit cleanly. Callers handle logging.
+ */
+export declare function parseProgressComment(raw: {
+    id: string;
+    type: ProgressCommentType;
+} | null | undefined): ProgressComment | undefined;
+interface CommentResponse {
+    data: {
+        id: number;
+        body?: string | null | undefined;
+        html_url: string;
+        node_id?: string;
+    };
+}
+export interface ProgressCommentOctokit {
+    rest: {
+        issues: {
+            createComment: (params: {
+                owner: string;
+                repo: string;
+                issue_number: number;
+                body: string;
+            }) => Promise<CommentResponse>;
+            getComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+            }) => Promise<CommentResponse>;
+            updateComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+                body: string;
+            }) => Promise<CommentResponse>;
+            deleteComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+            }) => Promise<unknown>;
+        };
+        pulls: {
+            createReplyForReviewComment: (params: {
+                owner: string;
+                repo: string;
+                pull_number: number;
+                comment_id: number;
+                body: string;
+            }) => Promise<CommentResponse>;
+            getReviewComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+            }) => Promise<CommentResponse>;
+            updateReviewComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+                body: string;
+            }) => Promise<CommentResponse>;
+            deleteReviewComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+            }) => Promise<unknown>;
+        };
+    };
+}
+interface ApiCtx {
+    octokit: ProgressCommentOctokit;
+    owner: string;
+    repo: string;
+}
+/**
+ * Fetch a progress comment via the appropriate REST endpoint for its type.
+ * Returns the common subset of fields callers actually use.
+ */
+export declare function getProgressComment(ctx: ApiCtx, comment: ProgressComment): Promise<{
+    id: number;
+    body: string | undefined;
+    html_url: string;
+}>;
+/**
+ * Update a progress comment in place via the appropriate REST endpoint.
+ * Returns the common subset of fields callers actually use.
+ */
+export declare function updateProgressComment(ctx: ApiCtx, comment: ProgressComment, body: string): Promise<{
+    id: number;
+    body: string | undefined;
+    html_url: string;
+    node_id: string | undefined;
+}>;
+/**
+ * Delete a progress comment via the appropriate REST endpoint.
+ * Lower-level than `deleteProgressComment` in mcp/comment.ts — that one also clears
+ * tool state. Callers that don't have a ToolContext (post cleanup, error handlers)
+ * should use this directly; the higher-level wrapper delegates here.
+ */
+export declare function deleteProgressCommentApi(ctx: ApiCtx, comment: ProgressComment): Promise<void>;
+/**
+ * Discriminated target for `createLeapingProgressComment`. The two variants map to the two
+ * distinct GitHub create endpoints; review-reply additionally needs the parent comment ID.
+ */
+export type CreateProgressCommentTarget = {
+    kind: "issue";
+    issueNumber: number;
+} | {
+    kind: "reviewReply";
+    pullNumber: number;
+    replyToCommentId: number;
+};
+export interface CreatedProgressComment {
+    comment: ProgressComment;
+    body: string | undefined;
+    html_url: string;
+}
+/**
+ * Create the initial "Leaping into action..." progress comment.
+ *
+ * Reliability: when `kind: "reviewReply"` fails (e.g. the parent comment was deleted or the
+ * thread is otherwise unreachable), falls back to a top-level issue comment on the same PR
+ * rather than leaving the run with no progress surface. The fallback is logged.
+ *
+ * (PR # === issue # in GitHub's number space, so `pullNumber` doubles as the fallback target.)
+ */
+export declare function createLeapingProgressComment(ctx: ApiCtx, target: CreateProgressCommentTarget, body: string): Promise<CreatedProgressComment>;
+export {};

package/dist/utils/providerErrors.d.ts

@@ -0,0 +1,31 @@
+/** Stable label for the BYOK provider-billing-exhausted classification. */
+export declare const PROVIDER_BILLING_EXHAUSTED_LABEL = "provider billing exhausted";
+/**
+ * Result of a provider-error scan: the classification label plus a
+ * human-readable excerpt centered on the matched line. The excerpt is what
+ * gets surfaced in `» provider error detected (...)` log lines — see
+ * `extractExcerpt` for the windowing/byte-cap policy.
+ */
+export type ProviderErrorMatch = {
+    label: string;
+    excerpt: string;
+};
+export declare function findProviderErrorMatch(text: string): ProviderErrorMatch | null;
+export declare function detectProviderError(text: string): string | null;
+export declare function isRouterKeylimitExhaustedError(text: string): boolean;
+/**
+ * BYOK billing-exhausted: provider rejected the request because the user's
+ * provider wallet is empty (DeepSeek "Insufficient Balance", Anthropic
+ * "credit balance is too low", OpenCode Zen `CreditsError` /
+ * `FreeUsageLimitError`, Gemini "spending cap"). Distinct from
+ * `isRouterKeylimitExhaustedError` — that's Infraweaver's Router wallet, this
+ * is the user's own provider account.
+ */
+export declare function isProviderBillingExhausted(text: string): boolean;
+/**
+ * Extract `providerID=foo` from agent error logs (OpenCode emits this on
+ * `provider error detected (...)` lines). Returns the lowercase provider
+ * slug, or null when absent. Used to render a provider-specific dashboard
+ * link in the BYOK billing-exhausted summary.
+ */
+export declare function extractProviderId(text: string): string | null;