sdkproof 0.1.0

package/dist/core/verify.js

@@ -0,0 +1,191 @@
+import { execFile } from "node:child_process";
+import { writeFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+// A tsc "--pretty false" primary diagnostic line:
+//   path/candidate.ts(4,22): error TS2551: Property 'createOne' does not exist ...
+const DIAG_RE = /^(.+?)\((\d+),(\d+)\):\s+error\s+(TS\d+):\s+(.*)$/;
+// Error codes that indicate misuse of an API surface (a hallucinated/wrong/
+// removed member or signature) rather than a generic JS mistake.
+export const API_SHAPE_CODES = new Set([
+    "TS2339", // property does not exist on type
+    "TS2551", // property does not exist — did you mean X
+    "TS2353", // object literal may only specify known properties (invented field)
+    "TS2561", // did you mean to write X
+    "TS2554", // wrong number of arguments
+    "TS2345", // argument type not assignable
+    "TS2322", // type not assignable
+    "TS2559", // type has no properties in common with
+    "TS2307", // cannot find module (bad import path)
+    "TS2724", // module has no exported member — did you mean X
+    "TS2305", // module has no exported member (the member moved entrypoint)
+    "TS1192", // module has no default export (the default export was removed)
+    "TS2694", // namespace has no exported member
+    // The call/type-argument shape changed under the model's feet. All four were
+    // landing in the residual bucket while being exactly the thing this harness
+    // measures: TS2314 alone accounts for more diagnostics across the bench than
+    // any other code, and TS2558 is the third error in the README's own
+    // TanStack Table example.
+    "TS2769", // no overload matches this call
+    "TS2314", // generic type requires N type argument(s)
+    "TS2558", // expected N type arguments, but got M
+    "TS2707", // generic type requires between N and M type arguments
+    "TS2347", // untyped function calls may not accept type arguments
+]);
+/**
+ * Type-check a model-generated candidate against the real installed package,
+ * inside the library's sandbox fixture. A candidate "passes" iff it compiles
+ * clean under the fixture's strict tsconfig.
+ */
+export async function verify(candidate, spec, opts) {
+    // An empty or bodyless candidate compiles clean, so without this it scores as
+    // a PASS — a generation failure recorded as a perfect answer. Found on the
+    // first Stripe run (2026-08-04): four of fifteen candidates came back empty
+    // because the model hit max_tokens, lost its closing fence, and extraction
+    // returned nothing. All four "passed" and the library scored 100/100.
+    //
+    // Every task skeleton asks for an export, so a candidate with no `export`
+    // has not answered. That is a harness failure, not model drift, and it is
+    // reported with a code outside API_SHAPE_CODES so it can never be counted as
+    // a library-drift finding.
+    // A candidate may not redefine the library it is being measured against.
+    // TypeScript module augmentation ADDS the declared members to the module's
+    // exports, so `declare module "react-router" { interface AppLoadContext {} }`
+    // re-creates a type v8 deleted and the accompanying import resolves — a
+    // candidate written entirely against the REMOVED API compiles clean and
+    // scores as a PASS. Found 2026-08-17 probing react-router v8: two of five
+    // candidates that reached for the deleted `AppLoadContext` passed, purely
+    // because they also wrote the augmentation. The third, which imported it
+    // without augmenting, failed with TS2305 as it should.
+    //
+    // This is the same failure class as an empty candidate passing: the harness
+    // converts "the model used the old API" into "the model got it right".
+    // SDKP002 is deliberately outside API_SHAPE_CODES so it can never be counted
+    // as library drift either.
+    const augmented = augmentsLibrary(candidate.code, spec.packageName);
+    if (augmented) {
+        return {
+            taskId: candidate.taskId,
+            model: candidate.model,
+            passed: false,
+            errors: [{ code: "SDKP002", message: augmented, line: 0, column: 0, libraryRelated: false }],
+        };
+    }
+    // Runs BEFORE the empty-candidate check on purpose: augmentation is the more
+    // specific diagnosis, and emptyCandidate's `declare` strip is line-oriented in
+    // intent but its [^;]* spans newlines, so a multi-line `declare module` block
+    // swallows the rest of the candidate and reports SDKP001 instead.
+    const empty = emptyCandidate(candidate.code);
+    if (empty) {
+        return {
+            taskId: candidate.taskId,
+            model: candidate.model,
+            passed: false,
+            errors: [{ code: "SDKP001", message: empty, line: 0, column: 0, libraryRelated: false }],
+        };
+    }
+    const candidatePath = path.join(spec.fixtureDir, spec.candidateFile ?? "candidate.ts");
+    const tsconfigPath = path.join(spec.fixtureDir, "tsconfig.json");
+    await writeFile(candidatePath, candidate.code, "utf8");
+    try {
+        const output = await runTsc(opts.tscEntry, tsconfigPath);
+        const errors = parseDiagnostics(output, spec);
+        return {
+            taskId: candidate.taskId,
+            model: candidate.model,
+            passed: errors.length === 0,
+            errors,
+        };
+    }
+    finally {
+        await rm(candidatePath, { force: true });
+    }
+}
+/**
+ * Detect a candidate that augments the module it is supposed to be USING.
+ * Matches the package itself and any subpath entrypoint of it, so
+ * `declare module "@apollo/client/react"` is caught as well as
+ * `declare module "@apollo/client"`.
+ *
+ * Deliberately conservative: it fires on ANY augmentation of the library's own
+ * module, not only ones that redeclare a removed symbol. Telling those apart
+ * needs type introspection, and the cost of being wrong is asymmetric — a
+ * false positive costs one task, a false negative silently inflates a
+ * published score. Measured before shipping: `declare module` appears in 0 of
+ * 35 stored candidate files, so this fires on nothing that has ever been run.
+ */
+export function augmentsLibrary(code, packageName) {
+    const pkg = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`declare\\s+module\\s+["'\`]${pkg}(?:/[^"'\`]*)?["'\`]`);
+    const m = re.exec(code);
+    return m
+        ? `module augmentation: the candidate redefines "${packageName}" (${m[0].trim()}), which can re-create an API the package removed`
+        : null;
+}
+/**
+ * Reject candidates that cannot possibly be an answer. Returns a reason string
+ * when the candidate is unusable, or null when it is worth compiling.
+ */
+export function emptyCandidate(code) {
+    const trimmed = code.trim();
+    if (!trimmed)
+        return "empty candidate: the model returned no code";
+    // Strip comments and single-line imports; what remains must contain an export.
+    //
+    // The character class excludes newlines, which the original did not. `[^;]*`
+    // spans lines, so a candidate written WITHOUT SEMICOLONS had its entire body
+    // swallowed by the import strip and was reported as an empty candidate —
+    // a complete, correct answer recorded as a generation failure. It cost
+    // zustand a task on 2026-08-04 (`shallow-equality`, a 78-line answer scored
+    // as "no implementation") and every candidate of the first @sanity/client run
+    // through the CLI on 2026-08-22, because that model writes semicolon-free TS.
+    //
+    // A multi-line import is now left in place rather than stripped, which is the
+    // safe direction: it only ever makes `body` non-empty, so the candidate goes
+    // to the compiler and tsc decides instead of this heuristic.
+    const body = trimmed
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/^\s*\/\/.*$/gm, "")
+        .replace(/^\s*import\s[^;\n]*;?\s*$/gm, "")
+        .replace(/^\s*declare\s[^;\n]*;?\s*$/gm, "")
+        .trim();
+    if (!body)
+        return "empty candidate: only imports and comments, no implementation";
+    if (!/\bexport\b/.test(body))
+        return "no export: the candidate does not implement the requested export";
+    return null;
+}
+async function runTsc(tscEntry, tsconfigPath) {
+    try {
+        const { stdout } = await execFileAsync(process.execPath, [tscEntry, "-p", tsconfigPath, "--pretty", "false"], { maxBuffer: 16 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (err) {
+        // tsc exits non-zero when it reports errors; diagnostics are on stdout.
+        const e = err;
+        return (e.stdout ?? "") + (e.stderr ?? "");
+    }
+}
+/** Parse tsc "--pretty false" output into structured errors for the candidate. */
+export function parseDiagnostics(output, spec) {
+    const errors = [];
+    for (const line of output.split(/\r?\n/)) {
+        const m = DIAG_RE.exec(line);
+        if (!m)
+            continue;
+        const [, file, lineNo, colNo, code, message] = m;
+        // Only diagnostics in the candidate file reflect the model's code.
+        if (path.basename(file) !== (spec.candidateFile ?? "candidate.ts"))
+            continue;
+        errors.push({
+            code,
+            message,
+            line: Number(lineNo),
+            column: Number(colNo),
+            libraryRelated: API_SHAPE_CODES.has(code) || message.includes(spec.packageName),
+        });
+    }
+    return errors;
+}
+//# sourceMappingURL=verify.js.map

package/dist/core/verify.js.map

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

package/dist/drift.d.ts

@@ -0,0 +1,87 @@
+import { type Packument } from "./registry.ts";
+import { type Surface } from "./surface.ts";
+/**
+ * What changed between two published versions of a package, computed from the
+ * .d.ts files alone — no model, no API key, no install.
+ *
+ * This answers the question that decides whether a scored run is worth paying
+ * for: has this package removed anything a model is likely to still be writing?
+ */
+export interface DriftReport {
+    package: string;
+    from: {
+        version: string;
+        major: number;
+        published: string;
+    };
+    to: {
+        version: string;
+        major: number;
+        published: string;
+    };
+    /** months since the FIRST release in the `to` version's major line */
+    majorAgeMonths: number;
+    /** which extraction mode was used for BOTH versions — never mixed */
+    mode: "entry-only" | "all-dts";
+    fromCount: number;
+    toCount: number;
+    /** exported symbols present in `from` and gone in `to`, under `mode` */
+    removed: string[];
+    /**
+     * The subset of `removed` that carried no `@deprecated` jsdoc in the old
+     * version. Deprecate-then-remove gives a model's training data a signal to
+     * pick up; a silent removal does not, which is where the drift lives.
+     */
+    withoutRunway: string[];
+    /**
+     * The same thing computed from the package's declared type ENTRYPOINT only —
+     * what `import { x } from "pkg"` can actually reach. This is the sharp list.
+     * `removed` widens to every .d.ts in the package when either version's entry
+     * re-exports with `export *`, which drags in internals nobody imports.
+     */
+    removedFromEntry: string[];
+    /**
+     * The subset of `removedFromEntry` that the OLD version's README actually
+     * documents. A removed export nobody wrote produces no drift; a removed
+     * export the library taught people to write produces all of it. This is the
+     * list to lead with, and the reason `zod` looks alarming on raw counts —
+     * 155 exports went, but most were internal type aliases nobody imported.
+     */
+    documentedRemovals: string[];
+    /**
+     * The subset of `removedFromEntry` that was a value — a function, hook,
+     * class, const or enum — rather than a type-only declaration. A model writes
+     * values far more often than type names, so this is the sharper list when the
+     * package ships a README too thin to rank against.
+     */
+    valueRemovals: string[];
+}
+export interface DriftOptions {
+    /** explicit lower version; defaults to the top of the previous major line */
+    from?: string;
+    /** explicit upper version; defaults to the top of the newest major line */
+    to?: string;
+}
+export declare function computeDrift(p: Packument, opts?: DriftOptions): Promise<DriftReport>;
+/** What one surface lost relative to another. Split out so it can be tested without the network. */
+export declare function diffSurfaces(a: Surface, b: Surface, oldReadme: string): Pick<DriftReport, "mode" | "fromCount" | "toCount" | "removed" | "withoutRunway" | "removedFromEntry" | "documentedRemovals" | "valueRemovals">;
+/**
+ * The list worth showing a human, sharpest first: exports the old README
+ * documented, else everything that left the entrypoint, else the wide diff.
+ */
+export declare function headlineRemovals(d: DriftReport): string[];
+/** How the headline list was arrived at, for a caption the reader can trust. */
+export declare function headlineSource(d: DriftReport): string;
+/**
+ * Whether a scored run is likely to find anything, and why. Two facts drive
+ * this, both measured across 35 libraries on this project's bench:
+ *
+ *  - the drift window closes. Age of the major predicts drift better than the
+ *    size of the change does: Apollo v4 scored 0/12 once it had been out long
+ *    enough, and zustand v5 was fully absorbed by ~19 months.
+ *  - a removal with a deprecation runway produces almost nothing.
+ */
+export declare function driftVerdict(d: DriftReport): {
+    worth: boolean;
+    reason: string;
+};

package/dist/drift.js

@@ -0,0 +1,105 @@
+import { compareVersions, majorLines, monthsSince, readmeFor } from "./registry.js";
+import { isDeprecated, isPublicName, isValueExport, surfaceOf } from "./surface.js";
+export async function computeDrift(p, opts = {}) {
+    const lines = majorLines(p);
+    if ((!opts.from || !opts.to) && lines.length < 2) {
+        throw new Error(`${p.name} has only one major line — there is nothing to diff. Pass --from and --to to compare two specific versions.`);
+    }
+    const fromVersion = opts.from ?? lines[lines.length - 2].latest;
+    const toVersion = opts.to ?? lines[lines.length - 1].latest;
+    if (compareVersions(fromVersion, toVersion) >= 0) {
+        throw new Error(`--from (${fromVersion}) must be older than --to (${toVersion})`);
+    }
+    const [a, b] = await Promise.all([surfaceOf(p, fromVersion), surfaceOf(p, toVersion)]);
+    const diff = diffSurfaces(a, b, a.readme || readmeFor(p, fromVersion));
+    const toMajor = Number(toVersion.split(".")[0]);
+    const toLine = lines.find((l) => l.major === toMajor);
+    return {
+        package: p.name,
+        from: { version: fromVersion, major: Number(fromVersion.split(".")[0]), published: p.time?.[fromVersion] ?? "" },
+        to: { version: toVersion, major: toMajor, published: p.time?.[toVersion] ?? "" },
+        majorAgeMonths: Number(monthsSince(toLine?.first ?? p.time?.[toVersion] ?? "").toFixed(1)),
+        ...diff,
+    };
+}
+/** What one surface lost relative to another. Split out so it can be tested without the network. */
+export function diffSurfaces(a, b, oldReadme) {
+    // ONE mode for the pair. Deciding per version is what made Apollo read as a
+    // 674 -> 133 collapse when the real removal count was far smaller.
+    const widen = a.needsWiden || b.needsWiden;
+    const fromSyms = widen ? a.widened : a.entryOnly;
+    const toSyms = widen ? b.widened : b.entryOnly;
+    const removed = [...fromSyms].filter((s) => !toSyms.has(s) && isPublicName(s)).sort();
+    const withoutRunway = removed.filter((s) => !isDeprecated(a.sources, s));
+    const removedFromEntry = [...a.entryOnly]
+        .filter((s) => !b.entryOnly.has(s) && isPublicName(s) && !isDeprecated(a.sources, s))
+        .sort();
+    // Word-boundary hits in the old README, so `parse` does not match `safeParse`.
+    const documentedRemovals = removedFromEntry.filter((sym) => new RegExp(`\\b${sym.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(oldReadme));
+    const valueRemovals = removedFromEntry.filter((sym) => isValueExport(a.sources, sym));
+    return {
+        mode: widen ? "all-dts" : "entry-only",
+        fromCount: fromSyms.size,
+        toCount: toSyms.size,
+        removed,
+        withoutRunway,
+        removedFromEntry,
+        documentedRemovals,
+        valueRemovals,
+    };
+}
+/**
+ * The list worth showing a human, sharpest first: exports the old README
+ * documented, else everything that left the entrypoint, else the wide diff.
+ */
+export function headlineRemovals(d) {
+    if (d.documentedRemovals.length)
+        return d.documentedRemovals;
+    if (d.valueRemovals.length)
+        return d.valueRemovals;
+    return d.removedFromEntry.length ? d.removedFromEntry : d.withoutRunway;
+}
+/** How the headline list was arrived at, for a caption the reader can trust. */
+export function headlineSource(d) {
+    if (d.documentedRemovals.length) {
+        return "exports the old README documented, gone from the entrypoint with no deprecation first";
+    }
+    if (d.valueRemovals.length) {
+        return "functions, hooks and classes gone from the entrypoint with no deprecation first";
+    }
+    if (d.removedFromEntry.length)
+        return "exports gone from the entrypoint with no deprecation first";
+    return "symbols gone from a .d.ts in the package with no deprecation first";
+}
+/**
+ * Whether a scored run is likely to find anything, and why. Two facts drive
+ * this, both measured across 35 libraries on this project's bench:
+ *
+ *  - the drift window closes. Age of the major predicts drift better than the
+ *    size of the change does: Apollo v4 scored 0/12 once it had been out long
+ *    enough, and zustand v5 was fully absorbed by ~19 months.
+ *  - a removal with a deprecation runway produces almost nothing.
+ */
+export function driftVerdict(d) {
+    const headline = headlineRemovals(d);
+    if (!headline.length) {
+        return {
+            worth: false,
+            reason: d.removed.length
+                ? `${d.removed.length} symbol(s) went, but every one was deprecated first — that runway is what stops the drift`
+                : `nothing was removed from the package entrypoint between v${d.from.major} and v${d.to.major}`,
+        };
+    }
+    if (d.majorAgeMonths > 18) {
+        return {
+            worth: false,
+            reason: `v${d.to.major} is ${d.majorAgeMonths.toFixed(0)} months old — old enough that models have absorbed it`,
+        };
+    }
+    return {
+        worth: true,
+        reason: `${headline.length} ${headlineSource(d)}, ` +
+            `in a major that is ${d.majorAgeMonths.toFixed(0)} months old`,
+    };
+}
+//# sourceMappingURL=drift.js.map

package/dist/drift.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Programmatic entrypoint. Everything the CLI does is available here, so a
+ * project can score its own package in CI without shelling out.
+ */
+export { run, parseSpec, type RunOptions, type RunOutcome } from "./run.ts";
+export { computeDrift, driftVerdict, type DriftReport, type DriftOptions } from "./drift.ts";
+export { surfaceOf, symbolsFromSource, isDeprecated, type Surface } from "./surface.ts";
+export { fetchPackument, resolveVersion, majorLines, readmeFor, requiredPeers, type Packument, type VersionMeta, type MajorLine, } from "./registry.ts";
+export { prepareWorkspace, resolveTsc, cacheRoot, type Workspace } from "./workspace.ts";
+export { synthesizeTasks, loadTaskFile, validateTasks, type TaskSet } from "./tasks.ts";
+export { renderTerminal, renderMarkdown, renderDrift, type RunContext } from "./report.ts";
+export { anthropicAdapter, openaiAdapter, adapterFor, defaultAdapters, parseModelRef, type ModelRef, } from "./models.ts";
+export { verify, parseDiagnostics, augmentsLibrary, API_SHAPE_CODES } from "./core/verify.ts";
+export { score } from "./core/score.ts";
+export { classify, categorize } from "./core/classify.ts";
+export { buildUserPrompt, extractCode, GENERATION_SYSTEM } from "./core/prompt.ts";
+export { wilson, rates, fmtInterval } from "./core/stats.ts";
+export type * from "./core/types.ts";
+export { RefusalError, FatalApiError, type ModelAdapter, type GenerateRequest } from "./core/model.ts";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * Programmatic entrypoint. Everything the CLI does is available here, so a
+ * project can score its own package in CI without shelling out.
+ */
+export { run, parseSpec } from "./run.js";
+export { computeDrift, driftVerdict } from "./drift.js";
+export { surfaceOf, symbolsFromSource, isDeprecated } from "./surface.js";
+export { fetchPackument, resolveVersion, majorLines, readmeFor, requiredPeers, } from "./registry.js";
+export { prepareWorkspace, resolveTsc, cacheRoot } from "./workspace.js";
+export { synthesizeTasks, loadTaskFile, validateTasks } from "./tasks.js";
+export { renderTerminal, renderMarkdown, renderDrift } from "./report.js";
+export { anthropicAdapter, openaiAdapter, adapterFor, defaultAdapters, parseModelRef, } from "./models.js";
+export { verify, parseDiagnostics, augmentsLibrary, API_SHAPE_CODES } from "./core/verify.js";
+export { score } from "./core/score.js";
+export { classify, categorize } from "./core/classify.js";
+export { buildUserPrompt, extractCode, GENERATION_SYSTEM } from "./core/prompt.js";
+export { wilson, rates, fmtInterval } from "./core/stats.js";
+export { RefusalError, FatalApiError } from "./core/model.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,GAAG,EAAE,SAAS,EAAoC,MAAM,UAAU,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,YAAY,EAAuC,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAgB,MAAM,cAAc,CAAC;AACxF,OAAO,EACL,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,GAErE,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAkB,MAAM,gBAAgB,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAmB,MAAM,aAAa,CAAC;AAC3F,OAAO,EACL,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,GAE5E,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAE,aAAa,EAA2C,MAAM,iBAAiB,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,33 @@
+import type { ModelAdapter } from "./core/model.ts";
+/** Reset between runs; only the test suite and long-lived embeddings need this. */
+export declare function clearFatal(): void;
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Claude adapter over the raw Messages API — no SDK, so `npx sdkproof` installs
+ * one dependency (typescript) instead of a tree.
+ *
+ * ANTHROPIC_AUTH_TOKEN is accepted alongside ANTHROPIC_API_KEY because an OAuth
+ * token from a Claude subscription is the key most people already have.
+ */
+export declare function anthropicAdapter(model: string): ModelAdapter;
+/** GPT adapter over the raw Chat Completions API. */
+export declare function openaiAdapter(model: string): ModelAdapter;
+export interface ModelRef {
+    provider: "anthropic" | "openai";
+    model: string;
+}
+export declare const DEFAULT_ANTHROPIC_MODEL: string;
+export declare const DEFAULT_OPENAI_MODEL: string;
+/**
+ * Turn a `--model` value into a provider + model id. Accepts an explicit
+ * `anthropic:<id>` / `openai:<id>`, or a bare id whose provider is inferred
+ * from its prefix — so `--model claude-sonnet-5` and `--model gpt-5` both work.
+ */
+export declare function parseModelRef(value: string): ModelRef;
+export declare function adapterFor(ref: ModelRef): ModelAdapter;
+export declare function hasKeyFor(provider: ModelRef["provider"]): boolean;
+/** Every model the environment holds a key for, when --model was not given. */
+export declare function defaultAdapters(): ModelAdapter[];