​

Multi-Turn Conversation State

Implementation: src/lib/conversation-state-store.ts (store + backends), src/funcs/call-model-with-state.ts (turn-pipeline entry point). Integration tests: tests/unit/multi-turn-integration.test.ts.

​

Quick start

import { OpenRouter } from '@openrouter/sdk';
import {
  ConversationStateStore,
  InMemoryConversationStateBackend,
} from '@openrouter/sdk/lib/conversation-state-store.js';

const client = new OpenRouter();

// One store per application (or per tenant); reuse it for every turn.
const store = new ConversationStateStore(new InMemoryConversationStateBackend(), {
  ttlMs: 30 * 60 * 1000, // optional: expire idle conversations after 30 min
});

// Turn 1
const first = client.callModelWithState({
  model: 'openai/gpt-5',
  input: 'My name is Ada.',
  conversationId: 'user-123',
  stateStore: store,
});
await first.getText();

// Turn 2 — the model sees turn 1's context and answers "Ada".
const second = client.callModelWithState({
  model: 'openai/gpt-5',
  input: 'What is my name?',
  conversationId: 'user-123',
  stateStore: store,
});
console.log(await second.getText());

​

How state is keyed

• The id is the only lookup key. Each turn loads the state document under that id, appends the new input and the response output to the stored message history, and persists the result back under the same id before the response is returned.
• Choose ids that are stable for the lifetime of the conversation — e.g. a session id, user-<id>, or a UUID minted when the chat starts.
• Parallel conversations are fully isolated: two ids never share state, even when their turns interleave or run concurrently on the same store.
• The id guard: if the turn pipeline ever produces a state document whose id differs from the accessor’s bound id (e.g. the first turn creates a placeholder state internally), the store rebinds it to your conversationId on save. State can never strand under an id you don’t own.

​

The state document

interface ConversationState {
  id: string;                   // your conversationId
  messages: BaseInputsUnion[];  // user inputs + assistant outputs, in turn order
  status: 'in_progress' | 'awaiting_approval' | 'interrupted' | 'complete';
  createdAt: number;            // ms epoch
  updatedAt: number;            // ms epoch; drives TTL expiry
  previousResponseId?: string;  // last Responses API response id
  // ... pending tool results and metadata
}

​

Configuration

new ConversationStateStore(backend, {
  ttlMs?: number,      // idle expiry window; omit or 0 to disable
  now?: () => number,  // clock override (testing)
});

​

Backends

• InMemoryConversationStateBackend — process-local Map. Right for tests and ephemeral single-process use. Documents are deep-copied on read/write so callers can’t mutate stored state by aliasing. Implements list(), so store-wide expire() works.
• FileConversationStateBackend — JSON-file-per-conversation under a directory (Node.js only). Ids are sanitized to prevent path traversal. Useful for local durable execution without Redis.

interface ConversationStateBackend {
  load(id: string): Promise<ConversationState | null>;
  save(id: string, state: ConversationState): Promise<void>;
  delete(id: string): Promise<void>;
  list?(): Promise<string[]>;  // enables store-wide expire()
}

​

Expiry and cleanup

• TTL expiry (read-through): with ttlMs set, store.get(id) returns null for idle-expired documents. When a turn then arrives for that id the pipeline starts a fresh conversation under the same id — the model does not see the expired history.
• Store-wide sweep: store.expire() removes every stale conversation (requires the backend to implement list()) and returns the removed ids. store.expire(['id1', 'id2']) sweeps only the given ids. Run this on a timer if you want storage reclaimed rather than just hidden.
• Explicit deletion: store.clear(id) deletes one conversation immediately, regardless of TTL. The next turn for that id starts fresh. Clearing one conversation never affects siblings.

​

Missing or corrupted state

​

Testing recipes

• 3+ turn context: queue mocked betaResponsesSend responses and assert that turn N’s API request input contains every earlier turn’s user input and assistant output, in order.
• Parallel isolation: interleave turns across two conversationIds on one store and assert neither request input mentions the other conversation.
• Expiry: construct the store with a short ttlMs (or a fake now clock), sleep past the TTL, and assert the next turn starts fresh.
• Corruption: poison the backend (or the JSON file for FileConversationStateBackend) and assert CorruptedStateError.