terramend 0.2.0

package/dist/toolState.d.ts

@@ -0,0 +1,135 @@
+import type { AgentUsage } from "#app/agents/shared";
+import type { Concern } from "#app/mcp/terraform/types";
+import type { PrepResult } from "#app/prep/types";
+import type { AgentDiagnostic } from "#app/utils/agentHangReport";
+import type { DiffCoverageState } from "#app/utils/diffCoverage";
+import { type ProgressComment, type ProgressCommentType } from "#app/utils/progressComment";
+import type { TodoTracker } from "#app/utils/todoTracking";
+export type BackgroundProcess = {
+    pid: number;
+    outputPath: string;
+    pidPath: string;
+};
+export type StoredPushDest = {
+    remoteName: string;
+    remoteBranch: string;
+    localBranch: string;
+};
+/**
+ * Valid inline-comment anchor lines per side at a particular checkout SHA.
+ * Lives here (not in `mcp/review.ts`) so `ToolState` — which caches
+ * `Map<path, CommentableLines>` per checkout — does not pull the MCP server
+ * graph into every consumer of run state (the action's main loop, agent
+ * harnesses, cf-worker indexing).
+ */
+export type CommentableLines = {
+    RIGHT: Set<number>;
+    LEFT: Set<number>;
+};
+/**
+ * mutable per-run record of facts that occurred during execution. shared
+ * between the action process and the MCP server (one process — toolState is
+ * just a JS object passed by reference into both surfaces).
+ *
+ * design rule: ToolState is LITERAL. each field records a thing that
+ * happened — `review` is set when `create_pull_request_review` succeeded,
+ * `finalSummaryWritten` flips when `report_progress` wrote a non-plan body,
+ * `selectedMode` is set when `select_mode` was called. fields should never
+ * encode the absence of an event ("unsubmittedReview", "missingArtifact"),
+ * speculative state, or values derived from other fields.
+ *
+ * any predicate the rest of the code needs ("the agent picked review mode but
+ * never produced a review or progress write") is computed inline at the call
+ * site, not stored. derived state in this struct invariably drifts from the
+ * literal fields under refactors and is the wrong layer for the check.
+ *
+ * write narrowly: prefer adding state inside the tool that mutates it (e.g.
+ * `create_pull_request_review` populates `toolState.review`) and reading
+ * narrowly elsewhere. don't introduce flags from main.ts that mirror what an
+ * MCP tool already records.
+ */
+export interface ToolState {
+    pushUrl?: string;
+    pushDest?: StoredPushDest;
+    initialHead?: {
+        kind: "branch";
+        name: string;
+    } | {
+        kind: "detached";
+        sha: string;
+    };
+    issueNumber?: number;
+    createdTargets?: Set<number>;
+    checkoutSha?: string;
+    commentableLinesByFile?: Map<string, CommentableLines>;
+    commentableLinesPullNumber?: number;
+    commentableLinesCheckoutSha?: string | undefined;
+    beforeSha?: string;
+    selectedMode?: string;
+    remediationPrsOpened?: number;
+    plannedDestroy?: {
+        stateful: {
+            address: string;
+            action: string;
+            type: string;
+        }[];
+        ephemeral: {
+            address: string;
+            action: string;
+            type: string;
+        }[];
+    };
+    baselineConcernIds?: string[];
+    lastScanConcerns?: Concern[];
+    emittedSarifPath?: string;
+    lastBlastTier?: "low" | "medium" | "high";
+    lastIdempotent?: boolean;
+    lastCostDirection?: "increase" | "decrease" | "no-change" | "unknown";
+    prepushFailureCount: number;
+    backgroundProcesses: Map<string, BackgroundProcess>;
+    review?: {
+        id: number;
+        nodeId: string;
+        reviewedSha: string | undefined;
+    };
+    reviewReplies?: Map<number, {
+        commentId: number;
+        url: string | undefined;
+        bodyWithFooter: string;
+    }>;
+    dependencyInstallation?: {
+        status: "not_started" | "in_progress" | "completed" | "failed";
+        promise: Promise<PrepResult[]> | undefined;
+        results: PrepResult[] | undefined;
+    };
+    progressComment: ProgressComment | null | undefined;
+    hadProgressComment: boolean;
+    lastProgressBody?: string;
+    wasUpdated?: boolean;
+    finalSummaryWritten?: boolean;
+    existingPlanCommentId?: number;
+    previousPlanBody?: string;
+    summaryFilePath?: string;
+    summarySeed?: string;
+    summaryPersistAttempted?: boolean;
+    learningsFilePath?: string;
+    learningsSeed?: string;
+    learningsPersistAttempted?: boolean;
+    output?: string | undefined;
+    usageEntries: AgentUsage[];
+    model?: string | undefined;
+    modelFallback?: {
+        from: string;
+    } | undefined;
+    todoTracker?: TodoTracker | undefined;
+    diffCoverage?: DiffCoverageState | undefined;
+    agentDiagnostic?: AgentDiagnostic | undefined;
+}
+interface InitToolStateParams {
+    progressComment: {
+        id: string;
+        type: ProgressCommentType;
+    } | undefined;
+}
+export declare function initToolState(params: InitToolStateParams): ToolState;
+export {};

package/dist/utils/activity.d.ts

@@ -0,0 +1,40 @@
+/**
+ * generic `spawn()` idle default for ordinary short-lived subprocesses (prep
+ * probes, package-manager invocations, dependency installs). these should be
+ * producing output steadily, so a comparatively tight budget catches a wedged
+ * command promptly. the long-silent-tool tolerance the agent harnesses need
+ * lives in AGENT_ACTIVITY_TIMEOUT_MS, applied explicitly at those sites.
+ */
+export declare const DEFAULT_ACTIVITY_TIMEOUT_MS = 300000;
+/**
+ * flat idle budget for the agent activity watchdog (the outer process-output
+ * monitor, the v1 harness spawns, and the v2 inner event-silence watchdog).
+ * sized to exceed the worst-case legitimate silent tool window (issue #760:
+ * `checkout_pr` git fetch+deepen on a large monorepo, ~4-5min) with generous
+ * headroom, so no single in-flight tool call can be mistaken for a stall. a
+ * timeout this generous needs no suspend/resume bracketing — the cost of a
+ * genuinely hung run is only GitHub Actions minutes, not tokens.
+ */
+export declare const AGENT_ACTIVITY_TIMEOUT_MS = 900000;
+export declare const DEFAULT_ACTIVITY_CHECK_INTERVAL_MS = 5000;
+export declare const ACTIVITY_NOISE_PATTERNS: readonly RegExp[];
+export declare function isActivityNoise(chunk: string | Uint8Array): boolean;
+type ActivityTimeoutContext = {
+    timeoutMs: number;
+    checkIntervalMs: number;
+};
+export type ActivityTimeout = {
+    promise: Promise<never>;
+    stop: () => void;
+    /** force the timeout to reject immediately with a custom reason */
+    forceReject: (reason: string) => void;
+};
+/**
+ * mark activity to reset the no-output timeout.
+ * call this whenever the agent emits any event, even if it isn't logged to stdout.
+ */
+export declare function markActivity(): void;
+/** get the time since last activity in milliseconds. */
+export declare function getIdleMs(): number;
+export declare function createProcessOutputActivityTimeout(ctx: ActivityTimeoutContext): ActivityTimeout;
+export {};

package/dist/utils/agent.d.ts

@@ -0,0 +1,20 @@
+import type { Agent } from "#app/agents/index";
+/**
+ * resolve the effective model for this run.
+ *
+ * priority:
+ *   1. TERRAMEND_MODEL env var — resolved through the alias registry first,
+ *      so values like "anthropic/claude-opus" become "anthropic/claude-opus-4-7".
+ *      raw specifiers (e.g. "anthropic/claude-opus-4-6") pass through unchanged.
+ *      always wins — bypasses Bedrock routing entirely. to test a different
+ *      Bedrock model, change `BEDROCK_MODEL_ID`, not `TERRAMEND_MODEL`.
+ *   2. slug from repo config / payload → alias registry. routing slugs
+ *      (e.g. `bedrock/byok`) defer to a separate env var (`BEDROCK_MODEL_ID`).
+ *   3. undefined — agent will auto-select.
+ */
+export declare function resolveModel(ctx: {
+    slug?: string | undefined;
+}): string | undefined;
+export declare function resolveAgent(ctx: {
+    model?: string | undefined;
+}): Agent;

package/dist/utils/agentHangReport.d.ts

@@ -0,0 +1,38 @@
+/**
+ * mutable per-run handle the agent harness writes to as a run progresses.
+ * the action's outer try/catch in `main.ts` reads this off `toolState` when
+ * the activity-timeout watchdog wins the race against the harness's own
+ * catch — the bare timer reject reason ("activity timeout: no output for
+ * 302s") tells the user nothing actionable, but `recentStderr` +
+ * `lastProviderError` together usually point straight at the upstream cause.
+ *
+ * `recentStderr` is shared by reference with the harness's bounded ring
+ * buffer, so the diagnostic always reflects the latest captured tail.
+ */
+export type AgentDiagnostic = {
+    /** display label for the agent, e.g. "Terramend". used in the headline. */
+    label: string;
+    /** shared reference to the harness's bounded stderr ring buffer. */
+    recentStderr: string[];
+    /** most-recent provider-error label from `detectProviderError`, if any. */
+    lastProviderError: string | undefined;
+    /** count of stdout events successfully parsed before the failure. */
+    eventCount: number;
+};
+/**
+ * Build a user-facing markdown body for an agent hang or failure.
+ *
+ * Rendered into both the PR progress comment and the GitHub Actions job
+ * summary. Returns `null` when no diagnostic is available, which signals to
+ * the caller to fall back to its bare-error rendering.
+ *
+ * `errorMessage` is the underlying timer / spawn reject string (e.g.
+ * `activity timeout: no output for 301s`). The idle seconds are parsed out
+ * of it for the hang explanation — total runtime would overstate the stall
+ * for runs that streamed for a long time before going quiet.
+ */
+export declare function formatAgentHangBody(input: {
+    diagnostic: AgentDiagnostic | undefined;
+    isHang: boolean;
+    errorMessage: string;
+}): string | null;

package/dist/utils/apiFetch.d.ts

@@ -0,0 +1,19 @@
+type ApiFetchOptions = {
+    path: string;
+    method?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    body?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+/**
+ * fetch wrapper for hitting the Terramend API with Vercel deployment protection bypass.
+ *
+ * adds the bypass secret as BOTH a query parameter and a header for maximum reliability.
+ * the server-side forwarding code uses query params, and the Vercel docs say both work,
+ * so we do both as belt-and-suspenders.
+ *
+ * the query param approach is the primary bypass mechanism (matches server-side forwarding).
+ * the header is added as a fallback.
+ */
+export declare function apiFetch(options: ApiFetchOptions): Promise<Response>;
+export {};

package/dist/utils/apiKeys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Validate that the resolved model can actually be served by the chosen
+ * agent. For routing slugs (Bedrock / Vertex) the auth shape is multi-var
+ * (auth + region/location + model-id) and `opencode models` doesn't catch
+ * gaps in the latter two — keep dedicated setup validators. For the
+ * opencode path, the authoritative answer comes from OpenCode's own model
+ * introspection (`authorized` set captured in `openCodeModels.ts`). For
+ * the claude path, fall back to the static check (`ANTHROPIC_API_KEY` /
+ * `CLAUDE_CODE_OAUTH_TOKEN`).
+ */
+export declare function validateAgentApiKey(params: {
+    agent: {
+        name: string;
+    };
+    model: string | undefined;
+    authorized: Set<string>;
+    owner: string;
+    name: string;
+}): void;
+/**
+ * Detect agent-runtime auth failures that should be reformatted as an actionable
+ * key-fix CTA before being shown to the user. Covers the shapes we see:
+ *   - missing key (validateAgentApiKey throw): contains MISSING_KEY_MARKER
+ *   - revoked / invalid key (Claude CLI 401 surfaced via api_error_status):
+ *     "Invalid API key · Fix external API key" + similar provider variants
+ *   - direct-Anthropic 401 (`Failed to authenticate. API Error: 401 ...
+ *     {"type":"error","error":{"type":"authentication_error", ...
+ *     "Invalid bearer token"}}`) emitted by the Claude CLI for revoked /
+ *     mistyped / rotated `ANTHROPIC_API_KEY`. see #782.
+ */
+export declare function isApiKeyAuthError(text: string): boolean;
+/**
+ * Friendly Markdown summary for both the missing-key and invalid-key cases.
+ * Used in the catch / result-failure paths in `main.ts` to overwrite the raw
+ * agent error before it's posted to the PR progress comment.
+ */
+export declare function formatApiKeyErrorSummary(params: {
+    owner: string;
+    name: string;
+    raw: string;
+}): string;

package/dist/utils/apiUrl.d.ts

@@ -0,0 +1,20 @@
+/**
+ * resolve the Terramend API base URL.
+ *
+ * in the action: API_URL is not explicitly set, so this falls back to https://terramend.com.
+ * in local dev: API_URL=http://localhost:3000 (from .env).
+ *
+ * enforces https:// for non-local URLs to prevent cleartext credential transmission.
+ */
+export declare function getApiUrl(): string;
+/**
+ * Whether a real Terramend backend is configured.
+ *
+ * Standalone BYOK runs (the OSS default) leave `API_URL` unset — `getApiUrl`
+ * then falls back to the marketing host, which serves no API. The dormant
+ * open-core persistence seams (repo learnings, run-field PATCHes) must no-op
+ * in that case rather than POST into the void and surface the host's 404 as a
+ * CI warning. A real backend — the hosted SaaS, or local dev with
+ * `API_URL=http://localhost:3000` — sets `API_URL` explicitly.
+ */
+export declare function isBackendConfigured(): boolean;

package/dist/utils/assets.d.ts

@@ -0,0 +1,8 @@
+/**
+ * downloads any github-hosted image/video assets referenced in `markdown` to
+ * `<tmpdir>/assets` and rewrites the urls to the local file paths, so the agent can
+ * read screenshots directly instead of relying on remote (often short-lived, signed)
+ * urls. unique urls are downloaded once and every occurrence is rewritten. assets that
+ * fail to download are left untouched.
+ */
+export declare function downloadAssetsInMarkdown(markdown: string, tmpdir: string, githubToken: string): Promise<string>;

package/dist/utils/billingErrors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Billing-error classification + user-facing copy for `/api/proxy-token`
+ * failures and OpenRouter mid-run exhaustion. Two error classes (Billing vs.
+ * Transient) keep the framing honest: a card decline is *not* the same UX as
+ * a 503 from the proxy service. Both originate in `utils/proxy.ts` (mint
+ * failures) and `utils/runErrorRenderer.ts` (mid-run keylimit reclassify).
+ *
+ * Renderers return markdown bodies that are written into both the GitHub
+ * Actions job summary and the PR progress comment.
+ *
+ * Lives outside `main.ts` so adding a new error `code` branch is a one-file
+ * edit that does not retrigger the full LLM CI matrix (`action/main.ts` is
+ * in `action/test/coverage.ts::ALWAYS_RUN_ALL`).
+ */
+/**
+ * Billing-layer error surfaced from `/api/proxy-token` as a 402. User-actionable
+ * — distinct from TransientError (503 / transient sync issue) so the job
+ * summary + PR comment can use affirmative "you need to do X" copy rather than
+ * the ambiguous "billing error" label that makes transient outages look like
+ * the user's fault.
+ *
+ * `code` is a server-side discriminator: `router_requires_card` (no card + no
+ * wallet balance on Router), or null for unclassified. `declineCode` is
+ * Stripe's more specific sub-reason on `card_declined` (e.g.
+ * `insufficient_funds`, `lost_card`). `needsReauthentication` is the 3DS case
+ * broken out for convenience.
+ */
+export declare class BillingError extends Error {
+    code: string | null;
+    declineCode: string | null;
+    needsReauthentication: boolean;
+    constructor(message: string, opts?: {
+        code?: string | null;
+        declineCode?: string | null;
+        needsReauthentication?: boolean;
+    });
+}
+/**
+ * Transient service failures from `/api/proxy-token` (503: partial OpenRouter
+ * usage sync, DB flake, in-flight payment intent). Not the user's fault — the
+ * summary uses "temporarily unavailable" framing, and the non-zero exit lets
+ * GH Actions apply whatever retry policy the workflow has configured.
+ */
+export declare class TransientError extends Error {
+    constructor(message: string);
+}
+/**
+ * Render a BillingError as user-facing markdown (shared between GH job summary
+ * and the PR progress comment). Goals:
+ *
+ *   - quiet, not alarmist — bold first line instead of an `### ❌` H3, since
+ *     the comment already has Terramend branding in the footer
+ *   - actionable — every branch ends in a single CTA deep-linked to the
+ *     correct section of the owner's console
+ *   - honest — say what actually went wrong (card declined vs. balance
+ *     empty vs. 3DS required), don't lump them under "billing error"
+ *
+ * Branches:
+ *   - `router_requires_card`: user is on Router mode with no card AND no
+ *     wallet balance (signup credit exhausted or not granted). Frame as
+ *     "add a card to continue", link to `#model-access` where the Add
+ *     Card flow lives.
+ *   - `router_balance_exhausted`: user has a card on file but auto-reload is
+ *     disabled and they've spent past their $5 overdraft buffer. Frame as
+ *     "balance ran out" and surface both remediation paths (top up, or flip
+ *     on auto-reload).
+ *   - `router_keylimit_exhausted`: OpenRouter rejected mid-run because the
+ *     per-run key budget was exhausted while the agent was working. The
+ *     wallet is now negative; same remediation as `router_balance_exhausted`
+ *     but framed for the after-the-fact case ("this run was cut short").
+ *   - `needsReauthentication`: issuer requires 3DS on every off-session
+ *     charge. Re-adding the card won't help — the only escape is a manual
+ *     top-up where 3DS runs interactively in Stripe Checkout.
+ *   - `declineCode` set: Stripe declined a real charge. Show the sub-code
+ *     so support can act on it; tell the user we'll retry on next dispatch.
+ *   - default: balance hit zero with no in-flight charge (auto-reload off
+ *     or amount below threshold). Direct them to top up or enable auto-reload.
+ */
+export declare function formatBillingErrorSummary(error: BillingError, owner: string): string;
+/**
+ * Render a TransientError as user-facing markdown. Distinct framing from
+ * BillingError so the user doesn't read an alarm and assume their card
+ * failed — this branch is "our fault, retry shortly", not theirs.
+ */
+export declare function formatTransientErrorSummary(error: TransientError, owner: string): string;

package/dist/utils/body.d.ts

@@ -0,0 +1,34 @@
+import type { PayloadEvent } from "#app/external";
+import type { OctokitWithPlugins } from "#app/utils/github";
+import type { RunContextData } from "#app/utils/runContextData";
+interface ResolveBodyContext {
+    event: PayloadEvent;
+    octokit: OctokitWithPlugins;
+    repo: RunContextData["repo"];
+    tmpdir: string;
+    githubToken: string;
+}
+/**
+ * resolves the body of an event by fetching body_html and converting to markdown.
+ * only fetches body_html if the body contains images (to avoid unnecessary API calls).
+ * this ensures agents receive markdown with working signed image URLs instead of
+ * broken user-attachments URLs.
+ */
+export declare function resolveBody(ctx: ResolveBodyContext): Promise<string | null>;
+interface ResolveBodyAssetsContext {
+    body: string | null | undefined;
+    bodyHtml: string | null | undefined;
+    tmpdir: string;
+    githubToken: string;
+}
+/**
+ * downloads github-hosted image assets in a body to disk and rewrites the urls to local
+ * paths so the agent can read them. when the body has images and a rendered `bodyHtml`
+ * is supplied, the html is turndowned first: github only exposes attachments as signed,
+ * self-authenticating `*.githubusercontent.com` urls through body_html — the raw
+ * `github.com/user-attachments/...` urls in unrendered markdown 404 for the installation
+ * token. callers that fetch a body should request it with the `application/vnd.github.full+json`
+ * media type and pass `body_html` here.
+ */
+export declare function resolveBodyAssets(ctx: ResolveBodyAssetsContext): Promise<string | null>;
+export {};

package/dist/utils/buildTerramendFooter.d.ts

@@ -0,0 +1,25 @@
+export declare const TERRAMEND_DIVIDER = "<!-- TERRAMEND_DIVIDER_DO_NOT_REMOVE_PLZ -->";
+export interface BuildTerramendFooterParams {
+    /** add "via Terramend" link */
+    triggeredBy?: boolean;
+    /** arbitrary custom parts (e.g., action links) */
+    customParts?: string[] | undefined;
+    /** model slug from payload (e.g., "anthropic/claude-opus"). shown in footer as "Using `Model Name`" */
+    model?: string | undefined;
+    /**
+     * When the action engaged the BYOK fallback, this is the slug the user
+     * had configured (e.g. "anthropic/claude-opus") — the footer renders
+     * `Using <free model> (credentials for <configured> not configured)`
+     * so the substitution is visible in PR comments + reviews.
+     */
+    fallbackFrom?: string | undefined;
+}
+/**
+ * build a terramend footer with configurable parts
+ * order: action links (customParts) > model > attribution
+ */
+export declare function buildTerramendFooter(params: BuildTerramendFooterParams): string;
+/**
+ * strip any existing terramend footer from a comment body
+ */
+export declare function stripExistingFooter(body: string): string;

package/dist/utils/byokFallback.d.ts

@@ -0,0 +1,85 @@
+import type { AgentId } from "#app/external";
+/**
+ * Slug we fall back to when a BYOK-required model is configured but the
+ * runner has no provider key in env. Picked because it's free, stable, and
+ * currently served by OpenCode Zen without a key.
+ *
+ * The slug is intentionally hard-coded and not a config knob — the
+ * fallback is a safety net, not a user-facing preference, and adding a
+ * config surface here would just push the same "what to fall back to"
+ * decision into another setting that goes stale the same way.
+ */
+export declare const FREE_FALLBACK_SLUG = "opencode/big-pickle";
+/**
+ * Outcome of the BYOK model gate.
+ *
+ *   - `use-resolved`: run the configured model as-is.
+ *   - `fallback`: the runner has NO provider key for this model's provider,
+ *     so swap to the free OpenCode slug — a genuine no-key safety net.
+ *   - `unavailable`: a provider key IS present but the configured model is
+ *     not one OpenCode can route with it. This is almost always a wrong or
+ *     mistyped model id (or a key scoped to other models). We must NOT
+ *     silently downgrade to the free model — that hides the misconfiguration
+ *     and produces a free run the user didn't ask for (see PR #2). The caller
+ *     fails loudly with the authorized-model list instead.
+ */
+export type FallbackDecision = {
+    kind: "use-resolved";
+} | {
+    kind: "fallback";
+    from: string;
+    to: string;
+} | {
+    kind: "unavailable";
+    model: string;
+};
+/**
+ * Does the runner have a provider credential for `resolvedModel`'s provider?
+ *
+ * Uses the provider→envVars map in `models.ts` (provider-level, since a
+ * resolved specifier like `google/gemini-3.5-flash-lite` won't match a catalog
+ * model key and correctly falls through to the provider's env vars). A present
+ * key is what distinguishes the two not-authorized situations: key present =
+ * wrong/unavailable model id (fail loudly); no key = genuine BYOK gap (free
+ * fallback).
+ */
+export declare function hasProviderKeyForModel(resolvedModel: string): boolean;
+/**
+ * Decide whether to run the configured model, fall back to the free model, or
+ * fail because the model is unavailable to the present key.
+ *
+ * `authorized` is OpenCode's authoritative "what can I route right now"
+ * snapshot, captured after Codex auth.json is in place.
+ *
+ * Skip cases (always `use-resolved`, without consulting `authorized`):
+ *   - No resolved model: auto-select handles it downstream.
+ *   - Resolved model is the free fallback already.
+ *   - Resolved model is a raw Bedrock / Vertex ID (no `/`): the routing
+ *     validators (`validateBedrockSetup` / `validateVertexSetup`) cover
+ *     auth + region/location/model-id; `opencode models` does not.
+ *   - The selected agent is `claude`: the Claude Code harness brings its own
+ *     auth and `resolveAgent` only returns it when that auth is present.
+ *     `opencode models` can't see `CLAUDE_CODE_OAUTH_TOKEN`, so without this
+ *     an OAuth-subscription run on an Anthropic model would land in
+ *     `unavailable` (the token counts as a present provider key) and fail a
+ *     run the claude harness serves fine. `validateAgentApiKey` still covers
+ *     the claude path with its own Anthropic auth check.
+ */
+export declare function selectFallbackModelIfNeeded(input: {
+    resolvedModel: string | undefined;
+    authorized: Set<string>;
+    /** whether a provider key for the resolved model's provider is present in env */
+    providerKeyPresent: boolean;
+    /** which agent harness `resolveAgent` picks for the resolved model */
+    agentName: AgentId;
+}): FallbackDecision;
+/**
+ * Loud, actionable error for the `unavailable` decision: a provider key is
+ * present but the configured model isn't one the key can serve. Lists the
+ * models OpenCode CAN route (same-provider first) so the user can copy a valid
+ * slug instead of getting a silent free downgrade.
+ */
+export declare function buildUnavailableModelError(input: {
+    model: string;
+    authorized: Set<string>;
+}): string;

package/dist/utils/claudeSubscription.d.ts

@@ -0,0 +1,30 @@
+export type SubscriptionPreflight = {
+    usable: true;
+} | {
+    usable: false;
+    reason: string;
+};
+/**
+ * preflight a Claude subscription OAuth token (`CLAUDE_CODE_OAUTH_TOKEN`)
+ * with a 1-token Messages call, so the agent can fall back to
+ * `ANTHROPIC_API_KEY` when the subscription is exhausted or revoked instead
+ * of failing the whole run at its first model call. rides the same de-facto
+ * OAuth surface Claude Code itself uses: Bearer auth + the
+ * `claude-code-20250219,oauth-2025-04-20` betas + the identity system prompt.
+ *
+ * probes the run's own model when known — subscription limits can be
+ * per-model ("You've hit your Opus limit"), so a cheaper stand-in could pass
+ * preflight and still leave the run dead on arrival.
+ *
+ * fail-open by design: only 401 (revoked/expired token) and 429
+ * (session/weekly/per-model limit) mark the token unusable. network errors,
+ * 5xx, and request-shape drift (400) all keep today's subscription-first
+ * behavior, so the preflight can never fail a run that would have worked —
+ * the worst wrong answer is a run that bills the API key instead of the
+ * subscription.
+ */
+export declare function preflightClaudeSubscription(params: {
+    token: string;
+    /** bare Anthropic model id the run will use (e.g. "claude-fable-5") */
+    model: string | undefined;
+}): Promise<SubscriptionPreflight>;

package/dist/utils/cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI utilities
+ */
+export { formatIndentedField, formatJsonValue, formatUsageSummary, log, writeSummary, } from "#app/utils/log";
+/**
+ * Finds a CLI executable path by checking if it's installed globally
+ * @param name The name of the CLI executable to find
+ * @returns The path to the CLI executable, or null if not found
+ */
+export declare function findCliPath(name: string): string | null;

package/dist/utils/codexHome.d.ts

@@ -0,0 +1,29 @@
+/** sandbox-hidden home for terramend-managed on-disk secrets in CI. bash via
+ * MCP shell tmpfs-overlays this path; opencode's internal auth module
+ * bypasses external_directory and reaches the real file. mirrors the
+ * pattern in action/agents/claude.ts installManagedSettings.
+ *
+ * not used for codex auth in local dev — the sandbox is no-op there, so
+ * the path doesn't matter. local dev keeps the existing $HOME path. */
+export declare const TERRAMEND_DATA_DIR = "/var/lib/terramend";
+export interface InstalledCodexAuth {
+    /** absolute path of the auth.json we wrote — caller passes this to the
+     * post-hook via core.saveState for refresh-detection later. */
+    authPath: string;
+    /** value to set as XDG_DATA_HOME for the OpenCode subprocess. */
+    xdgDataHome: string;
+    /** refresh_token from the env at materialization time. post-hook
+     * compares against the on-disk file after the run to detect whether
+     * OpenCode refreshed during the session (only happens on long runs
+     * that span >50min — see wiki/codex-auth.md "Concurrency"). */
+    originalRefresh: string;
+}
+/** materialize CODEX_AUTH_JSON from env into a disk path OpenCode reads from.
+ * returns null when the env var is absent, malformed, or wrong auth mode —
+ * caller treats null as "no codex auth, fall through to API key flow".
+ *
+ * The env value is read as-is — we parse + write it here and set
+ * `process.env.XDG_DATA_HOME` so every opencode subprocess discovers the
+ * auth.json; no refresh and no DB interaction. Freshness is the supplier's
+ * responsibility (see the header caveat on static-secret expiry). */
+export declare function installCodexAuth(): InstalledCodexAuth | null;