Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,40 @@
+# ---- Build Stage ----
+FROM node:18-alpine AS builder
+
+# Install pnpm as root
+RUN corepack enable && corepack prepare pnpm@10.10.0 --activate
+
+USER node
+ENV HOME=/home/node \
+    PATH=/home/node/.local/bin:$PATH
+
+WORKDIR $HOME/app
+
+# Install dependencies and build
+COPY --chown=node package.json pnpm-lock.yaml* ./
+COPY --chown=node tsconfig.json ./
+COPY --chown=node src ./src
+RUN pnpm install --frozen-lockfile
+RUN pnpm run build
+RUN chown -R node:node $HOME/app
+
+# ---- Production Stage ----
+FROM node:18-alpine AS runner
+
+# No need to install pnpm here, just switch to node user
+USER node
+ENV HOME=/home/node \
+    PATH=/home/node/.local/bin:$PATH
+
+# Create app directory
+WORKDIR $HOME/app
+
+# Copy only necessary files from builder
+COPY --chown=node --from=builder /home/node/app/dist ./dist
+COPY --chown=node --from=builder /home/node/app/package.json ./
+COPY --chown=node --from=builder /home/node/app/node_modules ./node_modules
+
+# Use a non-root user for security
+EXPOSE 3000
+
+CMD ["node", "dist/index.js"]

README.md

@@ -1,12 +1,208 @@
 ---
-title: Openrespones
-emoji: 👀
-colorFrom: indigo
-colorTo: blue
-sdk: gradio
-sdk_version: 6.3.0
-app_file: app.py
+title: OpenResponses
+emoji: 😻
+colorFrom: red
+colorTo: red
+sdk: docker
 pinned: false
+license: mit
+short_description: Private space for OpenResponses
+app_port: 3000
+private: true
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# responses.js
+
+A lightweight Express.js server that implements a translation layer between the two main LLM APIs currently available, Responses API and Chat Completions. Works with any Chat Completion API, local or remotely hosted.
+
+## 🎮 Live Demo
+
+[**Try responses.js right now, no installation needed!**](https://huggingface.co/spaces/Wauplin/responses.js)
+
+## ✨ Features
+
+- **ResponsesAPI**: Partial implementation of [OpenAI's Responses API](https://platform.openai.com/docs/api-reference/responses), on top of Chat Completion API
+- **Provider Agnostic**: Works with any Chat Completion API (local or remote)
+- **Streaming Support**: Support for streamed responses
+- **Structured Output**: Support for structured data responses (e.g. jsonschema)
+- **Function Calling**: Tool and function calling capabilities
+- **Multi-modal Input**: Text and image input support
+- **Remote MCP**: Execute MCP tool calls remotely
+- **Demo UI**: Interactive web interface for testing
+
+Not implemented: remote function calling, file upload, stateful API, etc.
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js (v18 or higher)
+- pnpm (recommended) or npm
+- an Hugging Face token with inference permissions. Create one from your [user settings](https://huggingface.co/settings/tokens).
+
+### Installation & Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/huggingface/responses.js.git
+cd responses.js
+
+# Install dependencies
+pnpm install
+
+# Start the development server
+pnpm dev
+```
+
+The server will be available at `http://localhost:3000`.
+
+### Running Examples
+
+Explore the various capabilities with our example scripts located in the [./examples](./examples) folder:
+
+```bash
+# Basic text input
+pnpm run example text
+
+# Multi-turn conversations
+pnpm run example multi_turn
+
+# Text + image input
+pnpm run example image
+
+# Streaming responses
+pnpm run example streaming
+
+# Structured output
+pnpm run example structured_output
+pnpm run example structured_output_streaming
+
+# Function calling
+pnpm run example function
+pnpm run example function_streaming
+```
+
+## 🧪 Testing
+
+### Important Notes
+
+- Server must be running (`pnpm dev`) on `http://localhost:3000`
+- `API_KEY` environment variable set with your LLM provider's API key
+- Tests use real inference providers and may incur costs
+- Tests are not run in CI due to billing requirements
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run specific test patterns
+pnpm test --grep "streaming"
+pnpm test --grep "function"
+pnpm test --grep "structured"
+```
+
+### Interactive Demo UI
+
+Experience the API through our interactive web interface, adapted from the [openai-responses-starter-app](https://github.com/openai/openai-responses-starter-app).
+
+[![Demo Video](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/responses.js/demo_mini.png)](https://youtu.be/F-tAUnW-nd0)
+
+
+#### Setup
+
+1. Create a configuration file:
+
+```bash
+# Create demo/.env
+cat > demo/.env << EOF
+MODEL="moonshotai/Kimi-K2-Instruct:groq"
+OPENAI_BASE_URL=http://localhost:3000/v1
+OPENAI_API_KEY=${HF_TOKEN:-<your-huggingface-token>}
+EOF
+```
+
+2. Install demo dependencies:
+
+```bash
+pnpm demo:install
+```
+
+3. Launch the demo:
+
+```bash
+pnpm demo:dev
+```
+
+The demo will be available at `http://localhost:3001`.
+
+## 🐳 Running with Docker
+
+You can run the server in a production-ready container using Docker.
+
+### Build the Docker image
+
+```bash
+docker build -t responses.js .
+```
+
+### Run the server
+
+```bash
+docker run -p 3000:3000 responses.js
+```
+
+The server will be available at `http://localhost:3000`.
+
+## 📁 Project Structure
+
+```
+responses.js/
+├── demo/             # Interactive chat UI demo
+├── examples/         # Example scripts using openai-node client
+├── src/
+│   ├── index.ts      # Application entry point
+│   ├── server.ts     # Express app configuration and route definitions
+│   ├── routes/       # API route implementations
+│   ├── middleware/   # Middleware (validation, logging, etc.)
+│   └── schemas/      # Zod validation schemas
+├── scripts/          # Utility and build scripts
+├── package.json      # Package configuration and dependencies
+└── README.md         # This file
+```
+
+## 🛣️ Done / TODOs
+
+> **Note**: This project is in active development. The roadmap below represents our current priorities and may evolve. Do not take anything for granted.
+
+- [x] OpenAI types integration for consistent output
+- [x] Streaming mode support
+- [x] Structured output capabilities
+- [x] Function calling implementation
+- [x] Repository migration to dedicated responses.js repo
+- [x] Basic development tooling setup
+- [x] Demo application with comprehensive instructions
+- [x] Multi-turn conversation fixes for text messages + tool calls
+- [x] Correctly return "usage" field
+- [x] MCP support (non-streaming)
+- [x] MCP support (streaming)
+- [ ] Tools execution (web search, file search, image generation, code interpreter)
+- [ ] Background mode support
+- [ ] Additional API routes (GET, DELETE, CANCEL, LIST responses)
+- [ ] Reasoning capabilities
+
+## 🤝 Contributing
+
+We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Based on OpenAI's [Responses API specification](https://platform.openai.com/docs/api-reference/responses)
+- Built on top of [OpenAI's nodejs client](https://github.com/openai/openai-node)
+- Demo UI adapted from [openai-responses-starter-app](https://github.com/openai/openai-responses-starter-app)

package.json

@@ -0,0 +1,80 @@
+{
+	"name": "@huggingface/responses.js",
+	"packageManager": "pnpm@10.28.0+sha512.05df71d1421f21399e053fde567cea34d446fa02c76571441bfc1c7956e98e363088982d940465fd34480d4d90a0668bc12362f8aa88000a64e83d0b0e47be48",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Server for handling AI responses",
+	"repository": "https://github.com/huggingface/huggingface.js.git",
+	"publishConfig": {
+		"access": "public"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"require": "./dist/index.js",
+			"import": "./dist/index.mjs"
+		}
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"source": "index.ts",
+	"scripts": {
+		"build": "tsup src/*.ts --format cjs,esm --clean && tsc --emitDeclarationOnly --declaration",
+		"check": "tsc",
+		"dev": "tsx watch src/index.ts",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"lint": "eslint --quiet --fix --ext .cjs,.ts .",
+		"lint:check": "eslint --ext .cjs,.ts .",
+		"prepublishOnly": "pnpm run build",
+		"prepare": "pnpm run build",
+		"start": "node dist/index.js",
+		"example": "node examples/_run.js",
+		"demo:build": "cd demo && npm run build",
+		"demo:dev": "cd demo && npm run dev",
+		"demo:install": "cd demo && npm install",
+		"demo:lint": "cd demo && npm run lint",
+		"demo:format": "cd demo && npm run format",
+		"demo:start": "cd demo && npm run start",
+		"deploy:spaces": "./push_to_space.sh",
+		"test": "mocha --timeout 20000 \"tests/**/*.test.js\""
+	},
+	"files": [
+		"src",
+		"dist",
+		"tsconfig.json"
+	],
+	"keywords": [
+		"huggingface",
+		"ai",
+		"llm",
+		"responses-api",
+		"server"
+	],
+	"author": "Hugging Face",
+	"license": "MIT",
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.15.0",
+		"express": "^4.21.2",
+		"openai": "^5.8.2",
+		"zod": "^3.25.71"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.30.1",
+		"@types/express": "^4.17.23",
+		"@typescript-eslint/eslint-plugin": "^8.35.1",
+		"@typescript-eslint/parser": "^8.35.1",
+		"eslint": "^9.30.1",
+		"eslint-config-prettier": "^10.1.5",
+		"eslint-plugin-prettier": "^5.5.1",
+		"mocha": "^11.7.1",
+		"prettier": "^3.6.2",
+		"tsup": "^8.5.0",
+		"tsx": "^4.20.3",
+		"typescript": "^5.8.3"
+	}
+}

src/index.ts

@@ -0,0 +1,26 @@
+import { createApp } from "./server.js";
+
+const app = createApp();
+const port = process.env.PORT || 3000;
+
+// Start server
+app.listen(port, () => {
+	console.log(`🚀 Server started at ${new Date().toISOString()}`);
+	console.log(`🌐 Server is running on http://localhost:${port}`);
+	console.log("─".repeat(60));
+});
+
+// Graceful shutdown logging
+process.on("SIGINT", () => {
+	console.log("─".repeat(60));
+	console.log(`🛑 Server shutting down at ${new Date().toISOString()}`);
+	process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+	console.log("─".repeat(60));
+	console.log(`🛑 Server shutting down at ${new Date().toISOString()}`);
+	process.exit(0);
+});
+
+export default app;

src/lib/McpResultFormatter.ts

@@ -0,0 +1,92 @@
+/**
+ * Vendored from `@huggingface/mcp-client`
+ *
+ * https://github.com/huggingface/huggingface.js/blob/main/packages/mcp-client/src/ResultFormatter.ts
+ */
+
+import type {
+	TextResourceContents,
+	BlobResourceContents,
+	CompatibilityCallToolResult,
+} from "@modelcontextprotocol/sdk/types";
+
+/**
+ * A utility class for formatting CallToolResult contents into human-readable text.
+ * Processes different content types, extracts text, and summarizes binary data.
+ */
+export class McpResultFormatter {
+	/**
+	 * Formats a CallToolResult's contents into a single string.
+	 * - Text content is included directly
+	 * - Binary content (images, audio, blobs) is summarized
+	 *
+	 * @param result The CallToolResult to format
+	 * @returns A human-readable string representation of the result contents
+	 */
+	static format(result: CompatibilityCallToolResult): string {
+		if (!result.content || !Array.isArray(result.content) || result.content.length === 0) {
+			return "[No content]";
+		}
+
+		const formattedParts: string[] = [];
+
+		for (const item of result.content) {
+			switch (item.type) {
+				case "text":
+					// Extract text content directly
+					formattedParts.push(item.text);
+					break;
+
+				case "image": {
+					// Summarize image content
+					const imageSize = this.getBase64Size(item.data);
+					formattedParts.push(
+						`[Binary Content: Image ${item.mimeType}, ${imageSize} bytes]\nThe task is complete and the content accessible to the User`
+					);
+					break;
+				}
+
+				case "audio": {
+					// Summarize audio content
+					const audioSize = this.getBase64Size(item.data);
+					formattedParts.push(
+						`[Binary Content: Audio ${item.mimeType}, ${audioSize} bytes]\nThe task is complete and the content accessible to the User`
+					);
+					break;
+				}
+
+				case "resource":
+					// Handle embedded resources - explicitly type the resource
+					if ("text" in item.resource) {
+						// It's a text resource with a text property
+						const textResource = item.resource as TextResourceContents;
+						formattedParts.push(textResource.text);
+					} else if ("blob" in item.resource) {
+						// It's a binary resource with a blob property
+						const blobResource = item.resource as BlobResourceContents;
+						const blobSize = this.getBase64Size(blobResource.blob);
+						const uri = blobResource.uri ? ` (${blobResource.uri})` : "";
+						const mimeType = blobResource.mimeType ? blobResource.mimeType : "unknown type";
+						formattedParts.push(
+							`[Binary Content${uri}: ${mimeType}, ${blobSize} bytes]\nThe task is complete and the content accessible to the User`
+						);
+					}
+					break;
+			}
+		}
+
+		return formattedParts.join("\n");
+	}
+
+	/**
+	 * Calculates the approximate size in bytes of base64-encoded data
+	 */
+	private static getBase64Size(base64: string): number {
+		// Remove base64 header if present (e.g., data:image/png;base64,)
+		const cleanBase64 = base64.includes(",") ? base64.split(",")[1] : base64;
+
+		// Calculate size: Base64 encodes 3 bytes into 4 characters
+		const padding = cleanBase64.endsWith("==") ? 2 : cleanBase64.endsWith("=") ? 1 : 0;
+		return Math.floor((cleanBase64.length * 3) / 4 - padding);
+	}
+}

src/lib/buildProviderScopedModel.ts

@@ -0,0 +1,15 @@
+export function buildProviderScopedModel(model: string, provider?: string | null): string {
+	if (!provider) {
+		return model;
+	}
+
+	const trimmedProvider = provider.trim();
+	if (!trimmedProvider) {
+		return model;
+	}
+
+	const colonIndex = model.indexOf(":");
+	const baseModel = colonIndex === -1 ? model : model.slice(0, colonIndex);
+
+	return `${baseModel}:${trimmedProvider}`;
+}

src/lib/generateUniqueId.ts

@@ -0,0 +1,11 @@
+/**
+ * AI-generated file using Cursor + Claude 4
+ *
+ * Generate a unique ID for the response
+ */
+import { randomBytes } from "crypto";
+
+export function generateUniqueId(prefix?: string): string {
+	const id = randomBytes(24).toString("hex");
+	return prefix ? `${prefix}_${id}` : id;
+}

src/mcp.ts

@@ -0,0 +1,56 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { version as packageVersion } from "../package.json";
+import { URL } from "url";
+
+import type { McpServerParams } from "./schemas";
+import { McpResultFormatter } from "./lib/McpResultFormatter";
+
+export async function connectMcpServer(mcpServer: McpServerParams): Promise<Client> {
+	const mcp = new Client({ name: "@huggingface/responses.js", version: packageVersion });
+
+	// Try to connect with http first, if that fails, try sse
+	const url = new URL(mcpServer.server_url);
+	const options = {
+		requestInit: mcpServer.headers
+			? {
+					headers: mcpServer.headers,
+				}
+			: undefined,
+	};
+	try {
+		const transport = new StreamableHTTPClientTransport(url, options);
+		await mcp.connect(transport);
+	} catch {
+		const transport = new SSEClientTransport(url, options);
+		await mcp.connect(transport);
+	}
+
+	console.log("Connected to MCP server", mcpServer.server_url);
+
+	return mcp;
+}
+
+export async function callMcpTool(
+	mcpServer: McpServerParams,
+	toolName: string,
+	argumentsString: string
+): Promise<{ error: string; output?: undefined } | { error?: undefined; output: string }> {
+	try {
+		const client = await connectMcpServer(mcpServer);
+		const toolArgs: Record<string, unknown> = argumentsString === "" ? {} : JSON.parse(argumentsString);
+		console.log(`Calling MCP tool '${toolName}'`);
+		const toolResponse = await client.callTool({ name: toolName, arguments: toolArgs });
+		const formattedResult = McpResultFormatter.format(toolResponse);
+		return {
+			output: formattedResult,
+		};
+	} catch (error) {
+		const errorMessage =
+			error instanceof Error ? error.message : typeof error === "string" ? error : JSON.stringify(error);
+		return {
+			error: errorMessage,
+		};
+	}
+}

src/middleware/logging.ts

@@ -0,0 +1,68 @@
+/**
+ * AI-generated file using Cursor + Claude 4
+ *
+ * Middleware to log all HTTP requests with duration, status code, method, and route
+ */
+import { type Request, type Response, type NextFunction } from "express";
+
+interface LogContext {
+	timestamp: string;
+	method: string;
+	url: string;
+	statusCode?: number;
+	duration?: number;
+}
+
+function formatLogMessage(context: LogContext): string {
+	const { timestamp, method, url, statusCode, duration } = context;
+
+	if (statusCode === undefined) {
+		return `[${timestamp}] 📥 ${method} ${url}`;
+	}
+
+	const statusEmoji =
+		statusCode >= 200 && statusCode < 300
+			? "✅"
+			: statusCode >= 400 && statusCode < 500
+				? "⚠️"
+				: statusCode >= 500
+					? "❌"
+					: "ℹ️";
+	return `[${timestamp}] ${statusEmoji} ${statusCode} ${method} ${url} (${duration}ms)`;
+}
+
+/**
+ * Middleware to log all HTTP requests with duration, status code, method, and route
+ */
+export function requestLogger() {
+	return (req: Request, res: Response, next: NextFunction): void => {
+		const startTime = Date.now();
+		const { method, url } = req;
+
+		// Log incoming request
+		console.log(
+			formatLogMessage({
+				timestamp: new Date().toISOString(),
+				method,
+				url,
+			})
+		);
+
+		// Listen for when the response finishes
+		res.on("finish", () => {
+			const duration = Date.now() - startTime;
+
+			console.log(
+				formatLogMessage({
+					timestamp: new Date().toISOString(),
+					method,
+					url,
+					statusCode: res.statusCode,
+					duration,
+				})
+			);
+		});
+
+		next();
+	};
+}

src/middleware/validation.ts

@@ -0,0 +1,42 @@
+/**
+ * AI-generated file using Cursor + Claude 4
+ */
+
+import { type Request, type Response, type NextFunction } from "express";
+import { z } from "zod";
+
+/**
+ * Middleware to validate request body against a Zod schema
+ * @param schema - Zod schema to validate against
+ * @returns Express middleware function
+ */
+export function validateBody<T extends z.ZodTypeAny>(schema: T) {
+	return (req: Request, res: Response, next: NextFunction): void => {
+		try {
+			const validatedBody = schema.parse(req.body);
+			req.body = validatedBody;
+			next();
+		} catch (error) {
+			if (error instanceof z.ZodError) {
+				console.log(req.body);
+				res.status(400).json({
+					success: false,
+					error: error.errors,
+					details: error.errors,
+				});
+			} else {
+				res.status(500).json({
+					success: false,
+					error: "Internal server error",
+				});
+			}
+		}
+	};
+}
+
+/**
+ * Type helper to create a properly typed request with validated body
+ */
+export interface ValidatedRequest<T> extends Request {
+	body: T;
+}

src/openai_patch.ts

@@ -0,0 +1,92 @@
+/*
+ * This file patches OpenAI SDK types for OpenResponses spec compliance.
+ *
+ * The OpenAI SDK uses event type names like "response.reasoning_text.delta",
+ * but the OpenResponses spec uses "response.reasoning.delta" (without "_text").
+ * We maintain custom event types here to match the OpenResponses specification.
+ *
+ * Once the OpenAI SDK aligns with OpenResponses spec, this file can be simplified.
+ */
+import type {
+	ResponseReasoningItem as OpenAIResponseReasoningItem,
+	ResponseStreamEvent as OpenAIResponseStreamEvent,
+	ResponseOutputRefusal,
+	ResponseOutputText,
+	ResponseContentPartAddedEvent,
+	ResponseContentPartDoneEvent,
+	ResponseTextDeltaEvent,
+	ResponseTextDoneEvent,
+} from "openai/resources/responses/responses";
+
+import type { ChatCompletionChunk } from "openai/resources/chat/completions";
+
+export interface ReasoningTextContent {
+	type: "reasoning_text";
+	text: string;
+}
+
+export type PatchedResponseReasoningItem = OpenAIResponseReasoningItem & {
+	// Raw CoT returned in reasoning item (in addition to the summary)
+	content: ReasoningTextContent[];
+};
+
+// Custom event types for OpenResponses spec (differs from SDK's "response.reasoning_text.*")
+interface PatchedResponseReasoningDeltaEvent {
+	type: "response.reasoning.delta";
+	sequence_number: number;
+	item_id: string;
+	output_index: number;
+	content_index: number;
+	delta: string;
+}
+
+interface PatchedResponseReasoningDoneEvent {
+	type: "response.reasoning.done";
+	sequence_number: number;
+	item_id: string;
+	output_index: number;
+	content_index: number;
+	text: string;
+}
+
+export type PatchedResponseStreamEvent =
+	| OpenAIResponseStreamEvent
+	| PatchedResponseReasoningDeltaEvent
+	| PatchedResponseReasoningDoneEvent
+	| PatchedResponseContentPartAddedEvent
+	| PatchedResponseContentPartDoneEvent
+	| PatchedResponseOutputTextDeltaEvent
+	| PatchedResponseOutputTextDoneEvent;
+
+export type PatchedResponseContentPart = ResponseOutputText | ResponseOutputRefusal | ReasoningTextContent;
+
+export interface PatchedResponseOutputTextDeltaEvent extends ResponseTextDeltaEvent {
+	logprobs: unknown[];
+}
+
+export interface PatchedResponseOutputTextDoneEvent extends ResponseTextDoneEvent {
+	logprobs: unknown[];
+}
+
+interface PatchedResponseContentPartAddedEvent {
+	content_index: number;
+	item_id: string;
+	output_index: number;
+	part: PatchedResponseContentPart;
+	sequence_number: number;
+	type: "response.content_part.added";
+}
+
+interface PatchedResponseContentPartDoneEvent {
+	content_index: number;
+	item_id: string;
+	output_index: number;
+	part: PatchedResponseContentPart;
+	sequence_number: number;
+	type: "response.content_part.done";
+}
+
+export type PatchedDeltaWithReasoning = ChatCompletionChunk.Choice.Delta & {
+	reasoning?: string;
+	reasoning_content?: string;
+};

src/routes/health.ts

@@ -0,0 +1,5 @@
+import type { Request, Response } from "express";
+
+export function getHealth(req: Request, res: Response): void {
+	res.send("OK");
+}

src/routes/index.ts

@@ -0,0 +1,3 @@
+export { postCreateResponse } from "./responses.js";
+export { getLandingPageHtml } from "./landingPageHtml.js";
+export { getHealth } from "./health.js";

src/routes/landingPageHtml.ts

@@ -0,0 +1,724 @@
+import type { Request, Response } from "express";
+
+export function getLandingPageHtml(req: Request, res: Response): void {
+	const host = req.get("host");
+	const protocol = host && host.endsWith(".hf.space") ? "https" : req.protocol;
+	const baseUrl = `${protocol}://${host}/v1`;
+	res.setHeader("Content-Type", "text/html; charset=utf-8");
+	res.send(`
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>responses.js – OpenAI-compatible Responses API</title>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      --primary: #2563eb;
+      --primary-dark: #1e40af;
+      --accent: #fbbf24;
+      --bg: #f8fafc;
+      --card-bg: #fff;
+      --border: #e5e7eb;
+      --text: #1e293b;
+      --muted: #64748b;
+      --radius: 14px;
+      --shadow: 0 4px 24px #0002;
+    }
+    html, body {
+      height: 100%;
+      max-width: 100vw;
+      overflow-x: hidden;
+    }
+    body {
+      font-family: 'Inter', Arial, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      margin: 0;
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .header-inner, main, .hero, .api-endpoint-box, .features, .feature-card, .examples-section, .more-info-footer {
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .sticky-header {
+      position: sticky;
+      top: 0;
+      z-index: 100;
+      background: linear-gradient(90deg, var(--primary) 0%, #60a5fa 100%);
+      color: #fff;
+      box-shadow: 0 2px 12px #0001;
+      width: 100%;
+    }
+    .header-inner {
+      max-width: 1100px;
+      margin: 0 auto;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 1.5rem 1.5rem 1.2rem 1.5rem;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .header-title {
+      display: flex;
+      align-items: center;
+      gap: 0.8rem;
+      min-width: 0;
+    }
+    .header-title svg {
+      height: 2.2rem;
+      width: 2.2rem;
+      display: block;
+    }
+    .header-title h1 {
+      font-size: 2.1rem;
+      font-weight: 700;
+      margin: 0;
+      letter-spacing: -1px;
+      white-space: pre-line;
+      word-break: break-word;
+      overflow-wrap: anywhere;
+    }
+    .github-btn {
+      background: #fff2;
+      color: #fff;
+      border: 1.5px solid #fff4;
+      border-radius: 8px;
+      padding: 0.6em 1.3em;
+      font-weight: 600;
+      font-size: 1.05em;
+      text-decoration: none;
+      display: flex;
+      align-items: center;
+      gap: 0.5em;
+      transition: background 0.2s, color 0.2s;
+      min-width: 0;
+    }
+    .github-btn:hover {
+      background: #fff;
+      color: var(--primary-dark);
+    }
+    main {
+      flex: 1;
+      max-width: 900px;
+      margin: 0 auto;
+      padding: 2.5rem 1.2rem 1.5rem 1.2rem;
+      display: flex;
+      flex-direction: column;
+      gap: 2.5rem;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .hero {
+      background: linear-gradient(120deg, #dbeafe 0%, #f0fdf4 100%);
+      border-radius: var(--radius);
+      box-shadow: var(--shadow);
+      padding: 2.5rem 2rem 2rem 2rem;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      text-align: center;
+      position: relative;
+      overflow: hidden;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .hero h2 {
+      font-size: 2rem;
+      font-weight: 700;
+      margin: 0 0 0.7rem 0;
+      color: var(--primary-dark);
+      word-break: break-word;
+      overflow-wrap: anywhere;
+    }
+    .hero p {
+      font-size: 1.18rem;
+      color: var(--muted);
+      margin: 0 0 1.5rem 0;
+      word-break: break-word;
+      overflow-wrap: anywhere;
+    }
+    .api-endpoint-box {
+      background: #fff;
+      border: 2px solid var(--primary);
+      border-radius: 12px;
+      padding: 1.3rem 1.2rem 1.3rem 1.2rem;
+      margin: 1.5rem 0 1.5rem 0;
+      text-align: center;
+      font-size: 1.18rem;
+      box-shadow: 0 2px 8px #174ea610;
+      position: relative;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 0.5em;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .api-endpoint-url {
+      display: inline-block;
+      background: #f1f5f9;
+      color: var(--primary-dark);
+      font-family: 'Fira Mono', 'Consolas', monospace;
+      font-size: 1.15em;
+      padding: 0.3em 0.7em;
+      border-radius: 6px;
+      border: 1px solid #cbd5e1;
+      margin: 0.5em 0 0.5em 0;
+      word-break: break-all;
+      overflow-wrap: anywhere;
+      max-width: 100%;
+    }
+    .copy-endpoint-btn {
+      position: absolute;
+      top: 16px;
+      right: 16px;
+      background: var(--primary);
+      color: #fff;
+      border: none;
+      border-radius: 4px;
+      padding: 0.3em 1em;
+      font-size: 1em;
+      cursor: pointer;
+      opacity: 0.85;
+      transition: background 0.2s, opacity 0.2s;
+      z-index: 2;
+      min-width: 0;
+    }
+    .copy-endpoint-btn:hover { background: var(--primary-dark); opacity: 1; }
+    .copy-endpoint-btn.copied { background: #388e3c; color: #fff; opacity: 1; }
+    .cta {
+      margin: 1.5rem auto 0 auto;
+      background: var(--primary);
+      color: #fff;
+      text-decoration: none;
+      font-weight: bold;
+      padding: 1rem 2.5rem;
+      border-radius: 8px;
+      font-size: 1.2rem;
+      transition: background 0.2s;
+      box-shadow: 0 2px 8px #2563eb20;
+      display: inline-block;
+      max-width: 100%;
+    }
+    .cta:hover { background: var(--primary-dark); }
+    .features {
+      display: grid;
+      grid-template-columns: repeat(2, 1fr); /* 2 columns for 2x2 grid */
+      gap: 1.5rem;
+      margin: 2rem 0 0 0;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .feature-card {
+      background: var(--card-bg);
+      border-radius: var(--radius);
+      box-shadow: 0 1px 6px #0001;
+      padding: 1.2rem 1.3rem;
+      border: 1.5px solid var(--border);
+      display: flex;
+      flex-direction: column;
+      align-items: flex-start;
+      gap: 0.5em;
+      min-height: 120px;
+      position: relative;
+      transition: box-shadow 0.2s, border 0.2s;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .feature-card:hover {
+      box-shadow: 0 4px 16px #2563eb22;
+      border: 1.5px solid var(--primary);
+    }
+    .feature-card b {
+      font-size: 1.08em;
+      color: var(--primary-dark);
+    }
+    .examples-section {
+      margin-top: 2.5rem;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .examples-tabs {
+      display: flex;
+      gap: 0.5em;
+      margin-bottom: 1.2em;
+      border-bottom: 2px solid #e5e7eb;
+      width: 100%;
+      box-sizing: border-box;
+      min-width: 0;
+    }
+    .examples-tab {
+      background: none;
+      border: none;
+      font-size: 1.08em;
+      font-weight: 600;
+      color: var(--muted);
+      padding: 0.7em 1.2em 0.5em 1.2em;
+      cursor: pointer;
+      border-radius: 8px 8px 0 0;
+      transition: color 0.2s, background 0.2s;
+      min-width: 0;
+    }
+    .examples-tab.active {
+      color: var(--primary-dark);
+      background: #fff;
+      border-bottom: 2px solid var(--primary);
+    }
+    .example-panel { display: none; }
+    .example-panel.active { display: block; }
+    pre {
+      background: #f4f4f8;
+      border-radius: 8px;
+      padding: 1.1rem 1rem 1.1rem 1rem;
+      overflow-x: auto;
+      font-size: 0.98rem;
+      position: relative;
+      margin: 0.5em 0 0.5em 0;
+      width: 100%;
+      box-sizing: border-box;
+      max-width: 100vw;
+    }
+    code {
+      font-family: 'Fira Mono', 'Consolas', monospace;
+      font-size: 1em;
+      background: none;
+      color: #222;
+      word-break: break-word;
+      overflow-wrap: anywhere;
+      max-width: 100%;
+      display: block;
+    }
+    .copy-btn {
+      position: absolute;
+      top: 10px;
+      right: 10px;
+      background: #e0e4ea;
+      border: none;
+      border-radius: 4px;
+      padding: 0.2em 0.7em;
+      font-size: 0.95em;
+      color: var(--primary-dark);
+      cursor: pointer;
+      opacity: 0.7;
+      transition: opacity 0.2s, background 0.2s;
+      z-index: 2;
+      min-width: 0;
+    }
+    .copy-btn:hover { opacity: 1; background: #c9d3e6; }
+    .copy-btn.copied { color: #388e3c; background: #d0f5dd; opacity: 1; }
+    .more-info-footer {
+      background: #f1f5f9;
+      border-top: 1.5px solid #e5e7eb;
+      margin-top: 3rem;
+      padding: 2rem 1rem 1.5rem 1rem;
+      border-radius: 0 0 var(--radius) var(--radius);
+      text-align: center;
+      color: var(--muted);
+      font-size: 1.08em;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .more-info-footer ul {
+      list-style: none;
+      padding: 0;
+      margin: 0.5em 0 0 0;
+      display: flex;
+      flex-wrap: wrap;
+      gap: 1.5em;
+      justify-content: center;
+      width: 100%;
+      box-sizing: border-box;
+    }
+    .more-info-footer a {
+      color: var(--primary-dark);
+      text-decoration: none;
+      font-weight: 500;
+      transition: color 0.2s;
+    }
+    .more-info-footer a:hover { color: var(--primary); }
+    @media (max-width: 700px) {
+      .header-inner {
+        flex-direction: row;
+        align-items: center;
+        gap: 1.2em;
+        width: 100%;
+        flex-wrap: nowrap;
+      }
+      .header-title { flex-shrink: 1; min-width: 0; }
+      .github-btn { margin-left: auto; }
+      .header-title h1 { font-size: 1.5rem; }
+      main { padding: 1.2rem; }
+      .hero { padding: 1.2rem 0.7rem 1.2rem 0.7rem; }
+      .features { grid-template-columns: 1fr; gap: 1.1rem; }
+      .feature-card { min-height: unset; font-size: 0.98em; }
+      .api-endpoint-box { padding: 1rem 0.7rem; font-size: 1em; }
+      .api-endpoint-url { font-size: 1em; }
+      .cta { padding: 0.8rem 1.5rem; font-size: 1rem; }
+      .examples-section { margin-top: 1.5rem; }
+      .examples-tabs { flex-wrap: wrap; gap: 0.2em; }
+      .examples-tab { font-size: 1em; padding: 0.5em 0.7em 0.4em 0.7em; }
+      pre { font-size: 0.92rem; padding: 0.8rem 0.5rem; }
+      .copy-btn { top: 6px; right: 6px; font-size: 0.9em; padding: 0.15em 0.5em; }
+      .api-endpoint-box > div[style*="font-size"] {
+        font-size: 0.95em !important;
+        white-space: normal;
+        word-break: break-word;
+        overflow-wrap: anywhere;
+      }
+    }
+    @media (max-width: 500px) {
+      .header-inner { padding: 1rem 0.5rem 1rem 0.5rem; }
+      .header-title h1 { font-size: 1.1rem; }
+      .header-title svg, .header-title img { height: 2.2rem !important; width: 2.2rem !important; }
+      main { padding: 0.5rem; }
+      .hero { padding: 0.7rem 0.2rem 0.7rem 0.2rem; }
+      .features { gap: 0.7rem; }
+      .feature-card { padding: 0.7rem 0.5rem; font-size: 0.92em; }
+      .api-endpoint-box { padding: 0.7rem 0.3rem; font-size: 0.95em; }
+      .api-endpoint-url { font-size: 0.95em; }
+      .cta { padding: 0.6rem 1rem; font-size: 0.95rem; }
+      .examples-section { margin-top: 1rem; }
+      .examples-tabs { gap: 0.1em; }
+      .examples-tab { font-size: 0.95em; padding: 0.4em 0.5em 0.3em 0.5em; }
+      pre { font-size: 0.88rem; padding: 0.6rem 0.2rem; }
+      .copy-btn { top: 4px; right: 4px; font-size: 0.85em; padding: 0.1em 0.3em; }
+      .more-info-footer { font-size: 0.98em; padding: 1rem 0.2rem 1rem 0.2rem; }
+      .api-endpoint-box > div[style*="font-size"] {
+        font-size: 0.88em !important;
+      }
+    }
+    /* Make code blocks and tabs horizontally scrollable on small screens */
+    @media (max-width: 700px) {
+      .examples-tabs { overflow-x: auto; }
+      pre { overflow-x: auto; }
+    }
+  </style>
+  <!-- Prism.js for syntax highlighting -->
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-javascript.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-python.min.js"></script>
+  <script>
+    function copyCode(btn) {
+      const pre = btn.parentElement;
+      const code = pre.querySelector('code');
+      if (!code) return;
+      const text = code.innerText;
+      navigator.clipboard.writeText(text).then(() => {
+        btn.textContent = 'Copied!';
+        btn.classList.add('copied');
+        setTimeout(() => {
+          btn.textContent = 'Copy';
+          btn.classList.remove('copied');
+        }, 1200);
+      });
+    }
+    function copyEndpointUrl(btn) {
+      const url = document.getElementById('api-endpoint-url').innerText;
+      navigator.clipboard.writeText(url).then(() => {
+        btn.textContent = 'Copied!';
+        btn.classList.add('copied');
+        setTimeout(() => {
+          btn.textContent = 'Copy';
+          btn.classList.remove('copied');
+        }, 1200);
+      });
+    }
+    // Tabs for examples
+    function showExampleTab(idx) {
+      document.querySelectorAll('.examples-tab').forEach((tab, i) => {
+        tab.classList.toggle('active', i === idx);
+      });
+      document.querySelectorAll('.example-panel').forEach((panel, i) => {
+        panel.classList.toggle('active', i === idx);
+      });
+    }
+    window.addEventListener('DOMContentLoaded', function() {
+      showExampleTab(0);
+      document.querySelectorAll('.examples-tab').forEach((tab, i) => {
+        tab.addEventListener('click', () => showExampleTab(i));
+      });
+    });
+  </script>
+</head>
+<body>
+  <header class="sticky-header">
+    <div class="header-inner">
+      <div class="header-title">
+        <img src="https://huggingface.co/datasets/huggingface/brand-assets/resolve/main/hf-logo.svg" alt="Hugging Face Logo" style="height:4.0rem;width:4.0rem;display:block;"/>
+        <h1>open responses</h1>
+      </div>
+      <a href="https://github.com/huggingface/responses.js" target="_blank" aria-label="GitHub Repository" class="github-btn">
+        <svg height="20" width="20" viewBox="0 0 16 16" fill="currentColor" style="display: block;"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.19 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
+        GitHub
+      </a>
+    </div>
+  </header>
+  <main>
+    <section class="hero">
+      <h2>Open Responses Compatible API</h2>
+      <p style="text-wrap: balance;">
+        <b>Open Responses</b> is an open-source specification and ecosystem for building multi-provider, interoperable LLM interfaces based on the OpenAI Responses API.
+      </p>
+      <div class="api-endpoint-box">
+        <button class="copy-endpoint-btn" onclick="copyEndpointUrl(this)">Copy</button>
+        <div><b>API Endpoint:</b></div>
+        <span class="api-endpoint-url" id="api-endpoint-url">${baseUrl}</span>
+        <div style="font-size:0.98em; color:#333; margin-top:0.5em;">Get started by sending requests to this endpoint</div>
+      </div>
+      <a class="cta" href="https://github.com/huggingface/responses.js" target="_blank">View on GitHub</a>
+    </section>
+    <section>
+      <div class="features">
+        <div class="feature-card">
+          <b>Open Responses Compatible</b><br>Connect to Hugging Face Inference Providers with <a href="https://openresponses.org" target="_blank">Open Responses</a>
+        </div>
+        <div class="feature-card">
+          <b>Provider Agnostic</b><br>Configurable to work any Chat Completion API back-end (local or remote).
+        </div>
+        <div class="feature-card">
+          <b>Multi-modal, streaming, structured output</b><br>Supports text and image inputs, streaming output, JSON schema, and function calling.
+        </div>
+        <div class="feature-card">
+          <b>Remote MCP</b><br>Server-side MCP tool execution.
+        </div>
+      </div>
+    </section>
+    <section class="examples-section">
+      <h2 style="color:var(--primary-dark);margin-bottom:1.2em;">Examples</h2>
+      <div class="examples-tabs">
+        <button class="examples-tab active" type="button">Text</button>
+        <button class="examples-tab" type="button">Text + Image Input</button>
+        <button class="examples-tab" type="button">Multi-turn</button>
+        <button class="examples-tab" type="button">Streaming</button>
+        <button class="examples-tab" type="button">Function Calling</button>
+        <button class="examples-tab" type="button">Structured Output</button>
+        <button class="examples-tab" type="button">MCP</button>
+        <button class="examples-tab" type="button">Reasoning</button>
+      </div>
+      <div class="example-panel active">
+        <pre><button class="copy-btn" onclick="copyCode(this)">Copy</button><code class="language-python">from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="${baseUrl}",
+    api_key=os.getenv("HF_TOKEN"), # visit https://huggingface.co/settings/tokens
+)
+
+response = client.responses.create(
+    model="moonshotai/Kimi-K2-Instruct:groq",
+    instructions="You are a helpful assistant.",
+    input="Tell me a three sentence bedtime story about a unicorn.",
+)
+
+print(response)
+print(response.output_text)</code></pre>
+      </div>
+      <div class="example-panel">
+        <pre><button class="copy-btn" onclick="copyCode(this)">Copy</button><code class="language-python">from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="${baseUrl}",
+    api_key=os.getenv("HF_TOKEN"), # visit https://huggingface.co/settings/tokens
+)
+
+response = client.responses.create(
+    model="Qwen/Qwen2.5-VL-7B-Instruct",
+    input=[
+        {
+            "role": "user",
+            "content": [
+                {"type": "input_text", "text": "what is in this image?"},
+                {
+                    "type": "input_image",
+                    "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
+                },
+            ],
+        }
+    ],
+)
+
+print(response)
+print(response.output_text)</code></pre>
+      </div>
+      <div class="example-panel">
+        <pre><button class="copy-btn" onclick="copyCode(this)">Copy</button><code class="language-python">from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="${baseUrl}",
+    api_key=os.getenv("HF_TOKEN"), # visit https://huggingface.co/settings/tokens
+)
+
+response = client.responses.create(
+    model="moonshotai/Kimi-K2-Instruct:groq",
+    input=[
+        {
+            "role": "developer",
+            "content": "Talk like a pirate.",
+        },
+        {
+            "role": "user",
+            "content": "Are semicolons optional in JavaScript?",
+        },
+    ],
+)
+
+print(response)
+print(response.output_text)</code></pre>
+      </div>
+      <div class="example-panel">
+        <pre><button class="copy-btn" onclick="copyCode(this)">Copy</button><code class="language-python">from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="${baseUrl}",
+    api_key=os.getenv("HF_TOKEN"), # visit https://huggingface.co/settings/tokens
+)
+
+stream = client.responses.create(
+    model="moonshotai/Kimi-K2-Instruct:groq",
+    input=[
+        {
+            "role": "user",
+            "content": "Say 'double bubble bath' ten times fast.",
+        },
+    ],
+    stream=True,
+)
+
+for event in stream:
+    print(event)</code></pre>
+      </div>
+      <div class="example-panel">
+        <pre><button class="copy-btn" onclick="copyCode(this)">Copy</button><code class="language-python">from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="${baseUrl}",
+    api_key=os.getenv("HF_TOKEN"), # visit https://huggingface.co/settings/tokens
+)
+
+tools = [
+    {
+        "type": "function",
+        "name": "get_current_weather",
+        "description": "Get the current weather in a given location",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
+                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
+            },
+            "required": ["location", "unit"],
+        },
+    }
+]
+
+response = client.responses.create(
+    model="moonshotai/Kimi-K2-Instruct:groq",
+    tools=tools,
+    input="What is the weather like in Boston today?",
+    tool_choice="auto",
+)
+
+print(response)</code></pre>
+      </div>
+      <div class="example-panel">
+        <pre><button class="copy-btn" onclick="copyCode(this)">Copy</button><code class="language-python">from openai import OpenAI
+from pydantic import BaseModel
+import os
+
+client = OpenAI(
+    base_url="${baseUrl}",
+    api_key=os.getenv("HF_TOKEN"), # visit https://huggingface.co/settings/tokens
+)
+
+class CalendarEvent(BaseModel):
+    name: str
+    date: str
+    participants: list[str]
+
+response = client.responses.parse(
+    model="moonshotai/Kimi-K2-Instruct:groq",
+    input=[
+        {"role": "system", "content": "Extract the event information."},
+        {
+            "role": "user",
+            "content": "Alice and Bob are going to a science fair on Friday.",
+        },
+    ],
+    text_format=CalendarEvent,
+)
+
+print(response.output_parsed)</code></pre>
+      </div>
+      <div class="example-panel">
+        <pre><button class="copy-btn" onclick="copyCode(this)">Copy</button><code class="language-python">from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="${baseUrl}",
+    api_key=os.getenv("HF_TOKEN"), # visit https://huggingface.co/settings/tokens
+)
+
+response = client.responses.create(
+    model="moonshotai/Kimi-K2-Instruct:groq",
+    input="how does tiktoken work?",
+    tools=[
+        {
+            "type": "mcp",
+            "server_label": "gitmcp",
+            "server_url": "https://gitmcp.io/openai/tiktoken",
+            "allowed_tools": ["search_tiktoken_documentation", "fetch_tiktoken_documentation"],
+            "require_approval": "never",
+        },
+    ],
+)
+
+for output in response.output:
+    print(output)</code></pre>
+      </div>
+      <div class="example-panel">
+        <pre><button class="copy-btn" onclick="copyCode(this)">Copy</button><code class="language-python">from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="${baseUrl}",
+    api_key=os.getenv("HF_TOKEN"), # visit https://huggingface.co/settings/tokens
+)
+
+response = client.responses.create(
+    model="deepseek-ai/DeepSeek-R1",
+    instructions="You are a helpful assistant.",
+    input="Say hello to the world.",
+    reasoning={
+        "effort": "low",
+    }
+)
+
+for index, item in enumerate(response.output):
+    print(f"Output #{index}: {item.type}", item.content)</code></pre>
+      </div>
+    </section>
+    <footer class="more-info-footer">
+      <div style="font-weight:600; color:var(--primary-dark); font-size:1.13em; margin-bottom:0.5em;">More Info</div>
+      <ul>
+        <li><a href="https://github.com/huggingface/responses.js" target="_blank">GitHub Repository</a></li>
+        <li><a href="https://platform.openai.com/docs/api-reference/responses" target="_blank">OpenAI Responses API Docs</a></li>
+        <li><a href="https://huggingface.co/docs/inference-providers/index" target="_blank">Hugging Face Inference Providers</a></li>
+      </ul>
+    </footer>
+  </main>
+</body>
+</html>
+  `);
+}

src/routes/responses.ts

@@ -0,0 +1,1161 @@
+import { type Response as ExpressResponse } from "express";
+import { type ValidatedRequest } from "../middleware/validation.js";
+import type { CreateResponseParams, McpServerParams, McpApprovalRequestParams } from "../schemas.js";
+import { generateUniqueId } from "../lib/generateUniqueId.js";
+import { buildProviderScopedModel } from "../lib/buildProviderScopedModel.js";
+import { OpenAI } from "openai";
+import type {
+	Response,
+	ResponseContentPartAddedEvent,
+	ResponseOutputMessage,
+	ResponseFunctionToolCall,
+	ResponseOutputItem,
+	ResponseTextConfig,
+} from "openai/resources/responses/responses";
+import type {
+	PatchedResponseContentPart,
+	PatchedResponseStreamEvent,
+	ReasoningTextContent,
+	PatchedDeltaWithReasoning,
+} from "../openai_patch";
+import type {
+	ChatCompletionCreateParamsStreaming,
+	ChatCompletionMessageParam,
+	ChatCompletionTool,
+	ChatCompletion,
+} from "openai/resources/chat/completions.js";
+import type { FunctionParameters } from "openai/resources/shared.js";
+import { callMcpTool, connectMcpServer } from "../mcp.js";
+
+class StreamingError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "StreamingError";
+	}
+}
+
+type SpecAugmentedFields = {
+	completed_at: number | null;
+	frequency_penalty: number;
+	max_tool_calls: number | null;
+	presence_penalty: number;
+	prompt_cache_key: string | null;
+	prompt_cache_retention: "in_memory" | "24h" | null;
+	safety_identifier: string | null;
+	store: boolean;
+	top_logprobs: number;
+	user: string | null;
+};
+type IncompleteResponse = Omit<Response, "user"> & SpecAugmentedFields;
+const SEQUENCE_NUMBER_PLACEHOLDER = -1;
+
+// All headers are forwarded by default, except these ones.
+const NOT_FORWARDED_HEADERS = new Set([
+	"accept",
+	"accept-encoding",
+	"authorization",
+	"connection",
+	"content-length",
+	"content-type",
+	"host",
+	"keep-alive",
+	"te",
+	"trailer",
+	"trailers",
+	"transfer-encoding",
+	"upgrade",
+]);
+
+export const postCreateResponse = async (
+	req: ValidatedRequest<CreateResponseParams>,
+	res: ExpressResponse
+): Promise<void> => {
+	if (process.env.DEBUG_TOOL_STREAM === "1") {
+		console.debug("[responses.js] incoming request", JSON.stringify(req.body, null, 2));
+	}
+	// To avoid duplicated code, we run all requests as stream.
+	const events = runCreateResponseStream(req, res);
+
+	// Then we return in the correct format depending on the user 'stream' flag.
+	if (req.body.stream) {
+		res.setHeader("Content-Type", "text/event-stream");
+		res.setHeader("Connection", "keep-alive");
+		console.debug("Stream request");
+		for await (const event of events) {
+			console.debug(`Event #${event.sequence_number}: ${event.type}`);
+			res.write(`data: ${JSON.stringify(event)}\n\n`);
+		}
+		res.end();
+	} else {
+		console.debug("Non-stream request");
+		for await (const event of events) {
+			if (event.type === "response.completed" || event.type === "response.failed") {
+				console.debug(event.type);
+				res.json(event.response);
+			}
+		}
+	}
+};
+
+/*
+ * Top-level stream.
+ *
+ * Handles response lifecycle + execute inner logic (MCP list tools, MCP tool calls, LLM call, etc.).
+ * Handles sequenceNumber by overwriting it in the events.
+ */
+async function* runCreateResponseStream(
+	req: ValidatedRequest<CreateResponseParams>,
+	res: ExpressResponse
+): AsyncGenerator<PatchedResponseStreamEvent> {
+	let sequenceNumber = 0;
+	const resolvedModel = buildProviderScopedModel(req.body.model, req.body.provider);
+	const responseTextConfig: ResponseTextConfig = req.body.text ?? { format: { type: "text" } };
+	// NOTE: The OpenResponses response schema (schema/open_responses.md#response-object) requires these base fields to always be present,
+	// so we eagerly hydrate them here even when they would otherwise be null or falsey.
+	const responseObject: IncompleteResponse = {
+		background: req.body.background ?? false,
+		completed_at: null,
+		created_at: Math.floor(new Date().getTime() / 1000),
+		error: null,
+		frequency_penalty: req.body.frequency_penalty ?? 0,
+		id: generateUniqueId("resp"),
+		incomplete_details: null,
+		instructions: req.body.instructions,
+		max_output_tokens: req.body.max_output_tokens,
+		max_tool_calls: req.body.max_tool_calls ?? null,
+		metadata: req.body.metadata,
+		model: resolvedModel,
+		object: "response",
+		output: [],
+		output_text: "",
+		parallel_tool_calls: req.body.parallel_tool_calls ?? false,
+		presence_penalty: req.body.presence_penalty ?? 0,
+		previous_response_id: req.body.previous_response_id ?? null,
+		prompt_cache_key: req.body.prompt_cache_key ?? null,
+		prompt_cache_retention: req.body.prompt_cache_retention ?? null,
+		reasoning: req.body.reasoning ?? null,
+		safety_identifier: req.body.safety_identifier ?? null,
+		service_tier: req.body.service_tier ?? "auto",
+		status: "in_progress",
+		store: req.body.store ?? false,
+		text: responseTextConfig,
+		tool_choice: req.body.tool_choice ?? "auto",
+		tools: req.body.tools ?? [],
+		temperature: req.body.temperature,
+		top_logprobs: req.body.top_logprobs ?? 0,
+		top_p: req.body.top_p,
+		truncation: req.body.truncation ?? "disabled",
+		usage: {
+			input_tokens: 0,
+			input_tokens_details: { cached_tokens: 0 },
+			output_tokens: 0,
+			output_tokens_details: { reasoning_tokens: 0 },
+			total_tokens: 0,
+		},
+		user: req.body.user ?? null,
+	};
+
+	// Response created event
+	yield {
+		type: "response.created",
+		response: responseObject as Response,
+		sequence_number: sequenceNumber++,
+	};
+
+	// Response in progress event
+	yield {
+		type: "response.in_progress",
+		response: responseObject as Response,
+		sequence_number: sequenceNumber++,
+	};
+
+	// Any events (LLM call, MCP call, list tools, etc.)
+	try {
+		for await (const event of innerRunStream(req, res, responseObject, resolvedModel)) {
+			yield { ...event, sequence_number: sequenceNumber++ };
+		}
+	} catch (error) {
+		// Error event => stop
+		console.error("Error in stream:", error);
+
+		const message =
+			typeof error === "object" &&
+			error &&
+			"message" in error &&
+			typeof (error as { message: unknown }).message === "string"
+				? (error as { message: string }).message
+				: "An error occurred in stream";
+
+		responseObject.status = "failed";
+		responseObject.completed_at = Math.floor(new Date().getTime() / 1000);
+		responseObject.error = {
+			code: "server_error",
+			message,
+		};
+		if (process.env.DEBUG_FINAL_RESPONSE === "1") {
+			console.dir({ finalResponse: responseObject }, { depth: null });
+		}
+		yield {
+			type: "response.failed",
+			response: responseObject as Response,
+			sequence_number: sequenceNumber++,
+		};
+		return;
+	}
+
+	// Response completed event
+	responseObject.status = "completed";
+	responseObject.completed_at = Math.floor(new Date().getTime() / 1000);
+	if (process.env.DEBUG_FINAL_RESPONSE === "1") {
+		console.dir({ finalResponse: responseObject }, { depth: null });
+	}
+	yield {
+		type: "response.completed",
+		response: responseObject as Response,
+		sequence_number: sequenceNumber++,
+	};
+}
+
+async function* innerRunStream(
+	req: ValidatedRequest<CreateResponseParams>,
+	res: ExpressResponse,
+	responseObject: IncompleteResponse,
+	resolvedModel: string
+): AsyncGenerator<PatchedResponseStreamEvent> {
+	// Retrieve API key from headers
+	const apiKey = req.headers.authorization?.split(" ")[1];
+	if (!apiKey) {
+		res.status(401).json({
+			success: false,
+			error: "Unauthorized",
+		});
+		return;
+	}
+
+	// Forward headers (except authorization handled separately)
+	const defaultHeaders = Object.fromEntries(
+		Object.entries(req.headers).filter(([key]) => !NOT_FORWARDED_HEADERS.has(key.toLowerCase()))
+	) as Record<string, string>;
+
+	// Return early if not supported param
+	if (req.body.reasoning?.summary && req.body.reasoning?.summary !== "auto") {
+		throw new Error(`Not implemented: only 'auto' summary is supported. Got '${req.body.reasoning?.summary}'`);
+	}
+
+	// List MCP tools from server (if required) + prepare tools for the LLM
+	let tools: ChatCompletionTool[] | undefined = [];
+	const mcpToolsMapping: Record<string, McpServerParams> = {};
+	if (req.body.tools) {
+		for (const tool of req.body.tools) {
+			switch (tool.type) {
+				case "function":
+					tools?.push({
+						type: tool.type,
+						function: {
+							name: tool.name,
+							parameters: tool.parameters,
+							description: tool.description,
+							strict: tool.strict,
+						},
+					});
+					break;
+				case "mcp": {
+					let mcpListTools: ResponseOutputItem.McpListTools | undefined;
+
+					// If MCP list tools is already in the input, use it
+					if (Array.isArray(req.body.input)) {
+						for (const item of req.body.input) {
+							if (item.type === "mcp_list_tools" && item.server_label === tool.server_label) {
+								mcpListTools = item;
+								console.debug(`Using MCP list tools from input for server '${tool.server_label}'`);
+								break;
+							}
+						}
+					}
+					// Otherwise, list tools from MCP server
+					if (!mcpListTools) {
+						for await (const event of listMcpToolsStream(tool, responseObject)) {
+							yield event;
+						}
+						mcpListTools = responseObject.output.at(-1) as ResponseOutputItem.McpListTools;
+					}
+
+					// Only allowed tools are forwarded to the LLM
+					const allowedTools = tool.allowed_tools
+						? Array.isArray(tool.allowed_tools)
+							? tool.allowed_tools
+							: tool.allowed_tools.tool_names
+						: [];
+					if (mcpListTools?.tools) {
+						for (const mcpTool of mcpListTools.tools) {
+							if (allowedTools.length === 0 || allowedTools.includes(mcpTool.name)) {
+								tools?.push({
+									type: "function" as const,
+									function: {
+										name: mcpTool.name,
+										parameters: mcpTool.input_schema as FunctionParameters,
+										description: mcpTool.description ?? undefined,
+									},
+								});
+							}
+							mcpToolsMapping[mcpTool.name] = tool;
+						}
+						break;
+					}
+				}
+			}
+		}
+	}
+	if (tools.length === 0) {
+		tools = undefined;
+	}
+
+	// Prepare payload for the LLM
+
+	// Format input to Chat Completion format
+	const messages: ChatCompletionMessageParam[] = req.body.instructions
+		? [{ role: "system", content: req.body.instructions }]
+		: [];
+	if (Array.isArray(req.body.input)) {
+		messages.push(
+			...req.body.input
+				.map((item) => {
+					switch (item.type) {
+						case "function_call":
+							return {
+								role: "tool" as const,
+								content: item.arguments,
+								tool_call_id: item.call_id,
+							};
+						case "function_call_output":
+							return {
+								role: "tool" as const,
+								content: item.output,
+								tool_call_id: item.call_id,
+							};
+						case "message":
+						case undefined:
+							if (item.role === "assistant" || item.role === "user" || item.role === "system") {
+								const content =
+									typeof item.content === "string"
+										? item.content
+										: item.content
+												.map((content) => {
+													switch (content.type) {
+														case "input_image":
+															return {
+																type: "image_url" as const,
+																image_url: {
+																	url: content.image_url,
+																},
+															};
+														case "output_text":
+															return content.text
+																? {
+																		type: "text" as const,
+																		text: content.text,
+																	}
+																: undefined;
+														case "refusal":
+															return undefined;
+														case "input_text":
+															return {
+																type: "text" as const,
+																text: content.text,
+															};
+													}
+												})
+												.filter((item) => {
+													return item !== undefined;
+												});
+								const maybeFlatContent =
+									content.length === 1 &&
+									typeof content[0] === "object" &&
+									"type" in content[0] &&
+									content[0].type === "text"
+										? content[0].text
+										: content;
+								return {
+									role: item.role,
+									content: maybeFlatContent,
+								} as ChatCompletionMessageParam;
+							}
+							return undefined;
+						case "mcp_list_tools": {
+							return {
+								role: "tool" as const,
+								content: "MCP list tools. Server: '${item.server_label}'.",
+								tool_call_id: "mcp_list_tools",
+							};
+						}
+						case "mcp_call": {
+							return {
+								role: "tool" as const,
+								content: `MCP call (${item.id}). Server: '${item.server_label}'. Tool: '${item.name}'. Arguments: '${item.arguments}'.`,
+								tool_call_id: "mcp_call",
+							};
+						}
+						case "mcp_approval_request": {
+							return {
+								role: "tool" as const,
+								content: `MCP approval request (${item.id}). Server: '${item.server_label}'. Tool: '${item.name}'. Arguments: '${item.arguments}'.`,
+								tool_call_id: "mcp_approval_request",
+							};
+						}
+						case "mcp_approval_response": {
+							return {
+								role: "tool" as const,
+								content: `MCP approval response (${item.id}). Approved: ${item.approve}. Reason: ${item.reason}.`,
+								tool_call_id: "mcp_approval_response",
+							};
+						}
+					}
+				})
+				.filter(
+					(message): message is NonNullable<typeof message> =>
+						message !== undefined &&
+						(typeof message.content === "string" || (Array.isArray(message.content) && message.content.length !== 0))
+				)
+		);
+	} else {
+		messages.push({ role: "user", content: req.body.input } as const);
+	}
+
+	// Prepare payload for the LLM
+	const payload: ChatCompletionCreateParamsStreaming = {
+		// main params
+		model: resolvedModel,
+		messages,
+		stream: true,
+		// options
+		max_tokens: req.body.max_output_tokens === null ? undefined : req.body.max_output_tokens,
+		response_format: req.body.text?.format
+			? req.body.text.format.type === "json_schema"
+				? {
+						type: "json_schema",
+						json_schema: {
+							description: req.body.text.format.description,
+							name: req.body.text.format.name,
+							schema: req.body.text.format.schema,
+							strict: false, // req.body.text.format.strict,
+						},
+					}
+				: { type: req.body.text.format.type }
+			: undefined,
+		reasoning_effort: req.body.reasoning?.effort,
+		temperature: req.body.temperature,
+		tool_choice:
+			typeof req.body.tool_choice === "string"
+				? req.body.tool_choice
+				: req.body.tool_choice
+					? {
+							type: "function",
+							function: {
+								name: req.body.tool_choice.name,
+							},
+						}
+					: undefined,
+		tools,
+		top_p: req.body.top_p,
+	};
+	if (process.env.DEBUG_TOOL_STREAM === "1") {
+	console.debug("[responses.js] upstream request payload", JSON.stringify(payload, null, 2));
+}
+
+
+	// If MCP approval requests => execute them and return (no LLM call)
+	if (Array.isArray(req.body.input)) {
+		for (const item of req.body.input) {
+			if (item.type === "mcp_approval_response" && item.approve) {
+				const approvalRequest = req.body.input.find(
+					(i) => i.type === "mcp_approval_request" && i.id === item.approval_request_id
+				) as McpApprovalRequestParams | undefined;
+				const mcpCallId = "mcp_" + item.approval_request_id.split("_")[1];
+				const mcpCall = req.body.input.find((i) => i.type === "mcp_call" && i.id === mcpCallId);
+				if (mcpCall) {
+					// MCP call for that approval request has already been made, so we can skip it
+					continue;
+				}
+
+				for await (const event of callApprovedMCPToolStream(
+					item.approval_request_id,
+					mcpCallId,
+					approvalRequest,
+					mcpToolsMapping,
+					responseObject,
+					payload
+				)) {
+					yield event;
+				}
+			}
+		}
+	}
+
+	// Call the LLM until no new message is added to the payload.
+	// New messages can be added if the LLM calls an MCP tool that is automatically run.
+	// A maximum number of iterations is set to avoid infinite loops.
+	let previousMessageCount: number;
+	let currentMessageCount = payload.messages.length;
+	const MAX_ITERATIONS = 5; // hard-coded
+	let iterations = 0;
+	do {
+		previousMessageCount = currentMessageCount;
+
+		for await (const event of handleOneTurnStream(apiKey, payload, responseObject, mcpToolsMapping, defaultHeaders)) {
+			yield event;
+		}
+
+		currentMessageCount = payload.messages.length;
+		iterations++;
+	} while (currentMessageCount > previousMessageCount && iterations < MAX_ITERATIONS);
+}
+
+async function* listMcpToolsStream(
+	tool: McpServerParams,
+	responseObject: IncompleteResponse
+): AsyncGenerator<PatchedResponseStreamEvent> {
+	const outputObject: ResponseOutputItem.McpListTools = {
+		id: generateUniqueId("mcpl"),
+		type: "mcp_list_tools",
+		server_label: tool.server_label,
+		tools: [],
+	};
+	responseObject.output.push(outputObject);
+
+	yield {
+		type: "response.output_item.added",
+		output_index: responseObject.output.length - 1,
+		item: outputObject,
+		sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+	};
+
+	yield {
+		type: "response.mcp_list_tools.in_progress",
+		sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+	};
+
+	try {
+		const mcp = await connectMcpServer(tool);
+		const mcpTools = await mcp.listTools();
+		yield {
+			type: "response.mcp_list_tools.completed",
+			sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+		};
+		outputObject.tools = mcpTools.tools.map((mcpTool) => ({
+			input_schema: mcpTool.inputSchema,
+			name: mcpTool.name,
+			annotations: mcpTool.annotations,
+			description: mcpTool.description,
+		}));
+		yield {
+			type: "response.output_item.done",
+			output_index: responseObject.output.length - 1,
+			item: outputObject,
+			sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+		};
+	} catch (error) {
+		const errorMessage = `Failed to list tools from MCP server '${tool.server_label}': ${error instanceof Error ? error.message : "Unknown error"}`;
+		console.error(errorMessage);
+		yield {
+			type: "response.mcp_list_tools.failed",
+			sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+		};
+		throw new Error(errorMessage);
+	}
+}
+
+/*
+ * Call LLM and stream the response.
+ */
+async function* handleOneTurnStream(
+	apiKey: string | undefined,
+	payload: ChatCompletionCreateParamsStreaming,
+	responseObject: IncompleteResponse,
+	mcpToolsMapping: Record<string, McpServerParams>,
+	defaultHeaders: Record<string, string>
+): AsyncGenerator<PatchedResponseStreamEvent> {
+	const client = new OpenAI({
+		baseURL: process.env.OPENAI_BASE_URL ?? "https://router.huggingface.co/v1",
+		apiKey: apiKey,
+		defaultHeaders,
+	});
+	const stream = await client.chat.completions.create(payload);
+	let previousInputTokens = responseObject.usage?.input_tokens ?? 0;
+	const observedToolCallIds = new Set<string>();
+	const debugToolStream = process.env.DEBUG_TOOL_STREAM === "1";
+	let previousOutputTokens = responseObject.usage?.output_tokens ?? 0;
+	let previousTotalTokens = responseObject.usage?.total_tokens ?? 0;
+
+	for await (const chunk of stream) {
+		if (chunk.usage) {
+			// Overwrite usage with the latest chunk's usage
+			responseObject.usage = {
+				input_tokens: previousInputTokens + chunk.usage.prompt_tokens,
+				input_tokens_details: { cached_tokens: 0 },
+				output_tokens: previousOutputTokens + chunk.usage.completion_tokens,
+				output_tokens_details: { reasoning_tokens: 0 },
+				total_tokens: previousTotalTokens + chunk.usage.total_tokens,
+			};
+		}
+
+		if (!chunk.choices[0]) {
+			continue;
+		}
+
+		const delta = chunk.choices[0].delta as PatchedDeltaWithReasoning;
+		if (debugToolStream) {
+			const debugPayload = {
+				finish_reason: chunk.choices[0].finish_reason,
+				delta: chunk.choices[0].delta,
+				tool_calls: chunk.choices[0].delta?.tool_calls,
+			};
+			console.debug("[responses.js] stream delta", JSON.stringify(debugPayload, null, 2));
+		}
+		const reasoningText = delta.reasoning ?? delta.reasoning_content;
+
+		if (delta.content || reasoningText) {
+			let currentOutputItem = responseObject.output.at(-1);
+			if (currentOutputItem?.type !== "message" || currentOutputItem?.status !== "in_progress") {
+				const outputObject: ResponseOutputMessage = {
+					id: generateUniqueId("msg"),
+					type: "message",
+					role: "assistant",
+					status: "in_progress",
+					content: [],
+				};
+				responseObject.output.push(outputObject);
+
+				// Response output item added event
+				yield {
+					type: "response.output_item.added",
+					output_index: responseObject.output.length - 1,
+					item: outputObject,
+					sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+				};
+			}
+
+			const currentOutputMessage = responseObject.output.at(-1) as ResponseOutputMessage;
+			const messageContent = currentOutputMessage.content as unknown as PatchedResponseContentPart[];
+			const outputIndex = responseObject.output.length - 1;
+
+			if (reasoningText) {
+				let reasoningPart = messageContent.at(-1);
+				if (!reasoningPart || reasoningPart.type !== "reasoning_text") {
+					const part: ReasoningTextContent = {
+						type: "reasoning_text",
+						text: "",
+					};
+					messageContent.push(part as unknown as PatchedResponseContentPart);
+
+					yield {
+						type: "response.content_part.added",
+						item_id: currentOutputMessage.id,
+						output_index: outputIndex,
+						content_index: messageContent.length - 1,
+						part: part as unknown as PatchedResponseContentPart,
+						sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+					};
+					reasoningPart = part as unknown as PatchedResponseContentPart;
+				}
+
+				const reasoningContent = reasoningPart as ReasoningTextContent;
+				reasoningContent.text += reasoningText as string;
+				yield {
+					type: "response.reasoning.delta",
+					item_id: currentOutputMessage.id,
+					output_index: outputIndex,
+					content_index: messageContent.length - 1,
+					delta: reasoningText as string,
+					sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+				};
+			}
+
+			if (delta.content) {
+				let textPart = messageContent.at(-1);
+				if (!textPart || textPart.type !== "output_text") {
+					const newPart: ResponseContentPartAddedEvent["part"] = {
+						type: "output_text",
+						text: "",
+						annotations: [],
+						logprobs: [],
+					};
+					messageContent.push(newPart as unknown as PatchedResponseContentPart);
+
+					yield {
+						type: "response.content_part.added",
+						item_id: currentOutputMessage.id,
+						output_index: outputIndex,
+						content_index: messageContent.length - 1,
+						part: newPart,
+						sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+					};
+					textPart = newPart as unknown as PatchedResponseContentPart;
+				}
+
+				if (!textPart || textPart.type !== "output_text") {
+					throw new StreamingError(`Not implemented: expected output_text content part, got ${textPart?.type}`);
+				}
+
+				textPart.text += delta.content as string;
+				responseObject.output_text += delta.content as string;
+				yield {
+					type: "response.output_text.delta",
+					item_id: currentOutputMessage.id,
+					output_index: outputIndex,
+					content_index: messageContent.length - 1,
+					delta: delta.content as string,
+					logprobs: [],
+					sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+				};
+			}
+		} else if (delta.tool_calls && delta.tool_calls.length > 0) {
+			if (debugToolStream) {
+				console.debug("[responses.js] delta tool_calls", JSON.stringify(delta.tool_calls, null, 2));
+			}
+			for await (const event of closeLastOutputItem(responseObject, payload, mcpToolsMapping)) {
+				yield event;
+			}
+			if (delta.tool_calls.length > 1) {
+				console.log("Multiple tool calls are not supported. Only the first one will be processed.");
+			}
+
+			let currentOutputItem = responseObject.output.at(-1);
+			if (delta.tool_calls[0].function?.name) {
+				const incomingToolCallId = delta.tool_calls[0].id;
+				if (incomingToolCallId) {
+					observedToolCallIds.add(incomingToolCallId);
+				}
+				const functionName = delta.tool_calls[0].function.name;
+				// Tool call with a name => new tool call
+				let newOutputObject:
+					| ResponseOutputItem.McpCall
+					| ResponseFunctionToolCall
+					| ResponseOutputItem.McpApprovalRequest;
+				if (functionName in mcpToolsMapping) {
+					if (requiresApproval(functionName, mcpToolsMapping)) {
+						newOutputObject = {
+							id: generateUniqueId("mcpr"),
+							type: "mcp_approval_request",
+							name: functionName,
+							server_label: mcpToolsMapping[functionName].server_label,
+							arguments: "",
+						};
+					} else {
+						newOutputObject = {
+							type: "mcp_call",
+							id: generateUniqueId("mcp"),
+							name: functionName,
+							server_label: mcpToolsMapping[functionName].server_label,
+							arguments: "",
+						};
+					}
+				} else {
+					newOutputObject = {
+						type: "function_call",
+						id: generateUniqueId("fc"),
+						call_id: delta.tool_calls[0].id ?? "",
+						name: functionName,
+						arguments: "",
+					};
+				}
+
+				// Response output item added event
+				responseObject.output.push(newOutputObject);
+				yield {
+					type: "response.output_item.added",
+					output_index: responseObject.output.length - 1,
+					item: newOutputObject,
+					sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+				};
+				if (newOutputObject.type === "mcp_call") {
+					yield {
+						type: "response.mcp_call.in_progress",
+						sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+						item_id: newOutputObject.id,
+						output_index: responseObject.output.length - 1,
+					};
+				}
+			}
+
+			if (delta.tool_calls[0].function?.arguments) {
+				// Current item is necessarily a tool call
+				currentOutputItem = responseObject.output.at(-1) as
+					| ResponseOutputItem.McpCall
+					| ResponseFunctionToolCall
+					| ResponseOutputItem.McpApprovalRequest;
+				currentOutputItem.arguments += delta.tool_calls[0].function.arguments;
+				if (currentOutputItem.type === "mcp_call" || currentOutputItem.type === "function_call") {
+					yield {
+						type:
+							currentOutputItem.type === "mcp_call"
+								? ("response.mcp_call_arguments.delta" as "response.mcp_call.arguments_delta") // bug workaround (see https://github.com/openai/openai-node/issues/1562)
+								: "response.function_call_arguments.delta",
+						item_id: currentOutputItem.id as string,
+						output_index: responseObject.output.length - 1,
+						delta: delta.tool_calls[0].function.arguments,
+						sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+					};
+				}
+			}
+		}
+	}
+
+	const fallbackEvents = await buildFinalToolCallFallbackEvents(stream, responseObject, observedToolCallIds, debugToolStream);
+	for (const event of fallbackEvents) {
+		yield event;
+	}
+
+	for await (const event of closeLastOutputItem(responseObject, payload, mcpToolsMapping)) {
+		yield event;
+	}
+}
+
+/*
+ * Perform an approved MCP tool call and stream the response.
+ */
+async function* callApprovedMCPToolStream(
+	approval_request_id: string,
+	mcpCallId: string,
+	approvalRequest: McpApprovalRequestParams | undefined,
+	mcpToolsMapping: Record<string, McpServerParams>,
+	responseObject: IncompleteResponse,
+	payload: ChatCompletionCreateParamsStreaming
+): AsyncGenerator<PatchedResponseStreamEvent> {
+	if (!approvalRequest) {
+		throw new Error(`MCP approval request '${approval_request_id}' not found`);
+	}
+
+	const outputObject: ResponseOutputItem.McpCall = {
+		type: "mcp_call",
+		id: mcpCallId,
+		name: approvalRequest.name,
+		server_label: approvalRequest.server_label,
+		arguments: approvalRequest.arguments,
+	};
+	responseObject.output.push(outputObject);
+
+	// Response output item added event
+	yield {
+		type: "response.output_item.added",
+		output_index: responseObject.output.length - 1,
+		item: outputObject,
+		sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+	};
+
+	yield {
+		type: "response.mcp_call.in_progress",
+		item_id: outputObject.id as string,
+		output_index: responseObject.output.length - 1,
+		sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+	};
+
+	const toolParams = mcpToolsMapping[approvalRequest.name];
+	const toolResult = await callMcpTool(toolParams, approvalRequest.name, approvalRequest.arguments);
+
+	if (toolResult.error) {
+		outputObject.error = toolResult.error;
+		yield {
+			type: "response.mcp_call.failed",
+			sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+		};
+	} else {
+		outputObject.output = toolResult.output;
+		yield {
+			type: "response.mcp_call.completed",
+			sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+		};
+	}
+
+	yield {
+		type: "response.output_item.done",
+		output_index: responseObject.output.length - 1,
+		item: outputObject,
+		sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+	};
+
+	// Updating the payload for next LLM call
+	payload.messages.push(
+		{
+			role: "assistant",
+			tool_calls: [
+				{
+					id: outputObject.id,
+					type: "function",
+					function: {
+						name: outputObject.name,
+						arguments: outputObject.arguments,
+						// Hacky: type is not correct in inference.js. Will fix it but in the meantime we need to cast it.
+						// TODO: fix it in the inference.js package. Should be "arguments" and not "parameters".
+					},
+				},
+			],
+		},
+		{
+			role: "tool",
+			tool_call_id: outputObject.id,
+			content: outputObject.output ? outputObject.output : outputObject.error ? `Error: ${outputObject.error}` : "",
+		}
+	);
+}
+
+function requiresApproval(toolName: string, mcpToolsMapping: Record<string, McpServerParams>): boolean {
+	const toolParams = mcpToolsMapping[toolName];
+	return toolParams.require_approval === "always"
+		? true
+		: toolParams.require_approval === "never"
+			? false
+			: toolParams.require_approval.always?.tool_names?.includes(toolName)
+				? true
+				: toolParams.require_approval.never?.tool_names?.includes(toolName)
+					? false
+					: true; // behavior is undefined in specs, let's default to true
+}
+
+async function buildFinalToolCallFallbackEvents(
+	stream: { finalResponse?: () => Promise<ChatCompletion> } | AsyncIterable<unknown>,
+	responseObject: IncompleteResponse,
+	observedToolCallIds: Set<string>,
+	debugToolStream: boolean
+): Promise<PatchedResponseStreamEvent[]> {
+	const events: PatchedResponseStreamEvent[] = [];
+	if (!stream || typeof (stream as { finalResponse?: () => Promise<ChatCompletion> }).finalResponse !== "function") {
+		return events;
+	}
+
+	let finalResponse: ChatCompletion | null = null;
+	try {
+		finalResponse = await (stream as { finalResponse: () => Promise<ChatCompletion> }).finalResponse();
+	} catch (error) {
+		if (debugToolStream) {
+			console.debug("[responses.js] finalResponse unavailable", error);
+		}
+		return events;
+	}
+
+	const choices = finalResponse?.choices ?? [];
+	if (debugToolStream) {
+		console.debug("[responses.js] finalResponse", JSON.stringify(finalResponse, null, 2));
+	}
+	for (const choice of choices) {
+		const toolCalls = choice.message?.tool_calls;
+		if (!toolCalls || toolCalls.length === 0) {
+			continue;
+		}
+
+		for (const toolCall of toolCalls) {
+			if (debugToolStream) {
+				console.debug("[responses.js] final tool_call", JSON.stringify(toolCall, null, 2));
+			}
+			if (toolCall.type !== "function" || !toolCall.function) {
+				continue;
+			}
+			if (toolCall.id && observedToolCallIds.has(toolCall.id)) {
+				continue;
+			}
+
+			const outputObject: ResponseFunctionToolCall = {
+				id: generateUniqueId("fc"),
+				type: "function_call",
+				call_id: toolCall.id ?? generateUniqueId("call"),
+				name: toolCall.function.name ?? "function",
+				arguments: toolCall.function.arguments ?? "",
+				status: "completed",
+			};
+			responseObject.output.push(outputObject);
+			const outputIndex = responseObject.output.length - 1;
+
+			events.push({
+				type: "response.output_item.added",
+				output_index: outputIndex,
+				item: outputObject,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			});
+
+			if (outputObject.arguments) {
+				events.push({
+					type: "response.function_call_arguments.delta",
+					item_id: outputObject.id as string,
+					output_index: outputIndex,
+					delta: outputObject.arguments,
+					sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+				});
+			}
+
+			events.push({
+				type: "response.function_call_arguments.done",
+				item_id: outputObject.id as string,
+				output_index: outputIndex,
+				arguments: outputObject.arguments,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			});
+
+			events.push({
+				type: "response.output_item.done",
+				output_index: outputIndex,
+				item: outputObject,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			});
+
+			if (toolCall.id) {
+				observedToolCallIds.add(toolCall.id);
+			}
+		}
+	}
+
+	return events;
+}
+
+
+async function* closeLastOutputItem(
+	responseObject: IncompleteResponse,
+	payload: ChatCompletionCreateParamsStreaming,
+	mcpToolsMapping: Record<string, McpServerParams>
+): AsyncGenerator<PatchedResponseStreamEvent> {
+	const lastOutputItem = responseObject.output.at(-1);
+	if (lastOutputItem) {
+		if (lastOutputItem?.type === "message") {
+			const messageContent = lastOutputItem.content as unknown as PatchedResponseContentPart[];
+			const outputIndex = responseObject.output.length - 1;
+			for (let i = 0; i < messageContent.length; i++) {
+				const contentPart = messageContent[i];
+				const partType = (contentPart as { type?: string }).type ?? "unknown";
+				switch (contentPart.type) {
+					case "output_text": {
+						yield {
+							type: "response.output_text.done",
+							item_id: lastOutputItem.id,
+							output_index: outputIndex,
+							content_index: i,
+							text: contentPart.text,
+							logprobs: [],
+							sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+						};
+						break;
+					}
+					case "reasoning_text": {
+						yield {
+							type: "response.reasoning.done",
+							item_id: lastOutputItem.id,
+							output_index: outputIndex,
+							content_index: i,
+							text: contentPart.text,
+							sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+						};
+						break;
+					}
+					case "refusal": {
+						// Fall through to shared content_part.done below without extra events.
+						break;
+					}
+					default: {
+						throw new StreamingError(`Unsupported content part type: ${partType}`);
+					}
+				}
+
+				yield {
+					type: "response.content_part.done",
+					item_id: lastOutputItem.id,
+					output_index: outputIndex,
+					content_index: i,
+					part: contentPart,
+					sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+				};
+			}
+
+			lastOutputItem.status = "completed";
+			yield {
+				type: "response.output_item.done",
+				output_index: outputIndex,
+				item: lastOutputItem,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			};
+		} else if (lastOutputItem?.type === "function_call") {
+			yield {
+				type: "response.function_call_arguments.done",
+				item_id: lastOutputItem.id as string,
+				output_index: responseObject.output.length - 1,
+				arguments: lastOutputItem.arguments,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			};
+
+			lastOutputItem.status = "completed";
+			yield {
+				type: "response.output_item.done",
+				output_index: responseObject.output.length - 1,
+				item: lastOutputItem,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			};
+		} else if (lastOutputItem?.type === "mcp_call") {
+			yield {
+				type: "response.mcp_call_arguments.done" as "response.mcp_call.arguments_done", // bug workaround (see https://github.com/openai/openai-node/issues/1562)
+				item_id: lastOutputItem.id as string,
+				output_index: responseObject.output.length - 1,
+				arguments: lastOutputItem.arguments,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			};
+
+			// Call MCP tool
+			const toolParams = mcpToolsMapping[lastOutputItem.name];
+			const toolResult = await callMcpTool(toolParams, lastOutputItem.name, lastOutputItem.arguments);
+			if (toolResult.error) {
+				lastOutputItem.error = toolResult.error;
+				yield {
+					type: "response.mcp_call.failed",
+					sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+				};
+			} else {
+				lastOutputItem.output = toolResult.output;
+				yield {
+					type: "response.mcp_call.completed",
+					sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+				};
+			}
+
+			yield {
+				type: "response.output_item.done",
+				output_index: responseObject.output.length - 1,
+				item: lastOutputItem,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			};
+
+			// Updating the payload for next LLM call
+			payload.messages.push(
+				{
+					role: "assistant",
+					tool_calls: [
+						{
+							id: lastOutputItem.id,
+							type: "function",
+							function: {
+								name: lastOutputItem.name,
+								arguments: lastOutputItem.arguments,
+								// Hacky: type is not correct in inference.js. Will fix it but in the meantime we need to cast it.
+								// TODO: fix it in the inference.js package. Should be "arguments" and not "parameters".
+							},
+						},
+					],
+				},
+				{
+					role: "tool",
+					tool_call_id: lastOutputItem.id,
+					content: lastOutputItem.output
+						? lastOutputItem.output
+						: lastOutputItem.error
+							? `Error: ${lastOutputItem.error}`
+							: "",
+				}
+			);
+		} else if (lastOutputItem?.type === "mcp_approval_request" || lastOutputItem?.type === "mcp_list_tools") {
+			yield {
+				type: "response.output_item.done",
+				output_index: responseObject.output.length - 1,
+				item: lastOutputItem,
+				sequence_number: SEQUENCE_NUMBER_PLACEHOLDER,
+			};
+		} else {
+			throw new StreamingError(
+				`Not implemented: expected message, function_call, or mcp_call, got ${lastOutputItem?.type}`
+			);
+		}
+	}
+}

src/schemas.ts

@@ -0,0 +1,240 @@
+import { z } from "zod";
+
+/**
+ * https://platform.openai.com/docs/api-reference/responses/create
+ * commented out properties are not supported by the server
+ */
+
+const inputContentSchema = z.array(
+	z.union([
+		z.object({
+			type: z.literal("input_text"),
+			text: z.string(),
+		}),
+		z.object({
+			type: z.literal("input_image"),
+			// file_id: z.string().nullable().default(null),
+			image_url: z.string(),
+			// detail: z.enum(["auto", "low", "high"]).default("auto"),
+		}),
+		// z.object({
+		// 	type: z.literal("input_file"),
+		// 	file_data: z.string().nullable().default(null),
+		// 	file_id: z.string().nullable().default(null),
+		// 	filename: z.string().nullable().default(null),
+		// }),
+	])
+);
+
+const mcpServerParamsSchema = z.object({
+	server_label: z.string(),
+	server_url: z.string(),
+	type: z.literal("mcp"),
+	allowed_tools: z
+		.union([
+			z.array(z.string()),
+			z.object({
+				tool_names: z.array(z.string()),
+			}),
+		])
+		.nullable()
+		.default(null),
+	headers: z.record(z.string()).nullable().default(null),
+	require_approval: z
+		.union([
+			z.enum(["always", "never"]),
+			z.object({
+				always: z.object({ tool_names: z.array(z.string()).optional() }).optional(),
+				never: z.object({ tool_names: z.array(z.string()).optional() }).optional(),
+			}),
+		])
+		.default("always"),
+});
+
+const mcpApprovalRequestParamsSchema = z.object({
+	type: z.literal("mcp_approval_request"),
+	id: z.string(),
+	server_label: z.string(),
+	name: z.string(),
+	arguments: z.string(),
+});
+const mcpApprovalResponseParamsSchema = z.object({
+	type: z.literal("mcp_approval_response"),
+	id: z.string().nullable().default(null),
+	approval_request_id: z.string(),
+	approve: z.boolean(),
+	reason: z.string().nullable().default(null),
+});
+const mcpCallParamsSchema = z.object({
+	type: z.literal("mcp_call"),
+	id: z.string(),
+	name: z.string(),
+	server_label: z.string(),
+	arguments: z.string(),
+});
+
+const truncationEnum = z.enum(["auto", "disabled"]);
+const serviceTierEnum = z.enum(["auto", "default", "flex", "priority"]);
+const promptCacheRetentionEnum = z.enum(["in_memory", "24h"]);
+
+export const createResponseParamsSchema = z.object({
+	background: z.boolean().default(false),
+	// include:
+	input: z.union([
+		z.string(),
+		z.array(
+			z.union([
+				z.object({
+					content: z.union([z.string(), inputContentSchema]),
+					role: z.enum(["user", "assistant", "system", "developer"]),
+					type: z.enum(["message"]).default("message"),
+				}),
+				z.object({
+					role: z.enum(["user", "system", "developer"]),
+					status: z.enum(["in_progress", "completed", "incomplete"]).nullable().default(null),
+					content: inputContentSchema,
+					type: z.enum(["message"]).default("message"),
+				}),
+				z.object({
+					id: z.string().optional(),
+					role: z.enum(["assistant"]),
+					status: z.enum(["in_progress", "completed", "incomplete"]).optional(),
+					type: z.enum(["message"]).default("message"),
+					content: z.array(
+						z.union([
+							z.object({
+								type: z.literal("output_text"),
+								text: z.string(),
+								annotations: z.array(z.record(z.any())).nullable().optional(), // TODO: incomplete
+								logprobs: z.array(z.record(z.any())).nullable().optional(), // TODO: incomplete
+							}),
+							z.object({
+								type: z.literal("refusal"),
+								refusal: z.string(),
+							}),
+							// TODO: much more objects: File search tool call, Computer tool call, Computer tool call output, Web search tool call, Function tool call, Function tool call output, Reasoning, Image generation call, Code interpreter tool call, Local shell call, Local shell call output, MCP list tools, MCP approval request, MCP approval response, MCP tool call
+						])
+					),
+				}),
+				z.object({
+					type: z.literal("function_call"),
+					id: z.string().optional(),
+					call_id: z.string(),
+					name: z.string(),
+					arguments: z.string(),
+					status: z.enum(["in_progress", "completed", "incomplete"]).optional(),
+				}),
+				z.object({
+					call_id: z.string(),
+					output: z.string(),
+					type: z.literal("function_call_output"),
+					id: z.string().optional(),
+					status: z.enum(["in_progress", "completed", "incomplete"]).optional(),
+				}),
+				z.object({
+					type: z.literal("mcp_list_tools"),
+					id: z.string(),
+					server_label: z.string(),
+					tools: z.array(
+						z.object({
+							name: z.string(),
+							input_schema: z.record(z.any()),
+							description: z.string().nullable().optional(),
+							annotations: z.object({}).optional(),
+						})
+					),
+					error: z.string().nullable().optional(),
+				}),
+				mcpApprovalRequestParamsSchema,
+				mcpApprovalResponseParamsSchema,
+				mcpCallParamsSchema,
+			])
+		),
+	]),
+	instructions: z.string().nullable().default(null),
+	max_output_tokens: z.number().int().min(0).nullable().default(null),
+	max_tool_calls: z.number().int().min(1).nullable().default(null),
+	metadata: z
+		.record(z.string().max(64), z.string().max(512))
+		.refine((val) => Object.keys(val).length <= 16, {
+			message: "Must have at most 16 items",
+		})
+		.nullable()
+		.default(null),
+	model: z.string(),
+	previous_response_id: z.string().nullable().default(null),
+	provider: z.string().min(1).optional(),
+	parallel_tool_calls: z.boolean().nullable().default(null),
+	// previous_response_id: z.string().nullable().default(null),
+	reasoning: z
+		.object({
+			effort: z.enum(["low", "medium", "high"]).default("medium"),
+			summary: z.enum(["auto", "concise", "detailed"]).nullable().default(null),
+		})
+		.optional(),
+	store: z.boolean().default(false),
+	service_tier: serviceTierEnum.nullable().default(null),
+	safety_identifier: z.string().max(64).nullable().default(null),
+	prompt_cache_key: z.string().max(64).nullable().default(null),
+	prompt_cache_retention: promptCacheRetentionEnum.nullable().default(null),
+	stream: z.boolean().default(false),
+	temperature: z.number().min(0).max(2).default(1),
+	text: z
+		.object({
+			format: z.union([
+				z.object({
+					type: z.literal("text"),
+				}),
+				z.object({
+					type: z.literal("json_object"),
+				}),
+				z.object({
+					type: z.literal("json_schema"),
+					name: z
+						.string()
+						.max(64, "Must be at most 64 characters")
+						.regex(/^[a-zA-Z0-9_-]+$/, "Only letters, numbers, underscores, and dashes are allowed"),
+					description: z.string().optional(),
+					schema: z.record(z.any()),
+					strict: z.boolean().default(false),
+				}),
+			]),
+		})
+		.optional(),
+	tool_choice: z
+		.union([
+			z.enum(["auto", "none", "required"]),
+			z.object({
+				type: z.literal("function"),
+				name: z.string(),
+			}),
+			// TODO: also hosted tool and MCP tool
+		])
+		.optional(),
+	tools: z
+		.array(
+			z.union([
+				z.object({
+					name: z.string(),
+					parameters: z.record(z.any()),
+					strict: z.boolean().default(false),
+					type: z.literal("function"),
+					description: z.string().optional(),
+				}),
+				mcpServerParamsSchema,
+			])
+		)
+		.optional(),
+	top_logprobs: z.number().int().min(0).max(20).nullable().default(null),
+	top_p: z.number().min(0).max(1).default(1),
+	presence_penalty: z.number().min(-2).max(2).nullable().default(null),
+	frequency_penalty: z.number().min(-2).max(2).nullable().default(null),
+	truncation: truncationEnum.nullable().default(null),
+	user: z.string().max(64).nullable().default(null),
+});
+
+export type CreateResponseParams = z.infer<typeof createResponseParamsSchema>;
+export type McpServerParams = z.infer<typeof mcpServerParamsSchema>;
+export type McpApprovalRequestParams = z.infer<typeof mcpApprovalRequestParamsSchema>;
+export type McpApprovalResponseParams = z.infer<typeof mcpApprovalResponseParamsSchema>;
+export type McpCallParams = z.infer<typeof mcpCallParamsSchema>;

src/server.ts

@@ -0,0 +1,22 @@
+import express, { type Express } from "express";
+import { createResponseParamsSchema } from "./schemas.js";
+import { validateBody } from "./middleware/validation.js";
+import { requestLogger } from "./middleware/logging.js";
+import { getLandingPageHtml, postCreateResponse, getHealth } from "./routes/index.js";
+
+export const createApp = (): Express => {
+	const app: Express = express();
+
+	// Middleware
+	app.use(requestLogger());
+	app.use(express.json());
+
+	// Routes
+	app.get("/", getLandingPageHtml);
+
+	app.get("/health", getHealth);
+
+	app.post("/v1/responses", validateBody(createResponseParamsSchema), postCreateResponse);
+
+	return app;
+};

tsconfig.json

@@ -0,0 +1,21 @@
+{
+	"compilerOptions": {
+		"allowSyntheticDefaultImports": true,
+		"lib": ["ES2022", "DOM"],
+		"module": "CommonJS",
+		"moduleResolution": "node",
+		"target": "ES2022",
+		"forceConsistentCasingInFileNames": true,
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"skipLibCheck": true,
+		"noImplicitOverride": true,
+		"outDir": "./dist",
+		"declaration": true,
+		"declarationMap": true,
+		"resolveJsonModule": true
+	},
+	"include": ["src", "test"],
+	"exclude": ["dist"]
+}