@oharness/engine 0.1.0

package/dist/paths.js

@@ -0,0 +1,63 @@
+import { homedir } from "node:os";
+import path from "node:path";
+/**
+ * Where OHarness keeps everything that outlives a project: credentials,
+ * sessions, the model catalog, user-level skills, agents and plugins.
+ *
+ * One resolver, because nine call sites each computing `homedir()` themselves
+ * is how `OHARNESS_HOME` ended up honoured by the session store and ignored
+ * by the other eight — an escape hatch that only worked for one kind of data
+ * is worse than none, since it reads as if the whole thing is redirected.
+ *
+ * Set `OHARNESS_HOME` to redirect all of it. Developing on the harness
+ * itself should always set it (the repo's npm scripts do), so working on the
+ * tool never writes into the home directory of the person working on it.
+ */
+export function userDir() {
+    const override = process.env["OHARNESS_HOME"];
+    if (override)
+        return path.resolve(override);
+    // On Linux, respect the XDG layout when the user has opted into it; falling
+    // back to a dotfile in $HOME everywhere else, which is what CLI tools of
+    // this shape are expected to do.
+    const xdg = process.env["XDG_CONFIG_HOME"];
+    if (xdg && process.platform === "linux")
+        return path.join(xdg, "oharness");
+    return path.join(homedir(), ".oharness");
+}
+/** A path inside the user directory, e.g. `userPath("sessions")`. */
+export function userPath(...segments) {
+    return path.join(userDir(), ...segments);
+}
+/**
+ * Project-local storage: `.oharness/` in the working directory.
+ *
+ * Kept separate from the user directory on purpose. Settings, skills and
+ * agents exist at both levels and the merge order between them is meaningful,
+ * so collapsing them into one path helper would blur a distinction the
+ * permission and skill layers depend on.
+ */
+export function projectPath(cwd, ...segments) {
+    return path.join(cwd, ".oharness", ...segments);
+}
+/**
+ * Expand a leading `~` the way a shell would, and leave everything else alone.
+ *
+ * Lives here rather than in the workspace policy because both the policy and
+ * the file tools need it and neither may import the other. A path the agent
+ * typed as `~/.oharness/skills` has to become the same string the shell would
+ * have produced, or a refusal message ends up naming a path that exists
+ * nowhere and the reader learns nothing from it.
+ */
+export function expandHome(input) {
+    if (input === "~")
+        return homedir();
+    if (input.startsWith("~/"))
+        return path.join(homedir(), input.slice(2));
+    return input;
+}
+/** Whether `target` is one of `roots` or sits underneath one. */
+export function within(roots, target) {
+    return roots.some((root) => target === root || target.startsWith(root + path.sep));
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC9C,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE5C,4EAA4E;IAC5E,yEAAyE;IACzE,iCAAiC;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3C,IAAI,GAAG,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAE3E,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAC3C,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,QAAQ,CAAC,GAAG,QAAkB;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,GAAG,QAAkB;IAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,KAAK,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IACpC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,MAAM,CAAC,KAAwB,EAAE,MAAc;IAC7D,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrF,CAAC"}

package/dist/plugins.d.ts

@@ -0,0 +1,55 @@
+import type { HookConfig } from "./agent/hooks.ts";
+import type { SubagentDefinition } from "./agent/subagent.ts";
+import type { McpServerConfig } from "./mcp/client.ts";
+/**
+ * A plugin is a declarative bundle of existing extension points: skills,
+ * agents, hooks and MCP server declarations. It contains no code of its own —
+ * tools still arrive through the host application — but two of those four
+ * name things that run, so where a plugin came from decides how much of it is
+ * adopted. See `pluginContributions`.
+ *
+ * Two manifest layouts are read, this project's and Claude Code's, because
+ * they describe the same thing and reading both costs about twenty lines.
+ */
+export interface PluginManifest {
+    name: string;
+    description?: string;
+    version?: string;
+    hooks?: HookConfig;
+    mcpServers?: Record<string, McpServerConfig>;
+    subagents?: SubagentDefinition[];
+}
+export interface PluginDefinition extends PluginManifest {
+    directory: string;
+    source: "user" | "project" | "config" | "claude";
+    skillDir: string;
+    agentDir: string;
+}
+export interface PluginConfig {
+    /** Extra directories containing plugin folders, relative to the project. */
+    dirs?: string[];
+    /** If set, only these plugin names load. */
+    enabled?: string[];
+    /** Disabled wins over enabled, useful for project-level policy. */
+    disabled?: string[];
+    /**
+     * Read plugins Claude Code has already installed. On by default: they are
+     * files on this machine that this user chose to install, and the alternative
+     * is an empty list beside a directory full of them. Set false to ignore it.
+     */
+    claudeCode?: boolean;
+}
+/** Where Claude Code keeps what it has installed; overridable for tests. */
+export declare function claudePluginCache(): string;
+/** Discover plugins in a stable override order: Claude → user → project → config. */
+export declare function discoverPlugins(cwd: string, config?: PluginConfig): Promise<PluginDefinition[]>;
+/** Convert installed plugin declarations into ordinary harness configuration. */
+export declare function pluginContributions(plugins: PluginDefinition[]): {
+    skillDirs: string[];
+    agentDirs: string[];
+    hooks: HookConfig;
+    mcpServers: Record<string, McpServerConfig>;
+    subagents: SubagentDefinition[];
+};
+/** Lightweight validation keeps plugin manifests dependency-free and safe to ignore when malformed. */
+export declare function parsePluginManifest(value: unknown): PluginManifest | undefined;

package/dist/plugins.js

@@ -0,0 +1,201 @@
+import { homedir } from "node:os";
+import { userPath } from "./paths.js";
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { parseJson } from "./util/json.js";
+const MANIFEST = "oharness.plugin.json";
+/**
+ * The other manifest this reads.
+ *
+ * A plugin here is a manifest plus a `skills/` and an `agents/` directory, and
+ * so is a Claude Code plugin — the same idea arrived at twice. Reading both is
+ * about twenty lines, and it is the difference between a menu with an
+ * ecosystem behind it and a menu that is empty until somebody hand-copies a
+ * folder into place. Nothing is imported or converted: the directory stays
+ * where it is and is read where it lies.
+ */
+const CLAUDE_MANIFEST = path.join(".claude-plugin", "plugin.json");
+/** Its two sidecars, which hold what our manifest keeps inline. */
+const CLAUDE_MCP = ".mcp.json";
+const CLAUDE_HOOKS = path.join("hooks", "hooks.json");
+/** `<marketplace>/<plugin>/<version>/` — three levels down from the cache. */
+const CLAUDE_CACHE_DEPTH = 3;
+/** Where Claude Code keeps what it has installed; overridable for tests. */
+export function claudePluginCache() {
+    return process.env["OHARNESS_CLAUDE_PLUGINS"] ?? path.join(homedir(), ".claude", "plugins", "cache");
+}
+/** Discover plugins in a stable override order: Claude → user → project → config. */
+export async function discoverPlugins(cwd, config = {}) {
+    const roots = [
+        // First, so anything of this project's own overrides it by name.
+        ...(config.claudeCode === false
+            ? []
+            : [
+                {
+                    directory: claudePluginCache(),
+                    source: "claude",
+                    depth: CLAUDE_CACHE_DEPTH,
+                },
+            ]),
+        { directory: userPath("plugins"), source: "user" },
+        { directory: path.join(cwd, ".oharness", "plugins"), source: "project" },
+        ...((config.dirs ?? []).map((dir) => ({
+            directory: path.resolve(cwd, dir),
+            source: "config",
+        }))),
+    ];
+    // A later layer with the same name deliberately replaces the earlier one.
+    const byName = new Map();
+    for (const root of roots) {
+        for (const plugin of await scanPluginRoot(root.directory, root.source, root.depth ?? 1)) {
+            // Within one root the same plugin can be cached at several versions;
+            // the newest is the one that was installed, the rest are history.
+            const seen = byName.get(plugin.name);
+            if (seen && seen.source === plugin.source && newer(seen, plugin))
+                continue;
+            byName.set(plugin.name, plugin);
+        }
+    }
+    const enabled = config.enabled ? new Set(config.enabled) : undefined;
+    const disabled = new Set(config.disabled ?? []);
+    return [...byName.values()].filter((plugin) => (!enabled || enabled.has(plugin.name)) && !disabled.has(plugin.name));
+}
+/** Convert installed plugin declarations into ordinary harness configuration. */
+export function pluginContributions(plugins) {
+    const out = {
+        skillDirs: [],
+        agentDirs: [],
+        hooks: {},
+        mcpServers: {},
+        subagents: [],
+    };
+    for (const plugin of plugins) {
+        out.skillDirs.push(plugin.skillDir);
+        out.agentDirs.push(plugin.agentDir);
+        out.subagents.push(...(plugin.subagents ?? []));
+        // Skills and agents are text the agent reads when it decides to. Hooks and
+        // MCP servers are not: a hook is a command line that runs on its own
+        // schedule, and a server is a process started at launch. Adopting those
+        // from a directory the user filled in for a different program would mean
+        // this harness executing things nobody pointed at it. They are still
+        // reported, so a plugin's servers can be added the ordinary way, with the
+        // confirmation and the login that path already has.
+        if (plugin.source === "claude")
+            continue;
+        Object.assign(out.mcpServers, plugin.mcpServers ?? {});
+        for (const [event, hooks] of Object.entries(plugin.hooks ?? {})) {
+            out.hooks[event] = [...(out.hooks[event] ?? []), ...(hooks ?? [])];
+        }
+    }
+    return out;
+}
+/**
+ * Every plugin under a root, to a bounded depth.
+ *
+ * Depth exists because the two layouts nest differently: ours is one folder
+ * per plugin, and Claude Code's cache is marketplace, then plugin, then
+ * version. A directory that is itself a plugin is not descended into, so the
+ * walk stops at the first thing it recognises rather than picking up whatever
+ * a plugin happens to keep in a subfolder.
+ */
+async function scanPluginRoot(root, source, depth) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const plugins = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        // Dot-directories at a scan level are bookkeeping, never plugins.
+        if (entry.name.startsWith("."))
+            continue;
+        const directory = path.join(root, entry.name);
+        const plugin = await readPlugin(directory, source);
+        if (plugin)
+            plugins.push(plugin);
+        else if (depth > 1)
+            plugins.push(...(await scanPluginRoot(directory, source, depth - 1)));
+    }
+    return plugins;
+}
+/** One directory, in either layout, or nothing if it is neither. */
+async function readPlugin(directory, source) {
+    const own = await readManifest(path.join(directory, MANIFEST));
+    if (own) {
+        return {
+            ...own,
+            directory,
+            source,
+            skillDir: path.join(directory, "skills"),
+            agentDir: path.join(directory, "agents"),
+        };
+    }
+    const claude = await readManifest(path.join(directory, CLAUDE_MANIFEST));
+    if (!claude)
+        return undefined;
+    // The same declarations, kept in sidecar files rather than inline.
+    const mcp = await readJsonFile(path.join(directory, CLAUDE_MCP));
+    const hooks = await readJsonFile(path.join(directory, CLAUDE_HOOKS));
+    return {
+        ...claude,
+        ...(isRecord(mcp?.mcpServers) ? { mcpServers: mcp.mcpServers } : {}),
+        ...(isRecord(hooks?.hooks) ? { hooks: hooks.hooks } : {}),
+        directory,
+        source,
+        skillDir: path.join(directory, "skills"),
+        agentDir: path.join(directory, "agents"),
+    };
+}
+async function readManifest(file) {
+    const value = await readJsonFile(file);
+    return value === undefined ? undefined : parsePluginManifest(value);
+}
+async function readJsonFile(file) {
+    try {
+        const info = await stat(file);
+        if (!info.isFile())
+            return undefined;
+        const parsed = parseJson(await readFile(file, "utf8"));
+        return parsed.ok ? parsed.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `a` is at least as new as `b`, comparing dotted versions. */
+function newer(a, b) {
+    const parts = (v) => (v ?? "0").split(/[.-]/).map((n) => Number.parseInt(n, 10) || 0);
+    const left = parts(a.version);
+    const right = parts(b.version);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const one = left[i] ?? 0;
+        const two = right[i] ?? 0;
+        if (one !== two)
+            return one > two;
+    }
+    return true;
+}
+/** Lightweight validation keeps plugin manifests dependency-free and safe to ignore when malformed. */
+export function parsePluginManifest(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (typeof raw.name !== "string" || raw.name.trim() === "")
+        return undefined;
+    return {
+        name: raw.name.trim(),
+        ...(typeof raw.description === "string" ? { description: raw.description } : {}),
+        ...(typeof raw.version === "string" ? { version: raw.version } : {}),
+        ...(isRecord(raw.hooks) ? { hooks: raw.hooks } : {}),
+        ...(isRecord(raw.mcpServers) ? { mcpServers: raw.mcpServers } : {}),
+        ...(Array.isArray(raw.subagents) ? { subagents: raw.subagents } : {}),
+    };
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

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

package/dist/providers/builtin.d.ts

@@ -0,0 +1,23 @@
+import type { Api, Model as PiModel } from "@earendil-works/pi-ai";
+import type { CatalogProvider } from "./catalog.ts";
+import type { ModelSpec } from "./types.ts";
+export interface SeedOptions {
+    /** Entries already stated by a catalog file; these are never replaced. */
+    existing?: ModelSpec[];
+}
+/**
+ * Model specs for every catalog provider pi-ai has built-in entries for.
+ *
+ * A failure here is never fatal: the seed is a convenience, and a catalog that
+ * loads with fewer models is a far better outcome than a harness that will not
+ * start because a dependency reorganised its data.
+ */
+export declare function builtinModels(providers: Record<string, CatalogProvider>, opts?: SeedOptions): Promise<ModelSpec[]>;
+/**
+ * Translate one pi-ai model into a harness spec.
+ *
+ * The endpoint deliberately does not come across: pi-ai carries a `baseUrl`
+ * per model, but which host a provider talks to is the catalog entry's to
+ * decide — that is what makes pointing Kimi at its mainland endpoint work.
+ */
+export declare function specFromPiModel(entry: CatalogProvider, model: PiModel<Api>): ModelSpec;

package/dist/providers/builtin.js

@@ -0,0 +1,141 @@
+import { PI_APIS } from "./piai.js";
+/**
+ * Levels pi-ai only offers when the model names them.
+ *
+ * `thinkingLevelMap` is a patch, not a listing: an absent key means "provider
+ * default", and null means unsupported. That reads in opposite directions for
+ * the two halves of the scale, since `xhigh` and `max` are opt-in upstream.
+ */
+const OPT_IN_EFFORTS = ["xhigh", "max"];
+const DEFAULT_EFFORTS = ["low", "medium", "high"];
+/**
+ * Model specs for every catalog provider pi-ai has built-in entries for.
+ *
+ * A failure here is never fatal: the seed is a convenience, and a catalog that
+ * loads with fewer models is a far better outcome than a harness that will not
+ * start because a dependency reorganised its data.
+ */
+export async function builtinModels(providers, opts = {}) {
+    let catalog;
+    try {
+        // Dynamic, so the ~600KB of bundled model data is read when a catalog is
+        // built and not merely because something imported this module.
+        catalog = (await import("@earendil-works/pi-ai/providers/all"));
+    }
+    catch {
+        return [];
+    }
+    let known;
+    try {
+        known = new Set(catalog.getBuiltinProviders());
+    }
+    catch {
+        return [];
+    }
+    // Which catalog entry claims each pi-ai provider. Ids mostly match; where
+    // they do not, the catalog says so with `piProvider`.
+    const claims = new Map();
+    for (const entry of Object.values(providers)) {
+        const piId = entry.piProvider ?? entry.id;
+        if (!known.has(piId))
+            continue;
+        // An entry naming the provider outright beats one that only shares its id
+        // by accident, so a mapping is never stolen by declaration order.
+        const held = claims.get(piId);
+        if (held && (held.piProvider === piId || held.id === piId))
+            continue;
+        claims.set(piId, entry);
+    }
+    const taken = new Set();
+    for (const spec of opts.existing ?? []) {
+        taken.add(spec.id);
+        taken.add(`${spec.provider} ${spec.model}`);
+    }
+    const seeded = [];
+    for (const [piId, entry] of claims) {
+        let models;
+        try {
+            models = catalog.getBuiltinModels(piId);
+        }
+        catch {
+            continue;
+        }
+        for (const model of models) {
+            // A model pi-ai serves over the Responses API cannot be driven over Chat
+            // Completions just because the catalog entry points at the same vendor;
+            // the request shape differs. Seed only what this entry can actually call.
+            if (model.api !== PI_APIS[entry.protocol])
+                continue;
+            const spec = specFromPiModel(entry, model);
+            if (taken.has(spec.id) || taken.has(`${spec.provider} ${spec.model}`))
+                continue;
+            taken.add(spec.id);
+            taken.add(`${spec.provider} ${spec.model}`);
+            seeded.push(spec);
+        }
+    }
+    return seeded;
+}
+/**
+ * Translate one pi-ai model into a harness spec.
+ *
+ * The endpoint deliberately does not come across: pi-ai carries a `baseUrl`
+ * per model, but which host a provider talks to is the catalog entry's to
+ * decide — that is what makes pointing Kimi at its mainland endpoint work.
+ */
+export function specFromPiModel(entry, model) {
+    const compat = (model.compat ?? {});
+    const levels = model.thinkingLevelMap;
+    return {
+        id: `${entry.id}/${model.id}`,
+        provider: entry.id,
+        model: model.id,
+        displayName: model.name || model.id,
+        contextWindow: model.contextWindow,
+        maxOutputTokens: model.maxTokens,
+        // pi-ai publishes no tool flag, and a chat model that cannot call tools is
+        // useless here anyway — the harness's own default assumes the same.
+        supportsTools: true,
+        supportsImages: model.input.includes("image"),
+        supportsParallelToolCalls: true,
+        // A quoted cache-read price is the only evidence in this data that the
+        // vendor caches at all.
+        supportsPromptCache: (model.cost?.cacheRead ?? 0) > 0,
+        thinkingMode: thinkingMode(model, compat),
+        effortLevels: effortLevels(model, levels),
+        supportsSampling: compat["supportsTemperature"] !== false,
+        ...price("costPer1MInput", model.cost?.input),
+        ...price("costPer1MOutput", model.cost?.output),
+        ...price("costPer1MCacheRead", model.cost?.cacheRead),
+        ...price("costPer1MCacheWrite", model.cost?.cacheWrite),
+    };
+}
+/**
+ * pi-ai models are `reasoning: true/false` plus a per-protocol rendering, so
+ * "effort" is the honest translation of every reasoning model here. The one
+ * distinction worth keeping is the Anthropic quirk the wire layer round-trips:
+ * a model that only accepts an adaptive config rejects a budget outright.
+ */
+function thinkingMode(model, compat) {
+    if (!model.reasoning)
+        return "none";
+    return compat["forceAdaptiveThinking"] === true ? "adaptive" : "effort";
+}
+function effortLevels(model, levels) {
+    if (!model.reasoning)
+        return [];
+    if (!levels)
+        return [...DEFAULT_EFFORTS];
+    return [
+        ...DEFAULT_EFFORTS.filter((level) => levels[level] !== null),
+        ...OPT_IN_EFFORTS.filter((level) => typeof levels[level] === "string"),
+    ];
+}
+/**
+ * Zero means "not quoted" in this data, and a spec carrying a zero price reads
+ * as free everywhere downstream — a worse answer than saying nothing.
+ */
+function price(field, value) {
+    return value && value > 0 ? { [field]: value } : {};
+}
+//# sourceMappingURL=builtin.js.map

package/dist/providers/builtin.js.map

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

package/dist/providers/catalog.d.ts

@@ -0,0 +1,129 @@
+import type { ModelSpec } from "./types.ts";
+/**
+ * The model catalog is data, not code.
+ *
+ * Vendor model ids turn over faster than releases of this package, so baking
+ * them into TypeScript guarantees the list is wrong within weeks. Provider
+ * facts (endpoint, env var, protocol) are stable and worth shipping; model ids
+ * mostly come from `/models refresh`, which asks the vendor directly.
+ */
+/**
+ * Wire formats a catalog entry may declare.
+ *
+ * The first three are the historical names and stay as they are — renaming
+ * them would invalidate every user catalog in existence. The rest were opened
+ * up by moving the wire layer onto pi-ai, which implements them already:
+ * `openai-responses` for vendors that have moved off Chat Completions, and the
+ * two cloud-signed endpoints that were previously out of reach.
+ */
+export type ProtocolId = "anthropic-messages" | "openai-chat" | "gemini" | "openai-responses" | "bedrock" | "vertex";
+export type DiscoveryFormat = "openai" | "openrouter";
+export interface CatalogProvider {
+    id: string;
+    label: string;
+    /** Which wire format this endpoint speaks. */
+    protocol: ProtocolId;
+    baseUrl: string;
+    /** Env vars consulted in order for an API key. */
+    envVars: string[];
+    headers?: Record<string, string>;
+    /** How to read `/models`; absent means the endpoint is not worth calling. */
+    discovery?: DiscoveryFormat;
+    /**
+     * The id this vendor goes by in pi-ai's built-in model catalog, when it is
+     * not this entry's own id. Only naming exists to be reconciled here — the
+     * endpoint and credentials stay this entry's.
+     */
+    piProvider?: string;
+    /** Some servers reject `stream_options: {include_usage: true}`. */
+    includeUsage?: boolean;
+    /**
+     * Send an `Idempotency-Key` header, one value per request.
+     *
+     * Not a nicety on the endpoints that ask for it: a metering gateway reserves
+     * the worst-case cost before it forwards, and the key is what lets a retry
+     * resume that reservation instead of opening a second one. OttoPort rejects
+     * a completion without it outright.
+     *
+     * It cannot be an entry in `headers` — that map is one static value for the
+     * life of the process, and a key reused across two different requests is
+     * precisely what the header exists to prevent.
+     */
+    idempotencyKey?: boolean;
+    /**
+     * A ceiling on `max_tokens`, when the endpoint imposes one below what its
+     * models advertise.
+     *
+     * Gateways cap output to bound what a single request can cost, and the cap
+     * is the gateway's rather than the model's — so `/models` does not mention
+     * it and discovery lands on its own default, which is higher. The result is
+     * a 400 on every request rather than a shorter answer, so the number is
+     * stated here where the endpoint is described.
+     */
+    maxOutputTokens?: number;
+    docsUrl?: string;
+    /**
+     * Surfaced without being searched for.
+     *
+     * Which vendors are worth showing first is a fact about the market, not
+     * about this code, so it lives in the catalog data with everything else that
+     * changes on its own schedule.
+     */
+    popular?: boolean;
+    /**
+     * The one this project stands behind. At most one entry should carry it —
+     * a badge that half the list wears recommends nothing.
+     */
+    recommended?: boolean;
+    /** One line shown under the name, so a chooser is not a list of bare names. */
+    description?: string;
+}
+export interface Catalog {
+    /** When the bundled model entries were last checked. */
+    verified?: string;
+    providers: Record<string, CatalogProvider>;
+    models: ModelSpec[];
+}
+/**
+ * A catalog as read from one file. Fields are optional because a later file
+ * is a *patch*: a user catalog that only changes `baseUrl` must not blank out
+ * the label and env vars it did not mention.
+ */
+export interface CatalogPatch {
+    verified?: string;
+    providers: Record<string, Partial<CatalogProvider>>;
+    models: ModelSpec[];
+}
+/** Where a user's own catalog lives; overrides the bundled one. */
+export declare function userCatalogPath(): string;
+/**
+ * Load the catalog: bundled file, then the user's, then any explicit paths.
+ * Later sources override earlier ones per provider id and per model id.
+ *
+ * Under all of them sits pi-ai's built-in model catalog, which is why a
+ * provider nobody has written an entry for still has models to offer. It is
+ * seeded last but ranked lowest: appended after the stated entries so the
+ * order callers see — and the default model, which is the first of them —
+ * still comes from what this package verified.
+ */
+export declare function loadCatalog(extraPaths?: string[]): Promise<Catalog>;
+/** Parse and finalize a single complete catalog. */
+export declare function parseCatalog(raw: unknown, source?: string): Catalog;
+/**
+ * Parse one catalog file into a patch, keeping absent fields absent so a later
+ * merge can tell "not mentioned" from "set to empty".
+ */
+export declare function parsePatch(raw: unknown, source?: string): CatalogPatch;
+export declare function mergeCatalog(base: Catalog, override: Catalog): Catalog;
+export declare function mergePatch(base: CatalogPatch, override: CatalogPatch): CatalogPatch;
+/**
+ * Resolve a merged patch into a usable catalog, dropping providers that are
+ * still incomplete after every layer has been applied.
+ */
+export declare function finalize(patch: CatalogPatch): Catalog;
+/**
+ * Fill in a partial model entry. Defaults are deliberately conservative:
+ * claiming a capability the model lacks is a 400 at request time, whereas
+ * under-claiming only costs a feature.
+ */
+export declare function normalizeModel(entry: unknown): ModelSpec | undefined;