@dereekb/openrouter 13.37.0

package/firebase-server/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dereekb/openrouter/firebase-server",
+  "version": "13.37.0",
+  "peerDependencies": {
+    "@dereekb/analytics": "13.37.0",
+    "@dereekb/date": "13.37.0",
+    "@dereekb/firebase": "13.37.0",
+    "@dereekb/firebase-server": "13.37.0",
+    "@dereekb/model": "13.37.0",
+    "@dereekb/nestjs": "13.37.0",
+    "@dereekb/openrouter": "13.37.0",
+    "@dereekb/rxjs": "13.37.0",
+    "@dereekb/util": "13.37.0",
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/config": "^4.0.4",
+    "@openrouter/sdk": "^1.2.26",
+    "arktype": "^2.2.0",
+    "date-fns": "^4.1.0",
+    "express": "^5.2.1",
+    "firebase-functions": "^7.2.5",
+    "make-error": "^1.3.6"
+  },
+  "devDependencies": {
+    "@nestjs/testing": "^11.1.19"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/firebase-server/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/firebase-server/src/lib/index.d.ts

@@ -0,0 +1,10 @@
+export * from './openrouter.action.server';
+export * from './openrouter.broadcast';
+export * from './openrouter.call.inline';
+export * from './openrouter.file.attachment';
+export * from './openrouter.module';
+export * from './openrouter.prompt.service';
+export * from './openrouter.runtask.handle';
+export * from './openrouter.runtask.service';
+export * from './openrouter.runtask.sweep';
+export * from './openrouter.state.accessor';

package/firebase-server/src/lib/openrouter.action.server.d.ts

@@ -0,0 +1,196 @@
+import { type FirebaseServerActionsContext } from '@dereekb/firebase-server';
+import { type FirestoreContextReference } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterPromptKey } from '@dereekb/openrouter';
+import { type CreateOpenRouterPromptVersionParams, type CreateOpenRouterPromptVersionResult, type OpenRouterPromptDocument, type OpenRouterPromptFirestoreCollections, type OpenRouterPromptVersionDocument, type UpdateOpenRouterPromptParams, type UpdateOpenRouterPromptVersionParams, type UpdateOpenRouterPromptVersionResult } from '@dereekb/openrouter/firebase';
+import { type OpenRouterPromptService } from './openrouter.prompt.service';
+/**
+ * Context required by the OpenRouter prompt server actions.
+ */
+export interface OpenRouterPromptServerActionsContext extends FirebaseServerActionsContext, OpenRouterPromptFirestoreCollections, FirestoreContextReference {
+    /**
+     * The prompt service, so a publish or promote can drop its cached resolution immediately instead of
+     * leaving the change invisible for the cache window.
+     */
+    readonly openRouterPromptService: OpenRouterPromptService;
+}
+/**
+ * Parameters for {@link OpenRouterPromptServerActions.createOpenRouterPrompt}.
+ *
+ * Server-side only, and deliberately not part of the model API: a prompt comes into existence from a
+ * seed run against an {@link OpenRouterPromptDefinition} the code already carries, so there is no
+ * external caller whose input needs validating.
+ */
+export interface CreateOpenRouterPromptParams {
+    /**
+     * The prompt key, used as the document id. Lowercase, dash-separated by convention.
+     */
+    readonly key: OpenRouterPromptKey;
+    /**
+     * Human-readable name.
+     */
+    readonly name: string;
+    /**
+     * What the prompt is for.
+     */
+    readonly description?: Maybe<string>;
+    /**
+     * Grouping tags.
+     */
+    readonly tags?: Maybe<string[]>;
+}
+/**
+ * Parameters for {@link OpenRouterPromptServerActions.seedOpenRouterPrompts}.
+ *
+ * Server-side only, and deliberately not part of the model API, for the same reason
+ * {@link CreateOpenRouterPromptParams} is not: the only input is a filter over keys the code itself
+ * declares, and every caller is server-side. Seeding is also not CRUD on `openRouterPrompt` — exposing
+ * it over callModel would hand any admin a button that rewrites prompt pointers.
+ */
+export interface SeedOpenRouterPromptsParams {
+    /**
+     * Restrict the run to these keys. Omit to seed every definition the prompt service carries.
+     */
+    readonly promptKeys?: Maybe<OpenRouterPromptKey[]>;
+}
+/**
+ * Result of {@link OpenRouterPromptServerActions.seedOpenRouterPrompts}.
+ *
+ * The counts partition the run: `considered === versionsPublished + upToDate + skipped`.
+ */
+export interface SeedOpenRouterPromptsResult {
+    /**
+     * Definitions looked at, after filtering.
+     */
+    readonly considered: number;
+    /**
+     * Prompt documents created. Always `<= versionsPublished`, since creating one always publishes its
+     * declared version too.
+     */
+    readonly promptsCreated: number;
+    /**
+     * Versions written at their declared number.
+     */
+    readonly versionsPublished: number;
+    /**
+     * Definitions whose declared number the store already carried — the steady state, so a scheduled
+     * reseed reports every definition here once it has converged.
+     */
+    readonly upToDate: number;
+    /**
+     * The only drift alarm: a definition the seed refused to write. Either the store advanced past it,
+     * something else already wrote the number it declares, or the prompt is ARCHIVED. Recovery is to bump
+     * the definition's version, which works precisely because the seed pins rather than allocates.
+     */
+    readonly skipped: number;
+    /**
+     * Config warnings raised while validating the definitions, each prefixed with its prompt key.
+     */
+    readonly warnings: string[];
+}
+/**
+ * Server actions for managing prompts.
+ *
+ * The writes exist instead of an Angular UI: they reach the model API, and the existing callModel MCP
+ * surface makes them callable without building a screen for it. Reads are absent because the prompt and
+ * version model services already make both fetchable by key through model-get, and listing is the
+ * model API's standard query operation over {@link openRouterPromptsWithStateQuery}.
+ */
+export declare abstract class OpenRouterPromptServerActions {
+    abstract createOpenRouterPrompt(params: CreateOpenRouterPromptParams): Promise<OpenRouterPromptDocument>;
+    abstract updateOpenRouterPrompt(params: UpdateOpenRouterPromptParams): Promise<(document: OpenRouterPromptDocument) => Promise<OpenRouterPromptDocument>>;
+    abstract createOpenRouterPromptVersion(params: CreateOpenRouterPromptVersionParams): Promise<(document: OpenRouterPromptDocument) => Promise<CreateOpenRouterPromptVersionResult>>;
+    abstract updateOpenRouterPromptVersion(params: UpdateOpenRouterPromptVersionParams): Promise<(document: OpenRouterPromptVersionDocument) => Promise<UpdateOpenRouterPromptVersionResult>>;
+    /**
+     * Uncurried, like {@link createOpenRouterPrompt}: a seed has no target document to curry over — the
+     * documents it writes are the ones it is deciding whether to create.
+     */
+    abstract seedOpenRouterPrompts(params: SeedOpenRouterPromptsParams): Promise<SeedOpenRouterPromptsResult>;
+}
+/**
+ * Creates the {@link OpenRouterPromptServerActions}.
+ *
+ * @param context - The actions context.
+ * @returns The server actions.
+ */
+export declare function openRouterPromptServerActions(context: OpenRouterPromptServerActionsContext): OpenRouterPromptServerActions;
+/**
+ * Creates a new prompt at its caller-supplied key, refusing a key that already exists.
+ *
+ * Takes its params directly rather than through an arktype-validated action: the only callers are a
+ * seed and a test, both of them server-side.
+ *
+ * @param context - The actions context.
+ * @returns The create action.
+ */
+export declare function createOpenRouterPromptFactory(context: OpenRouterPromptServerActionsContext): (params: CreateOpenRouterPromptParams) => Promise<OpenRouterPromptDocument>;
+/**
+ * Updates a prompt's metadata, lifecycle state, or active version, then drops its cached resolution.
+ *
+ * @param context - The actions context.
+ * @returns The update action.
+ */
+export declare function updateOpenRouterPromptFactory(context: OpenRouterPromptServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateOpenRouterPromptParams, (document: OpenRouterPromptDocument) => Promise<OpenRouterPromptDocument>, object, unknown>;
+/**
+ * Creates a new version, allocating its number inside the transaction, locking the version it succeeds,
+ * and optionally promoting it.
+ *
+ * @param context - The actions context.
+ * @returns The create version action.
+ */
+export declare function createOpenRouterPromptVersionFactory(context: OpenRouterPromptServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateOpenRouterPromptVersionParams, (document: OpenRouterPromptDocument) => Promise<CreateOpenRouterPromptVersionResult>, object, unknown>;
+/**
+ * Edits the latest version of a prompt in place, refusing one the next version has locked.
+ *
+ * The lock is re-read inside the transaction rather than trusted from the caller's snapshot: a create
+ * racing this edit would otherwise let the write land on a version that had just stopped being the head.
+ *
+ * @param context - The actions context.
+ * @returns The update version action.
+ */
+export declare function updateOpenRouterPromptVersionFactory(context: OpenRouterPromptServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateOpenRouterPromptVersionParams, (document: OpenRouterPromptVersionDocument) => Promise<UpdateOpenRouterPromptVersionResult>, object, unknown>;
+/**
+ * How many definitions {@link seedOpenRouterPromptsFactory} publishes at a time.
+ *
+ * Each definition's writes are their own commit against documents no other definition touches, so the
+ * bound is not a correctness requirement — it keeps a large registry from opening one connection per
+ * prompt against Firestore all at once.
+ */
+export declare const OPENROUTER_SEED_PROMPTS_MAX_PARALLEL_UPDATES = 25;
+/**
+ * Publishes each code definition the prompt service carries at ITS OWN declared version number.
+ *
+ * The number is a compile-time constant rather than one allocated from `lv`, which is the whole point:
+ * an auto-allocating writer cannot converge on a number chosen in code, because its write address moves
+ * with its own effect — so a store seeded by {@link createOpenRouterPromptVersionFactory} sits
+ * permanently behind the definition and the resolver stands in for it forever. Pinning makes the write
+ * address a pure function of the definition, so a re-seed is a no-op rather than a step toward
+ * convergence, and a scheduled reseed can keep the store in step with deploys.
+ *
+ * Publishing is gated on `lv` rather than `av`: `lv` is the allocator and is monotone, while `av` is a
+ * pointer an operator can move backwards — gating on it would let a demotion re-trigger a publish on
+ * every scheduled tick, forever.
+ *
+ * Deliberately NOT built on {@link createOpenRouterPromptVersionFactory}: that action is reachable over
+ * callModel/MCP, and its in-transaction allocation is a race-safety contract on a public surface rather
+ * than an implementation detail. A seed needs no allocator at all, because the number it writes is a
+ * compile-time constant — something `CreateOpenRouterPromptVersionParams` cannot assert about an
+ * arbitrary caller.
+ *
+ * No transaction, at any scope. A version document carries a whole prompt's text, so a registry of them
+ * can put megabytes through a single commit, and a commit — transaction or write batch alike — is capped
+ * around 10MB. The run is instead one read pass over every prompt document, then each definition
+ * published independently through its OWN write batch, at most
+ * {@link OPENROUTER_SEED_PROMPTS_MAX_PARALLEL_UPDATES} at a time. The batch is what keeps a publish
+ * atomic — the version, the lock on the head it replaces, and the pointer move land together or not at
+ * all — while holding any one commit to the three documents a single definition touches.
+ *
+ * What that costs is the transaction's read set: the check that nothing else already holds the number
+ * being written is now a read taken shortly before the commit rather than a conflict detected at it.
+ * Losing that window means a seed overwrites a version an operator published under the same number in
+ * the same instant — narrow enough to trade for a run whose size cannot refuse it.
+ *
+ * @param context - The actions context.
+ * @returns The seed action.
+ */
+export declare function seedOpenRouterPromptsFactory(context: OpenRouterPromptServerActionsContext): (params: SeedOpenRouterPromptsParams) => Promise<SeedOpenRouterPromptsResult>;

package/firebase-server/src/lib/openrouter.broadcast.d.ts

@@ -0,0 +1,93 @@
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterRunTaskKey, type OpenRouterRunUsage } from '@dereekb/openrouter';
+import { type OpenRouterRunTaskFirestoreCollections } from '@dereekb/openrouter/firebase';
+/**
+ * The generation fields a broadcast span carries.
+ *
+ * Structurally the `OpenRouterGenerationInfo` that `@dereekb/nestjs/openrouter` already extracts from an
+ * OTLP span; declared independently so this package does not depend on the NestJS entry just for a shape.
+ */
+export interface OpenRouterBroadcastGenerationInfo {
+    readonly generationId?: Maybe<string>;
+    readonly model?: Maybe<string>;
+    readonly provider?: Maybe<string>;
+    readonly promptTokens?: Maybe<number>;
+    readonly completionTokens?: Maybe<number>;
+    readonly totalTokens?: Maybe<number>;
+    readonly cost?: Maybe<number>;
+}
+/**
+ * The attribute key OpenRouter surfaces a `trace: { runTaskKey }` property under.
+ *
+ * OpenRouter's docs: "custom metadata from the `trace` field is included as span attributes in the OTLP
+ * JSON payload". The exact prefix is not contractual, so several candidates are checked.
+ */
+export declare const OPENROUTER_BROADCAST_RUN_TASK_KEY_ATTRIBUTES: readonly string[];
+/**
+ * Reads the run task key out of a span's attribute map.
+ *
+ * @param attributes - The flattened span attributes.
+ * @returns The run task key, when the span carries one.
+ */
+export declare function openRouterRunTaskKeyFromBroadcastAttributes(attributes: Maybe<Map<string, string | number | boolean>>): Maybe<OpenRouterRunTaskKey>;
+/**
+ * Params for {@link reconcileOpenRouterRunTaskFromBroadcast}.
+ */
+export interface ReconcileOpenRouterRunTaskFromBroadcastParams {
+    /**
+     * The run task collections.
+     */
+    readonly collections: OpenRouterRunTaskFirestoreCollections;
+    /**
+     * The run task the span belongs to.
+     */
+    readonly key: Maybe<OpenRouterRunTaskKey>;
+    /**
+     * The generation info extracted from the span.
+     */
+    readonly generation: OpenRouterBroadcastGenerationInfo;
+}
+/**
+ * Result of a reconciliation attempt.
+ */
+export interface ReconcileOpenRouterRunTaskFromBroadcastResult {
+    /**
+     * Whether a run task was found and updated.
+     */
+    readonly reconciled: boolean;
+}
+/**
+ * Reconciles generation id, usage, and cost onto a run task from a broadcast span.
+ *
+ * This exists for the one thing the runner cannot always know: cost is finalised server-side, so the
+ * value the runner wrote from the response can be provisional.
+ *
+ * TELEMETRY ONLY — it never changes `s`, and a span it cannot match is dropped silently. Broadcast is
+ * enabled account-wide rather than per request, delivery is asynchronous and best-effort, and a dropped
+ * trace must not be able to strand a task. Putting control flow here would make a missing trace look
+ * exactly like a stuck run.
+ *
+ * @param params - The collections, run task key, and generation info.
+ * @returns Whether anything was written.
+ */
+export declare function reconcileOpenRouterRunTaskFromBroadcast(params: ReconcileOpenRouterRunTaskFromBroadcastParams): Promise<ReconcileOpenRouterRunTaskFromBroadcastResult>;
+/**
+ * Merges broadcast-reported usage into the usage already stored on a task.
+ *
+ * The broadcast value wins where it is present — it is the later, authoritative measurement — and the
+ * stored value is kept where the span is silent, so an incomplete span cannot erase what the runner knew.
+ *
+ * The filter MUST be `NULL`, not `mergeObjects`' default of `UNDEFINED`. Every field here is a `Maybe`, so a
+ * span reporting `cost: null` means "did not measure" — and under the default filter that `null` would win
+ * and erase the cost the runner actually recorded.
+ *
+ * `reasoningTokens` / `cachedTokens` / `isByok` are absent from the literal because a broadcast span carries
+ * none of them; they ride along from `existing` untouched.
+ *
+ * @param existing - Usage already stored.
+ * @param generation - The span's generation info.
+ * @returns The merged usage.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function mergeOpenRouterRunUsage(existing: Maybe<OpenRouterRunUsage>, generation: OpenRouterBroadcastGenerationInfo): OpenRouterRunUsage;

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

@@ -0,0 +1,57 @@
+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 OpenRouterPromptService } from './openrouter.prompt.service';
+/**
+ * Params for {@link callModelForPrompt}.
+ */
+export interface CallModelForPromptParams {
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * The prompt service used to resolve the version.
+     */
+    readonly promptService: OpenRouterPromptService;
+    /**
+     * The prompt to run.
+     */
+    readonly promptKey: OpenRouterPromptKey;
+    /**
+     * Version to pin. Omit to use the prompt's active version.
+     */
+    readonly version?: Maybe<OpenRouterPromptVersionNumber>;
+    /**
+     * The call input.
+     */
+    readonly input?: Maybe<OpenRouterInput>;
+    /**
+     * Per-call config overrides.
+     */
+    readonly configOverrides?: Maybe<OpenRouterModelConfig>;
+    /**
+     * Files, already attached for this call — see `openRouterFileAttachmentResolver`.
+     *
+     * Attached rather than by path, unlike the queued path: an inline call runs once, right now, so there
+     * is no later attempt for which a url could have expired.
+     */
+    readonly files?: Maybe<OpenRouterAttachedFileReference[]>;
+    /**
+     * Client-side tools.
+     */
+    readonly tools?: Maybe<readonly Tool[]>;
+    /**
+     * Trace metadata for cost/usage reconciliation.
+     */
+    readonly trace?: Maybe<Record<string, unknown>>;
+}
+/**
+ * Runs a prompt INLINE and returns the result, with no run task document.
+ *
+ * Use this wherever a call reliably finishes in a few seconds. The queue exists for calls that do not,
+ * and paying for a document, a lease, and a sweep interval on a two-second call buys nothing.
+ *
+ * @param params - The client, prompt service, prompt, and input.
+ * @returns The normalized call result.
+ */
+export declare function callModelForPrompt(params: CallModelForPromptParams): Promise<OpenRouterCallResult>;

package/firebase-server/src/lib/openrouter.file.attachment.d.ts

@@ -0,0 +1,97 @@
+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 OpenRouterFileReference } from '@dereekb/openrouter';
+/**
+ * How a file is carried to OpenRouter on one attempt.
+ *
+ * - `signedUrl` — a short-lived signed url OpenRouter dereferences itself. Cheap, and the default.
+ * - `inlineData` — the bytes, base64'd into the request body. The only option when the object is not
+ *   reachable from the public internet, which is exactly the case against the Firebase storage
+ *   emulator: signing is unsupported there, so the accessor falls back to a `publicUrl()` on localhost.
+ */
+export type OpenRouterFileAttachmentMode = 'signedUrl' | 'inlineData';
+/**
+ * Default lifetime of a signed url minted for one attempt.
+ *
+ * Deliberately short. The url only has to survive the single request it is attached to, and every
+ * attempt gets a freshly signed one — so a short TTL costs nothing and narrows the window in which a
+ * third party holds a bearer credential to the object.
+ */
+export declare const DEFAULT_OPENROUTER_SIGNED_URL_TTL: Milliseconds;
+/**
+ * Cap on the size of a file carried inline.
+ *
+ * Base64 inflates the payload by roughly a third, and the cost is re-paid on EVERY attempt rather than
+ * amortized the way a url is — so this is a guard against turning a retry loop into a bandwidth bill,
+ * not a correctness limit.
+ */
+export declare const DEFAULT_OPENROUTER_MAX_INLINE_FILE_SIZE_BYTES: number;
+/**
+ * Content type assumed for an inlined object whose metadata reports none.
+ *
+ * Matches {@link openRouterInputFileDataPart}'s own default, so the two cannot disagree.
+ */
+export declare const DEFAULT_OPENROUTER_INLINE_FILE_CONTENT_TYPE = "application/pdf";
+/**
+ * Config for {@link openRouterFileAttachmentResolver}.
+ */
+export interface OpenRouterFileAttachmentResolverConfig {
+    /**
+     * Storage context the files are read from. Required only when files are actually attached.
+     */
+    readonly storageContext?: Maybe<FirebaseStorageContext>;
+    /**
+     * Selects the mode when `mode` is not given: a non-production environment picks `inlineData`.
+     *
+     * This is the whole environment gate. An app wires its env service in once and both the emulator and
+     * production do the right thing without a second switch to keep in sync.
+     */
+    readonly envService?: Maybe<FirebaseServerEnvService>;
+    /**
+     * Explicit mode override. Wins over `envService`.
+     *
+     * For a unit test that wants one specific transport, or an app that knows its objects are (or are
+     * not) publicly reachable regardless of environment.
+     */
+    readonly mode?: Maybe<OpenRouterFileAttachmentMode>;
+    /**
+     * Signed-url lifetime. Defaults to {@link DEFAULT_OPENROUTER_SIGNED_URL_TTL}.
+     */
+    readonly signedUrlTtl?: Maybe<Milliseconds>;
+    /**
+     * Inline size cap. Defaults to {@link DEFAULT_OPENROUTER_MAX_INLINE_FILE_SIZE_BYTES}.
+     */
+    readonly maxInlineFileSizeBytes?: Maybe<number>;
+}
+/**
+ * Resolves file references into the attachments to send on ONE attempt.
+ */
+export type OpenRouterFileAttachmentResolver = (files: Maybe<OpenRouterFileReference[]>) => Promise<OpenRouterAttachedFileReference[]>;
+/**
+ * The mode a config resolves to.
+ *
+ * Order: the explicit override, then the environment service, then `signedUrl`.
+ *
+ * Gated on `isProduction` rather than `isTestingEnv`, because the question is whether OpenRouter can
+ * reach the object, not whether this is a test. Every non-production environment here is a localhost
+ * one — the emulator under `nx serve` as much as a spec run — and `isTestingEnv` is only
+ * `NODE_ENV === 'test'`, so it covered the spec run and left the emulator handing OpenRouter a
+ * `127.0.0.1` url that it rejects outright.
+ *
+ * @param config - The resolver config.
+ * @returns The mode.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterFileAttachmentModeForConfig(config: OpenRouterFileAttachmentResolverConfig): OpenRouterFileAttachmentMode;
+/**
+ * Creates an {@link OpenRouterFileAttachmentResolver}.
+ *
+ * Called once per attempt, never at enqueue time: both transports produce something that is only valid
+ * for the request it is attached to.
+ *
+ * @param config - The storage context, environment service, and transport settings.
+ * @returns The resolver.
+ */
+export declare function openRouterFileAttachmentResolver(config: OpenRouterFileAttachmentResolverConfig): OpenRouterFileAttachmentResolver;

package/firebase-server/src/lib/openrouter.module.d.ts

@@ -0,0 +1,65 @@
+import { type DynamicModule, type ModuleMetadata, type Provider } from '@nestjs/common';
+import { type OpenRouterPromptService } from './openrouter.prompt.service';
+import { type OpenRouterRunTaskService } from './openrouter.runtask.service';
+/**
+ * Config for {@link appOpenRouterModuleMetadata}.
+ */
+export interface AppOpenRouterModuleMetadataConfig {
+    /**
+     * Module providing the concrete {@link OpenRouterPromptService},
+     * {@link OpenRouterRunTaskService}, and the actions context.
+     *
+     * Kept as a caller-supplied dependency module rather than constructed here: the run-task service needs
+     * the app's Firestore collections, its storage context, its OpenRouter client, and its
+     * terminal-state handler — every one of which is app-specific.
+     */
+    readonly dependencyModule: Required<ModuleMetadata>['imports'][0];
+    /**
+     * Provider for {@link OpenRouterPromptServerActions}.
+     */
+    readonly serverActionsProvider: Provider;
+    /**
+     * Additional providers to expose.
+     */
+    readonly providers?: Provider[];
+    /**
+     * Additional exports.
+     */
+    readonly exports?: Required<ModuleMetadata>['exports'];
+}
+/**
+ * Builds the module metadata for an app's OpenRouter module.
+ *
+ * @param config - The dependency module and server-actions provider.
+ * @returns The module metadata.
+ */
+export declare function appOpenRouterModuleMetadata(config: AppOpenRouterModuleMetadataConfig): ModuleMetadata;
+/**
+ * Base class an app's OpenRouter module extends.
+ */
+export declare abstract class AbstractAppOpenRouterModule {
+}
+/**
+ * A reference to an {@link OpenRouterPromptService}, for an actions context to extend.
+ */
+export interface OpenRouterPromptServiceRef {
+    readonly openRouterPromptService: OpenRouterPromptService;
+}
+/**
+ * A reference to an {@link OpenRouterRunTaskService}, for an actions context to extend.
+ */
+export interface OpenRouterRunTaskServiceRef {
+    readonly openRouterRunTaskService: OpenRouterRunTaskService;
+}
+/**
+ * Injection token for the {@link OpenRouterPromptService}.
+ */
+export declare const OPENROUTER_PROMPT_SERVICE_TOKEN = "OPENROUTER_PROMPT_SERVICE_TOKEN";
+/**
+ * Injection token for the {@link OpenRouterRunTaskService}.
+ */
+export declare const OPENROUTER_RUN_TASK_SERVICE_TOKEN = "OPENROUTER_RUN_TASK_SERVICE_TOKEN";
+/**
+ * Type of a dynamic module produced for the OpenRouter services.
+ */
+export type OpenRouterDynamicModule = DynamicModule;

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

@@ -0,0 +1,109 @@
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+import { type OpenRouterPromptDefinition, type OpenRouterPromptKey, type OpenRouterPromptVersionNumber, type OpenRouterResolvedPrompt } from '@dereekb/openrouter';
+import { type OpenRouterPrompt, type OpenRouterPromptFirestoreCollections } from '@dereekb/openrouter/firebase';
+/**
+ * Error thrown when a prompt cannot be resolved.
+ */
+export declare class OpenRouterPromptResolutionError extends Error {
+    readonly promptKey: OpenRouterPromptKey;
+    readonly version: Maybe<OpenRouterPromptVersionNumber>;
+    constructor(promptKey: OpenRouterPromptKey, message: string, version?: Maybe<OpenRouterPromptVersionNumber>);
+}
+/**
+ * Params for resolving a prompt version.
+ */
+export interface OpenRouterResolvePromptParams {
+    /**
+     * The prompt to resolve.
+     */
+    readonly promptKey: OpenRouterPromptKey;
+    /**
+     * The version to pin to. When omitted the prompt's `activeVersion` is used.
+     */
+    readonly version?: Maybe<OpenRouterPromptVersionNumber>;
+}
+/**
+ * Default time a resolved prompt is cached for.
+ *
+ * What can go stale is which version is active, and what the latest — still editable — version says.
+ * Neither is critical to serve to the second: a run that used the previous text for a few minutes is a
+ * run against a prompt that was live a few minutes ago, not a wrong run. Bounded rather than permanent
+ * is the requirement, so the change lands on its own rather than at the next cold start.
+ */
+export declare const OPENROUTER_PROMPT_CACHE_DURATION: Milliseconds;
+/**
+ * Loads prompts and resolves their versions.
+ */
+export declare abstract class OpenRouterPromptService {
+    /**
+     * Loads the prompt definitions this service resolves against, de-duplicated by key.
+     *
+     * Exposed so a seeder publishes the exact values the resolver would otherwise stand in with, rather
+     * than a second registry wired in parallel that can drift from this one. De-duplicated because
+     * `definitionsByKey` is what resolution actually reads: `arrayToMap` is last-wins, so iterating the
+     * raw config array would let a seeder publish a definition that never resolves.
+     *
+     * Async even though the configured implementation answers from memory: a later one may read its
+     * registry from somewhere the process does not already hold it — a manifest in storage, another
+     * service — and a getter is the one shape that cannot be widened to cover that without breaking
+     * every caller.
+     */
+    abstract loadPromptDefinitions(): Promise<OpenRouterPromptDefinition[]>;
+    /**
+     * Loads a prompt document by key.
+     *
+     * Reads the STORE only — a prompt that exists solely as a code definition has no document, so this
+     * returns undefined for it while {@link resolvePrompt} still serves it.
+     */
+    abstract loadPrompt(promptKey: OpenRouterPromptKey): Promise<Maybe<OpenRouterPrompt>>;
+    /**
+     * Resolves the version to serve for a prompt, pinned or active.
+     *
+     * Resolves from the store, falling back to a configured {@link OpenRouterPromptDefinition} when the
+     * store cannot serve or is behind it.
+     *
+     * @throws {OpenRouterPromptResolutionError} when the prompt, or the requested version, is not servable.
+     */
+    abstract resolvePrompt(params: OpenRouterResolvePromptParams): Promise<OpenRouterResolvedPrompt>;
+    /**
+     * Drops any cached resolution for a prompt. Called after a publish/promote so the change is visible
+     * immediately rather than after the cache expires.
+     */
+    abstract clearCachedPrompt(promptKey: OpenRouterPromptKey): void;
+}
+/**
+ * Config for {@link openRouterPromptService}.
+ */
+export interface OpenRouterPromptServiceConfig {
+    /**
+     * The prompt collections.
+     */
+    readonly collections: OpenRouterPromptFirestoreCollections;
+    /**
+     * Prompts defined in code, served when the stored prompt cannot serve or is behind them.
+     *
+     * See {@link OpenRouterPromptDefinition} for the precedence rules. Omit to resolve from Firestore
+     * only, which is the behaviour of a service configured without definitions.
+     */
+    readonly definitions?: Maybe<OpenRouterPromptDefinition[]>;
+    /**
+     * How long a resolution is cached for. Defaults to {@link OPENROUTER_PROMPT_CACHE_DURATION}.
+     */
+    readonly cacheDuration?: Maybe<Milliseconds>;
+    /**
+     * Whether a resolved config that fails validation is rejected instead of returned.
+     *
+     * Defaults to false: a warning-level problem (an unpinned PDF engine, say) should not take a
+     * production path down, and an error-level one will fail the request anyway with a clearer message
+     * from OpenRouter. Turn it on in tests and in prompt-authoring tooling, where failing early is the
+     * point.
+     */
+    readonly rejectInvalidConfig?: Maybe<boolean>;
+}
+/**
+ * Creates an {@link OpenRouterPromptService}.
+ *
+ * @param config - The collections and cache configuration.
+ * @returns The service.
+ */
+export declare function openRouterPromptService(config: OpenRouterPromptServiceConfig): OpenRouterPromptService;