@dereekb/openrouter 13.37.0

package/firebase-server/src/lib/openrouter.state.accessor.d.ts

@@ -0,0 +1,106 @@
+import { type Maybe } from '@dereekb/util';
+import { type ConversationState, type ConversationStatus, type OpenRouterAttachedFileReference, type OpenRouterInputMessage, type OpenRouterRunTaskKey, type StateAccessor, type Tool } from '@dereekb/openrouter';
+import { type OpenRouterRunTask, type OpenRouterRunTaskDocument, OpenRouterRunTaskState } from '@dereekb/openrouter/firebase';
+/**
+ * Maps a run task state to the SDK's conversation status.
+ *
+ * @param state - The run task state.
+ * @returns The conversation status.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function conversationStatusForOpenRouterRunTaskState(state: OpenRouterRunTaskState): ConversationStatus;
+/**
+ * Maps a conversation status back to the run task state to persist.
+ *
+ * @param status - The conversation status.
+ * @param hasPendingToolCalls - Whether the state carries tool calls this process cannot resolve.
+ * @returns The run task state.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterRunTaskStateForConversationStatus(status: ConversationStatus, hasPendingToolCalls: boolean): OpenRouterRunTaskState;
+/**
+ * Builds a {@link ConversationState} from a run task.
+ *
+ * `updatedAt` is derived rather than stored: the run task's existing timestamps already order the
+ * lifecycle (`fat` > `lat` > `sat` > `qat`), and the SDK uses the value informationally.
+ *
+ * @param key - The run task key, which is the conversation id.
+ * @param task - The run task.
+ * @returns The conversation state.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function conversationStateForOpenRouterRunTask<TTools extends readonly Tool[] = readonly Tool[]>(key: OpenRouterRunTaskKey, task: OpenRouterRunTask): ConversationState<TTools>;
+/**
+ * The subset of a run task that a conversation-state save writes.
+ */
+export type OpenRouterRunTaskStateUpdate = Pick<OpenRouterRunTask, 's' | 'msg' | 'ptc' | 'utr'>;
+/**
+ * Builds the run task update for a conversation state.
+ *
+ * @param state - The conversation state to persist.
+ * @returns The fields to write.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterRunTaskUpdateForConversationState(state: ConversationState): OpenRouterRunTaskStateUpdate;
+/**
+ * Strips `undefined` out of a value on its way into Firestore, at ANY DEPTH.
+ *
+ * Conversation state is whatever the SDK hands back, arbitrarily nested, and its response items carry
+ * explicit `undefined`s for absent optional fields at every level. Firestore rejects `undefined` outright,
+ * so persisting one unfiltered fails the whole write — and it fails inside the SDK's `saveStateSafely`,
+ * which surfaces as an opaque "Failed to persist conversation state" rather than as the run-task write it
+ * actually is.
+ *
+ * A JSON round-trip rather than `copyValueWithoutUndefinedValues` (which filters just as deeply, and is
+ * what the run task converter's passthrough-JSON fields use): the round-trip additionally flattens
+ * anything that is not wire json — a `Date`, a class instance with a `toJSON` — which is correct here
+ * precisely because this data IS json. It came off the wire, and `load()` hands it straight back to the
+ * SDK expecting the same shapes. The converter's fields, by contrast, must leave a `Date`/`Timestamp`
+ * intact for Firestore.
+ *
+ * @param value - The value to sanitize.
+ * @returns The value with every `undefined` removed.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterConversationValueForFirestore<T>(value: T): T;
+/**
+ * Config for {@link firestoreOpenRouterStateAccessor}.
+ */
+export interface FirestoreOpenRouterStateAccessorConfig {
+    /**
+     * The conversation to start from when the run task has no history yet.
+     *
+     * The SDK never records the request's own input into conversation state — it only appends what comes
+     * BACK — so a run that resumes from state alone would resume having forgotten what it was asked. The
+     * runner seeds the assembled request input here so the persisted conversation is the whole
+     * conversation, and passes an empty `input` on the request itself to avoid sending it twice.
+     */
+    readonly initialMessages?: Maybe<OpenRouterInputMessage[]>;
+    /**
+     * The files attached for THIS attempt.
+     *
+     * Loaded history is re-pointed at these attachments, so a resume hours later does not replay a signed
+     * url that expired minutes after the attempt that persisted it — or, in inline mode, a part whose
+     * payload was deliberately stripped on save.
+     */
+    readonly attachedFiles?: Maybe<OpenRouterAttachedFileReference[]>;
+}
+/**
+ * Creates a {@link StateAccessor} backed by a run task document.
+ *
+ * This is the persistent backend the SDK's docs ask for — its own example is a `Map`, with the note to
+ * "implement `StateAccessor` with a persistent backend". Because OpenRouter allocates no conversation
+ * id (and rejects `previous_response_id` outright), the conversation id is ours: the run task key.
+ *
+ * A single-shot run simply never populates `msg` / `ptc` / `utr`, so nothing is paid for not using it.
+ *
+ * @param document - The run task document to read and write.
+ * @param config - The initial conversation and this attempt's attached files.
+ * @returns The state accessor.
+ */
+export declare function firestoreOpenRouterStateAccessor<TTools extends readonly Tool[] = readonly Tool[]>(document: OpenRouterRunTaskDocument, config?: Maybe<FirestoreOpenRouterStateAccessorConfig>): StateAccessor<TTools>;

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

@@ -0,0 +1,134 @@
+/**
+ * Test doubles for the emulator integration suite.
+ *
+ * The OpenRouter client faked here is a REAL `OpenRouterCore` wired to a stub `fetcher` rather than a
+ * hand-rolled object. That matters: every scenario that asserts something about the outgoing request
+ * (a freshly signed url, an echoed annotation, a trace attribute) is then asserting against the JSON
+ * OpenRouter would actually receive, after the SDK's own outbound serialization — which is where a
+ * field silently gets dropped. A stubbed `callModel` would assert against our own intermediate shape
+ * and prove nothing about the wire.
+ */
+import { OpenRouterCore } from '@openrouter/sdk/core';
+import { type FirebaseStorageContext } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+/**
+ * A tool call the fake model should emit.
+ */
+export interface FakeOpenRouterToolCall {
+    readonly callId: string;
+    readonly name: string;
+    readonly arguments?: Maybe<Record<string, unknown>>;
+}
+/**
+ * What the fake model should answer with on one turn.
+ */
+export interface FakeOpenRouterReply {
+    readonly id?: Maybe<string>;
+    readonly text?: Maybe<string>;
+    readonly toolCalls?: Maybe<FakeOpenRouterToolCall[]>;
+    /**
+     * A response-level error, which the runner treats as a failed attempt.
+     *
+     * `code` is a string because OpenRouter's `ResponsesErrorField` models it as one — a numeric HTTP
+     * status here fails the SDK's inbound validation and produces a transport error instead of the
+     * response-level error the test meant to exercise.
+     */
+    readonly error?: Maybe<{
+        readonly code: string;
+        readonly message: string;
+    }>;
+    /**
+     * Cost/usage to report.
+     */
+    readonly cost?: Maybe<number>;
+    /**
+     * Milliseconds to stall before answering, for the time-budget and concurrency scenarios.
+     */
+    readonly delayMs?: Maybe<number>;
+    /**
+     * Thrown instead of answered, for the transport-failure path.
+     */
+    readonly throws?: Maybe<Error>;
+}
+/**
+ * Decides the reply for one request. Receives the request body exactly as it went on the wire.
+ */
+export type FakeOpenRouterReplyFactory = (body: Record<string, unknown>, callIndex: number) => FakeOpenRouterReply | Promise<FakeOpenRouterReply>;
+/**
+ * A fake OpenRouter client plus the requests it received.
+ */
+export interface FakeOpenRouterClient {
+    readonly client: OpenRouterCore;
+    /**
+     * Every request body sent, in order, serialized exactly as OpenRouter would have received it.
+     */
+    readonly requests: Record<string, unknown>[];
+    readonly callCount: number;
+}
+/**
+ * Builds an `OpenResponsesResult` JSON body in the wire (snake_case) shape the SDK's inbound schema
+ * parses.
+ *
+ * @param reply - What the fake model should answer with.
+ * @param index - The call ordinal, used to make a distinct generation id when none is given.
+ * @returns The response body.
+ */
+export declare function fakeOpenRouterResponseBody(reply: FakeOpenRouterReply, index: number): Record<string, unknown>;
+/**
+ * Creates a real {@link OpenRouterCore} whose HTTP layer is answered locally.
+ *
+ * @param replyFactory - Decides the reply per request, or a single fixed reply.
+ * @returns The client and its captured requests.
+ */
+export declare function fakeOpenRouterClient(replyFactory: FakeOpenRouterReplyFactory | FakeOpenRouterReply): FakeOpenRouterClient;
+/**
+ * One object held by a {@link FakeStorageContext}.
+ */
+export interface FakeStorageObject {
+    readonly bytes: Uint8Array;
+    readonly contentType?: Maybe<string>;
+}
+/**
+ * A read of an object's bytes, with the cap the caller asked for.
+ */
+export interface FakeStorageGetBytesCall {
+    readonly pathString: string;
+    readonly maxDownloadSizeBytes?: Maybe<number>;
+}
+/**
+ * A storage context that mints a distinct, timestamped url per call and serves in-memory bytes.
+ *
+ * The emulator's storage cannot mint a real signed url, and a real one would not answer the question
+ * the signed-url scenario asks anyway: it asks whether the runner mints a NEW url per attempt, which is
+ * observable only by making every mint distinguishable.
+ */
+export interface FakeStorageContext {
+    readonly storageContext: FirebaseStorageContext;
+    /**
+     * The urls minted so far, in order.
+     */
+    readonly signed: string[];
+    /**
+     * Every `getBytes` made, in order, with the cap it was made under.
+     */
+    readonly reads: FakeStorageGetBytesCall[];
+    /**
+     * The in-memory objects, by path string.
+     */
+    readonly objects: Record<string, FakeStorageObject>;
+    /**
+     * Seeds an object at a path.
+     */
+    putObject(pathString: string, object: FakeStorageObject): void;
+    /**
+     * Overridable clock, so a test can advance past a signed url's lifetime.
+     */
+    now: () => number;
+}
+/**
+ * Creates a {@link FakeStorageContext}.
+ *
+ * @param bucketId - The default bucket id to report.
+ * @returns The fake storage context.
+ */
+export declare function fakeStorageContext(bucketId?: string): FakeStorageContext;

package/index.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./index.cjs.js').default;