@openplan/dsh-fuse 0.1.0

package/dist/config.js

@@ -0,0 +1,125 @@
+/**
+ * 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";
+/**
+ * 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 const Config = Schema.object({
+    // Empty storeUrl means "the harness-home-anchored default store"
+    // (store.ts) — a stable ledger that does not wander with the CWD the
+    // harness was started from.
+    storeUrl: Schema.string().default(""),
+    project: Schema.string().default("default"),
+    dev: Schema.string().default("unknown"),
+    budgets: Schema.array(Schema.object({
+        limitUsd: Schema.number().min(0).required(),
+        window: Schema.union(["month", "day"]).default("month"),
+    })).default([]),
+    // "Unset" is encoded as an empty value rather than an absent key so the
+    // validated config always has a definite shape (a half-present policy
+    // object is exactly the kind of state that silently disables enforcement).
+    policies: Schema.object({
+        maxReasoningEffort: Schema.string().default(""),
+        allowedModels: Schema.array(Schema.string()).default([]),
+        denylistedProjects: Schema.array(Schema.string()).default([]),
+    }).default({
+        maxReasoningEffort: "",
+        allowedModels: [],
+        denylistedProjects: [],
+    }),
+    cascade: Schema.array(Schema.string()).default([]),
+    baseUrl: Schema.string(),
+    orgKey: Schema.string().role("secret"),
+    syncIntervalMs: Schema.number().min(1000).default(60_000),
+    policyRefreshMs: Schema.number().min(1000).default(300_000),
+    budgetStatusTool: Schema.boolean().default(true),
+    pricingTable: Schema.dict(Schema.object({
+        inputCentsPerM: Schema.number().min(0).required(),
+        outputCentsPerM: Schema.number().min(0).required(),
+        cacheReadCentsPerM: Schema.number().min(0),
+        cacheWriteCentsPerM: Schema.number().min(0),
+    })).default({}),
+    pricingAliases: Schema.dict(Schema.string()).default({}),
+    pricingRegistryUrl: Schema.string().default("https://models.dev/api.json"),
+    pricingGatewayUrl: Schema.string().default(""),
+    pricingGatewayProvider: Schema.string().default(""),
+    pricingGatewayApiKeyEnv: Schema.string().default(""),
+    unpricedFallback: Schema.object({
+        inputCentsPerM: Schema.number().min(0),
+        outputCentsPerM: Schema.number().min(0),
+        cacheReadCentsPerM: Schema.number().min(0),
+        cacheWriteCentsPerM: Schema.number().min(0),
+    }),
+});
+/**
+ * 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 function resolveConfig(raw) {
+    // A schema's whole job is to validate untrusted input, so this is the one
+    // place where the boundary is stated rather than assumed: `raw` is whatever
+    // a `cordis.yml` entry (or a test) contains, and Schemastery throws on a
+    // value whose type is wrong.
+    return Config(raw);
+}
+/**
+ * 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 function assertUsableConfig(config) {
+    if (Boolean(config.baseUrl) !== Boolean(config.orgKey)) {
+        throw new Error("baseUrl and orgKey must be configured together: without both, the plugin would report nothing and the panel could not reach the local fuse (local-only mode omits both).");
+    }
+    if (config.cascade.length > 0 && config.policies.allowedModels.length > 0) {
+        const allowed = new Set(config.policies.allowedModels);
+        const usable = config.cascade.some((model) => allowed.has(model));
+        if (!usable) {
+            throw new Error("cascade and policies.allowedModels do not intersect: the router could never pick a permitted model.");
+        }
+    }
+}

package/dist/fuse.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The local fuse — the PRIMARY enforcement (<100ms, offline). Decides
+ * whether a call may proceed; the SaaS 429 is only the secondary gate.
+ * Pure: budgets arrive with spentUsd precomputed (the store provides it) and
+ * the route's reasoning set arrives pre-resolved (the caller provides it).
+ *
+ * ## Reasoning caps are ranked by the ROUTE, never by a local table
+ *
+ * `ReasoningEffortId` is adapter-owned and opaque: the harness core "brands
+ * identifiers but does not enumerate their values; each adapter owns the
+ * ordered set, display names, and optional deployment default", and
+ * `LlmModelReasoningInfo.efforts` is published in "adapter-preferred display
+ * order". A locally invented ordinal table — or worse, an ordering derived
+ * from the id's characters — would rank an adapter id such as `none`/`off`
+ * ABOVE `high` and cut the CHEAPEST possible request: a false-positive lock,
+ * the exact failure the proposal's Phase 6 gate measures.
+ *
+ * So the cap compares indices inside the route's own ordered effort list.
+ * When that list is unavailable (no route metadata, or an id the route does
+ * not publish) the cap is UNENFORCEABLE, not satisfied: the decision reports
+ * it through {@link FuseDecision.notEnforced} so the caller can warn and the
+ * panel can show the gap. It never fabricates a verdict.
+ */
+export interface FuseBudget {
+    limitUsd: number;
+    spentUsd: number;
+    window: "month" | "day";
+}
+export interface FusePolicies {
+    /** Highest allowed reasoning effort, as an id from the route's own set. */
+    maxReasoningEffort?: string;
+    allowedModels?: string[];
+    denylistedProjects?: string[];
+}
+export interface FuseDecision {
+    allowed: boolean;
+    rule: string | null;
+    resetAt: string | null;
+    /**
+     * Configured policies that could not be evaluated for this call (an
+     * observable gap, never a silent pass). Empty when every policy applied.
+     */
+    notEnforced: string[];
+}
+export declare function fuseDecision(input: {
+    project: string;
+    model: string;
+    reasoningEffort?: string;
+    estimatedCostUsd: number;
+    budgets: FuseBudget[];
+    policies: FusePolicies;
+    now: Date;
+    /**
+     * The route's ordered reasoning-effort ids, cheapest first (harness
+     * `LlmModelReasoningInfo.efforts`, adapter-preferred display order).
+     * Absent/empty means the route publishes no reasoning metadata.
+     */
+    reasoningEfforts?: readonly string[];
+}): FuseDecision;

package/dist/fuse.js

@@ -0,0 +1,83 @@
+/**
+ * The local fuse — the PRIMARY enforcement (<100ms, offline). Decides
+ * whether a call may proceed; the SaaS 429 is only the secondary gate.
+ * Pure: budgets arrive with spentUsd precomputed (the store provides it) and
+ * the route's reasoning set arrives pre-resolved (the caller provides it).
+ *
+ * ## Reasoning caps are ranked by the ROUTE, never by a local table
+ *
+ * `ReasoningEffortId` is adapter-owned and opaque: the harness core "brands
+ * identifiers but does not enumerate their values; each adapter owns the
+ * ordered set, display names, and optional deployment default", and
+ * `LlmModelReasoningInfo.efforts` is published in "adapter-preferred display
+ * order". A locally invented ordinal table — or worse, an ordering derived
+ * from the id's characters — would rank an adapter id such as `none`/`off`
+ * ABOVE `high` and cut the CHEAPEST possible request: a false-positive lock,
+ * the exact failure the proposal's Phase 6 gate measures.
+ *
+ * So the cap compares indices inside the route's own ordered effort list.
+ * When that list is unavailable (no route metadata, or an id the route does
+ * not publish) the cap is UNENFORCEABLE, not satisfied: the decision reports
+ * it through {@link FuseDecision.notEnforced} so the caller can warn and the
+ * panel can show the gap. It never fabricates a verdict.
+ */
+/** Index of `effort` inside the route's ordered effort ids, or -1. */
+function effortIndex(efforts, effort) {
+    return efforts.indexOf(effort);
+}
+export function fuseDecision(input) {
+    const notEnforced = [];
+    if (input.policies.denylistedProjects?.includes(input.project)) {
+        return {
+            allowed: false,
+            rule: `denylist:${input.project}`,
+            resetAt: null,
+            notEnforced,
+        };
+    }
+    if (input.policies.allowedModels &&
+        !input.policies.allowedModels.includes(input.model)) {
+        return {
+            allowed: false,
+            rule: `model_not_allowed:${input.model}`,
+            resetAt: null,
+            notEnforced,
+        };
+    }
+    const cap = input.policies.maxReasoningEffort;
+    const requested = input.reasoningEffort;
+    if (cap && requested) {
+        const efforts = input.reasoningEfforts ?? [];
+        const requestedIndex = effortIndex(efforts, requested);
+        const capIndex = effortIndex(efforts, cap);
+        if (requestedIndex < 0 || capIndex < 0) {
+            // Not rankable against this route — report it, never guess.
+            notEnforced.push(`reasoning_cap:${cap}`);
+        }
+        else if (requestedIndex > capIndex) {
+            return {
+                allowed: false,
+                rule: `reasoning_cap:${cap}`,
+                resetAt: null,
+                notEnforced,
+            };
+        }
+    }
+    for (const budget of input.budgets) {
+        if (budget.spentUsd + input.estimatedCostUsd > budget.limitUsd) {
+            const reset = new Date(input.now);
+            if (budget.window === "month")
+                reset.setUTCMonth(reset.getUTCMonth() + 1, 1);
+            else
+                reset.setUTCDate(reset.getUTCDate() + 1);
+            reset.setUTCHours(0, 0, 0, 0);
+            return {
+                allowed: false,
+                rule: "budget_exceeded",
+                resetAt: reset.toISOString(),
+                notEnforced,
+            };
+        }
+    }
+    return { allowed: true, rule: null, resetAt: null, notEnforced };
+}

package/dist/harness.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The harness integration — the Cordis wiring that makes the pure modules
+ * live against the DeepSeek Harness runtime.
+ *
+ * Types are the REAL `@deepseek-ai/*` packages (exact-rc devDeps): the
+ * waterfall signatures, `PreStepDecision`, `LlmCallConfig` and `SessionEvent`
+ * come from the installed declarations, never from local re-declarations.
+ *
+ * ## Wiring, and the dispatch contracts each one obeys
+ *
+ * - `session/event` → **meter**. This event is `@mode emit`: a synchronous,
+ *   fire-and-forget broadcast ("returned promises and values are not awaited
+ *   or collected") emitted post-commit. An `async` listener therefore leaves a
+ *   floating promise that a one-shot headless run can exit before it lands.
+ *   The handler is consequently SYNCHRONOUS and only enqueues; a single shared
+ *   drain writes to libsql, and the plugin flushes it on `turn/end`,
+ *   `session/disposed`, and its own disposal — the same non-blocking-enqueue +
+ *   explicit-drain contract the harness's own telemetry seam documents for
+ *   this exact hot path.
+ * - `agent/pre-step` → **fuse**. `@mode waterfall`; returning
+ *   `{ kind: 'reject' }` without calling `next()` short-circuits the step
+ *   before any token is spent.
+ * - `agent/request` → **router**. `@mode waterfall`; always calls `next()` and
+ *   rewrites the returned config, never the messages.
+ * - interval → **sync + policy pull**, registered through `ctx.effect()` so
+ *   every resource Cordis does not manage itself is released on unload, hot
+ *   reload, config edit, or loss of a required service.
+ *
+ * The plugin declares **no `inject`**: `ctx.logger` is framework surface, not
+ * an injectable service, and `tokenMeter` / `llm` are optional — a hard
+ * dependency on an optional service would leave the fiber PENDING forever,
+ * silently enforcing nothing.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import { type DshPluginConfig } from "./config.js";
+/**
+ * The plugin entry points.
+ *
+ * Exported as NAMED functions (the shape the harness's own tutorials use) and
+ * re-assembled into the object form by `index.ts`, which is what the loader
+ * needs: it unwraps a module to `exports.default` when one exists
+ * (`Loader.unwrapExports`) and then reads `plugin.Config` to validate the row's
+ * config. A bare-function default export therefore arrives with `Config`
+ * undefined — the schema is skipped, defaults are never applied, and `apply`
+ * receives partial config. That failure is silent at the type level and only
+ * shows up against a real profile, which is why the smoke test boots one.
+ */
+export declare function apply(ctx: Context, config: DshPluginConfig): void;