@dereekb/openrouter 14.6.0 → 14.8.0

package/firebase-server/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@dereekb/openrouter/firebase-server",
-  "version": "14.6.0",
+  "version": "14.8.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.6.0",
-    "@dereekb/date": "14.6.0",
-    "@dereekb/firebase": "14.6.0",
-    "@dereekb/firebase-server": "14.6.0",
-    "@dereekb/model": "14.6.0",
-    "@dereekb/nestjs": "14.6.0",
-    "@dereekb/openrouter": "14.6.0",
-    "@dereekb/rxjs": "14.6.0",
-    "@dereekb/util": "14.6.0",
+    "@dereekb/analytics": "14.8.0",
+    "@dereekb/date": "14.8.0",
+    "@dereekb/firebase": "14.8.0",
+    "@dereekb/firebase-server": "14.8.0",
+    "@dereekb/model": "14.8.0",
+    "@dereekb/nestjs": "14.8.0",
+    "@dereekb/openrouter": "14.8.0",
+    "@dereekb/rxjs": "14.8.0",
+    "@dereekb/util": "14.8.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
-    "@openrouter/sdk": "^1.2.26",
+    "@openrouter/sdk": "^1.3.8",
     "arktype": "^2.2.0",
     "date-fns": "^4.1.0",
     "express": "^5.2.1",
@@ -23,7 +23,7 @@
     "make-error": "^1.3.6"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/nestjs": "14.8.0",
     "@nestjs/testing": "^12.0.1"
   },
   "exports": {

package/firebase-server/src/lib/openrouter.call.inline.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type OpenRouterAttachedFileReference, type OpenRouterCallResult, type OpenRouterCore, type OpenRouterInput, type OpenRouterModelConfig, type OpenRouterPromptKey, type OpenRouterPromptVersionNumber, type Tool } from '@dereekb/openrouter';
+import { type OpenRouterAttachedFileReference, type OpenRouterCallResult, type OpenRouterCore, type OpenRouterDecisionQuestions, type OpenRouterDecisionResult, type OpenRouterDecisionState, type OpenRouterInput, type OpenRouterModelConfig, type OpenRouterPromptKey, type OpenRouterPromptVersionNumber, type Tool } from '@dereekb/openrouter';
 import { type OpenRouterPromptService } from './openrouter.prompt.service';
 /**
  * Params for {@link callModelForPrompt}.
@@ -55,3 +55,60 @@ export interface CallModelForPromptParams {
  * @returns The normalized call result.
  */
 export declare function callModelForPrompt(params: CallModelForPromptParams): Promise<OpenRouterCallResult>;
+/**
+ * Params for {@link decideForPrompt}.
+ */
+export interface DecideForPromptParams {
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * The prompt service used to resolve the version.
+     */
+    readonly promptService: OpenRouterPromptService;
+    /**
+     * The decision prompt to ask.
+     */
+    readonly promptKey: OpenRouterPromptKey;
+    /**
+     * Version to pin. Omit to use the prompt's active version.
+     */
+    readonly version?: Maybe<OpenRouterPromptVersionNumber>;
+    /**
+     * The content to judge.
+     */
+    readonly state: OpenRouterDecisionState;
+    /**
+     * Questions declared for THIS call, merged over the version's stored questions by id.
+     */
+    readonly questions?: Maybe<OpenRouterDecisionQuestions>;
+    /**
+     * Per-call config overrides.
+     */
+    readonly configOverrides?: Maybe<OpenRouterModelConfig>;
+    /**
+     * Observability grouping id.
+     */
+    readonly sessionId?: Maybe<string>;
+    /**
+     * Trace metadata for cost/usage reconciliation.
+     */
+    readonly trace?: Maybe<Record<string, unknown>>;
+}
+/**
+ * Asks a decision prompt INLINE and returns its answers, with no run task document.
+ *
+ * The default way to ask a decision. A System One call typically answers in around a hundred
+ * milliseconds, has no tools to loop and nothing to defer, so the queue's lease, sweep interval and
+ * retry ladder buy nothing on the happy path — paying for a document to run a call that finishes before
+ * the write does is pure overhead.
+ *
+ * Reach for `enqueueRunTask({ state, questions, immediate: true })` instead when a FAILURE needs to
+ * survive this process: that keeps the same run-it-now latency and leaves a retryable failure queued for
+ * the sweep, at the cost of one document per run.
+ *
+ * @param params - The client, prompt service, prompt, state, and questions.
+ * @returns The decision result.
+ */
+export declare function decideForPrompt(params: DecideForPromptParams): Promise<OpenRouterDecisionResult>;

package/firebase-server/src/lib/openrouter.runtask.handle.d.ts

@@ -1,5 +1,31 @@
 import { type Maybe } from '@dereekb/util';
+import { type OpenRouterDecisionAnswers, type OpenRouterDecisionQuestions } from '@dereekb/openrouter';
 import { type OpenRouterRunTask } from '@dereekb/openrouter/firebase';
+/**
+ * Whether a run task is a DECISION run.
+ *
+ * Reads the state field, which is the discriminator — see `OpenRouterRunTask.st`.
+ *
+ * @param task - The run task.
+ * @returns True when the task asks a decision rather than a completion.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isOpenRouterDecisionRunTask(task: Maybe<OpenRouterRunTask>): boolean;
+/**
+ * Reads the answers off a completed decision run.
+ *
+ * The type parameter is the caller's own question map, which is what lets a consumer read
+ * `answers.urgency.noul` rather than walking an untyped record. It is an ASSERTION, not a check: the
+ * answers were membership-checked against the declared questions when they were written, so the only
+ * way this lies is a caller naming a different question map than the run used.
+ *
+ * @param task - The run task.
+ * @returns The answers, or undefined when the run is not a completed decision.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterRunTaskDecisionAnswers<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions>(task: Maybe<OpenRouterRunTask>): Maybe<OpenRouterDecisionAnswers<Q>>;
 /**
  * How a caller should proceed given a run task's current state.
  *

package/firebase-server/src/lib/openrouter.runtask.service.d.ts

@@ -1,7 +1,7 @@
 import { type FirebaseStorageContext } from '@dereekb/firebase';
 import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
 import { type Maybe, type Milliseconds } from '@dereekb/util';
-import { type OpenRouterAttachedFileReference, type OpenRouterCallResult, type OpenRouterCore, type OpenRouterDeferredToolResolution, type OpenRouterFileReference, type OpenRouterInput, type OpenRouterModelConfig, type OpenRouterPromptKey, type OpenRouterPromptVersionNumber, type OpenRouterRunTaskKey, type Tool } from '@dereekb/openrouter';
+import { type OpenRouterAttachedFileReference, type OpenRouterCallResult, type OpenRouterCore, type OpenRouterDecisionQuestions, type OpenRouterDecisionResult, type OpenRouterDeferredToolResolution, type OpenRouterFileReference, type OpenRouterInput, type OpenRouterModelConfig, type OpenRouterPromptKey, type OpenRouterPromptVersionNumber, type OpenRouterRunTaskKey, type OpenRouterStorableDecisionState, type Tool } from '@dereekb/openrouter';
 import { type OpenRouterRunTask, type OpenRouterRunTaskDocument, type OpenRouterRunTaskFirestoreCollections, type OpenRouterRunTaskPendingToolCall, OpenRouterRunTaskState, type OpenRouterRunTaskUnsentToolResult } from '@dereekb/openrouter/firebase';
 import { type OpenRouterFileAttachmentMode } from './openrouter.file.attachment';
 import { type OpenRouterPromptService } from './openrouter.prompt.service';
@@ -69,6 +69,30 @@ export interface OpenRouterEnqueueRunTaskParams {
      * that is already in flight or already finished.
      */
     readonly restart?: Maybe<boolean>;
+    /**
+     * The content to judge, making this a DECISION run.
+     *
+     * Presence of this is what sends the run to `POST /systemone` instead of `/responses`, and it is the
+     * only discriminator: which surface a request needs is a property of the request, and a second field
+     * declaring it is a second thing that can disagree.
+     */
+    readonly state?: Maybe<OpenRouterStorableDecisionState>;
+    /**
+     * Questions declared for THIS run, merged over the prompt version's own stored questions.
+     */
+    readonly questions?: Maybe<OpenRouterDecisionQuestions>;
+    /**
+     * Whether to run the task immediately rather than leaving it for the next sweep.
+     *
+     * The document is written either way, so a consumer's `readRunTask(key)` contract does not change
+     * shape depending on whether the inline attempt happened to succeed — which is the whole reason this
+     * is a flag on the queue rather than a separate inline call. What it buys is the queue's durability
+     * without the queue's latency: the common case answers within this call, and a run that fails
+     * RETRYABLY (OpenRouter down, a 429, a dropped connection) is left QUEUED for the sweep to pick up. A
+     * deterministic failure still reaches FAILED on the first attempt, because three sweep ticks would
+     * only reach the same answer more slowly.
+     */
+    readonly immediate?: Maybe<boolean>;
 }
 /**
  * Result of enqueueing a run task.
@@ -81,6 +105,14 @@ export interface OpenRouterEnqueueRunTaskResult {
      */
     readonly created: boolean;
     readonly task: OpenRouterRunTask;
+    /**
+     * What the immediate attempt did, when one was asked for and actually ran.
+     *
+     * Absent when `immediate` was not set, and also when it was but the task was not claimable — an
+     * already-running or already-finished run reached through an idempotent re-enqueue. A caller reads the
+     * document rather than assuming this is present.
+     */
+    readonly execution?: Maybe<OpenRouterRunTaskExecutionResult>;
 }
 /**
  * Params for claiming run tasks.
@@ -169,6 +201,10 @@ export interface OpenRouterRunTaskExecutionResult {
     readonly key: OpenRouterRunTaskKey;
     readonly state: OpenRouterRunTaskState;
     readonly result?: Maybe<OpenRouterCallResult>;
+    /**
+     * What a DECISION run produced. Present instead of `result`, never alongside it.
+     */
+    readonly decision?: Maybe<OpenRouterDecisionResult>;
     readonly error?: Maybe<unknown>;
 }
 /**

package/firebase-server/src/test/openrouter.fake.d.ts

@@ -19,6 +19,20 @@ export interface FakeOpenRouterToolCall {
     readonly name: string;
     readonly arguments?: Maybe<Record<string, unknown>>;
 }
+/**
+ * What the fake System One model should answer with, when the request went to `/systemone`.
+ */
+export interface FakeOpenRouterDecisionReply {
+    /**
+     * The answers, keyed by question id, in the WIRE shape (`{ type, noul }`, `{ type, choice }`, …).
+     *
+     * Deliberately untyped: a fixture has to be able to produce replies the declaration types forbid,
+     * which is the only way the membership check gets exercised at all.
+     */
+    readonly answers?: Maybe<Record<string, unknown>>;
+    readonly inputTokens?: Maybe<number>;
+    readonly outputTokens?: Maybe<number>;
+}
 /**
  * What the fake model should answer with on one turn.
  */
@@ -49,6 +63,14 @@ export interface FakeOpenRouterReply {
      * Thrown instead of answered, for the transport-failure path.
      */
     readonly throws?: Maybe<Error>;
+    /**
+     * An HTTP status to answer with instead of a success, for the retryable-vs-permanent classification.
+     */
+    readonly status?: Maybe<number>;
+    /**
+     * What to answer a DECISION request with. Ignored on a request that went to `/responses`.
+     */
+    readonly decision?: Maybe<FakeOpenRouterDecisionReply>;
 }
 /**
  * Decides the reply for one request. Receives the request body exactly as it went on the wire.
@@ -63,8 +85,31 @@ export interface FakeOpenRouterClient {
      * Every request body sent, in order, serialized exactly as OpenRouter would have received it.
      */
     readonly requests: Record<string, unknown>[];
+    /**
+     * Every request URL sent, in order, positionally matching {@link FakeOpenRouterClient.requests}.
+     *
+     * Recorded because the body alone cannot tell a completion from a decision, and because a fake that
+     * never looks at the URL stays green no matter which route the SDK resolves — which is how this
+     * vendor's decisions endpoint was once shipped 404ing on every live call with a fully green suite.
+     */
+    readonly urls: string[];
     readonly callCount: number;
 }
+/**
+ * The path a System One (decisions) request goes to.
+ */
+export declare const FAKE_OPENROUTER_SYSTEM_ONE_PATH = "/systemone";
+/**
+ * Builds a `DecisionsResponse` JSON body in the WIRE shape the SDK's inbound schema parses.
+ *
+ * Note the snake_case token counts: the SDK decodes those to camelCase, so a fake emitting the decoded
+ * names would hide the rename the usage mapper reads through.
+ *
+ * @param reply - What the fake System One model should answer with.
+ * @param index - The call ordinal, used to make a distinct generation id.
+ * @returns The response body.
+ */
+export declare function fakeOpenRouterDecisionResponseBody(reply: Maybe<FakeOpenRouterDecisionReply>, index: number): Record<string, unknown>;
 /**
  * Builds an `OpenResponsesResult` JSON body in the wire (snake_case) shape the SDK's inbound schema
  * parses.