terramend 0.2.0

package/dist/utils/log.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Logging utilities that work well in both local and GitHub Actions environments
+ */
+import { type AgentUsage } from "#app/agents/shared";
+/** run `fn` with every log line prefixed by `prefix` (e.g. "[task-label]") in magenta */
+export declare function withLogPrefix<T>(prefix: string, fn: () => Promise<T>): Promise<T>;
+type LogSink = "actions" | "stderr";
+/**
+ * Route ALL log output to stderr instead of `@actions/core` (which writes to
+ * stdout). Required before starting a stdio MCP server: stdout is the JSON-RPC
+ * channel there, and a single stray diagnostic line corrupts the framing.
+ * The GitHub Action path never calls this — its sink stays `@actions/core`.
+ */
+export declare function setLogSink(next: LogSink): void;
+/**
+ * Start a collapsed group (GitHub Actions) or regular group (local)
+ */
+declare function startGroup(name: string): void;
+/**
+ * End a collapsed group
+ */
+declare function endGroup(): void;
+/**
+ * Run a callback within a collapsed group
+ */
+declare function group(name: string, fn: () => void): void;
+/**
+ * Print a formatted box with text
+ */
+declare function box(text: string, options?: {
+    title?: string;
+    maxWidth?: number;
+}): void;
+/**
+ * Overwrite the job summary with the given text.
+ * Skips if:
+ * - Not in GitHub Actions
+ * - Running inside Docker (CI tests inherit host env vars but can't access host paths)
+ * - GITHUB_STEP_SUMMARY not set
+ */
+export declare function writeSummary(text: string): Promise<void>;
+/**
+ * Print a formatted table using the table package
+ */
+declare function printTable(rows: Array<Array<{
+    data: string;
+    header?: boolean;
+} | string>>, options?: {
+    title?: string;
+}): void;
+/**
+ * Print a separator line
+ */
+declare function separator(length?: number): void;
+/**
+ * Main logging utility object - import this once and access all utilities
+ */
+export declare const log: {
+    /** Print info message */
+    info: (...args: unknown[]) => void;
+    /** Print a warning message. Use only for warnings that should be displayed in the job summary. */
+    warning: (...args: unknown[]) => void;
+    /** Print an error message. Use only for errors that should be displayed in the job summary. */
+    error: (...args: unknown[]) => void;
+    /** Print success message */
+    success: (...args: unknown[]) => void;
+    /** Print debug message (only when debug mode is enabled) */
+    debug: (...args: unknown[]) => void;
+    /** Print a formatted box with text */
+    box: typeof box;
+    /** Print a formatted table using the table package */
+    table: typeof printTable;
+    /** Print a separator line */
+    separator: typeof separator;
+    /** Start a collapsed group (GitHub Actions) or regular group (local) */
+    startGroup: typeof startGroup;
+    /** End a collapsed group */
+    endGroup: typeof endGroup;
+    /** Run a callback within a collapsed group */
+    group: typeof group;
+    /** Log tool call information to console with formatted output */
+    toolCall: ({ toolName, input }: {
+        toolName: string;
+        input: unknown;
+    }) => void;
+};
+/**
+ * Format a value as JSON, using compact format for simple values and pretty-printed for complex ones
+ */
+export declare function formatJsonValue(value: unknown): string;
+/**
+ * Format a multi-line string with proper indentation for tool call output
+ * First line has the label, subsequent lines are indented 4 spaces
+ */
+export declare function formatIndentedField(label: string, content: string): string;
+/**
+ * format aggregated usage data as a markdown table for the GitHub step summary.
+ *
+ * columns mirror the per-run stdout token table emitted by `logTokenTable`
+ * (Input / Cache Read / Cache Write / Output / Total / Cost ($)) so the job
+ * summary and the in-run logs can be compared row-for-row.
+ *
+ * notes:
+ *   - `AgentUsage.inputTokens` is the sum of non-cached input + cache read
+ *     + cache write (set that way by both agent harnesses' `buildUsage`),
+ *     so the non-cached Input column is recovered by subtracting cache fields.
+ *   - `costUsd` is sourced from models.dev (OpenCode) or `total_cost_usd`
+ *     (Claude CLI). absent rows show `—` so per-agent coverage is obvious.
+ */
+export declare function formatUsageSummary(entries: AgentUsage[]): string;
+export {};

package/dist/utils/normalizeEnv.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Trim surrounding whitespace from a sensitive value and register it as a
+ * GitHub Actions log mask. Trailing newlines from terminal-copy paste are a
+ * common footgun: the value travels through GH Actions logs and any tool
+ * that re-emits parts of it leaks the unmasked tail. Trimming canonicalises
+ * the value so the mask matches exactly what downstream tools will print.
+ *
+ * Masking is delegated to `core.setSecret` (not raw `console.log`) so the
+ * toolkit percent-encodes `\r`/`\n`; the runner V2 parser decodes them and
+ * registers the full value plus every non-empty line as separate masks. That
+ * keeps us safe for embedded-newline values (PEMs, kubeconfigs, JSON blobs)
+ * even though they aren't currently used.
+ *
+ * Returns the trimmed value, or `null` when the input was whitespace-only —
+ * callers must leave `process.env` untouched in that case so a misconfigured
+ * value surfaces as a clear "missing key" downstream rather than silently
+ * mutating to the empty string.
+ */
+export declare function sanitizeSecret(key: string, value: string): string | null;
+/**
+ * Normalize environment variables to uppercase.
+ * This handles case-insensitive env var names (e.g., `anthropic_api_key` -> `ANTHROPIC_API_KEY`).
+ *
+ * If there are conflicts (same key with different capitalizations but different values),
+ * logs a warning and keeps the uppercase version.
+ *
+ * Also trims and masks sensitive values so accidental trailing whitespace
+ * doesn't defeat GitHub Actions log masking.
+ */
+export declare function normalizeEnv(): void;

package/dist/utils/openCodeModels.d.ts

@@ -0,0 +1,11 @@
+/** Snapshot the set of models OpenCode can serve from the current env, BEFORE
+ * Terramend-stored credentials are merged in. Call once early in `main.ts`. */
+export declare function captureBaselineModels(cliPath: string): void;
+/** Snapshot the set of models OpenCode can serve AFTER dbSecrets +
+ * Codex auth.json are in place. Logs the diff against the baseline as
+ * `» BYOK auth enabled N model(s): …`. */
+export declare function captureAuthorizedModels(cliPath: string): void;
+/** Authorized set captured after Terramend-stored auth is applied. Throws if
+ * called before `captureAuthorizedModels` — the call sites (fallback gate,
+ * api-key validation, auto-select) all run strictly after capture. */
+export declare function getAuthorizedModels(): Set<string>;

package/dist/utils/overrides.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Parse + apply the action's `unsafe_overrides` input — a JSON object of env
+ * var overrides that mutate `process.env` at the start of a run. Designed for
+ * e2e testing / debugging from `workflow_dispatch`; only callers with
+ * `actions:write` on the repo can supply it.
+ *
+ * The `unsafe` prefix is load-bearing: GH Actions echoes the value verbatim
+ * in the runner's step-header log, so the raw JSON (including any values
+ * passed in) is visible to anyone with `actions:read` on the calling repo.
+ * Treat the run log as compromised for any value placed in `unsafe_overrides`.
+ */
+/**
+ * Names refused even when present in the input. Overriding these would let a
+ * caller escape terramend's scope (GITHUB_TOKEN), break runner internals
+ * (ACTIONS_RUNTIME_*), forge OIDC tokens (ACTIONS_ID_TOKEN_REQUEST_*), or
+ * substitute our server-side auth (TERRAMEND_API_SECRET). Customer-facing
+ * provider keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, CLAUDE_CODE_OAUTH_TOKEN,
+ * etc.) are intentionally NOT denied — overriding those is the use case.
+ */
+export declare const DENIED_OVERRIDE_NAMES: ReadonlySet<string>;
+export interface ApplyOverridesResult {
+    applied: string[];
+    denied: string[];
+}
+/** Parse the JSON input. Returns `{}` for empty/whitespace. Throws on shape errors. */
+export declare function parseOverrides(raw: string): Record<string, string>;
+/**
+ * Mutate `params.env` in place with the supplied JSON overrides, skipping any
+ * names in `DENIED_OVERRIDE_NAMES`. Each applied value is registered with
+ * `core.setSecret` so the runner masks it in subsequent log output, and the
+ * raw `UNSAFE_OVERRIDES` env var is deleted so spawned subprocesses don't
+ * inherit the original JSON (which would defeat both the deny-list and the
+ * masking by exposing the values verbatim).
+ *
+ * Returns the applied/denied breakdown so the caller can render an audit log.
+ */
+export declare function applyOverrides(params: {
+    raw: string;
+    env: NodeJS.ProcessEnv;
+}): ApplyOverridesResult;

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 { ToolContext } from "#app/mcp/server";
+/**
+ * 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 (Terramend JWT, not GitHub). */
+export declare function patchWorkflowRunFields(ctx: ToolContext, 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,105 @@
+import type { PayloadEvent } from "#app/external";
+import type { RepoSettings } from "#app/utils/runContext";
+export declare const JsonPayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    "~terramend": true;
+    version: string;
+    prompt: string;
+    model?: string | undefined;
+    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;
+    severity_threshold?: string | undefined;
+    max_prs?: string | undefined;
+    allowed_paths?: string | undefined;
+    base_branch?: string | undefined;
+    allow_replace?: string | undefined;
+    protected_paths?: string | undefined;
+    autonomy_threshold?: string | undefined;
+    gitleaks?: string | undefined;
+    cost_increase_block_usd?: string | undefined;
+    module_catalogue?: string | undefined;
+    terratest?: string | undefined;
+    terraform_mcp?: string | undefined;
+    review_instructions?: string | undefined;
+    fp_filtering_instructions?: string | undefined;
+}, {}>;
+export type Inputs = typeof Inputs.infer;
+export type ResolvedPromptInput = string | typeof JsonPayload.infer;
+export declare function resolvePromptInput(): ResolvedPromptInput;
+/**
+ * Canonicalize the `mode` input against the built-in mode names
+ * (case-insensitive). Returns the canonical name (e.g. "remediate" →
+ * "Remediate") 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 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;
+export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput, repoSettings: RepoSettings): {
+    "~terramend": 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;
+    severityThreshold: string | undefined;
+    maxPrs: number | undefined;
+    allowedPaths: string[] | undefined;
+    protectedPaths: string[] | undefined;
+    autonomyThreshold: string | undefined;
+    gitleaks: boolean;
+    costIncreaseBlockUsd: number | undefined;
+    moduleCatalogue: string | undefined;
+    terratest: boolean;
+    terraformMcp: boolean;
+    remediationCommand: import("#app/utils/remediationCommand").RemediationCommand | null;
+    baseBranch: string | undefined;
+    allowReplace: string[] | undefined;
+    reviewInstructions: string | undefined;
+    fpFilteringInstructions: 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
+ * `action/modes.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 = "terramend-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/progressComment.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Single source of truth for reading, updating, deleting, and creating "progress comments" —
+ * the GitHub comments Terramend 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 Terramend'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;