llm-mock-server 1.0.0

package/src/formats/openai/schema.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+
+const ContentPartSchema = z.looseObject({
+  type: z.string(),
+  text: z.string().optional(),
+});
+
+const MessageSchema = z.object({
+  role: z.enum(["system", "developer", "user", "assistant", "tool"]).optional(),
+  content: z.union([z.string(), z.array(ContentPartSchema), z.null()]).optional(),
+  name: z.string().optional(),
+  tool_calls: z.array(z.object({
+    index: z.number().optional(),
+    id: z.string().optional(),
+    type: z.string().optional(),
+    function: z.object({
+      name: z.string(),
+      arguments: z.string(),
+    }),
+  })).optional(),
+  tool_call_id: z.string().optional(),
+});
+
+const ToolSchema = z.object({
+  type: z.string(),
+  function: z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    parameters: z.record(z.string(), z.unknown()).optional(),
+  }),
+});
+
+export const OpenAIRequestSchema = z.looseObject({
+  model: z.string().min(1),
+  messages: z.array(MessageSchema).min(1),
+  temperature: z.number().optional(),
+  top_p: z.number().optional(),
+  n: z.number().optional(),
+  stop: z.union([z.string(), z.array(z.string())]).optional(),
+  max_tokens: z.number().optional(),
+  presence_penalty: z.number().optional(),
+  frequency_penalty: z.number().optional(),
+  tools: z.array(ToolSchema).optional(),
+  stream: z.boolean().optional(),
+  tool_choice: z.unknown().optional(),
+  user: z.string().optional(),
+  audio: z.unknown().optional(),
+  function_call: z.unknown().optional(),
+  functions: z.array(z.unknown()).optional(),
+  logit_bias: z.record(z.string(), z.number()).optional(),
+  logprobs: z.boolean().optional(),
+  max_completion_tokens: z.number().optional(),
+  metadata: z.record(z.string(), z.string()).optional(),
+  modalities: z.array(z.string()).optional(),
+  parallel_tool_calls: z.boolean().optional(),
+  prediction: z.unknown().optional(),
+  prompt_cache_key: z.string().optional(),
+  prompt_cache_retention: z.string().optional(),
+  reasoning_effort: z.string().optional(),
+  response_format: z.unknown().optional(),
+  safety_identifier: z.string().optional(),
+  seed: z.number().optional(),
+  service_tier: z.string().optional(),
+  store: z.boolean().optional(),
+  stream_options: z.unknown().optional(),
+  top_logprobs: z.number().optional(),
+  verbosity: z.string().optional(),
+  web_search_options: z.unknown().optional(),
+});
+
+export type OpenAIRequest = z.infer<typeof OpenAIRequestSchema>;
+
+const ToolCallResponseSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  function: z.object({ name: z.string(), arguments: z.string() }),
+});
+
+const UsageSchema = z.object({
+  prompt_tokens: z.number(),
+  completion_tokens: z.number(),
+  total_tokens: z.number(),
+  prompt_tokens_details: z.object({
+    cached_tokens: z.number().optional(),
+    audio_tokens: z.number().optional(),
+  }).optional(),
+  completion_tokens_details: z.object({
+    reasoning_tokens: z.number().optional(),
+    audio_tokens: z.number().optional(),
+    accepted_prediction_tokens: z.number().optional(),
+    rejected_prediction_tokens: z.number().optional(),
+  }).optional(),
+});
+
+export const OpenAIChunkSchema = z.object({
+  id: z.string(),
+  object: z.literal("chat.completion.chunk"),
+  created: z.number(),
+  model: z.string(),
+  system_fingerprint: z.string().nullable().optional(),
+  service_tier: z.string().optional(),
+  choices: z.array(z.object({
+    index: z.number(),
+    delta: z.object({
+      role: z.string(),
+      content: z.string(),
+      tool_calls: z.array(ToolCallResponseSchema),
+    }).partial(),
+    logprobs: z.unknown().nullable().optional(),
+    finish_reason: z.string().nullable(),
+  })),
+  usage: UsageSchema.nullable().optional(),
+});
+
+export type OpenAIChunk = z.infer<typeof OpenAIChunkSchema>;
+
+export const OpenAICompleteSchema = z.object({
+  id: z.string(),
+  object: z.literal("chat.completion"),
+  created: z.number(),
+  model: z.string(),
+  system_fingerprint: z.string().nullable().optional(),
+  service_tier: z.string().optional(),
+  choices: z.array(z.object({
+    index: z.number(),
+    message: z.object({
+      role: z.string(),
+      content: z.string().nullable(),
+      tool_calls: z.array(ToolCallResponseSchema).optional(),
+    }),
+    logprobs: z.unknown().nullable().optional(),
+    finish_reason: z.string(),
+  })),
+  usage: UsageSchema.optional(),
+});
+
+export type OpenAIComplete = z.infer<typeof OpenAICompleteSchema>;
+
+export const OpenAIErrorSchema = z.object({
+  error: z.object({
+    message: z.string(),
+    type: z.string(),
+    code: z.string().nullable(),
+  }),
+});
+
+export type OpenAIError = z.infer<typeof OpenAIErrorSchema>;

package/src/formats/openai/serialize.ts

@@ -0,0 +1,92 @@
+import type { ReplyObject, ReplyOptions } from "../../types.js";
+import type { SSEChunk } from "../types.js";
+import { splitText, genId, toolId, finishReason, MS_PER_SECOND, DEFAULT_USAGE } from "../parse-helpers.js";
+
+function chunkEnvelope(
+  id: string, created: number, model: string,
+  delta: Record<string, unknown>, finish_reason: string | null = null,
+  usage: Record<string, unknown> | null = null,
+): SSEChunk {
+  return {
+    data: JSON.stringify({
+      id, object: "chat.completion.chunk", created, model,
+      system_fingerprint: null,
+      service_tier: "default",
+      choices: [{ index: 0, delta, logprobs: null, finish_reason }],
+      usage,
+    }),
+  };
+}
+
+export function serialize(reply: ReplyObject, model: string, options: ReplyOptions = {}): readonly SSEChunk[] {
+  const id = genId("chatcmpl");
+  const created = Math.floor(Date.now() / MS_PER_SECOND);
+  const usage = reply.usage ?? DEFAULT_USAGE;
+
+  const textChunks = reply.text
+    ? splitText(reply.text, options.chunkSize ?? 0).map((piece) =>
+        chunkEnvelope(id, created, model, { content: piece }),
+      )
+    : [];
+
+  const toolChunks = (reply.tools ?? []).map((tool, i) =>
+    chunkEnvelope(id, created, model, {
+      tool_calls: [{
+        index: i, id: toolId(tool, "call", i), type: "function",
+        function: { name: tool.name, arguments: JSON.stringify(tool.args) },
+      }],
+    }),
+  );
+
+  const usageChunk = {
+    prompt_tokens: usage.input,
+    completion_tokens: usage.output,
+    total_tokens: usage.input + usage.output,
+    prompt_tokens_details: { cached_tokens: 0, audio_tokens: 0 },
+    completion_tokens_details: { reasoning_tokens: 0, audio_tokens: 0, accepted_prediction_tokens: 0, rejected_prediction_tokens: 0 },
+  };
+
+  return [
+    chunkEnvelope(id, created, model, { role: "assistant" }),
+    ...textChunks,
+    ...toolChunks,
+    chunkEnvelope(id, created, model, {}, finishReason(reply, "tool_calls", "stop")),
+    chunkEnvelope(id, created, model, {}, null, usageChunk),
+    { data: "[DONE]" },
+  ];
+}
+
+export function serializeComplete(reply: ReplyObject, model: string): unknown {
+  const id = genId("chatcmpl");
+  const created = Math.floor(Date.now() / MS_PER_SECOND);
+  const usage = reply.usage ?? DEFAULT_USAGE;
+
+  const message: Record<string, unknown> = {
+    role: "assistant",
+    content: reply.text ?? null,
+    ...(reply.tools?.length && {
+      tool_calls: reply.tools.map((tool, i) => ({
+        id: toolId(tool, "call", i), type: "function",
+        function: { name: tool.name, arguments: JSON.stringify(tool.args) },
+      })),
+    }),
+  };
+
+  return {
+    id, object: "chat.completion", created, model,
+    system_fingerprint: null,
+    service_tier: "default",
+    choices: [{ index: 0, message, logprobs: null, finish_reason: finishReason(reply, "tool_calls", "stop") }],
+    usage: {
+      prompt_tokens: usage.input,
+      completion_tokens: usage.output,
+      total_tokens: usage.input + usage.output,
+      prompt_tokens_details: { cached_tokens: 0, audio_tokens: 0 },
+      completion_tokens_details: { reasoning_tokens: 0, audio_tokens: 0, accepted_prediction_tokens: 0, rejected_prediction_tokens: 0 },
+    },
+  };
+}
+
+export function serializeError(error: { status: number; message: string; type?: string }): unknown {
+  return { error: { message: error.message, type: error.type ?? "server_error", code: null } };
+}

package/src/formats/parse-helpers.ts

@@ -0,0 +1,79 @@
+import type { FormatName, Message, MockRequest, ReplyObject, ToolDef } from "../types.js";
+
+export const MS_PER_SECOND = 1000;
+const BASE_36 = 36;
+export const DEFAULT_USAGE = { input: 10, output: 5 } as const;
+
+function asRecord(body: unknown): Record<string, unknown> {
+  if (typeof body === "object" && body !== null) return body as Record<string, unknown>;
+  return {};
+}
+
+export function splitText(text: string, chunkSize: number): string[] {
+  if (chunkSize <= 0 || text.length <= chunkSize) return [text];
+  const chunks: string[] = [];
+  for (let i = 0; i < text.length; i += chunkSize) {
+    chunks.push(text.slice(i, i + chunkSize));
+  }
+  return chunks;
+}
+
+export function genId(prefix: string): string {
+  return `${prefix}_${Date.now().toString(BASE_36)}`;
+}
+
+export function toolId(tool: { id?: string | undefined }, prefix: string, index: number): string {
+  return tool.id ?? `${prefix}_${Date.now().toString(BASE_36)}_${index}`;
+}
+
+export function shouldEmitText(reply: ReplyObject): boolean {
+  return Boolean(reply.text) || (!reply.tools?.length && !reply.reasoning);
+}
+
+export function finishReason(reply: ReplyObject, onTools: string, onStop: string): string {
+  return reply.tools?.length ? onTools : onStop;
+}
+
+export function isStreaming(body: unknown): boolean {
+  return asRecord(body)["stream"] !== false;
+}
+
+export interface RequestMeta {
+  readonly headers: Readonly<Record<string, string | undefined>>;
+  readonly path: string;
+}
+
+const EMPTY_META: RequestMeta = { headers: {}, path: "" };
+
+export interface ParsedBody {
+  readonly model?: string | undefined;
+  readonly stream?: boolean | undefined;
+}
+
+export function buildMockRequest(
+  format: FormatName,
+  body: ParsedBody,
+  messages: readonly Message[],
+  tools: readonly ToolDef[] | undefined,
+  defaultModel: string,
+  raw: unknown,
+  meta: RequestMeta = EMPTY_META,
+): MockRequest {
+  const userMessages = messages.filter((m) => m.role === "user");
+  const toolCallMsgs = messages.filter((m) => m.toolCallId !== undefined);
+
+  return {
+    format,
+    model: body.model || defaultModel,
+    streaming: body.stream !== false,
+    messages,
+    lastMessage: userMessages.at(-1)?.content ?? "",
+    systemMessage: messages.find((m) => m.role === "system")?.content ?? "",
+    tools,
+    toolNames: tools?.map((t) => t.name) ?? [],
+    lastToolCallId: toolCallMsgs.at(-1)?.toolCallId,
+    raw,
+    headers: meta.headers,
+    path: meta.path,
+  };
+}

package/src/formats/responses/index.ts

@@ -0,0 +1,14 @@
+import type { Format } from "../types.js";
+import { isStreaming } from "../parse-helpers.js";
+import { parseRequest } from "./parse.js";
+import { serialize, serializeComplete, serializeError } from "./serialize.js";
+
+export const responsesFormat: Format = {
+  name: "responses",
+  route: "/v1/responses",
+  parseRequest,
+  isStreaming,
+  serialize,
+  serializeComplete,
+  serializeError,
+};

package/src/formats/responses/parse.ts

@@ -0,0 +1,56 @@
+import type { MockRequest, Message, ToolDef } from "../../types.js";
+import { buildMockRequest, type RequestMeta } from "../parse-helpers.js";
+import { ResponsesRequestSchema, FunctionToolSchema, type ResponsesRequest } from "./schema.js";
+
+function extractInputContent(content: string | Record<string, unknown>[]): string {
+  if (typeof content === "string") return content;
+  return content
+    .filter((b) => b["type"] === "input_text" || b["type"] === "text")
+    .map((b) => String(b["text"] ?? ""))
+    .join("\n");
+}
+
+function parseInput(req: ResponsesRequest): readonly Message[] {
+  const instructions: Message[] = req.instructions
+    ? [{ role: "system", content: req.instructions }]
+    : [];
+
+  if (req.input === undefined) return instructions;
+
+  if (typeof req.input === "string") {
+    return [...instructions, { role: "user", content: req.input }];
+  }
+
+  const messages = req.input.map((item): Message => {
+    if ("call_id" in item) {
+      return {
+        role: "tool",
+        content: "output" in item ? item.output : item.arguments,
+        toolCallId: item.call_id,
+      };
+    }
+    return {
+      role: item.role === "developer" ? "system" : item.role,
+      content: extractInputContent(item.content),
+    };
+  });
+
+  return [...instructions, ...messages];
+}
+
+function parseTools(req: ResponsesRequest): readonly ToolDef[] | undefined {
+  if (!req.tools) return undefined;
+  return req.tools
+    .map((t) => FunctionToolSchema.safeParse(t))
+    .filter((r) => r.success)
+    .map((r) => ({
+      name: r.data.name,
+      description: r.data.description,
+      parameters: r.data.parameters,
+    }));
+}
+
+export function parseRequest(body: unknown, meta?: RequestMeta): MockRequest {
+  const req = ResponsesRequestSchema.parse(body);
+  return buildMockRequest("responses", req, parseInput(req), parseTools(req), "codex-mini", body, meta);
+}

package/src/formats/responses/schema.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+
+const InputMessageSchema = z.object({
+  type: z.literal("message").optional(),
+  role: z.enum(["user", "assistant", "system", "developer"]),
+  content: z.union([z.string(), z.array(z.record(z.string(), z.unknown()))]),
+});
+
+const FunctionCallInputSchema = z.object({
+  type: z.literal("function_call"),
+  id: z.string().optional(),
+  call_id: z.string(),
+  name: z.string(),
+  arguments: z.string(),
+});
+
+const FunctionCallOutputSchema = z.object({
+  type: z.literal("function_call_output"),
+  call_id: z.string(),
+  output: z.string(),
+});
+
+const InputItemSchema = z.union([
+  InputMessageSchema,
+  FunctionCallInputSchema,
+  FunctionCallOutputSchema,
+]);
+
+const RawToolSchema = z.record(z.string(), z.unknown());
+
+export const FunctionToolSchema = z.object({
+  type: z.literal("function"),
+  name: z.string(),
+  description: z.string().optional(),
+  parameters: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type FunctionTool = z.infer<typeof FunctionToolSchema>;
+
+export const ResponsesRequestSchema = z.looseObject({
+  model: z.string().min(1).optional(),
+  input: z.union([z.string(), z.array(InputItemSchema)]).optional(),
+  instructions: z.string().optional(),
+  tools: z.array(RawToolSchema).optional(),
+  stream: z.boolean().optional(),
+  temperature: z.number().optional(),
+  previous_response_id: z.string().optional(),
+  background: z.boolean().optional(),
+  context_management: z.unknown().optional(),
+  conversation: z.unknown().optional(),
+  include: z.array(z.string()).optional(),
+  max_output_tokens: z.number().optional(),
+  max_tool_calls: z.number().optional(),
+  metadata: z.record(z.string(), z.string()).optional(),
+  parallel_tool_calls: z.boolean().optional(),
+  prompt: z.unknown().optional(),
+  prompt_cache_key: z.string().optional(),
+  prompt_cache_retention: z.string().optional(),
+  reasoning: z.unknown().optional(),
+  safety_identifier: z.string().optional(),
+  service_tier: z.string().optional(),
+  store: z.boolean().optional(),
+  stream_options: z.unknown().optional(),
+  text: z.unknown().optional(),
+  tool_choice: z.unknown().optional(),
+  top_logprobs: z.number().optional(),
+  top_p: z.number().optional(),
+  truncation: z.string().optional(),
+  user: z.string().optional(),
+});
+
+export type ResponsesRequest = z.infer<typeof ResponsesRequestSchema>;
+
+const OutputContentSchema = z.object({
+  type: z.string(),
+  text: z.string(),
+  annotations: z.array(z.unknown()).optional(),
+});
+
+const OutputItemSchema = z.object({
+  type: z.string(),
+  id: z.string().optional(),
+  status: z.string().optional(),
+  role: z.string().optional(),
+  content: z.array(OutputContentSchema).optional(),
+  call_id: z.string().optional(),
+  name: z.string().optional(),
+  arguments: z.string().optional(),
+  summary: z.array(z.object({ type: z.string(), text: z.string() })).optional(),
+});
+
+export type ResponsesOutputItem = z.infer<typeof OutputItemSchema>;
+
+export const ResponsesEventSchema = z.object({
+  type: z.string(),
+  sequence_number: z.number().optional(),
+  response: z.object({
+    id: z.string(),
+    object: z.string(),
+    created_at: z.number(),
+    model: z.string(),
+    status: z.string(),
+    output: z.array(OutputItemSchema),
+    usage: z.object({
+      input_tokens: z.number(),
+      output_tokens: z.number(),
+      total_tokens: z.number(),
+    }).optional(),
+  }).optional(),
+  item: OutputItemSchema.optional(),
+  part: z.object({
+    type: z.string(),
+    text: z.string().optional(),
+    annotations: z.array(z.unknown()).optional(),
+  }).optional(),
+  delta: z.string().optional(),
+  item_id: z.string().optional(),
+});
+
+export type ResponsesEvent = z.infer<typeof ResponsesEventSchema>;
+
+export const ResponsesCompleteSchema = z.object({
+  id: z.string(),
+  object: z.literal("response"),
+  created_at: z.number(),
+  status: z.literal("completed"),
+  model: z.string(),
+  output: z.array(OutputItemSchema),
+  usage: z.object({
+    input_tokens: z.number(),
+    output_tokens: z.number(),
+    total_tokens: z.number(),
+  }),
+});
+
+export type ResponsesComplete = z.infer<typeof ResponsesCompleteSchema>;
+
+export const ResponsesErrorSchema = z.object({
+  type: z.literal("error"),
+  error: z.object({ message: z.string(), type: z.string().optional(), code: z.string().optional() }),
+});
+
+export type ResponsesError = z.infer<typeof ResponsesErrorSchema>;

package/src/formats/responses/serialize.ts

@@ -0,0 +1,129 @@
+import type { ReplyObject, ReplyOptions, ToolCall } from "../../types.js";
+import type { SSEChunk } from "../types.js";
+import { splitText, genId, toolId, shouldEmitText, MS_PER_SECOND, DEFAULT_USAGE } from "../parse-helpers.js";
+
+interface StreamBlock { chunks: SSEChunk[]; outputItem: unknown }
+
+const NO_ANNOTATIONS: readonly unknown[] = [];
+
+type Chunk = (payload: Record<string, unknown>) => SSEChunk;
+
+function createChunk(): Chunk {
+  let seq = 0;
+  return (payload) => ({ data: JSON.stringify({ ...payload, sequence_number: seq++ }) });
+}
+
+function reasoningStreamBlock(c: Chunk, i: number, reasoning: string): StreamBlock {
+  const itemId = `rs_${genId("rs")}`;
+  const summaryPart = { type: "summary_text" as const, text: reasoning };
+  const item = { type: "reasoning", id: itemId, status: "completed", summary: [summaryPart] };
+
+  return {
+    outputItem: item,
+    chunks: [
+      c({ type: "response.output_item.added", output_index: i, item: { type: "reasoning", id: itemId, status: "in_progress", summary: [] } }),
+      c({ type: "response.reasoning_summary_part.added", item_id: itemId, output_index: i, summary_index: 0, part: { type: "summary_text", text: "" } }),
+      c({ type: "response.reasoning_summary_text.delta", item_id: itemId, output_index: i, summary_index: 0, delta: reasoning }),
+      c({ type: "response.reasoning_summary_text.done", item_id: itemId, output_index: i, summary_index: 0, text: reasoning }),
+      c({ type: "response.reasoning_summary_part.done", item_id: itemId, output_index: i, summary_index: 0, part: summaryPart }),
+      c({ type: "response.output_item.done", output_index: i, item }),
+    ],
+  };
+}
+
+function textStreamBlock(c: Chunk, i: number, text: string, chunkSize: number): StreamBlock {
+  const itemId = `msg_${genId("msg")}`;
+  const outputText = { type: "output_text" as const, text, annotations: NO_ANNOTATIONS };
+  const outputItem = { type: "message", id: itemId, status: "completed", role: "assistant", content: [outputText] };
+
+  return {
+    outputItem,
+    chunks: [
+      c({ type: "response.output_item.added", output_index: i, item: { type: "message", id: itemId, status: "in_progress", role: "assistant", content: [] } }),
+      c({ type: "response.content_part.added", item_id: itemId, output_index: i, content_index: 0, part: { type: "output_text", text: "", annotations: [] } }),
+      ...splitText(text, chunkSize).map((piece) =>
+        c({ type: "response.output_text.delta", item_id: itemId, output_index: i, content_index: 0, delta: piece }),
+      ),
+      c({ type: "response.output_text.done", item_id: itemId, output_index: i, content_index: 0, text }),
+      c({ type: "response.content_part.done", item_id: itemId, output_index: i, content_index: 0, part: outputText }),
+      c({ type: "response.output_item.done", output_index: i, item: outputItem }),
+    ],
+  };
+}
+
+function toolStreamBlock(c: Chunk, i: number, tool: ToolCall): StreamBlock {
+  const callId = toolId(tool, "call", i);
+  const argsJson = JSON.stringify(tool.args);
+  const outputItem = { type: "function_call", id: callId, status: "completed", name: tool.name, call_id: callId, arguments: argsJson };
+
+  return {
+    outputItem,
+    chunks: [
+      c({ type: "response.output_item.added", output_index: i, item: { ...outputItem, status: "in_progress", arguments: "" } }),
+      c({ type: "response.function_call_arguments.delta", item_id: callId, output_index: i, delta: argsJson }),
+      c({ type: "response.function_call_arguments.done", item_id: callId, output_index: i, arguments: argsJson }),
+      c({ type: "response.output_item.done", output_index: i, item: outputItem }),
+    ],
+  };
+}
+
+export function serialize(reply: ReplyObject, model: string, options: ReplyOptions = {}): readonly SSEChunk[] {
+  const id = genId("resp");
+  const createdAt = Math.floor(Date.now() / MS_PER_SECOND);
+  const usage = reply.usage ?? DEFAULT_USAGE;
+  const c = createChunk();
+  let i = 0;
+
+  const baseResponse = { id, object: "response", created_at: createdAt, model };
+  const header = [
+    c({ type: "response.created", response: { ...baseResponse, status: "in_progress", output: [] } }),
+    c({ type: "response.in_progress", response: { ...baseResponse, status: "in_progress", output: [] } }),
+  ];
+
+  const blocks: StreamBlock[] = [
+    ...(reply.reasoning ? [reasoningStreamBlock(c, i++, reply.reasoning)] : []),
+    ...(shouldEmitText(reply) ? [textStreamBlock(c, i++, reply.text ?? "", options.chunkSize ?? 0)] : []),
+    ...(reply.tools ?? []).map((tool) => toolStreamBlock(c, i++, tool)),
+  ];
+
+  const allChunks = blocks.flatMap((b) => b.chunks);
+  const output = blocks.map((b) => b.outputItem);
+
+  return [
+    ...header,
+    ...allChunks,
+    c({
+      type: "response.completed",
+      response: { ...baseResponse, status: "completed", output,
+        usage: { input_tokens: usage.input, output_tokens: usage.output, total_tokens: usage.input + usage.output } },
+    }),
+  ];
+}
+
+export function serializeComplete(reply: ReplyObject, model: string): unknown {
+  const id = genId("resp");
+  const createdAt = Math.floor(Date.now() / MS_PER_SECOND);
+  const usage = reply.usage ?? DEFAULT_USAGE;
+
+  const output: unknown[] = [
+    ...(reply.reasoning
+      ? [{ type: "reasoning", id: `rs_${genId("rs")}`, status: "completed", summary: [{ type: "summary_text", text: reply.reasoning }] }]
+      : []),
+    ...(shouldEmitText(reply)
+      ? [{ type: "message", id: `msg_${genId("msg")}`, status: "completed", role: "assistant", content: [{ type: "output_text", text: reply.text ?? "", annotations: [] }] }]
+      : []),
+    ...(reply.tools ?? []).map((tool) => {
+      const callId = toolId(tool, "call", 0);
+      return { type: "function_call", id: callId, status: "completed", name: tool.name, call_id: callId, arguments: JSON.stringify(tool.args) };
+    }),
+  ];
+
+  return {
+    id, object: "response", created_at: createdAt, status: "completed", model, output,
+    usage: { input_tokens: usage.input, output_tokens: usage.output, total_tokens: usage.input + usage.output },
+  };
+}
+
+export function serializeError(error: { status: number; message: string; type?: string }): unknown {
+  return { type: "error", error: { message: error.message, type: error.type ?? "server_error", code: error.type ?? "server_error" } };
+}

package/src/formats/types.ts

@@ -0,0 +1,17 @@
+import type { FormatName, MockRequest, ReplyObject, ReplyOptions } from "../types.js";
+import type { RequestMeta } from "./parse-helpers.js";
+
+export interface SSEChunk {
+  readonly event?: string | undefined;
+  readonly data: string;
+}
+
+export interface Format {
+  readonly name: FormatName;
+  readonly route: string;
+  parseRequest(body: unknown, meta?: RequestMeta): MockRequest;
+  isStreaming(body: unknown): boolean;
+  serialize(reply: ReplyObject, model: string, options?: ReplyOptions): readonly SSEChunk[];
+  serializeComplete(reply: ReplyObject, model: string): unknown;
+  serializeError(error: { status: number; message: string; type?: string | undefined }): unknown;
+}