@dereekb/openrouter 14.7.0 → 14.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/openrouter",
-  "version": "14.7.0",
+  "version": "14.9.0",
   "sideEffects": false,
   "type": "module",
   "exports": {
@@ -19,19 +19,24 @@
       "types": "./index.d.ts",
       "import": "./index.esm.js",
       "default": "./index.esm.js"
+    },
+    "./decision": {
+      "types": "./decision.d.ts",
+      "import": "./decision.esm.js",
+      "default": "./decision.esm.js"
     }
   },
   "peerDependencies": {
-    "@dereekb/firebase": "14.7.0",
-    "@dereekb/firebase-server": "14.7.0",
-    "@dereekb/model": "14.7.0",
-    "@dereekb/util": "14.7.0",
+    "@dereekb/firebase": "14.9.0",
+    "@dereekb/firebase-server": "14.9.0",
+    "@dereekb/model": "14.9.0",
+    "@dereekb/util": "14.9.0",
     "@nestjs/common": "^12.0.1",
-    "@openrouter/sdk": "^1.3.0",
+    "@openrouter/sdk": "^1.3.8",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "14.7.0"
+    "@dereekb/nestjs": "14.9.0"
   },
   "module": "./index.esm.js",
   "main": "./index.esm.js",

package/src/decision.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@dereekb/openrouter/decision` — the System One (Jev) decision layer, loadable WITHOUT evaluating
+ * `@openrouter/sdk`.
+ *
+ * The root `@dereekb/openrouter` entry re-exports SDK values (`callModel`, `responsesSend`,
+ * `systemOneCreate`, …), so importing any value from it evaluates the SDK — a measurable cold-start cost
+ * that a test runner isolating each spec file pays once per file. This entry carries everything a decision
+ * is BUILT from and READ with, and nothing that sends one:
+ *
+ * - the declaration vocabulary — Choice / Score / Noul questions, answers, confidence bands, validation;
+ * - the request, the wire mapping (`openRouterDecisionRequestBody`), the reply reader
+ *   (`readOpenRouterDecisionAnswers`) and its faults, and the usage flattening;
+ * - the model config and the model ids, including the System One routing guard
+ *   (`isOpenRouterSystemOneModelId`).
+ *
+ * The transport, `openRouterDecision`, stays on the root entry because it is the one `systemOneCreate`
+ * caller. A consumer that owns its own transport pairs this entry with its own lazily-loaded client.
+ *
+ * Everything here is ALSO exported from the root entry, from the same modules — the two entries share one
+ * chunk, so a class such as `OpenRouterDecisionAnswerFaultError` has one identity whichever entry a value
+ * was imported through.
+ */
+export * from './lib/openrouter.config';
+export * from './lib/openrouter.decision';
+export * from './lib/openrouter.decision.question';
+export * from './lib/openrouter.type';

package/src/lib/index.d.ts

@@ -1,5 +1,8 @@
 export * from './openrouter.call';
 export * from './openrouter.config';
+export * from './openrouter.decision';
+export * from './openrouter.decision.call';
+export * from './openrouter.decision.question';
 export * from './openrouter.embedding';
 export * from './openrouter.generation';
 export * from './openrouter.input';

package/src/lib/openrouter.call.d.ts

@@ -2,7 +2,7 @@ import { type Maybe } from '@dereekb/util';
 import { type CallModelInput, type OpenResponsesResult, type OpenRouterCore, type RequestOptions, type StateAccessor, type Tool, ModelResult } from './openrouter.sdk';
 import { type OpenRouterHostedToolConfig, type OpenRouterModelConfig } from './openrouter.config';
 import { type OpenRouterPromptRequest } from './openrouter.request';
-import { type OpenRouterGenerationId, type OpenRouterRunError, type OpenRouterRunUsage } from './openrouter.type';
+import { type OpenRouterGenerationId, type OpenRouterModelId, type OpenRouterRunError, type OpenRouterRunUsage } from './openrouter.type';
 /**
  * A model config split into the part that goes on the request and the part that controls how the
  * request is executed.
@@ -106,14 +106,31 @@ export interface OpenRouterCallModelInputParams<TTools extends readonly Tool[] =
      */
     readonly state?: Maybe<StateAccessor<TTools>>;
 }
+/**
+ * Raised when a request naming a System One model is sent down the completion arm.
+ *
+ * Its own error type rather than a generic one because the fix is specific and mechanical — the call
+ * goes to `openRouterDecision` — and an error a reader can act on without opening the source is worth
+ * a named class.
+ */
+export declare class OpenRouterSystemOneModelOnCompletionArmError extends Error {
+    readonly model: OpenRouterModelId;
+    constructor(model: OpenRouterModelId);
+}
 /**
  * Converts a built request into the `/responses` request body.
  *
  * This is the whole wire body minus the SDK-only keys (`tools`/`state`/`stopWhen` on the `callModel`
  * path), so both dispatch paths assemble the request the same way and cannot drift.
  *
+ * It is also where a System One model is refused, because it is the ONE point every dispatch path
+ * converges on — `openRouterCallModelInput`, `sendOpenRouterResponsesRequest` and
+ * `openRouterModelResultForRequest` all build their body here — so no route to the completion arm can
+ * be added later that quietly skips the check.
+ *
  * @param request - The built request.
  * @returns The request body, in the SDK's camelCase request surface.
+ * @throws {OpenRouterSystemOneModelOnCompletionArmError} When the config names a System One model.
  */
 export declare function openRouterResponsesRequestBody(request: OpenRouterPromptRequest): Record<string, unknown>;
 /**

package/src/lib/openrouter.config.d.ts

@@ -289,6 +289,10 @@ export interface OpenRouterModelConfig {
 export declare function mergeOpenRouterModelConfig(configs: Maybe<OpenRouterModelConfig>[]): OpenRouterModelConfig;
 /**
  * Result of validating an {@link OpenRouterModelConfig}.
+ *
+ * Also the package's general validation shape — `validateOpenRouterDecisionQuestions` and
+ * `validateOpenRouterDecisionRequest` report through it too, so a caller publishing a prompt can gather
+ * config problems and question problems into one surface rather than branching on which produced them.
  */
 export interface OpenRouterModelConfigValidation {
     /**
@@ -304,11 +308,24 @@ export interface OpenRouterModelConfigValidation {
      */
     readonly warnings: string[];
 }
+/**
+ * Options for {@link validateOpenRouterModelConfig}.
+ */
+export interface ValidateOpenRouterModelConfigOptions {
+    /**
+     * Whether the config belongs to a DECISION rather than a completion.
+     *
+     * Only the model check differs, and it inverts: a decision requires a System One model and a
+     * completion refuses one. Defaults to false.
+     */
+    readonly decision?: Maybe<boolean>;
+}
 /**
  * Validates a merged model config, catching the misconfigurations that fail silently at runtime
  * rather than loudly.
  *
  * @param config - The merged config to check.
+ * @param options - Which arm the config is for.
  * @returns The validation result.
  */
-export declare function validateOpenRouterModelConfig(config: Maybe<OpenRouterModelConfig>): OpenRouterModelConfigValidation;
+export declare function validateOpenRouterModelConfig(config: Maybe<OpenRouterModelConfig>, options?: Maybe<ValidateOpenRouterModelConfigOptions>): OpenRouterModelConfigValidation;

package/src/lib/openrouter.decision.call.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The TRANSPORT half of the decision layer: {@link openRouterDecision}, the one caller of the SDK's
+ * `systemOneCreate`.
+ *
+ * Kept apart from `openrouter.decision.ts` (declaring, validating, the wire mapping, reading a reply) so
+ * that everything a decision is built from can be loaded without evaluating `@openrouter/sdk` — see the
+ * `@dereekb/openrouter/decision` entry. A caller that owns its own transport (its own timeout, retry
+ * policy or error shape) builds the body with `openRouterDecisionRequestBody` and reads the reply with
+ * `readOpenRouterDecisionAnswers`, and never needs this file.
+ */
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterDecisionRequest } from './openrouter.decision';
+import { type OpenRouterDecisionAnswers, type OpenRouterDecisionQuestions } from './openrouter.decision.question';
+import { type DecisionsResponse, type OpenRouterCore, type RequestOptions } from './openrouter.sdk';
+import { type OpenRouterGenerationId, type OpenRouterModelId, type OpenRouterRunUsage } from './openrouter.type';
+/**
+ * A normalized result of one decision.
+ *
+ * Field names deliberately match `OpenRouterCallResult` wherever the two have the same meaning, so a
+ * caller reading `model` / `generationIds` / `usage` does not have to learn a second vocabulary for the
+ * second arm. There is no `outputText` or `error`: a decision has no prose output, and the route reports
+ * a failure as a thrown transport error rather than as a field on a 200.
+ */
+export interface OpenRouterDecisionResult<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions> {
+    /**
+     * The answers, membership-checked against the declared questions.
+     */
+    readonly answers: OpenRouterDecisionAnswers<Q>;
+    /**
+     * The model that actually served the decision — a VERSIONED slug even when an alias was asked for,
+     * which is what makes an answer reproducible.
+     */
+    readonly model?: Maybe<OpenRouterModelId>;
+    /**
+     * The provider that served it.
+     */
+    readonly provider?: Maybe<string>;
+    /**
+     * Generation ids produced, for auditing. At most one on this route.
+     */
+    readonly generationIds: OpenRouterGenerationId[];
+    /**
+     * Token/cost usage.
+     */
+    readonly usage?: Maybe<OpenRouterRunUsage>;
+    /**
+     * The raw response, for anything the normalized shape drops.
+     */
+    readonly response: DecisionsResponse;
+}
+/**
+ * Params for {@link openRouterDecision}.
+ */
+export interface OpenRouterDecisionParams<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions> {
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * The built request.
+     */
+    readonly request: OpenRouterDecisionRequest<Q>;
+    /**
+     * Additional request options, merged under the config's `requestTimeoutMs`.
+     */
+    readonly options?: Maybe<RequestOptions>;
+}
+/**
+ * Asks a decision and returns its answers.
+ *
+ * The request is validated first, so a model that cannot serve a decision is refused HERE rather than by
+ * the route — the mirror of the refusal `callModelForOpenRouterRequest` makes for a System One model on
+ * the completion arm. Which surface a request belongs to is a property of the request, not a choice the
+ * caller makes at the call site.
+ *
+ * @param params - The client, request, and options.
+ * @returns The normalized decision result.
+ * @throws {OpenRouterDecisionDeclarationError} When the request cannot be asked as declared.
+ * @throws {OpenRouterDecisionAnswerFaultError} When the reply did not answer the declared questions.
+ */
+export declare function openRouterDecision<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions>(params: OpenRouterDecisionParams<Q>): Promise<OpenRouterDecisionResult<Q>>;

package/src/lib/openrouter.decision.d.ts

@@ -0,0 +1,286 @@
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterModelConfig, type OpenRouterModelConfigValidation } from './openrouter.config';
+import { type OpenRouterDecisionAnswer, type OpenRouterDecisionAnswers, type OpenRouterDecisionEntry, type OpenRouterDecisionQuestion, type OpenRouterDecisionQuestionId, type OpenRouterDecisionQuestions, type OpenRouterDecisionState } from './openrouter.decision.question';
+import { type OpenRouterResolvedPrompt } from './openrouter.prompt';
+import { type OpenRouterRequestTrace } from './openrouter.request';
+import type { DecisionsRequest, DecisionsResponse } from './openrouter.sdk';
+import { type OpenRouterRunUsage } from './openrouter.type';
+/**
+ * How far a distribution's probabilities may sum from 1 before the reply is read as malformed.
+ *
+ * Wide enough to absorb the float rounding a JSON round-trip introduces, narrow enough that a
+ * distribution missing an option does not pass.
+ */
+export declare const OPENROUTER_DECISION_DISTRIBUTION_SUM_TOLERANCE = 0.05;
+/**
+ * A caller-chosen id grouping related decisions for observability.
+ *
+ * Never sent to the provider — it exists for broadcast grouping and private logging only.
+ */
+export type OpenRouterDecisionSessionId = string;
+/**
+ * A decision request: the config naming the model, the state to judge, and the questions to ask of it.
+ *
+ * The decisions analogue of `OpenRouterPromptRequest`, and deliberately a separate type rather than a
+ * mode on it. The two share no content at all — one carries messages and an output contract, the other
+ * carries a state and an answer space — so folding them together would produce a type where half the
+ * fields are meaningless on any given request.
+ */
+export interface OpenRouterDecisionRequest<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions> {
+    /**
+     * The merged model config. Only `model`, `provider` and `user` reach the wire — see
+     * {@link splitOpenRouterDecisionModelConfig}.
+     */
+    readonly config: OpenRouterModelConfig;
+    /**
+     * The content to judge.
+     */
+    readonly state: OpenRouterDecisionState;
+    /**
+     * The declared questions.
+     */
+    readonly questions: Q;
+    /**
+     * Observability grouping id.
+     */
+    readonly sessionId?: Maybe<OpenRouterDecisionSessionId>;
+    /**
+     * Trace metadata, carried exactly as it is on a completion request.
+     */
+    readonly trace?: Maybe<OpenRouterRequestTrace>;
+}
+/**
+ * Params for {@link openRouterDecisionRequest}.
+ */
+export interface OpenRouterDecisionRequestParams<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions> {
+    /**
+     * The resolved prompt version supplying the base config and any STORED questions.
+     */
+    readonly prompt?: Maybe<OpenRouterResolvedPrompt>;
+    /**
+     * The content to judge.
+     */
+    readonly state: OpenRouterDecisionState;
+    /**
+     * Questions declared by the caller for THIS call, merged over the prompt's stored questions by id.
+     *
+     * Dynamic questions are the normal case for a decision whose answer space is derived from data the
+     * caller holds — a shortlist of rows, a set of candidates — which cannot be written down in advance.
+     */
+    readonly questions?: Maybe<Q>;
+    /**
+     * Per-call config overrides, applied on top of the prompt's config.
+     */
+    readonly overrides?: Maybe<OpenRouterModelConfig>;
+    /**
+     * Observability grouping id.
+     */
+    readonly sessionId?: Maybe<OpenRouterDecisionSessionId>;
+    /**
+     * Trace metadata.
+     */
+    readonly trace?: Maybe<OpenRouterRequestTrace>;
+}
+/**
+ * Raised when a decision cannot be asked as declared.
+ *
+ * Every declaration problem fails HERE — before a request is built, naming the question — rather than as
+ * a 4xx about a request body. The distinction matters because the fixes are different: a malformed
+ * declaration is a code or authoring bug, while a 4xx is an operational one.
+ */
+export declare class OpenRouterDecisionDeclarationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Builds a decision request from an optional resolved prompt plus the caller's state and questions.
+ *
+ * Stored questions and caller questions are merged BY ID with the caller winning, the same composition
+ * a prompt's static seed messages and dynamic `input` already use. What differs is the reason: there is
+ * no prompt cache on this route, so the merge is about where a question is authored — a fixed taxonomy
+ * belongs in a version an operator can edit, a per-call candidate set can only come from code.
+ *
+ * @param params - The prompt, state, questions, overrides, session id, and trace.
+ * @returns The built request.
+ * @throws {OpenRouterDecisionDeclarationError} When the merged question map cannot be asked.
+ */
+export declare function openRouterDecisionRequest<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions>(params: OpenRouterDecisionRequestParams<Q>): OpenRouterDecisionRequest<Q>;
+/**
+ * The parts of an {@link OpenRouterModelConfig} that reach a decisions request, and the parts that
+ * cannot.
+ */
+export interface OpenRouterSplitDecisionModelConfig {
+    /**
+     * The parameters the decisions route accepts.
+     */
+    readonly requestConfig: Pick<OpenRouterModelConfig, 'model' | 'provider' | 'user'>;
+    /**
+     * Per-request wall-clock timeout, when the config set one.
+     */
+    readonly requestTimeoutMs?: Maybe<number>;
+    /**
+     * Names of the config keys the decisions route has no equivalent for, in the order declared.
+     */
+    readonly dropped: string[];
+}
+/**
+ * Splits a model config into the parameters a decisions request accepts and the ones it does not.
+ *
+ * The decisions route takes only `model`, `provider` and `user`. Everything else on
+ * {@link OpenRouterModelConfig} describes a completion — an output format, a reasoning budget, a tool
+ * set, a temperature — and none of it has a meaning here: a decision has no free-form output to shape
+ * and no tools to call. Those keys are reported in `dropped` rather than quietly discarded, because a
+ * `temperature` a caller believes is in effect is exactly the kind of thing that is only noticed when
+ * an answer is already wrong.
+ *
+ * `models` (the fallback chain) is dropped for a sharper reason: the decisions route takes a single
+ * `model`, so a chain authored here does not degrade to its first entry — it simply does not exist.
+ *
+ * @param config - The merged model config.
+ * @returns The split config.
+ */
+export declare function splitOpenRouterDecisionModelConfig(config: Maybe<OpenRouterModelConfig>): OpenRouterSplitDecisionModelConfig;
+/**
+ * Validates a decision request before it is sent.
+ *
+ * The mirror of `validateOpenRouterModelConfig` for this arm, and the reason both exist: the model slug
+ * is the ONLY thing that says which of OpenRouter's two inference surfaces a request belongs to, so it
+ * is checked on both, and neither arm can be entered with a model the other one owns.
+ *
+ * @param request - The request to check.
+ * @returns The validation result.
+ */
+export declare function validateOpenRouterDecisionRequest(request: Maybe<OpenRouterDecisionRequest>): OpenRouterModelConfigValidation;
+/**
+ * One declared question in the shape the wire carries it.
+ *
+ * All three primitives collapse onto a single `criteria` key, which is why this mapping exists at all:
+ * the declaration types name what each primitive's criteria MEAN (`options`, `levels`, `means`), and the
+ * wire does not.
+ */
+export type OpenRouterDecisionWireQuestion = {
+    readonly type: 'choice';
+    readonly instructions: OpenRouterDecisionEntry;
+    readonly criteria: Readonly<Record<string, Maybe<OpenRouterDecisionEntry>>>;
+} | {
+    readonly type: 'score';
+    readonly instructions: OpenRouterDecisionEntry;
+    readonly criteria: readonly OpenRouterDecisionEntry[];
+} | {
+    readonly type: 'noul';
+    readonly instructions: OpenRouterDecisionEntry;
+    readonly criteria?: {
+        readonly true: OpenRouterDecisionEntry;
+        readonly false: OpenRouterDecisionEntry;
+    };
+};
+/**
+ * Converts one declared question to its wire shape.
+ *
+ * A pure rename. Three details carry meaning and are not incidental:
+ *
+ * - an option with no description becomes an explicit `null`, which is how the wire spells "undescribed
+ *   option" — omitting the key would instead remove the option from the answer space;
+ * - a Noul with no `means` omits `criteria` ENTIRELY rather than sending an empty object;
+ * - a structured entry is passed through by IDENTITY, never copied or re-serialized, because the wire
+ *   carries declaration guidance verbatim and a normalising round-trip is exactly the kind of silent
+ *   edit this mapping must not make.
+ *
+ * @param question - The declared question.
+ * @returns The wire question.
+ */
+export declare function openRouterDecisionWireQuestion(question: OpenRouterDecisionQuestion): OpenRouterDecisionWireQuestion;
+/**
+ * Converts a built request into the `/systemone` request body.
+ *
+ * @param request - The built request.
+ * @returns The request body, in the SDK's request surface.
+ */
+export declare function openRouterDecisionRequestBody(request: OpenRouterDecisionRequest): DecisionsRequest;
+/**
+ * What is wrong with one answer in a reply.
+ */
+export type OpenRouterDecisionFaultKind = 'answer-missing' | 'answer-mistyped' | 'choice-off-option' | 'value-out-of-range';
+/**
+ * One thing wrong with a reply.
+ */
+export interface OpenRouterDecisionFault {
+    readonly kind: OpenRouterDecisionFaultKind;
+    readonly question: OpenRouterDecisionQuestionId;
+    readonly detail: string;
+}
+/**
+ * Raised when a reply did not answer the questions that were declared.
+ *
+ * This is always a defect in the RESPONSE and never a judgement the model made. "None of these fits" is
+ * not a fault — it is said through a Noul the caller declared for it, and arrives as an ANSWER. A caller
+ * that catches this is handling a malformed reply, not a negative one.
+ */
+export declare class OpenRouterDecisionAnswerFaultError extends Error {
+    readonly faults: OpenRouterDecisionFault[];
+    constructor(faults: OpenRouterDecisionFault[]);
+}
+/**
+ * Config for {@link readOpenRouterDecisionAnswers}.
+ */
+export interface ReadOpenRouterDecisionAnswersConfig<Q extends OpenRouterDecisionQuestions> {
+    /**
+     * The questions that were declared.
+     */
+    readonly questions: Q;
+    /**
+     * The answers as returned.
+     */
+    readonly raw: Readonly<Record<string, Maybe<OpenRouterDecisionAnswer>>>;
+}
+/**
+ * Either the answers, or everything wrong with them.
+ */
+export type OpenRouterDecisionAnswersRead<Q extends OpenRouterDecisionQuestions> = {
+    readonly answers: OpenRouterDecisionAnswers<Q>;
+    readonly faults?: undefined;
+} | {
+    readonly answers?: undefined;
+    readonly faults: OpenRouterDecisionFault[];
+};
+/**
+ * Membership-checks a reply against the questions that were declared.
+ *
+ * This is the transport's GUARANTEE, and the reason no consumer re-checks: past this point a `choice` is
+ * one of the declared options, a `score` is inside the declared range, and a `noul` is a probability. It
+ * is what a decision has instead of the parse-and-salvage a completion needs — the answer space was
+ * declared, so an answer either sits inside it or the reply is broken.
+ *
+ * Every fault is collected rather than the first, because a reply that lost one answer has usually lost
+ * more than one and reporting them one round-trip at a time is no way to debug a declaration.
+ *
+ * An ABSENT distribution or confidence is checked for nothing: only `choice` / `score` / `noul` are
+ * guaranteed on the wire, so their absence is a real reply.
+ *
+ * @param config - The declared questions and the raw answers.
+ * @returns The answers, or the faults.
+ */
+export declare function readOpenRouterDecisionAnswers<Q extends OpenRouterDecisionQuestions>(config: ReadOpenRouterDecisionAnswersConfig<Q>): OpenRouterDecisionAnswersRead<Q>;
+/**
+ * Flattens a decisions reply's usage into the package's usage shape.
+ *
+ * Reported through the SAME {@link OpenRouterRunUsage} a completion reports, so the cost ledger needs no
+ * second counting site and a run's spend is readable without knowing which arm served it.
+ *
+ * Two things about this route's numbers, both measured rather than assumed:
+ *
+ * - `outputTokens` is REPORTED and non-zero, but it is not billed. `cost` is input alone at the model's
+ *   input rate — verified live at 350 input tokens and $0.042/Mtok giving exactly $0.0000147, with 34
+ *   output tokens on the same reply. So a cost-per-token derived from `totalTokens` here is wrong.
+ * - `cost` is FINAL when it arrives. A completion's is settled server-side afterwards and refined by the
+ *   broadcast webhook; a decision's is synchronous, which is why a decision run needs no reconciliation.
+ *
+ * A measurement the reply did not report is OMITTED rather than carried as `undefined`, because a spread
+ * `cost: undefined` reads downstream as "cost zero" rather than "cost unknown".
+ *
+ * @param usage - The usage as returned.
+ * @returns The flattened usage.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterRunUsageFromDecisionsUsage(usage: Maybe<DecisionsResponse['usage']>): Maybe<OpenRouterRunUsage>;