@openplan/dsh-fuse 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The dsh fuse — metering ≡ enforcement for local coding agents.
+ *
+ * A free plugin for the DeepSeek Harness that exports per-call telemetry
+ * (metrics only: model, tokens, cost — never content) and enforces the org's
+ * cost policy locally, before any token is spent. The SaaS aggregates the
+ * team's sessions and publishes the policy; the local fuse applies it offline
+ * and the batch's 429 is the secondary, central gate.
+ *
+ * ## How it extends the harness
+ *
+ * It is a **hook plugin** in the harness's own vocabulary (extension
+ * cookbook): "an ordinary Cordis plugin on an interception point". It listens
+ * on the `agent/pre-step` and `agent/request` waterfalls, and observes the
+ * durable feed through `session/event`. It is deliberately NOT a tool (the
+ * docs are explicit that deployment policy does not belong in a tool the
+ * model must choose to call) and it modifies no part of the loop.
+ *
+ * ## Local-only mode
+ *
+ * Without `baseUrl`/`orgKey` nothing ever leaves the machine: the fuse
+ * enforces the configured budgets and policies entirely offline, and the
+ * local libsql store (`$DSH_HOME/dsh-fuse/local.db` by default) is
+ * the spend source.
+ */
+export declare const name = "fuse";
+import { apply as pluginApply } from "./harness.js";
+export { assertUsableConfig, type BudgetConfig, Config, type DshPluginConfig, type PolicyConfig, resolveConfig, } from "./config.js";
+export { type FuseBudget, type FuseDecision, type FusePolicies, fuseDecision, } from "./fuse.js";
+export { type CallProjection, hashSessionId, type MessageProvenance, projectCall, type RequestHeaderView, type TokenUsageLike, } from "./meter.js";
+export { createPricingCache, DEFAULT_REGISTRY_URL, estimateCostUsd, fetchPricingTable, normalizeModelId, type PricingAliases, type PricingEntry, type PricingResolution, type PricingTable, type PricingVia, parseGatewayModelEntry, parseGatewayModels, parsePricingRegistry, pricingCandidates, resolvePricingEntry, type TokenCounts, } from "./pricing.js";
+export { type RouteDecision, type RouteReason, type RouterPolicies, routeDecision, } from "./router.js";
+export { createLocalStore, type LocalStore, type RemotePolicy, type StoredUsage, type UsageRecord, } from "./store.js";
+export { fetchPolicy, type OrgKeyTarget, parseRemotePolicy, type SyncResult, syncBatch, } from "./sync.js";
+export type { BatchEvent, CutEvent, UsageEvent } from "./wire.js";
+/**
+ * The Cordis entry.
+ *
+ * The DEFAULT export is the object form `{ name, apply, Config }` because the
+ * loader unwraps a module to `exports.default` before mounting it
+ * (`Loader.unwrapExports`) and then reads `plugin.Config` to validate the row's
+ * config. Exporting the bare `apply` function as default — the shape this
+ * package originally shipped — leaves `Config` undefined, so the schema is
+ * skipped, defaults are never applied, and `apply` receives partial config.
+ * The object form is the documented shape that keeps both together.
+ *
+ * The named exports above/below serve programmatic mounting and tests.
+ */
+export declare const apply: typeof pluginApply;
+export { pluginApply as plugin };
+declare const _default: {
+    name: string;
+    apply: typeof pluginApply;
+    Config: import("@deepseek-ai/schemastery").default<Partial<import("./config.js").DshPluginConfig>, import("./config.js").DshPluginConfig>;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,55 @@
+/**
+ * The dsh fuse — metering ≡ enforcement for local coding agents.
+ *
+ * A free plugin for the DeepSeek Harness that exports per-call telemetry
+ * (metrics only: model, tokens, cost — never content) and enforces the org's
+ * cost policy locally, before any token is spent. The SaaS aggregates the
+ * team's sessions and publishes the policy; the local fuse applies it offline
+ * and the batch's 429 is the secondary, central gate.
+ *
+ * ## How it extends the harness
+ *
+ * It is a **hook plugin** in the harness's own vocabulary (extension
+ * cookbook): "an ordinary Cordis plugin on an interception point". It listens
+ * on the `agent/pre-step` and `agent/request` waterfalls, and observes the
+ * durable feed through `session/event`. It is deliberately NOT a tool (the
+ * docs are explicit that deployment policy does not belong in a tool the
+ * model must choose to call) and it modifies no part of the loop.
+ *
+ * ## Local-only mode
+ *
+ * Without `baseUrl`/`orgKey` nothing ever leaves the machine: the fuse
+ * enforces the configured budgets and policies entirely offline, and the
+ * local libsql store (`$DSH_HOME/dsh-fuse/local.db` by default) is
+ * the spend source.
+ */
+export const name = "fuse";
+import { Config as PluginConfig } from "./config.js";
+import { apply as pluginApply } from "./harness.js";
+export { assertUsableConfig, Config, resolveConfig, } from "./config.js";
+export { fuseDecision, } from "./fuse.js";
+export { hashSessionId, projectCall, } from "./meter.js";
+export { createPricingCache, DEFAULT_REGISTRY_URL, estimateCostUsd, fetchPricingTable, normalizeModelId, parseGatewayModelEntry, parseGatewayModels, parsePricingRegistry, pricingCandidates, resolvePricingEntry, } from "./pricing.js";
+export { routeDecision, } from "./router.js";
+export { createLocalStore, } from "./store.js";
+export { fetchPolicy, parseRemotePolicy, syncBatch, } from "./sync.js";
+/**
+ * The Cordis entry.
+ *
+ * The DEFAULT export is the object form `{ name, apply, Config }` because the
+ * loader unwraps a module to `exports.default` before mounting it
+ * (`Loader.unwrapExports`) and then reads `plugin.Config` to validate the row's
+ * config. Exporting the bare `apply` function as default — the shape this
+ * package originally shipped — leaves `Config` undefined, so the schema is
+ * skipped, defaults are never applied, and `apply` receives partial config.
+ * The object form is the documented shape that keeps both together.
+ *
+ * The named exports above/below serve programmatic mounting and tests.
+ */
+export const apply = pluginApply;
+export { pluginApply as plugin };
+export default {
+    name,
+    apply: pluginApply,
+    Config: PluginConfig,
+};

package/dist/meter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The meter — projects one completed model call from the durable session log
+ * into the metrics the fuse prices and the SaaS stores.
+ *
+ * ## Sources, and why these ones
+ *
+ * - **Model and provider** come from the assistant message's own provenance.
+ *   `assistant/message.message.source` is `AssistantProvenance {provider,
+ *   model}`: "Model-produced assistant messages name the provider and model
+ *   that produced them", and the loop "stores the assembled assistant content
+ *   with the provider and model that produced it". This is per-call truth. A
+ *   session-keyed cache of the latest `request/header` — the previous
+ *   implementation — resolves to "unknown" on a resumed session or a missing
+ *   header, and then prices the call at zero.
+ * - **Reasoning effort** comes from the request header's `LlmCallConfig`,
+ *   which is the only place the log records it. When the caller omitted an
+ *   effort and the ADAPTER materialized its own default, the log records that
+ *   a default was applied (`EpochHeader.adapterDefaults.reasoningEffort`) but
+ *   not the value; the projection therefore reports the effort the log states
+ *   and stays empty otherwise rather than guessing.
+ * - **Tokens** are the harness's own disjoint counts (`TokenUsage`: uncached
+ *   input, output, cache reads, cache writes).
+ * - **Duration** is measured from the step's `step/start` to the assistant
+ *   settlement, i.e. the model request's latency for that step. The durable
+ *   `assistant/message.stream` is not persisted by this build (verified
+ *   against real logs: `data` carries only `message/step/turn/usage`), so the
+ *   step boundary is the honest available source. `null` when the step's start
+ *   was not observed (a resumed session, or a delivery that began before the
+ *   plugin loaded).
+ */
+import type { TokenCounts } from "./pricing.js";
+/** The harness's per-call token accounting (`TokenUsage`). */
+export interface TokenUsageLike {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+/** `AssistantProvenance` — the provider/model that produced one message. */
+export interface MessageProvenance {
+    provider?: string;
+    model?: string;
+}
+/** The subset of `EpochHeader` the meter reads (never the system prompt). */
+export interface RequestHeaderView {
+    provider?: string;
+    model?: string;
+    reasoningEffort?: string;
+}
+export interface CallProjection {
+    model: string;
+    provider: string;
+    reasoningEffort: string;
+    counts: Required<TokenCounts>;
+    durationMs: number | null;
+}
+/** sha256 — the session id never leaves the machine raw. */
+export declare function hashSessionId(sessionId: string): Promise<string>;
+/**
+ * Project one completed model call. Pure — no I/O, no clock: the caller
+ * supplies the settlement time and (when observed) the step's start time.
+ */
+export declare function projectCall(input: {
+    provenance?: MessageProvenance;
+    header?: RequestHeaderView;
+    usage: TokenUsageLike;
+    /** Epoch ms of the assistant settlement. */
+    settledAt: number;
+    /** Epoch ms when this step opened, when observed. */
+    stepStartedAt?: number;
+}): CallProjection;

package/dist/meter.js

@@ -0,0 +1,73 @@
+/**
+ * The meter — projects one completed model call from the durable session log
+ * into the metrics the fuse prices and the SaaS stores.
+ *
+ * ## Sources, and why these ones
+ *
+ * - **Model and provider** come from the assistant message's own provenance.
+ *   `assistant/message.message.source` is `AssistantProvenance {provider,
+ *   model}`: "Model-produced assistant messages name the provider and model
+ *   that produced them", and the loop "stores the assembled assistant content
+ *   with the provider and model that produced it". This is per-call truth. A
+ *   session-keyed cache of the latest `request/header` — the previous
+ *   implementation — resolves to "unknown" on a resumed session or a missing
+ *   header, and then prices the call at zero.
+ * - **Reasoning effort** comes from the request header's `LlmCallConfig`,
+ *   which is the only place the log records it. When the caller omitted an
+ *   effort and the ADAPTER materialized its own default, the log records that
+ *   a default was applied (`EpochHeader.adapterDefaults.reasoningEffort`) but
+ *   not the value; the projection therefore reports the effort the log states
+ *   and stays empty otherwise rather than guessing.
+ * - **Tokens** are the harness's own disjoint counts (`TokenUsage`: uncached
+ *   input, output, cache reads, cache writes).
+ * - **Duration** is measured from the step's `step/start` to the assistant
+ *   settlement, i.e. the model request's latency for that step. The durable
+ *   `assistant/message.stream` is not persisted by this build (verified
+ *   against real logs: `data` carries only `message/step/turn/usage`), so the
+ *   step boundary is the honest available source. `null` when the step's start
+ *   was not observed (a resumed session, or a delivery that began before the
+ *   plugin loaded).
+ */
+/** sha256 — the session id never leaves the machine raw. */
+export async function hashSessionId(sessionId) {
+    const data = new TextEncoder().encode(sessionId);
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+/** Coerce one provider-reported count to a non-negative integer. */
+function count(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return 0;
+    return Math.floor(value);
+}
+/**
+ * Project one completed model call. Pure — no I/O, no clock: the caller
+ * supplies the settlement time and (when observed) the step's start time.
+ */
+export function projectCall(input) {
+    // Provenance wins: it identifies the model that actually served the call.
+    const model = input.provenance?.model ?? input.header?.model ?? "";
+    const provider = input.provenance?.provider ??
+        input.header?.provider ??
+        (model.includes("/") ? model.split("/")[0] : "") ??
+        "";
+    const durationMs = typeof input.stepStartedAt === "number" &&
+        Number.isFinite(input.stepStartedAt) &&
+        input.settledAt >= input.stepStartedAt
+        ? Math.round(input.settledAt - input.stepStartedAt)
+        : null;
+    return {
+        model,
+        provider,
+        reasoningEffort: input.header?.reasoningEffort ?? "",
+        counts: {
+            inputTokens: count(input.usage.inputTokens),
+            outputTokens: count(input.usage.outputTokens),
+            cacheReadTokens: count(input.usage.cacheReadTokens),
+            cacheWriteTokens: count(input.usage.cacheWriteTokens),
+        },
+        durationMs,
+    };
+}

package/dist/pricing.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Pricing for the fuse and the meter — resolved generically, never hand-maintained.
+ *
+ * ## Why this module exists at all
+ *
+ * The harness reports **tokens**, exactly and for free (`TokenUsage`), and models
+ * **no monetary cost anywhere** (the only "pricing" in the harness is per-route
+ * *image* token pricing). The proposal asks for `cost_usd` and `limitUsd`, so
+ * `USD = tokens × price` and this module owns the `price` half.
+ *
+ * Nobody is invoiced from this number: its jobs are to express the customer's own
+ * policy in the unit they wrote it in, and to rank projects/sessions against each
+ * other. An approximate price is therefore fine; a MISSING price is fatal — it
+ * prices every call at zero, so no budget ever cuts and both gates go inert. That
+ * is the defect this resolver exists to prevent.
+ *
+ * ## Resolution order (measured against real gateways)
+ *
+ * 1. `pricingAliases[model]` — explicit escape hatch, highest precedence.
+ * 2. `${provider}/${model}` — the exact route, from the registry or the gateway's
+ *    own `/models`. This is the correct key: the same model costs different
+ *    amounts on different routes (`deepseek/deepseek-v4.1-flash` ranges
+ *    $0.15–$0.375 per 1M input across registries), so keying on model alone is
+ *    wrong in principle.
+ * 3. bare `model` — the provider is absent from the registry (a private gateway).
+ *    Falls back to the **consensus** price across every provider that publishes
+ *    the model: the modal quote, which measurements show is the upstream list
+ *    price that pass-through resellers charge "at cost".
+ * 4. progressively trimmed variants, then `${provider}/${bare}`.
+ * 5. `null` — reported as **unpriced**, never silently zero.
+ *
+ * Verified on this machine's real routes: a pass-through reseller that publishes
+ * "at cost" pricing reproduces the registry's numbers to the cent (8/8 models),
+ * and the generic resolver prices 68/69 of its catalogue with no per-provider
+ * configuration.
+ */
+export interface PricingEntry {
+    inputCentsPerM: number;
+    outputCentsPerM: number;
+    cacheReadCentsPerM?: number;
+    cacheWriteCentsPerM?: number;
+}
+export type PricingTable = Record<string, PricingEntry>;
+/** Token counts priced by {@link estimateCostUsd}. */
+export interface TokenCounts {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens?: number;
+}
+/** Explicit `model id → price-table key` overrides; highest precedence. */
+export type PricingAliases = Record<string, string>;
+/** Default registry: 200+ providers, `cost` in USD per 1M tokens. */
+export declare const DEFAULT_REGISTRY_URL = "https://models.dev/api.json";
+/** How a key was derived from the requested model id — feeds diagnostics. */
+export type PricingVia = "alias" | "exact" | "route" | "model" | "suffix" | "provider";
+/** Which candidate key resolved, and how. */
+export interface PricingResolution {
+    entry: PricingEntry;
+    /** The table key that matched. */
+    key: string;
+    /** How the key was derived from the requested model id. */
+    via: PricingVia;
+}
+/** Lowercase + separator-normalized form used for every lookup. */
+export declare function normalizeModelId(model: string): string;
+/**
+ * Ordered candidate keys for one model id, most specific first.
+ *
+ * `provider/anthropic/claude-sonnet-5` yields the full id, then each
+ * progressively stripped suffix (`anthropic/claude-sonnet-5`,
+ * `claude-sonnet-5`) — so a table keyed by a bare model id, by a
+ * vendor-qualified id, or by the adapter's own prefixed id all resolve. When
+ * the caller knows the provider route, `${provider}/${bare}` is tried too
+ * (a table keyed `openai/gpt-4o` still prices a reported `gpt-4o`).
+ */
+export declare function pricingCandidates(model: string, provider?: string): string[];
+/**
+ * Resolve the price entry for one model id.
+ *
+ * Precedence: explicit alias → exact key → `${provider}/${bare}` → bare model →
+ * progressively stripped suffix. Returns `null` when nothing matches, so callers
+ * can report the miss (and mark the call unpriced) instead of pricing at zero.
+ */
+export declare function resolvePricingEntry(table: PricingTable | undefined, model: string, opts?: {
+    provider?: string;
+    aliases?: PricingAliases;
+}): PricingResolution | null;
+/**
+ * Cost in USD from the resolved table entry (cents per 1M tokens).
+ *
+ * Cache reads and writes price at the entry's own cache rate when the table
+ * publishes one, and at the INPUT rate when it does not — deliberately
+ * conservative: the fuse prefers overestimating spend to missing a cut. The
+ * harness reports cache counts as DISJOINT from `inputTokens` (`TokenUsage`:
+ * "billed input = sum of the three"), so nothing is double counted here, and
+ * `reasoningTokens` is deliberately ignored because the docs state it is
+ * "already included in `outputTokens`; totals must not add it again".
+ *
+ * @returns USD cost plus the key that priced it, or `null` when the model is
+ *   unpriced — this function never invents a price.
+ */
+export declare function estimateCostUsd(table: PricingTable | undefined, model: string, counts: TokenCounts, opts?: {
+    provider?: string;
+    aliases?: PricingAliases;
+}): {
+    costUsd: number;
+    key: string;
+    via: PricingVia;
+} | null;
+/**
+ * Parse the registry into a table keyed BOTH ways:
+ *
+ * - `${provider}/${model}` — the exact route (authoritative).
+ * - bare `${model}` — the **modal** (most-agreed) quote across every provider,
+ *   used only when the route is absent. Measurements show this modal value is
+ *   the upstream list price (e.g. 34 of 39 providers quote exactly $5.00/1M for
+ *   `gpt-5.5`), which is what a pass-through reseller charges at cost.
+ *
+ * Every key is normalized so a reported `deepseek/deepseek-v4.1-flash` and a
+ * registry `deepseek-v4.1-flash` land on the same lookup.
+ */
+export declare function parsePricingRegistry(json: unknown): {
+    table: PricingTable;
+    routes: number;
+    models: number;
+};
+/**
+ * Normalize one OpenAI-compatible `/models` entry that publishes prices.
+ *
+ * The convention is real but the shape is not standardized; three layouts cover
+ * every publicly-readable gateway measured:
+ * - OpenRouter: `pricing.{prompt,completion,input_cache_read,input_cache_write}`
+ *   in USD **per token** (strings).
+ * - DeepInfra: `metadata.pricing.{input_tokens,output_tokens,cache_read_tokens}`
+ *   in USD **per 1M**.
+ * - Novita: `input_token_price_per_m` / `output_token_price_per_m` per 1M.
+ * A registry-shaped `cost.{input,output,cache_read,cache_write}` is accepted too.
+ */
+export declare function parseGatewayModelEntry(model: unknown): PricingEntry | null;
+/**
+ * Parse a gateway `/models` response, keyed by `${provider}/${model}`.
+ *
+ * Returns an empty table when the gateway publishes no prices (e.g. command-code)
+ * — the caller then falls back to the registry by model id.
+ */
+export declare function parseGatewayModels(json: unknown, provider: string): {
+    table: PricingTable;
+    priced: number;
+    total: number;
+};
+/**
+ * Fetch + merge every configured price source. Never throws: a failed source
+ * keeps whatever the config already carries, and a config override always wins
+ * on conflicts.
+ *
+ * The registry is the primary source (200+ providers, keyed by route, carries
+ * cache read/write). A gateway `/models` is consulted first when configured,
+ * because a gateway that publishes its own prices is authoritative for its own
+ * routes.
+ */
+export declare function fetchPricingTable(input: {
+    /** Registry URL; pass `""` to skip. Defaults to {@link DEFAULT_REGISTRY_URL}. */
+    registryUrl?: string;
+    /** OpenAI-compatible `/models` URL that may publish prices. */
+    gatewayUrl?: string;
+    /** Provider id used to key the gateway's routes (e.g. "opencode-go"). */
+    gatewayProvider?: string;
+    /** Env var holding the gateway bearer token, when the endpoint needs auth. */
+    gatewayApiKeyEnv?: string;
+    /** User config wins over every fetched source on per-key conflicts. */
+    override?: PricingTable;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    table: PricingTable;
+    failures: string[];
+    routes: number;
+    models: number;
+    gatewayPriced: number;
+}>;
+/**
+ * TTL cache for the sync (refresh hourly; the first call inside the plugin is
+ * non-blocking — the fuse starts on the config table and upgrades when the
+ * fetch lands). `onUpdate` lets the caller persist the table for offline use.
+ */
+export declare function createPricingCache(fetchTable: () => Promise<{
+    table: PricingTable;
+}>, ttlMs?: number, onUpdate?: (table: PricingTable) => void): {
+    current: () => PricingTable;
+    refresh: () => void;
+    /** Seed the cache from persisted state (offline first boot). */
+    hydrate: (table: PricingTable) => void;
+};