@indexyz/dsh-custom-provider-reasoning-efforts 0.0.1 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.1
+
+### Patch Changes
+
+- Read a Codex-shaped relay's reasoning levels from its /backend-api/codex/models manifest when its /v1/models inventory publishes none.
+
+## 0.1.0 - 2026-10-17
+
+- Initial release.
+- Declare `reasoningEfforts` for a hand-written `llm-pi-ai` provider route, whose models otherwise resolve to `reasoning: false` because the installed pi-ai catalog ships no entry to inherit from.
+- Carry the declarations in the plugin row's own `providers` table, keyed by provider route and exact model id, with each level mapped to the wire spelling it dispatches and `false` for a model that cannot reason; a malformed declaration fails the load, naming the route, the model, and the level.
+- Write the missing field through the Harness settings service over the `llm-pi-ai` row's volatile `providers` field, so the change reaches the running adapter without a restart; only models the profile already declares are filled, and nothing is invented.
+- Interrogate a custom route's `/v1/models` for the levels it advertises (`reasoning`, `supported_reasoning_levels`, and their sibling spellings) and map them onto the models the route declares, with endpoint failures contained to a warning.
+- Add `/reasoning-efforts` with `status`, `apply`, `discover`, and `clear`, reporting every change, every already-current pair, and every skip with its reason.
+- Run the pass once after startup, through the launcher's readiness signal when one exists, so a declaration lands without a restart and an unreachable gateway never blocks or fails boot.

package/README.md

@@ -1,8 +1,218 @@
-# Bootstrap placeholder
+# @indexyz/dsh-custom-provider-reasoning-efforts
 
-This version exists only to register the package name on npm, so that a trusted
-publisher can be configured for `@indexyz/dsh-custom-provider-reasoning-efforts`
-before its first real release. The real plugin is released as `0.1.0` from the
-repository `5aaee9/pi-agent-extensions` by the `publish.yml` workflow.
+Give a hand-written [dsh (DeepSeek Harness)](https://github.com/deepseek-ai/deepseek-harness)
+provider route the reasoning levels its gateway actually offers.
 
-Use `0.1.0` or later; do not install this version.
+```bash
+dsh plugin --profile web add @indexyz/dsh-custom-provider-reasoning-efforts
+```
+
+It is built and tested against dsh `0.2.0-rc.2` and declares that range as
+`engines.dsh` (`>=0.2.0-rc.2 <0.3.0-0`), which the plugin market reads before it
+installs. Node `22.19.0` or newer is required as well.
+
+To try a repository checkout instead (after `npm install` at the repository root):
+
+```bash
+dsh plugin --profile web add ./dsh-custom-provider-reasoning-efforts
+```
+
+## Why a custom route loses its levels
+
+`llm-pi-ai` resolves a model's reasoning capability from the profile entry's
+`reasoningEfforts` field and, only when that field is absent, from the installed
+pi-ai catalog. A route the catalog does not ship — `magpie` in the configuration
+this plugin was written for — has no catalog entry at all, so:
+
+| Step                                      | Result                                                       |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `catalogModels("magpie").get(id)`         | empty map, so `base` is undefined                            |
+| `resolveModelReasoning(entry, undefined)` | `{reasoning: base?.reasoning ?? false}` → `reasoning: false` |
+| `reasoningInfo(model)`                    | `if (!model.reasoning) return {}`                            |
+| model-selection menu                      | no levels to offer                                           |
+
+The gateway may advertise exactly what is missing — `reasoning: true` and
+`supported_reasoning_levels: [{effort: "low"}, {effort: "high"}, {effort: "max"}]`
+— but the Harness endpoint probe parses only `id`, `name`, `contextWindow`, and
+`maxTokens`, and it does not persist what it reads, so discovery cannot fill the
+gap by itself. The one thing that fixes it is the field the profile already
+supports, on every model entry of that route. This plugin writes it.
+
+## Declarations
+
+Declarations live in this plugin's own row in the profile patch
+(`~/.dsh/profiles/<profile>/cordis.patch.yml`):
+
+```yaml
+- insert:
+    - id: custom-provider-reasoning-efforts
+      name: "@indexyz/dsh-custom-provider-reasoning-efforts"
+      config:
+        providers:
+          magpie:
+            ollama-cloud/kimi-k3:
+              low: low
+              high: high
+              max: max
+            ollama-cloud/deepseek-v4.1-flash:
+              low: low
+              high: high
+              max: max
+```
+
+Each model's value is either the levels it offers — keyed by pi-ai thinking level
+(`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) and mapped to the wire
+spelling that level dispatches — or `false` for a model the route serves but that
+cannot reason. `off: null` is the one level that may carry no wire value, because
+not thinking is the parameter's absence. A declaration that is empty, offers no
+level beyond `off`, puts `null` or an empty string on a thinking level, or names a
+level pi-ai does not know fails the plugin's load with the route, the model, and
+the level named.
+
+The plugin writes only models the route already declares in the profile: it
+never invents a route, a `baseURL`, a protocol, a credential reference, or a
+model entry. A declaration for a route or model the profile does not carry is
+reported by the command and skipped.
+
+## The `/reasoning-efforts` command
+
+```text
+/reasoning-efforts           # what is pending; writes nothing (same as `status`)
+/reasoning-efforts status    # same
+/reasoning-efforts apply     # write the declarations above
+/reasoning-efforts discover  # interrogate each custom route, then write
+/reasoning-efforts clear     # remove the reasoningEfforts the declarations name
+```
+
+Every mode reports the route/model pairs it changed, how many were already
+current, and every pair it skipped with the reason. `status`, `apply`, and
+`clear` perform no network request. Nothing is written when the plan finds no
+change, so a repeat run leaves the file untouched.
+
+## Endpoint discovery
+
+A route is a discovery candidate when its profile declares both an explicit,
+non-empty `models` list and a `baseURL` — the shape of a hand-written route.
+`discoverRoutes` names the candidates instead when a deployment wants otherwise.
+Each candidate is interrogated once at `GET {baseURL}/models` (Anthropic Messages
+at the root `/v1/models`), with `authorization: Bearer <key>` for the OpenAI
+protocols and `x-api-key` plus `anthropic-version` for Anthropic Messages. The
+key is resolved from the route's own `apiKeyEnv` through the credential store,
+falling back to the process environment; when neither resolves, the probe is
+sent unauthenticated rather than failing.
+
+The reply's `data` array, or the `models` object some compatible gateways expose,
+is read; reasoning is taken from `supported_reasoning_levels`,
+`reasoning_levels`, `supported_reasoning_efforts`, or the `reasoning` object's
+`efforts` / `supported_efforts`, with string entries or `{effort}` / `{level}` /
+`{id}` / `{name}` objects. A name that is a pi-ai thinking level maps to itself
+as its wire spelling and `off` maps to `null`; anything else is ignored. Only
+models the route already declares are considered, so a gateway listing hundreds
+of models cannot add any. An explicit declaration always wins over a discovered
+one, and a model whose entry advertises no levels is left exactly as it is.
+
+### The Codex manifest, for a relay whose inventory says nothing
+
+A relay that proxies a Codex backend sometimes publishes an inventory with no
+capability at all — only `id`, `display_name`, and `owned_by`, the shape
+[`pi-provider-sub2api`](../pi-provider-sub2api) also works around. The same relay
+usually answers the backend's own model list at
+`GET {root}/backend-api/codex/models` (`root` is the route's `baseURL` with a
+trailing `/v1` removed), where each entry carries `slug` and the efforts the
+backend accepts:
+
+```json
+{
+  "models": [
+    {
+      "slug": "gpt-6.1-sol",
+      "supported_reasoning_levels": [
+        { "effort": "low" },
+        { "effort": "medium" },
+        { "effort": "high" },
+        { "effort": "xhigh" },
+        { "effort": "max" },
+        { "effort": "ultra" }
+      ]
+    }
+  ]
+}
+```
+
+That manifest is a second discovery source. It is consulted only for an
+`openai-responses` route whose own listing described no level for at least one
+model the route declares, so a relay that already answers costs no extra request;
+its levels are merged with the listing's (the listing's own spellings win) and
+only the route's declared models are considered. A relay without the endpoint
+answers `403`, `404`, or something that is not a manifest, which means "nothing
+more to say" rather than a failure; an endpoint that is unreachable, or that
+answers with its own error status, is reported. `ultra` is not a pi-ai thinking
+level, so it is dropped from a discovered declaration — declare `max: ultra` in
+the route's own `providers` entry to wire the `max` level to it.
+
+Discovery is on by default and runs once after startup (see `applyOnLoad` and
+`discover` below); `/reasoning-efforts discover` runs it on demand. Every
+interrogation failure is contained to a warning and one line in the command's
+answer — a gateway that is down never blocks startup or a declaration that does
+not need the network.
+
+## Configuration
+
+| Field            | Default     | Meaning                                                                                                    |
+| ---------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
+| `providers`      | `{}`        | Declarations keyed by provider route and then by exact model id; each value is an effort table or `false`. |
+| `discover`       | `true`      | Whether the load-time pass interrogates endpoints as well as applying declarations.                        |
+| `discoverRoutes` | `[]`        | Routes to interrogate instead of the heuristic's own set; empty means the heuristic.                       |
+| `namespace`      | `llm-pi-ai` | The configurable namespace whose `providers` field is written.                                             |
+| `applyOnLoad`    | `true`      | Whether the plugin writes at load. Off leaves `/reasoning-efforts` as the only writer.                     |
+
+## Behavior and limitations
+
+- The write goes through the Harness settings service
+  (`settings.describe()` / `update()`), the same seam the Models page uses, so
+  the Loader validates the change and reconciles the running `llm-pi-ai` row.
+  `providers` is a `volatile` field, so the change is live: the next
+  `resolveModelInfo()` — and the model-selection menu's next read — sees the
+  levels. No restart is involved.
+- Because that write is a configuration write, the `llm-pi-ai` config node is
+  re-serialized: comments inside that node do not survive a write, and the plugin
+  writes only when it has an actual change to make. The declarations themselves
+  are persisted, so they keep working if the plugin is later removed;
+  `/reasoning-efforts clear` is the way back.
+- Only models the profile's own patch layer declares can be filled. A route that
+  comes from a lower layer, or a model the route does not list, is reported and
+  skipped.
+- A gateway that advertises `reasoning: true` with no level list gets no
+  declaration: there is no level to offer, and inventing one would claim a
+  capability the endpoint did not declare.
+- A level name is used as its own wire spelling. A gateway that accepts a
+  different spelling for a level needs that spelling written explicitly in the
+  declaration.
+- Discovery reads `openai-completions`, `openai-responses`, and
+  `anthropic-messages` listings; any other protocol is reported as unsupported
+  and left to explicit declarations.
+- The load-time pass waits for the launcher's readiness signal when the
+  composition provides one, runs asynchronously, and contains every failure to a
+  log line. It never throws out of the plugin's load and never delays startup.
+
+## Development
+
+The host half is TypeScript compiled to `lib/` with `tsc`; there is no browser
+half.
+
+```bash
+npm run check          # typecheck, build, then test
+npm run build          # lib/ (Host half)
+npm test               # 96 Vitest cases
+```
+
+`test/smoke-release.ts` is the package's declared `release.smoke` check: the
+release engine runs it against the packed and installed tarball, verifying the
+manifest targets, the built host entry, and the bundle patch the `dsh` manifest
+points at.
+
+See the repository root for the workspace layout and release process.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# Bundle patch layer: the row loads this package's main entry as the Host half
+# (a plain Cordis plugin exporting `apply`, `inject`, and `Config`), and its
+# `providers` table is where a deployment declares the reasoning levels of a
+# hand-written provider route.
+- insert:
+    - id: custom-provider-reasoning-efforts
+      name: "@indexyz/dsh-custom-provider-reasoning-efforts"
+      config:
+        providers: {}

package/lib/apply.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Write a planned change through the Harness settings service.
+ *
+ * This is the only writer. It reads the namespace's descriptor, plans against
+ * the profile patch's own `providers` value, and calls `settings.update()` with
+ * the whole planned value and the revision `describe()` returned, so the Loader
+ * validates the candidate and reconciles the running `llm-pi-ai` adapter
+ * exactly as it does a Models-page save — `providers` is a `volatile` field, so
+ * the change is live without a restart. Nothing is written when the plan finds
+ * no change, and a revision conflict is retried once against a fresh read.
+ *
+ * @module @indexyz/dsh-custom-provider-reasoning-efforts/apply
+ */
+import { type Change, type Intent, type Skip } from "./plan.ts";
+/** One configurable namespace as the settings service describes it. */
+export interface ProviderDescriptor {
+    /** Profile entry id addressed by the settings service. */
+    readonly ns: string;
+    /** Revision `describe()` returned; `update()` refuses a stale one. */
+    readonly revision: number;
+    /** The live resolved value, including provider defaults. */
+    readonly value?: unknown;
+    /** The profile patch's own raw value for this entry. */
+    readonly user?: unknown;
+}
+/** The part of the settings service this plugin uses. */
+export interface SettingsSeam {
+    /** Whether the active profile accepts configuration edits. */
+    readonly writable: boolean;
+    /** Read the active namespaces with their revisions and layer values. */
+    describe(): readonly ProviderDescriptor[];
+    /** Write the namespace's volatile fields, guarded by the revision. */
+    update(ns: string, patch: object, expectedRevision?: number): Promise<void>;
+}
+/** What one pass did. */
+export interface ApplyResult {
+    readonly kind: "applied" | "pending" | "unchanged" | "unavailable" | "readonly";
+    readonly namespace: string;
+    readonly changes: readonly Change[];
+    readonly skipped: readonly Skip[];
+}
+/** One pass's inputs. */
+export interface ApplyOptions {
+    /** The configurable namespace whose `providers` field is written. */
+    readonly namespace: string;
+    /** The route/model pairs to apply. */
+    readonly intents: readonly Intent[];
+    /** Plan only; report the pending changes without writing. */
+    readonly dryRun?: boolean;
+}
+/**
+ * Plan and, unless `dryRun`, write one namespace's declared reasoning efforts.
+ *
+ * @param seam - the settings service, or a fake with the same shape.
+ * @param options - the namespace, the intents, and whether to write.
+ * @returns what the pass did, with the changes and the skips.
+ * @throws Whatever `update()` rejected with, other than a revision conflict.
+ */
+export declare function applyIntents(seam: SettingsSeam, options: ApplyOptions): Promise<ApplyResult>;
+//# sourceMappingURL=apply.d.ts.map

package/lib/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAiB,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAE/E,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,IAAI,SAAS,kBAAkB,EAAE,CAAC;IAC1C,sEAAsE;IACtE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7E;AAED,yBAAyB;AACzB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;CACnC;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAaD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,WAAW,CAAC,CA6BtB"}

package/lib/apply.js

@@ -0,0 +1,67 @@
+/**
+ * Write a planned change through the Harness settings service.
+ *
+ * This is the only writer. It reads the namespace's descriptor, plans against
+ * the profile patch's own `providers` value, and calls `settings.update()` with
+ * the whole planned value and the revision `describe()` returned, so the Loader
+ * validates the candidate and reconciles the running `llm-pi-ai` adapter
+ * exactly as it does a Models-page save — `providers` is a `volatile` field, so
+ * the change is live without a restart. Nothing is written when the plan finds
+ * no change, and a revision conflict is retried once against a fresh read.
+ *
+ * @module @indexyz/dsh-custom-provider-reasoning-efforts/apply
+ */
+import { planProviders } from "./plan.js";
+/** Whether an error is the settings service's revision conflict. */
+function isConflict(error) {
+    if (error === null || typeof error !== "object")
+        return false;
+    if (Reflect.get(error, "name") === "SettingsConflictError")
+        return true;
+    return Reflect.get(error, "code") === "SETTINGS_CONFLICT";
+}
+function descriptorFor(seam, namespace) {
+    return seam.describe().find((entry) => entry.ns === namespace);
+}
+/**
+ * Plan and, unless `dryRun`, write one namespace's declared reasoning efforts.
+ *
+ * @param seam - the settings service, or a fake with the same shape.
+ * @param options - the namespace, the intents, and whether to write.
+ * @returns what the pass did, with the changes and the skips.
+ * @throws Whatever `update()` rejected with, other than a revision conflict.
+ */
+export async function applyIntents(seam, options) {
+    const namespace = options.namespace;
+    if (!seam.writable)
+        return { kind: "readonly", namespace, changes: [], skipped: [] };
+    let descriptor = descriptorFor(seam, namespace);
+    if (descriptor === undefined) {
+        return { kind: "unavailable", namespace, changes: [], skipped: [] };
+    }
+    let plan = planProviders(descriptor.user, options.intents);
+    if (plan.changes.length === 0) {
+        return { kind: "unchanged", namespace, changes: [], skipped: plan.skipped };
+    }
+    if (options.dryRun === true) {
+        return { kind: "pending", namespace, changes: plan.changes, skipped: plan.skipped };
+    }
+    try {
+        await seam.update(namespace, { providers: plan.providers }, descriptor.revision);
+    }
+    catch (error) {
+        if (!isConflict(error))
+            throw error;
+        descriptor = descriptorFor(seam, namespace);
+        if (descriptor === undefined) {
+            return { kind: "unavailable", namespace, changes: [], skipped: plan.skipped };
+        }
+        plan = planProviders(descriptor.user, options.intents);
+        if (plan.changes.length === 0) {
+            return { kind: "unchanged", namespace, changes: [], skipped: plan.skipped };
+        }
+        await seam.update(namespace, { providers: plan.providers }, descriptor.revision);
+    }
+    return { kind: "applied", namespace, changes: plan.changes, skipped: plan.skipped };
+}
+//# sourceMappingURL=apply.js.map

package/lib/apply.js.map

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

package/lib/declarations.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The declaration model this plugin supplies to a hand-written provider route.
+ *
+ * A route the installed pi-ai catalog does not ship has no catalog entry to
+ * inherit reasoning capability from, so every one of its models resolves to
+ * `reasoning: false` unless its `llm-pi-ai` profile entry carries
+ * `reasoningEfforts`. This module is that field's authoring vocabulary: a
+ * declaration names the pi-ai thinking levels a model offers and the wire
+ * spelling each level dispatches, or says `false` for a model that cannot
+ * reason at all.
+ *
+ * @module @indexyz/dsh-custom-provider-reasoning-efforts/declarations
+ */
+/** One level's wire spelling; `null` is legal for `off` only and means dispatch sends nothing. */
+export type EffortWire = string | null;
+/** The levels one model offers, keyed by pi-ai thinking level. */
+export type Efforts = Record<string, EffortWire>;
+/** One model's declaration: the levels it offers, or `false` for a model that cannot reason. */
+export type ModelDeclaration = false | Efforts;
+/** Declarations keyed by provider route and then by exact model id. */
+export type Declarations = Record<string, Record<string, ModelDeclaration>>;
+/** A rejected declaration, naming the route, model, and level at fault. */
+export declare class DeclarationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate one model's declaration.
+ *
+ * A declaration is rejected when it is empty, offers no level beyond `off`,
+ * carries `null` or an empty string on a level that is not `off`, or names a
+ * key that is not a pi-ai thinking level. Every rejection names the route, the
+ * model, and — where one is at fault — the level.
+ *
+ * @param route - provider route the declaration belongs to, for diagnostics.
+ * @param model - exact model id the declaration belongs to, for diagnostics.
+ * @param raw - the declaration as the row configuration carried it.
+ * @returns the validated declaration.
+ * @throws DeclarationError when the declaration cannot be served.
+ */
+export declare function validateModelDeclaration(route: string, model: string, raw: unknown): ModelDeclaration;
+/**
+ * Validate every declaration the row configuration carries, so a malformed
+ * table fails the plugin's load instead of a later write.
+ *
+ * @param raw - the `providers` table as the row configuration carried it.
+ * @returns the validated table.
+ * @throws DeclarationError naming the first declaration that cannot be served.
+ */
+export declare function validateDeclarations(raw: Declarations | undefined): Declarations;
+/**
+ * Render a declaration's levels for a human-readable answer.
+ *
+ * @param value - one validated declaration.
+ * @returns the levels in escalation order, or the non-reasoning marker.
+ */
+export declare function describeEfforts(value: ModelDeclaration): string;
+//# sourceMappingURL=declarations.d.ts.map

package/lib/declarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarations.d.ts","sourceRoot":"","sources":["../declarations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,kGAAkG;AAClG,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;AAEvC,kEAAkE;AAClE,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEjD,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,OAAO,CAAC;AAE/C,uEAAuE;AACvE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAE5E,2EAA2E;AAC3E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,OAAO,GACX,gBAAgB,CA6ClB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,CAoBhF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAI/D"}

package/lib/declarations.js

@@ -0,0 +1,114 @@
+/**
+ * The declaration model this plugin supplies to a hand-written provider route.
+ *
+ * A route the installed pi-ai catalog does not ship has no catalog entry to
+ * inherit reasoning capability from, so every one of its models resolves to
+ * `reasoning: false` unless its `llm-pi-ai` profile entry carries
+ * `reasoningEfforts`. This module is that field's authoring vocabulary: a
+ * declaration names the pi-ai thinking levels a model offers and the wire
+ * spelling each level dispatches, or says `false` for a model that cannot
+ * reason at all.
+ *
+ * @module @indexyz/dsh-custom-provider-reasoning-efforts/declarations
+ */
+import { THINKING_LEVELS, isThinkingLevel } from "./levels.js";
+/** A rejected declaration, naming the route, model, and level at fault. */
+export class DeclarationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeclarationError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate one model's declaration.
+ *
+ * A declaration is rejected when it is empty, offers no level beyond `off`,
+ * carries `null` or an empty string on a level that is not `off`, or names a
+ * key that is not a pi-ai thinking level. Every rejection names the route, the
+ * model, and — where one is at fault — the level.
+ *
+ * @param route - provider route the declaration belongs to, for diagnostics.
+ * @param model - exact model id the declaration belongs to, for diagnostics.
+ * @param raw - the declaration as the row configuration carried it.
+ * @returns the validated declaration.
+ * @throws DeclarationError when the declaration cannot be served.
+ */
+export function validateModelDeclaration(route, model, raw) {
+    const where = `route "${route}" model "${model}"`;
+    if (raw === false)
+        return false;
+    if (!isRecord(raw)) {
+        throw new DeclarationError(`${where}: a declaration must be a level table or false, got ${JSON.stringify(raw)}`);
+    }
+    const entries = Object.entries(raw);
+    if (entries.length === 0) {
+        throw new DeclarationError(`${where}: the declaration is empty; name the offered levels, or set it to false`);
+    }
+    const efforts = {};
+    let thinking = 0;
+    for (const [level, wire] of entries) {
+        if (!isThinkingLevel(level)) {
+            throw new DeclarationError(`${where}: "${level}" is not a pi-ai thinking level (${THINKING_LEVELS.join(", ")})`);
+        }
+        if (wire === null) {
+            if (level !== "off") {
+                throw new DeclarationError(`${where}: level "${level}" needs the wire value dispatch should send; only "off" may stay empty`);
+            }
+            efforts[level] = null;
+            continue;
+        }
+        if (typeof wire !== "string" || wire.length === 0) {
+            throw new DeclarationError(`${where}: level "${level}" must be a non-empty string or null, got ${JSON.stringify(wire)}`);
+        }
+        efforts[level] = wire;
+        if (level !== "off")
+            thinking += 1;
+    }
+    if (thinking === 0) {
+        throw new DeclarationError(`${where}: the declaration offers no level beyond "off"; name a thinking level, or set it to false`);
+    }
+    return efforts;
+}
+/**
+ * Validate every declaration the row configuration carries, so a malformed
+ * table fails the plugin's load instead of a later write.
+ *
+ * @param raw - the `providers` table as the row configuration carried it.
+ * @returns the validated table.
+ * @throws DeclarationError naming the first declaration that cannot be served.
+ */
+export function validateDeclarations(raw) {
+    const declarations = {};
+    for (const [route, models] of Object.entries(raw ?? {})) {
+        if (route.length === 0)
+            throw new DeclarationError("a declaration names an empty provider route");
+        const validated = {};
+        for (const [model, value] of Object.entries(models)) {
+            if (model.length === 0) {
+                throw new DeclarationError(`route "${route}" names an empty model id`);
+            }
+            validated[model] = validateModelDeclaration(route, model, value);
+        }
+        if (Object.keys(validated).length === 0) {
+            throw new DeclarationError(`route "${route}" declares no models; remove the empty entry, or name its models`);
+        }
+        declarations[route] = validated;
+    }
+    return declarations;
+}
+/**
+ * Render a declaration's levels for a human-readable answer.
+ *
+ * @param value - one validated declaration.
+ * @returns the levels in escalation order, or the non-reasoning marker.
+ */
+export function describeEfforts(value) {
+    if (value === false)
+        return "no reasoning";
+    const levels = THINKING_LEVELS.filter((level) => level in value);
+    return levels.length === 0 ? "no levels" : levels.join("/");
+}
+//# sourceMappingURL=declarations.js.map

package/lib/declarations.js.map

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