@openplan/dsh-fuse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPlan Code Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# /dsh-fuse
+
+Política de custo multi-agente para o DeepSeek Harness: o plugin mede cada
+chamada do agente, **trava antes** de estourar o budget (fuse local, <100ms,
+offline) e sincroniza com o painel SaaS — cujo 429 é o portão secundário. Só
+métricas sobem: tokens, custo, modelo — o conteúdo das sessões **nunca sai da
+máquina**.
+
+Painel central: **https://dsh.openplan.cc** — gastos por organização, projeto
+e pessoa, budgets que o plugin aplica localmente, e o histórico de cortes.
+
+## Instalar
+
+O pacote declara `dsh.bundle`, que é o que faz `dsh plugin add` ativar a
+camada. Sem essa declaração o pnpm instalaria uma biblioteca inerte.
+
+```bash
+# npm — a forma canônica de instalação (publicado, v0.1.0)
+dsh plugin --profile <perfil> add @openplan/dsh-fuse
+
+# tarball (sem depender de registry)
+pnpm pack                       # gera openplan-dsh-fuse-<versão>.tgz
+dsh plugin --profile <perfil> add ./openplan-dsh-fuse-0.1.0.tgz
+
+# direto do git (exige allowlist de build do pnpm >= 10 — veja a doc do harness)
+dsh plugin --profile <perfil> add github:<org>/<repo>#<sha>
+```
+
+Fonte: **https://github.com/openplancc/dsh-fuse** (espelho gerado a cada
+release — cada tag `v<versão>` corresponde a um commit deste monorepo).
+
+O plugin usa `@libsql/client` como store local — zero build nativa,
+distribuível sem compilação (Node ≥ 20).
+
+Verifique a camada sem bootar:
+
+```bash
+dsh --profile <perfil> --dump-config   # mostra '# == @openplan/dsh-fuse'
+```
+
+## Configurar
+
+O bundle traz defaults seguros (modo local-only, store ancorado no harness
+home, sync de 60s). Para sobrescrever, edite o `cordis.patch.yml` **do seu
+profile** — a camada do usuário, aplicada depois de todas as camadas de bundle.
+A sobrescrita é uma **linha direta com o mesmo `id`** (não um segundo `insert:`,
+que duplicaria o id e faria o loader falhar com `duplicate loader entry id`):
+
+```yaml
+# ~/.dsh/profiles/<perfil>/cordis.patch.yml
+- id: fuse
+  name: '@openplan/dsh-fuse'
+  config:
+    project: meu-projeto
+    dev: eu@empresa.com
+    # Segredo nunca em texto puro no YAML — a tag !!js resolve no load.
+    orgKey: !!js process.env.DSH_ORG_KEY
+    baseUrl: https://dsh-api.openplan.cc
+    # Orçamento local (o fuse corta offline antes de gastar):
+    budgets:
+      - limitUsd: 50
+        window: month
+      - limitUsd: 5
+        window: day
+    # Políticas:
+    policies:
+      # maxReasoningEffort é um id da PRÓPRIA rota (adapter-owned):
+      maxReasoningEffort: medium
+      allowedModels:
+        - deepseek/deepseek-v4-flash
+      denylistedProjects:
+        - projeto-cliente-confidencial
+    # Preço (cents por 1M tokens) — OPCIONAL. Por padrão o plugin resolve o
+    # preço de cada modelo automaticamente (registry models.dev; veja abaixo),
+    # então esta tabela só existe para override explícito. As chaves podem ser
+    # o id do adapter (com prefixo de provider), o id nu, ou qualquer alias:
+    pricingTable:
+      deepseek/deepseek-v4.1-flash:
+        inputCentsPerM: 15
+        outputCentsPerM: 60
+        cacheReadCentsPerM: 3
+      gpt-4o:
+        inputCentsPerM: 250
+        outputCentsPerM: 1000
+    # Escape hatch quando o id do adapter não é adivinhável:
+    pricingAliases:
+      vendor/opaque-model-v9: gpt-4o
+    # Uma taxa ÚNICA opcional (cents por 1M) para modelos que nenhuma fonte
+    # precifica — um knob, não uma tabela. Sem ela, chamadas sem preço entram
+    # com custo zero mas marcadas como `unpriced` (nunca um zero silencioso).
+    unpricedFallback:
+      inputCentsPerM: 15
+      outputCentsPerM: 60
+```
+
+**Config inválida falha o load**, com erro acionável, em vez de ligar um plugin
+que não enforça nada: metade de um alvo de sync (só `baseUrl` ou só `orgKey`)
+ou uma `cascade` que não intersecta `policies.allowedModels` são recusados no
+boot. Preço **não** é exigido — o plugin resolve genericamente (abaixo); um
+modelo sem preço é um estado visível (`unpriced`), não um boot falho.
+
+## Como o preço é resolvido
+
+O harness reporta o modelo com o id do **adapter** (normalmente com prefixo de
+provider, ex. `deepseek/deepseek-v4-flash`), enquanto os catálogos de preço vêm
+keyed por rota (`provider/model`). O plugin junta **duas fontes**, ambas
+baixadas e cacheadas no libsql para uso offline:
+
+- **registry** (`pricingRegistryUrl`, default `https://models.dev/api.json`) —
+  catálogo de preços em USD por rota para 200+ providers. Cobre gateways que
+  não publicam preço (ex. command-code) resolvendo cada modelo por id.
+- **gateway** (`pricingGatewayUrl` + `pricingGatewayProvider`) — quando o
+  gateway publica preço no próprio `/models` (OpenRouter, DeepInfra, …), esses
+  números são **autoritativos** para as rotas dele.
+
+A resolução de um id de adapter procura, nesta ordem:
+
+1. `pricingAliases[model]` (explícito, sempre ganha)
+2. chave exata na tabela local
+3. rota `provider/model` no registry/gateway
+4. id nu no registry (o id do adapter sem prefixo)
+5. sufixos progressivos do id (ex. `provider/anthropic/x` → `anthropic/x` → `x`)
+
+Modelo que nenhuma fonte precifica é gravado com **`unpriced: true`** (contado
+e mostrado no painel) e logado — nunca um zero silencioso, porque um preço
+zerado faz o fuse nunca cortar e o budget do servidor nunca disparar. Se a org
+setou `unpricedFallback`, esses modelos usam a taxa única e o budget continua
+cortando.
+
+## O agente enxerga a política (model-facing tool)
+
+A doc do harness prescreve o par: o gate diz *não* (o fuse em `agent/pre-step`)
+— e uma **tool model-facing separada** deixa o próprio agente ler o estado da
+política. Quando a composição monta o serviço `tools` (`@deepseek-ai/dsh-tools`),
+o plugin registra `dsh_budget_status`: o modelo pode consultar, no meio da
+sessão, os budgets em vigor por escopo (org/projeto/dev), o total já gasto vs o
+limite, e se há um 429 remoto ativo (e até quando). É o que torna uma trava dura
+tolerável — o agente entende por que foi cortado e pode adaptar (perguntar,
+parar, escolher rota mais barata) em vez de morrer às cegas.
+
+A tool é **só leitura**, nunca uma decisão: lê o mesmo libsql que o fuse enforça
+(`spentForWindow`, `remoteBlockFor`, a política publicada) e formata uma visão.
+Ela não gateia nem reescreve nada. O schema viaja em toda request, então quem
+quiser zero presença na wire desliga com `budgetStatusTool: false` (default
+`true`); e se o serviço `tools` não estiver montado, o registro é simplesmente
+pulado — o plugin declara nenhum `inject`, então um serviço opcional nunca
+segura o load.
+
+## Modo local-only
+
+Sem `baseUrl`/`orgKey` o plugin funciona **sozinho**: nada sobe, o fuse enforça
+os budgets offline. As sessões ficam no libsql local, por padrão em
+`$DSH_HOME/dsh-fuse/local.db` (`~/.dsh/...` quando `DSH_HOME` não está
+definido) — ancorado no harness home, então o ledger não muda conforme o
+diretório de onde o harness foi iniciado. `storeUrl` troca o caminho; um
+caminho relativo só vale quando você o define explicitamente.
+
+## O que sobe pro painel (sync)
+
+A cada 60s (`syncIntervalMs`), um único batch (`POST /v1/usage/batch`):
+
+- **usage events** — projeto, dev, modelo, provider, reasoning effort, tokens
+  (entrada, saída, cache leitura, cache escrita), duração do step, custo e
+  timestamp. O session id sai **hasheado (SHA-256) no cliente**; conteúdo nunca.
+- **fuse cuts** — toda vez que o fuse travou uma chamada (regra + projeto), pro
+  painel mostrar "quantas vezes a política cortou".
+
+Um batch só marca as linhas como sincronizadas quando o SaaS **confirma** (2xx
+com `ok`): um 500, um 502 do proxy ou uma página de erro nunca aposentam uma
+linha sem ela ter sido gravada.
+
+Um `429 BudgetExceeded { rule, reset_at }` do SaaS **engata o fuse local** até o
+reset da janela — o time bloqueado centralmente fica bloqueado na máquina também.
+
+## O painel como control plane
+
+Além do 429, o plugin puxa `GET /v1/policy` (key-authed) no boot e a cada
+`policyRefreshMs`: budgets e políticas `hard` da org, no vocabulário do fuse.
+É isso que faz uma regra editada no painel chegar na máquina do dev — sem esse
+pull, o fuse local só enforçaria o que o YAML do deployment diz. O resultado
+fica em cache no libsql, então enforcement **não** depende da rede no boot.
+
+## Alertas (50/80/95% + desvio)
+
+Os thresholds graduados são disparados pelo backend (não pelo plugin) —
+configure os canais no painel (**Alertas → Canais**): Telegram (bot token +
+chat id) ou webhook (POST JSON `{kind, payload, at}`). O desvio de gasto acende
+quando a última hora queima ≥ 5× a média das últimas 7 dias E ≥ US$ 1.
+
+## Reasoning cap: por que não há lista fixa de valores
+
+`ReasoningEffortId` é *adapter-owned*: o core do harness "brands identifiers but
+does not enumerate their values; each adapter owns the ordered set". Então o cap
+é comparado **por índice na lista de efforts da própria rota**
+(`ctx.llm.resolveModelInfo`). Quando a rota não publica a lista, o cap é
+reportado como **não enforçável** (`notEnforced`, com aviso no log) em vez de
+adivinhado — um ranking local por nome, ou por código de caractere,
+classificaria um id como `none` acima de `high` e travaria justamente a
+requisição mais barata.
+
+## GitHub Action
+
+Veja `examples/agent-budget.yml`.
+
+## Verificação
+
+`pnpm dsh:smoke` (na raiz do monorepo) empacota o plugin, instala num profile
+descartável com o `dsh plugin add` real, boota o harness headless e exige que o
+fuse recuse um step que não cabe no budget e que um run permitido registre custo
+**diferente de zero**.
+
+## Licença
+
+MIT.

package/cordis.patch.yml

@@ -0,0 +1,29 @@
+# The bundle layer `dsh` applies when a profile lists this package.
+#
+# Every key this row needs is restated here because a patch REPLACES a row's
+# config rather than deep-merging it. It deliberately carries no `config:` at
+# all: the exported Config schema supplies the defaults a deployment is likely
+# to keep (local-only mode, harness-home-anchored store, 60s sync), and users
+# override what they need in their own profile's `cordis.patch.yml`, which is
+# applied after every bundle layer.
+#
+#   dsh plugin --profile <name> add @openplan/dsh-fuse
+#   dsh --profile <name> --dump-config   # shows the "# == @openplan/dsh-fuse" layer
+#
+# Local-only mode (nothing leaves the machine) is the default. To report to a
+# panel, add to the profile patch:
+#
+#   - id: fuse
+#     name: '@openplan/dsh-fuse'
+#     config:
+#       project: meu-projeto
+#       dev: eu@empresa.com
+#       orgKey: !!js process.env.DSH_ORG_KEY
+#       baseUrl: https://dsh-api.openplan.cc
+#       budgets:
+#         - limitUsd: 50
+#           window: month
+#
+- insert:
+    - id: fuse
+      name: '@openplan/dsh-fuse'

package/dist/budget-tool.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The model-facing budget-status tool — the documented *"separate
+ * model-facing ask tool"* that pairs with an enforcement gate.
+ *
+ * The harness extension cookbook prescribes the pair: a gate says *no* (the
+ * plugin's `agent/pre-step` fuse), and a separate tool lets the AGENT itself
+ * read the policy state — remaining budget per enforced scope, active remote
+ * blocks and their reset, the project/dev labels in force. A hard cut is only
+ * tolerable when the thing being cut understands it: the model can query this
+ * before spending in a long task (or right after being cut) and adapt —
+ * asking the user, stopping, or picking a cheaper route — instead of dying
+ * blind. This is the mitigation the proposal's Fase-6 metric
+ * ("falso-positivo de trava") needs.
+ *
+ * ## Status-only, never a decision
+ *
+ * The tool is deliberately inert as policy: it reads the same libsql store the
+ * fuse enforces (`spentForWindow`, `remoteBlockFor`, the published policy) and
+ * formats a view. It never gates, never rewrites, and its schema rides in the
+ * model's toolset only when the deployment left it enabled
+ * (`config.budgetStatusTool`). Registration is optional at load: it is skipped
+ * when the composition mounts no `tools` service (`@deepseek-ai/dsh-tools`),
+ * because the plugin declares no `inject` — an optional service must never
+ * hold the fiber PENDING.
+ *
+ * Types are the REAL `@deepseek-ai/dsh-tools` declarations (the same rule as
+ * the rest of the plugin): the object below is built as a literal so no
+ * runtime import of `dsh-tools` is needed — the plugin stays distributable
+ * standalone, and only the type surface is referenced.
+ */
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+/** One budget in force for this machine, with its governing scope. */
+export interface ScopedBudgetStatus {
+    scope: "org" | "project" | "dev";
+    /** Project label / developer id for scoped entries. */
+    reference?: string;
+    window: "month" | "day";
+    limitUsd: number;
+    spentUsd: number;
+}
+/** The active remote 429 block governing this machine, if any. */
+export interface RemoteBlockStatus {
+    rule: string;
+    resetAt: string;
+}
+/** The full model-facing view of the local policy state. */
+export interface BudgetStatus {
+    project: string;
+    dev: string;
+    /** ISO timestamp of the snapshot. */
+    at: string;
+    /** Budgets in force (no ordering guaranteed). */
+    budgets: ScopedBudgetStatus[];
+    block: RemoteBlockStatus | null;
+}
+/** Human-readable markdown-ish summary handed straight to the model. */
+export declare function budgetStatusText(status: BudgetStatus): string;
+/**
+ * Build the registry-ready tool definition. The status read is injected so the
+ * module stays pure (unit-testable without the harness); the wiring in
+ * `harness.ts` supplies the live read over the same store the fuse uses.
+ *
+ * @param readStatus - resolve the current policy state (store-backed).
+ * @returns a `ToolDefinition` for `ctx.tools.register(...)`.
+ */
+export declare function createBudgetStatusTool(readStatus: () => Promise<BudgetStatus>): ToolDefinition;

package/dist/budget-tool.js

@@ -0,0 +1,108 @@
+/**
+ * The model-facing budget-status tool — the documented *"separate
+ * model-facing ask tool"* that pairs with an enforcement gate.
+ *
+ * The harness extension cookbook prescribes the pair: a gate says *no* (the
+ * plugin's `agent/pre-step` fuse), and a separate tool lets the AGENT itself
+ * read the policy state — remaining budget per enforced scope, active remote
+ * blocks and their reset, the project/dev labels in force. A hard cut is only
+ * tolerable when the thing being cut understands it: the model can query this
+ * before spending in a long task (or right after being cut) and adapt —
+ * asking the user, stopping, or picking a cheaper route — instead of dying
+ * blind. This is the mitigation the proposal's Fase-6 metric
+ * ("falso-positivo de trava") needs.
+ *
+ * ## Status-only, never a decision
+ *
+ * The tool is deliberately inert as policy: it reads the same libsql store the
+ * fuse enforces (`spentForWindow`, `remoteBlockFor`, the published policy) and
+ * formats a view. It never gates, never rewrites, and its schema rides in the
+ * model's toolset only when the deployment left it enabled
+ * (`config.budgetStatusTool`). Registration is optional at load: it is skipped
+ * when the composition mounts no `tools` service (`@deepseek-ai/dsh-tools`),
+ * because the plugin declares no `inject` — an optional service must never
+ * hold the fiber PENDING.
+ *
+ * Types are the REAL `@deepseek-ai/dsh-tools` declarations (the same rule as
+ * the rest of the plugin): the object below is built as a literal so no
+ * runtime import of `dsh-tools` is needed — the plugin stays distributable
+ * standalone, and only the type surface is referenced.
+ */
+/** Human-readable markdown-ish summary handed straight to the model. */
+export function budgetStatusText(status) {
+    const lines = [
+        `dsh budget status — project "${status.project}", dev "${status.dev}" (at ${status.at})`,
+    ];
+    if (status.budgets.length === 0) {
+        lines.push("  no budgets in force");
+    }
+    else {
+        lines.push("  budgets in force:");
+        for (const budget of status.budgets) {
+            const label = budget.scope === "project"
+                ? `project "${budget.reference ?? status.project}"`
+                : budget.scope === "dev"
+                    ? `dev "${budget.reference ?? status.dev}"`
+                    : "org (this machine)";
+            const used = budget.limitUsd > 0
+                ? `${((budget.spentUsd / budget.limitUsd) * 100).toFixed(1)}% used`
+                : "no limit";
+            lines.push(`  - ${label} · ${budget.window} · $${budget.spentUsd.toFixed(4)} / $${budget.limitUsd.toFixed(2)} (${used})`);
+        }
+    }
+    if (status.block) {
+        lines.push(`  remote block: ${status.block.rule} until ${status.block.resetAt} (a SaaS 429 is engaging the local fuse)`);
+    }
+    else {
+        lines.push("  remote block: none");
+    }
+    lines.push("  note: figures are what the local fuse enforces; unpriced calls count at $0.");
+    return lines.join("\n");
+}
+/**
+ * Build the registry-ready tool definition. The status read is injected so the
+ * module stays pure (unit-testable without the harness); the wiring in
+ * `harness.ts` supplies the live read over the same store the fuse uses.
+ *
+ * @param readStatus - resolve the current policy state (store-backed).
+ * @returns a `ToolDefinition` for `ctx.tools.register(...)`.
+ */
+export function createBudgetStatusTool(readStatus) {
+    return {
+        name: "dsh_budget_status",
+        description: "Read the local dsh cost-policy status: remaining budget per enforced scope (org/project/dev), any active remote block and its reset time. Useful before spending in a long task or right after a step was cut by policy.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        output: {
+            schema: {
+                type: "object",
+                properties: {
+                    status: {
+                        type: "string",
+                        description: "Human-readable policy status summary.",
+                    },
+                },
+                required: ["status"],
+                additionalProperties: false,
+            },
+            render: (_args, value) => {
+                const status = value.status;
+                return [
+                    {
+                        type: "text",
+                        text: typeof status === "string" ? status : String(value),
+                    },
+                ];
+            },
+        },
+        execute: async () => {
+            const status = await readStatus();
+            return { status: budgetStatusText(status) };
+        },
+        // Pure read of shared state; parallel sibling calls are safe.
+        isConcurrencySafe: () => true,
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Plugin configuration — schema + cross-field validation.
+ *
+ * The harness plugin-config contract (develop/basic/config) asks for an
+ * exported `Config` that is BOTH a TypeScript type and a runtime schema:
+ * "Do not export a plain object as Config; it does not implement the Standard
+ * Schema interface required by Cordis." Cordis validates it while the plugin
+ * loads, so bad config fails the load "with a precise error — the plugin never
+ * starts half-configured".
+ *
+ * ## Why the cross-field check matters more here than in a normal plugin
+ *
+ * A cost-enforcement plugin that loads with unusable configuration does not
+ * merely misbehave — it enforces NOTHING, silently, while the deployment
+ * believes it is protected. Configuration that cannot be acted on is refused
+ * at load time (the documented rule: "A plugin should also reject
+ * schema-valid config that names an unavailable resource or provider"), and
+ * the shape that produces a silent no-op is rejected explicitly:
+ *
+ *  1. exactly one of `baseUrl` / `orgKey`. Half a sync target is not a
+ *     degraded sync, it is no sync (plus no `GET /v1/policy`, so the panel
+ *     cannot reach the local fuse at all).
+ *
+ * Prices are NOT required here: the plugin resolves them generically by model
+ * id (see pricing.ts) and reports an unpriced call visibly rather than
+ * refusing to load. The old "budgets require a price source" gate was removed
+ * because it forced every deployment to hand-maintain a price table — exactly
+ * the maintenance burden the generic resolver exists to eliminate; a missing
+ * price is a visible state, not a boot failure and not a silent zero.
+ */
+import Schema from "@deepseek-ai/schemastery";
+import type { PricingAliases, PricingTable } from "./pricing.js";
+export interface BudgetConfig {
+    limitUsd: number;
+    window: "month" | "day";
+}
+export interface PolicyConfig {
+    /**
+     * Highest allowed reasoning effort, as an id from the route's own set.
+     * Empty string means "no cap".
+     */
+    maxReasoningEffort: string;
+    /** Allowed models; empty means every model the harness routes is allowed. */
+    allowedModels: string[];
+    /** Denied projects; empty means nothing is denied. */
+    denylistedProjects: string[];
+}
+export interface DshPluginConfig {
+    /**
+     * libsql URL — a file for the installed plugin, `:memory:` for tests.
+     * Empty means the harness-home-anchored default
+     * (`$DSH_HOME/dsh-fuse/local.db`, `~/.dsh` when `$DSH_HOME` is
+     * unset); a relative `file:` path is honored only when explicitly set.
+     */
+    storeUrl: string;
+    /** Project label for windowing. */
+    project: string;
+    /** Developer identity carried on every usage row. */
+    dev: string;
+    /** Local caps — the fuse's budget inputs; spent comes from the store. */
+    budgets: BudgetConfig[];
+    /** Policy gates: reasoning cap, allowed models, project denylist. */
+    policies: PolicyConfig;
+    /** Routing cascade cheap → expensive (model ids). */
+    cascade: string[];
+    /** SaaS sync (optional): baseUrl + orgKey enable the 429 + policy pull. */
+    baseUrl?: string;
+    orgKey?: string;
+    /** Sync cadence in ms. */
+    syncIntervalMs: number;
+    /** Policy-refresh cadence in ms (`GET /v1/policy`). */
+    policyRefreshMs: number;
+    /**
+     * Expose the model-facing budget-status tool (`dsh_budget_status`) to the
+     * agent: the docs' "separate model-facing ask tool" paired with the fuse
+     * gate. It is status-only — reads the same store the fuse enforces and
+     * never decides. The schema rides in every request, so a deployment that
+     * wants zero tool presence on the wire can turn it off.
+     */
+    budgetStatusTool: boolean;
+    /**
+     * Cost table (cents per 1M tokens) — YAML-serializable so the fuse has real
+     * numbers offline. Keys may be bare (`gpt-4o`), vendor-qualified, the
+     * adapter's own prefixed id, or the normalized `provider/model` route; the
+     * resolver tries each form (see pricing.ts). Optional: prices are resolved
+     * generically when this is empty.
+     */
+    pricingTable: PricingTable;
+    /**
+     * Explicit `reported model id → price-table key` overrides. The escape
+     * hatch for an adapter whose id nothing else can guess.
+     */
+    pricingAliases: PricingAliases;
+    /**
+     * The registry of model prices, keyed by route — auto-synced, cached by the
+     * plugin for offline use, never hand-maintained. Empty string disables it.
+     */
+    pricingRegistryUrl: string;
+    /**
+     * The gateway's own OpenAI-compatible `/models` URL. When it publishes
+     * prices, those numbers are authoritative for its routes; when it does not
+     * (e.g. command-code), the registry resolves each model id generically.
+     */
+    pricingGatewayUrl: string;
+    /**
+     * Provider id used to key the gateway's routes in the table.
+     */
+    pricingGatewayProvider: string;
+    /**
+     * Env var holding the gateway bearer token, when `/models` needs auth.
+     */
+    pricingGatewayApiKeyEnv: string;
+    /**
+     * ONE optional org-level rate for models nothing prices (cents per 1M) — a
+     * knob, not a table. Lets a USD budget still cut on an unpriced route.
+     * Absent = unpriced calls count $0 and are reported visibly as unpriced.
+     */
+    unpricedFallback?: {
+        inputCentsPerM: number;
+        outputCentsPerM: number;
+        cacheReadCentsPerM?: number;
+        cacheWriteCentsPerM?: number;
+    };
+}
+/**
+ * The runtime schema Cordis validates before `apply` runs.
+ *
+ * Annotated as `Schema<Partial<DshPluginConfig>, DshPluginConfig>`: the first
+ * parameter is what a `cordis.yml` entry supplies (every field optional, filled
+ * by the schema defaults) and the second is what `apply` receives (complete).
+ * An explicit annotation is required because the inferred form cannot be named
+ * in the emitted declarations — it reaches into Schemastery's own type helpers
+ * and their vendored dependencies, which breaks the build of a package that
+ * ships `.d.ts`.
+ */
+export declare const Config: Schema<Partial<DshPluginConfig>, DshPluginConfig>;
+/**
+ * Validate raw configuration and apply defaults, exactly as Cordis does when it
+ * loads the plugin. Exposed so tests and embedders can exercise the schema
+ * without a cast: the parameter is the partially-populated shape a
+ * `cordis.yml` entry supplies, and Schemastery fills every absent field.
+ *
+ * @throws when a value has the wrong type — Cordis surfaces that as a FAILED
+ *   fibre ("invalid configuration fails the load with an actionable error").
+ */
+export declare function resolveConfig(raw: unknown): DshPluginConfig;
+/**
+ * Cross-field constraints the schema cannot express, evaluated on the resolved
+ * config (defaults applied) so they see exactly what `apply` will receive.
+ *
+ * @throws Error with an actionable message — Cordis turns it into a FAILED
+ *   fiber, which is the documented outcome for config naming what the plugin
+ *   cannot serve.
+ */
+export declare function assertUsableConfig(config: DshPluginConfig): void;