@deepseek-ai/dsh-llm-mock-server 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/support/llm-mock-server/README.md
+README.md: a535c086bf688ad48b1a3bb19c7b81da21cbad92
+README.zh.md: d814d8815b38bb34bd0d871d552e6f3ec75e042a

package/README.md

@@ -0,0 +1,86 @@
+# `@deepseek-ai/dsh-llm-mock-server`
+
+English | [中文](README.zh.md)
+
+A scriptable OpenAI-compatible HTTP/SSE server for exercising real LLM adapters, the agent loop, and recovery policy without a provider key. It accepts `POST /chat/completions` and `POST /v1/chat/completions`; each accepted request consumes one configured behavior in arrival order. Invalid methods, paths, bearer tokens, and JSON do not consume the script.
+
+The library entry exports `startMockLlmServer(options)`, behavior and telemetry types, the default random stress weights, the accepted Node timer bound, and a running handle with the bound `baseURL`, generated or configured `randomSeed`, captured requests, and idempotent `close()`. Closing force-terminates stalled connections.
+
+## Standalone use
+
+Run the source entry from this repository:
+
+```sh
+pnpm run mock:llm -- \
+  --port 8000 \
+  --api-key mock-key \
+  --sequence partial_disconnect,success \
+  --partial-text "discard this half"
+```
+
+Point the shipping DeepSeek adapter at the server; it appends `/chat/completions` to the configured base:
+
+```sh
+DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1 \
+DEEPSEEK_API_KEY=mock-key \
+pnpm run demo:headless "test provider recovery"
+```
+
+The repository script writes JSONL to stdout: a `ready` record carries the `/v1` base URL and random seed, followed by request/result records that name both the scripted behavior and the concrete selected behavior. The private support package exposes no installable binary.
+
+## Behavior script
+
+`--sequence` is a comma-separated FIFO. Exhaustion returns a structured HTTP 500; `--repeat-last` explicitly reuses the last entry.
+
+| Behavior | Wire result |
+|---|---|
+| `connection_reset` | Destroy the socket before HTTP headers |
+| `stream_disconnect` | Send SSE headers, then reset before the first event |
+| `partial_disconnect` | Send text deltas, then reset the socket |
+| `stall` | Send SSE headers and remain idle until client/server cancellation |
+| `empty` | Send a valid content-less stop and `[DONE]` |
+| `empty_body` / `stream_eof` / `partial_eof` | End cleanly without the required `[DONE]` boundary |
+| `malformed_json` / `malformed_event` | Send invalid SSE JSON or an invalid provider chunk shape |
+| `rate_limit` / `server_error` / `service_unavailable` | Return retry-oriented 429/500/503 JSON errors |
+| `auth_error` / `invalid_request` / `context_overflow` / `quota_exceeded` | Return terminal or separately recovered provider errors |
+| `success` / `slow_success` / `reasoning_success` | Stream a complete text response, optionally delayed or preceded by reasoning |
+| `tool_call_success` / `max_tokens` | Complete with a tool call or `length` finish |
+| `wrong_content_type` | Send a valid SSE body under `application/json` |
+| `random` | Select a concrete request behavior from weighted seeded randomness |
+
+`connection_refused` is CLI-only and must be the first entry. It delays binding a caller-specified nonzero port, so requests during `--listen-delay-ms` receive a real TCP refusal; the remaining entries begin after the listener starts.
+
+## Random mode
+
+Use a repeating `random` entry for an open-ended mixed run:
+
+```sh
+pnpm run mock:llm -- \
+  --port 8000 \
+  --sequence random \
+  --repeat-last \
+  --seed 42 \
+  --random-weights 'success=60,slow_success=10,connection_reset=5,stream_disconnect=5,partial_disconnect=10,empty=5,server_error=5'
+```
+
+Omitting `--seed` generates one and prints it in the `ready` record. `--random-weights` accepts non-negative relative `behavior=weight` entries and requires at least one positive concrete behavior. The exported default is a success-heavy stress profile containing reset, disconnect, partial output, empty completion, stall, 429/5xx, clean truncation, and malformed JSON; it is test pressure, not an estimate of production incident frequency. `connection_refused` is excluded because a bound request handler cannot produce a true refusal.
+
+When random weights include `stall`, configure the client under test with a short stream-idle timeout so the scenario terminates promptly.
+
+## Timing and content controls
+
+The CLI exposes `--success-text`, `--partial-text`, `--reasoning-text`, `--chunk-size`, `--chunk-delay-ms`, `--disconnect-delay-ms`, `--retry-after-ms`, `--request-id`, `--tool-name`, and `--tool-arguments`. Millisecond delays are bounded integers within Node's timer range; `retryAfterMs` must also be positive. The library accepts the same camel-case options. An optional exact `apiKey` validates `Authorization: Bearer <token>`; omission accepts any token.
+
+## Model Experience
+
+None, as this test server substitutes provider wire behavior without invoking a real model.
+
+#### KV Cache effect
+
+None; requests terminate locally and never reach a provider cache.
+
+## Known Limitations and Deferred Work
+
+- **Random weights model test pressure, not production incidence** — callers that want an environment-specific distribution must provide measured weights and record the emitted seed.
+- **Request scripts are arrival-ordered** — concurrent callers share one cursor, so deterministic per-session fault assignment requires separate server instances.
+- **True connection refusal is a listener lifecycle phase** — the CLI delay must overlap the client attempt; request-level random selection can only reset an accepted connection.

package/README.zh.md

@@ -0,0 +1,86 @@
+# `@deepseek-ai/dsh-llm-mock-server`
+
+[English](README.md) | 中文
+
+可编脚本的 OpenAI 兼容 HTTP／SSE（Server-Sent Events）服务器，用于在无提供方密钥的情况下测试真实 LLM（大语言模型）适配器、agent loop（智能体循环）和恢复策略。它接受 `POST /chat/completions` 和 `POST /v1/chat/completions`；每个已接受请求按到达顺序消费一个已配置行为。无效的请求方法、路径、Bearer token 和 JSON 不会消费脚本条目。
+
+库入口导出 `startMockLlmServer(options)`、行为类型和遥测（telemetry）类型、默认随机压力权重、Node 定时器允许的上限，以及带有绑定 `baseURL`、自动生成或显式配置 `randomSeed`、已捕获请求和幂等 `close()` 的运行句柄。关闭会强制终止停滞连接。
+
+## 独立使用
+
+从本仓库运行源入口：
+
+```sh
+pnpm run mock:llm -- \
+  --port 8000 \
+  --api-key mock-key \
+  --sequence partial_disconnect,success \
+  --partial-text "discard this half"
+```
+
+将发布的 DeepSeek 适配器指向服务器；它会将 `/chat/completions` 追加到已配置 base：
+
+```sh
+DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1 \
+DEEPSEEK_API_KEY=mock-key \
+pnpm run demo:headless "test provider recovery"
+```
+
+仓库脚本将 JSONL 写入 stdout：`ready` 记录携带以 `/v1` 结尾的基础 URL 和随机种子，后续请求/结果记录同时命名脚本行为和实际选中的具体行为。这个私有支持包不公开可安装的二进制命令。
+
+## 行为脚本
+
+`--sequence` 是逗号分隔的 FIFO。耗尽时返回结构化 HTTP 500；`--repeat-last` 显式重用最后一项。
+
+| 行为 | 协议结果 |
+|---|---|
+| `connection_reset` | 在发送 HTTP 标头前销毁 socket |
+| `stream_disconnect` | 发送 SSE 标头，然后在第一个事件前重置连接 |
+| `partial_disconnect` | 发送文本增量，然后重置 socket |
+| `stall` | 发送 SSE header，并保持空闲，直到客户端／服务器取消 |
+| `empty` | 发送有效的无内容 stop 和 `[DONE]` |
+| `empty_body` / `stream_eof` / `partial_eof` | 正常结束，但缺少必需的 `[DONE]` 边界 |
+| `malformed_json` / `malformed_event` | 发送无效 SSE JSON 或无效提供方分片形态 |
+| `rate_limit` / `server_error` / `service_unavailable` | 返回面向重试的 429/500/503 JSON 错误 |
+| `auth_error` / `invalid_request` / `context_overflow` / `quota_exceeded` | 返回终止性错误或需要单独恢复的提供方错误 |
+| `success` / `slow_success` / `reasoning_success` | 流式发送完整文本响应，可选延迟或先发送 reasoning |
+| `tool_call_success` / `max_tokens` | 以工具调用或结束原因 `length` 完成 |
+| `wrong_content_type` | 以 `application/json` 内容类型发送有效 SSE 正文 |
+| `random` | 按带权重的种子随机选择具体请求行为 |
+
+`connection_refused` 只能在 CLI 中使用，且必须是第一个条目。它会延迟绑定调用方指定的非零端口，因此 `--listen-delay-ms` 期间的请求会收到真实 TCP 拒绝；其余条目在 listener 启动后开始。
+
+## 随机模式
+
+使用重复 `random` 条目执行开放式混合运行：
+
+```sh
+pnpm run mock:llm -- \
+  --port 8000 \
+  --sequence random \
+  --repeat-last \
+  --seed 42 \
+  --random-weights 'success=60,slow_success=10,connection_reset=5,stream_disconnect=5,partial_disconnect=10,empty=5,server_error=5'
+```
+
+省略 `--seed` 会生成种子，并在 `ready` 记录中打印。`--random-weights` 接受非负的相对 `behavior=weight` 条目，并要求至少一个正权重具体行为。导出默认值是一个成功占主导的压力分布，包含 reset、disconnect、部分输出、空完成、stall、429/5xx、干净截断和格式错误的 JSON；它用于施加测试压力，而非估计生产事故频率。`connection_refused` 被排除，因为已绑定的请求处理器无法产生真实拒绝。
+
+随机权重包含 `stall` 时，为待测客户端配置较短的流空闲超时，使场景及时结束。
+
+## 时序与内容控制
+
+CLI 公开 `--success-text`、`--partial-text`、`--reasoning-text`、`--chunk-size`、`--chunk-delay-ms`、`--disconnect-delay-ms`、`--retry-after-ms`、`--request-id`、`--tool-name` 和 `--tool-arguments`。毫秒延迟是 Node timer 范围内的有界整数；`retryAfterMs` 还必须为正数。库接受相同的 camel-case 选项。可选的 `apiKey` 会精确验证 `Authorization: Bearer <token>`；省略时接受任何 token。
+
+## 模型体验
+
+无。该测试服务器替代提供方协议行为，而不调用真实模型。
+
+#### KV Cache 影响
+
+无；请求在本地终止，绝不会到达提供方缓存。
+
+## 已知限制与暂缓事项
+
+- **随机权重建模测试压力，而非生产事故频率**：需要环境专用分布的调用方必须提供已测量权重，并记录发出的种子。
+- **请求脚本按到达顺序执行**：并发调用方共享一个游标，因此确定性的每会话故障分配需要独立服务器实例。
+- **真实连接拒绝发生在监听器生命周期阶段**：CLI 延迟必须与客户端尝试重叠；请求级随机选择只能重置已接受的连接。

package/lib/index.js

@@ -0,0 +1,520 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { isIP } from "node:net";
+import { setTimeout } from "node:timers/promises";
+//#region lib/types/index.js
+/**
+* Scriptable OpenAI-compatible HTTP/SSE server for transport, protocol, and
+* semantic-empty LLM recovery tests. Each accepted chat-completions request
+* consumes one behavior; the server never retries or interprets harness policy.
+*
+* @module @deepseek-ai/dsh-llm-mock-server
+*/
+/** Request-scoped behaviors accepted by {@link startMockLlmServer}. */
+const MOCK_LLM_BEHAVIORS = [
+	"connection_reset",
+	"stream_disconnect",
+	"empty",
+	"empty_body",
+	"stream_eof",
+	"partial_eof",
+	"partial_disconnect",
+	"stall",
+	"malformed_json",
+	"malformed_event",
+	"wrong_content_type",
+	"rate_limit",
+	"server_error",
+	"service_unavailable",
+	"auth_error",
+	"invalid_request",
+	"context_overflow",
+	"quota_exceeded",
+	"success",
+	"reasoning_success",
+	"tool_call_success",
+	"max_tokens",
+	"slow_success",
+	"random"
+];
+/**
+* Default stress profile for `random`. Weights are configurable test pressure,
+* not a claim about production incident frequency.
+*/
+const DEFAULT_MOCK_LLM_RANDOM_WEIGHTS = Object.freeze({
+	success: 48,
+	slow_success: 10,
+	max_tokens: 2,
+	connection_reset: 5,
+	stream_disconnect: 5,
+	partial_disconnect: 10,
+	empty: 5,
+	stall: 2,
+	rate_limit: 5,
+	server_error: 4,
+	service_unavailable: 2,
+	partial_eof: 1,
+	malformed_json: 1
+});
+/** Largest millisecond delay accepted by Node timers without truncation. */
+const MAX_MOCK_LLM_TIMER_DELAY_MS = 2147483647;
+const DEFAULT_SUCCESS_TEXT = "mock response recovered";
+const DEFAULT_PARTIAL_TEXT = "discarded partial response";
+const DEFAULT_REASONING_TEXT = "mock reasoning";
+const CONCRETE_BEHAVIORS = new Set(MOCK_LLM_BEHAVIORS.filter((behavior) => behavior !== "random"));
+function boundedInteger(name, value, min, max) {
+	if (!Number.isInteger(value) || value < min || value > max) throw new Error(`llm-mock-server: ${name} must be an integer between ${min} and ${max}`);
+	return value;
+}
+function resolveOptions(options) {
+	const host = options.host ?? "127.0.0.1";
+	const port = boundedInteger("port", options.port ?? 0, 0, 65535);
+	const chunkSize = boundedInteger("chunkSize", options.chunkSize ?? 8, 1, Number.MAX_SAFE_INTEGER);
+	const chunkDelayMs = boundedInteger("chunkDelayMs", options.chunkDelayMs ?? 25, 0, MAX_MOCK_LLM_TIMER_DELAY_MS);
+	const disconnectDelayMs = boundedInteger("disconnectDelayMs", options.disconnectDelayMs ?? 10, 0, MAX_MOCK_LLM_TIMER_DELAY_MS);
+	const retryAfterMs = boundedInteger("retryAfterMs", options.retryAfterMs ?? 1e3, 1, MAX_MOCK_LLM_TIMER_DELAY_MS);
+	const randomSeed = boundedInteger("randomSeed", options.randomSeed ?? randomBytes(4).readUInt32LE(0), 0, 4294967295);
+	const successText = options.successText ?? DEFAULT_SUCCESS_TEXT;
+	const partialText = options.partialText ?? DEFAULT_PARTIAL_TEXT;
+	const reasoningText = options.reasoningText ?? DEFAULT_REASONING_TEXT;
+	const toolName = options.toolName ?? "mock_tool";
+	const toolArguments = options.toolArguments ?? "{\"value\":\"mock\"}";
+	if (host.length === 0) throw new Error("llm-mock-server: host must not be empty");
+	if (options.sequence.length === 0) throw new Error("llm-mock-server: sequence must not be empty");
+	const lastBehavior = options.sequence.reduce((_previous, behavior) => behavior);
+	if (options.apiKey === "") throw new Error("llm-mock-server: apiKey must not be empty");
+	if (successText.length === 0) throw new Error("llm-mock-server: successText must not be empty");
+	if (partialText.length === 0) throw new Error("llm-mock-server: partialText must not be empty");
+	if (reasoningText.length === 0) throw new Error("llm-mock-server: reasoningText must not be empty");
+	if (toolName.length === 0) throw new Error("llm-mock-server: toolName must not be empty");
+	if (options.requestId === "") throw new Error("llm-mock-server: requestId must not be empty");
+	try {
+		JSON.parse(toolArguments);
+	} catch {
+		throw new Error("llm-mock-server: toolArguments must be valid JSON");
+	}
+	const configuredWeights = options.randomWeights ?? DEFAULT_MOCK_LLM_RANDOM_WEIGHTS;
+	const randomWeights = [];
+	for (const [behavior, weight] of Object.entries(configuredWeights)) {
+		if (!CONCRETE_BEHAVIORS.has(behavior)) throw new Error(`llm-mock-server: randomWeights contains unknown concrete behavior ${JSON.stringify(behavior)}`);
+		if (!Number.isFinite(weight) || weight < 0) throw new Error(`llm-mock-server: random weight for ${behavior} must be a non-negative finite number`);
+		if (weight > 0) randomWeights.push([behavior, weight]);
+	}
+	if (randomWeights.length === 0) throw new Error("llm-mock-server: randomWeights must contain at least one positive weight");
+	return {
+		host,
+		port,
+		...options.apiKey === void 0 ? {} : { apiKey: options.apiKey },
+		sequence: [...options.sequence],
+		lastBehavior,
+		repeatLast: options.repeatLast ?? false,
+		randomSeed,
+		randomWeights,
+		successText,
+		partialText,
+		reasoningText,
+		chunkSize,
+		chunkDelayMs,
+		disconnectDelayMs,
+		retryAfterMs,
+		...options.requestId === void 0 ? {} : { requestId: options.requestId },
+		toolName,
+		toolArguments,
+		...options.onEvent === void 0 ? {} : { onEvent: options.onEvent }
+	};
+}
+function emit(options, event) {
+	try {
+		options.onEvent?.(Object.freeze(event));
+	} catch (_telemetryObserverFailure) {}
+}
+async function readJsonBody(request) {
+	const chunks = [];
+	for await (const chunk of request) chunks.push(Buffer.from(chunk));
+	const body = Buffer.concat(chunks).toString("utf8");
+	return body.length === 0 ? void 0 : JSON.parse(body);
+}
+function splitText(text, size) {
+	const points = Array.from(text);
+	const chunks = [];
+	for (let index = 0; index < points.length; index += size) chunks.push(points.slice(index, index + size).join(""));
+	return chunks;
+}
+function openSse(response, contentType = "text/event-stream; charset=utf-8") {
+	response.writeHead(200, {
+		"content-type": contentType,
+		"cache-control": "no-cache",
+		"connection": "keep-alive"
+	});
+	response.flushHeaders();
+}
+function writeSse(record, response, payload) {
+	response.write(`data: ${typeof payload === "string" ? payload : JSON.stringify(payload)}\n\n`);
+	record.chunksSent += 1;
+}
+function writeDone(record, response) {
+	writeSse(record, response, "[DONE]");
+}
+function finishRecord(options, record, outcome) {
+	if (record.outcome !== void 0) return;
+	record.outcome = outcome;
+	emit(options, {
+		type: "result",
+		attempt: record.attempt,
+		scriptBehavior: record.scriptBehavior,
+		behavior: record.behavior,
+		outcome,
+		chunksSent: record.chunksSent
+	});
+}
+function httpError(options, record, response, status, message, code, type = "mock_error") {
+	const headers = { "content-type": "application/json" };
+	if (record.behavior === "rate_limit") headers["retry-after"] = String(Math.ceil(options.retryAfterMs / 1e3));
+	if (options.requestId !== void 0) headers["x-request-id"] = options.requestId;
+	response.writeHead(status, headers);
+	response.end(JSON.stringify({ error: {
+		message,
+		type,
+		code
+	} }));
+	finishRecord(options, record, "completed");
+}
+function terminalChunk(reason, outputTokens) {
+	return {
+		choices: [{
+			index: 0,
+			delta: { content: "" },
+			finish_reason: reason
+		}],
+		usage: {
+			prompt_tokens: 3,
+			completion_tokens: outputTokens
+		}
+	};
+}
+async function pause(milliseconds, response) {
+	if (milliseconds === 0) return !response.destroyed;
+	const controller = new AbortController();
+	const stop = () => {
+		controller.abort();
+	};
+	response.once("close", stop);
+	try {
+		await setTimeout(milliseconds, void 0, { signal: controller.signal });
+		return true;
+	} catch (_responseClosed) {
+		return false;
+	} finally {
+		response.off("close", stop);
+	}
+}
+async function streamText(options, record, response, text, delayMs) {
+	for (const chunk of splitText(text, options.chunkSize)) {
+		writeSse(record, response, { choices: [{
+			index: 0,
+			delta: { content: chunk },
+			finish_reason: null
+		}] });
+		if (!await pause(delayMs, response)) return false;
+	}
+	return true;
+}
+async function completeText(options, record, response, reason, delayMs) {
+	if (!await streamText(options, record, response, options.successText, delayMs)) {
+		finishRecord(options, record, "client_closed");
+		return;
+	}
+	writeSse(record, response, terminalChunk(reason, Array.from(options.successText).length));
+	writeDone(record, response);
+	response.end();
+	finishRecord(options, record, "completed");
+}
+async function disconnect(options, record, response) {
+	if (!await pause(options.disconnectDelayMs, response)) {
+		finishRecord(options, record, "client_closed");
+		return;
+	}
+	finishRecord(options, record, "reset");
+	response.destroy();
+}
+function toolCallChunks(options) {
+	const midpoint = Math.max(1, Math.floor(options.toolArguments.length / 2));
+	return [{ choices: [{
+		index: 0,
+		delta: { tool_calls: [{
+			index: 0,
+			id: "mock-call-1",
+			type: "function",
+			function: {
+				name: options.toolName,
+				arguments: options.toolArguments.slice(0, midpoint)
+			}
+		}] },
+		finish_reason: null
+	}] }, { choices: [{
+		index: 0,
+		delta: { tool_calls: [{
+			index: 0,
+			function: { arguments: options.toolArguments.slice(midpoint) }
+		}] },
+		finish_reason: null
+	}] }];
+}
+async function runBehavior(options, record, request, response) {
+	switch (record.behavior) {
+		case "script_exhausted":
+			httpError(options, record, response, 500, "mock script exhausted", "MOCK_SCRIPT_EXHAUSTED");
+			return;
+		case "connection_reset":
+			finishRecord(options, record, "reset");
+			request.socket.destroy();
+			return;
+		case "stream_disconnect":
+			openSse(response);
+			await disconnect(options, record, response);
+			return;
+		case "empty":
+			openSse(response);
+			writeSse(record, response, terminalChunk("stop", 0));
+			writeDone(record, response);
+			response.end();
+			finishRecord(options, record, "completed");
+			return;
+		case "empty_body":
+			openSse(response);
+			response.end();
+			finishRecord(options, record, "completed");
+			return;
+		case "stream_eof":
+			openSse(response);
+			writeSse(record, response, { choices: [{
+				index: 0,
+				delta: { role: "assistant" },
+				finish_reason: null
+			}] });
+			response.end();
+			finishRecord(options, record, "completed");
+			return;
+		case "partial_eof":
+			openSse(response);
+			await streamText(options, record, response, options.partialText, 0);
+			response.end();
+			finishRecord(options, record, "completed");
+			return;
+		case "partial_disconnect":
+			openSse(response);
+			if (!await streamText(options, record, response, options.partialText, options.chunkDelayMs)) return;
+			await disconnect(options, record, response);
+			return;
+		case "stall":
+			openSse(response);
+			finishRecord(options, record, "stalled");
+			return;
+		case "malformed_json":
+			openSse(response);
+			writeSse(record, response, "{not-json");
+			writeDone(record, response);
+			response.end();
+			finishRecord(options, record, "completed");
+			return;
+		case "malformed_event":
+			openSse(response);
+			writeSse(record, response, { choices: [null] });
+			writeDone(record, response);
+			response.end();
+			finishRecord(options, record, "completed");
+			return;
+		case "wrong_content_type":
+			openSse(response, "application/json");
+			await completeText(options, record, response, "stop", 0);
+			return;
+		case "rate_limit":
+			httpError(options, record, response, 429, "mock rate limit", "rate_limit");
+			return;
+		case "server_error":
+			httpError(options, record, response, 500, "mock server error", "server_error");
+			return;
+		case "service_unavailable":
+			httpError(options, record, response, 503, "mock service unavailable", "service_unavailable");
+			return;
+		case "auth_error":
+			httpError(options, record, response, 401, "mock authentication failed", "invalid_api_key");
+			return;
+		case "invalid_request":
+			httpError(options, record, response, 400, "mock invalid request", "invalid_request");
+			return;
+		case "context_overflow":
+			httpError(options, record, response, 400, "mock input exceeds the model context window", "context_length_exceeded", "invalid_request_error");
+			return;
+		case "quota_exceeded":
+			httpError(options, record, response, 429, "mock insufficient quota", "insufficient_quota");
+			return;
+		case "success":
+			openSse(response);
+			await completeText(options, record, response, "stop", 0);
+			return;
+		case "reasoning_success":
+			openSse(response);
+			for (const chunk of splitText(options.reasoningText, options.chunkSize)) writeSse(record, response, { choices: [{
+				index: 0,
+				delta: { reasoning_content: chunk },
+				finish_reason: null
+			}] });
+			await completeText(options, record, response, "stop", 0);
+			return;
+		case "tool_call_success":
+			openSse(response);
+			for (const chunk of toolCallChunks(options)) writeSse(record, response, chunk);
+			writeSse(record, response, terminalChunk("tool_calls", 2));
+			writeDone(record, response);
+			response.end();
+			finishRecord(options, record, "completed");
+			return;
+		case "max_tokens":
+			openSse(response);
+			await completeText(options, record, response, "length", 0);
+			return;
+		case "slow_success":
+			openSse(response);
+			await completeText(options, record, response, "stop", options.chunkDelayMs);
+			return;
+	}
+}
+function seededRandom(seed) {
+	let state = seed;
+	return () => {
+		state = state + 1831565813 >>> 0;
+		let mixed = state;
+		mixed = Math.imul(mixed ^ mixed >>> 15, mixed | 1);
+		mixed ^= mixed + Math.imul(mixed ^ mixed >>> 7, mixed | 61);
+		return ((mixed ^ mixed >>> 14) >>> 0) / 4294967296;
+	};
+}
+function chooseRandomBehavior(weights, random) {
+	const total = weights.reduce((sum, entry) => sum + entry[1], 0);
+	let draw = random() * total;
+	for (const [behavior, weight] of weights) {
+		if (draw < weight) return behavior;
+		draw -= weight;
+	}
+	/* v8 ignore next -- seededRandom is strictly less than one; this guards floating-point residue only */
+	return weights.at(-1)[0];
+}
+/**
+* Start a local chat-completions server that consumes one configured behavior
+* per accepted request. Only a `POST` path ending in `/chat/completions` consumes the script;
+* invalid routes, methods, authorization, and JSON receive ordinary 4xx
+* responses. Closing the handle terminates stalled connections.
+*
+* @param options - listener, script, response content, timing, and telemetry options.
+* @returns the listening handle after the port is bound.
+*/
+async function startMockLlmServer(options) {
+	const resolved = resolveOptions(options);
+	const requests = [];
+	const random = seededRandom(resolved.randomSeed);
+	let cursor = 0;
+	const selectBehavior = () => {
+		const selected = resolved.sequence[cursor];
+		cursor += 1;
+		const scriptBehavior = selected ?? (resolved.repeatLast ? resolved.lastBehavior : "script_exhausted");
+		return {
+			scriptBehavior,
+			behavior: scriptBehavior === "random" ? chooseRandomBehavior(resolved.randomWeights, random) : scriptBehavior
+		};
+	};
+	const handle = async (request, response) => {
+		/* v8 ignore next -- node:http server requests always carry a URL despite the shared optional type */
+		const path = new URL(request.url ?? "/", "http://mock.invalid").pathname;
+		if (request.method !== "POST") {
+			response.writeHead(405, { allow: "POST" }).end();
+			return;
+		}
+		if (!path.endsWith("/chat/completions")) {
+			response.writeHead(404).end();
+			return;
+		}
+		if (resolved.apiKey !== void 0 && request.headers.authorization !== `Bearer ${resolved.apiKey}`) {
+			response.writeHead(401, { "content-type": "application/json" });
+			response.end(JSON.stringify({ error: {
+				message: "invalid mock bearer token",
+				code: "invalid_api_key"
+			} }));
+			return;
+		}
+		let body;
+		try {
+			body = await readJsonBody(request);
+		} catch {
+			response.writeHead(400, { "content-type": "application/json" });
+			response.end(JSON.stringify({ error: {
+				message: "request body must be valid JSON",
+				code: "invalid_json"
+			} }));
+			return;
+		}
+		const selected = selectBehavior();
+		const record = {
+			attempt: requests.length + 1,
+			scriptBehavior: selected.scriptBehavior,
+			behavior: selected.behavior,
+			path,
+			headers: { ...request.headers },
+			body,
+			chunksSent: 0
+		};
+		requests.push(record);
+		response.once("close", () => {
+			if (!response.writableFinished && record.outcome === void 0) finishRecord(resolved, record, "client_closed");
+		});
+		emit(resolved, {
+			type: "request",
+			attempt: record.attempt,
+			scriptBehavior: record.scriptBehavior,
+			behavior: record.behavior,
+			path
+		});
+		await runBehavior(resolved, record, request, response);
+	};
+	const server = createServer((request, response) => {
+		/* v8 ignore start -- last-resort containment for Node response failures after validated test inputs */
+		handle(request, response).catch((error) => {
+			const record = requests.at(-1);
+			if (record !== void 0) finishRecord(resolved, record, "server_error");
+			if (response.headersSent) {
+				response.destroy(error instanceof Error ? error : new Error(String(error)));
+				return;
+			}
+			response.writeHead(500, { "content-type": "application/json" });
+			response.end(JSON.stringify({ error: {
+				message: "mock server handler failed",
+				code: "MOCK_HANDLER_FAILED"
+			} }));
+		});
+		/* v8 ignore stop */
+	});
+	let closing;
+	const close = () => closing ??= new Promise((resolveClose) => {
+		server.close(() => {
+			resolveClose();
+		});
+		server.closeAllConnections();
+	});
+	await new Promise((resolveListen, rejectListen) => {
+		server.once("error", rejectListen);
+		server.listen(resolved.port, resolved.host, () => {
+			server.off("error", rejectListen);
+			resolveListen();
+		});
+	});
+	const address = server.address();
+	return {
+		baseURL: `http://${isIP(resolved.host) === 6 ? `[${resolved.host}]` : resolved.host}:${address.port}`,
+		port: address.port,
+		randomSeed: resolved.randomSeed,
+		requests,
+		close
+	};
+}
+//#endregion
+export { DEFAULT_MOCK_LLM_RANDOM_WEIGHTS, MAX_MOCK_LLM_TIMER_DELAY_MS, MOCK_LLM_BEHAVIORS, startMockLlmServer };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-llm-mock-server`.
+* @module @deepseek-ai/dsh-llm-mock-server/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-llm-mock-server";
+/** Cordis companion plugin name. */
+const name = "llm-mock-server-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this standalone test server owns no Cordis event stream or shared data;
+* its wire behavior and lifecycle are exercised through direct HTTP and assembled-loop tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/bin.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Standalone process wrapper for the scriptable mock LLM server.
+ * @module @deepseek-ai/dsh-llm-mock-server/src/bin
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/lib/types/cli.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Dependency-free CLI parsing for the standalone mock LLM server.
+ * @module @deepseek-ai/dsh-llm-mock-server/cli
+ */
+import type { MockLlmServerOptions } from './index.ts';
+/** Listener lifecycle behavior understood only by the standalone CLI. */
+export declare const CONNECTION_REFUSED_BEHAVIOR = "connection_refused";
+/** Parsed CLI configuration, including a pre-listen unavailable interval. */
+export interface MockLlmCliConfig {
+    /** Server options after removing the lifecycle-only `connection_refused` entry. */
+    readonly server: MockLlmServerOptions;
+    /** Delay before binding the model port; an integer from zero through the Node timer maximum. */
+    readonly listenDelayMs: number;
+    /** Whether the original sequence requested a true pre-listen refusal phase. */
+    readonly startsUnavailable: boolean;
+}
+/** Result of parsing `dsh-llm-mock-server` arguments. */
+export type MockLlmCliParseResult = {
+    readonly kind: 'help';
+} | {
+    readonly kind: 'run';
+    readonly config: MockLlmCliConfig;
+};
+/** Command usage written for `--help` and invalid arguments. */
+export declare const MOCK_LLM_CLI_USAGE = "Usage: dsh-llm-mock-server [options]\n\nRequired:\n  --sequence <a,b,...>       Ordered behaviors; connection_refused is allowed first\n\nListener:\n  --host <host>              Default 127.0.0.1\n  --port <port>              Default 8000; required and nonzero for connection_refused\n  --api-key <token>          Validate exact Bearer token when present\n  --listen-delay-ms <ms>     Unavailable interval (default 750 with connection_refused)\n  --repeat-last              Repeat the final request behavior after exhaustion\n  --seed <uint32>            Reproduce random selections\n  --random-weights <a=n,...> Relative weights for concrete behaviors\n\nResponse:\n  --success-text <text>\n  --partial-text <text>\n  --reasoning-text <text>\n  --chunk-size <count>\n  --chunk-delay-ms <ms>\n  --disconnect-delay-ms <ms>\n  --retry-after-ms <ms>\n  --request-id <id>\n  --tool-name <name>\n  --tool-arguments <json>\n\nOther:\n  --help\n";
+/**
+ * Parse standalone server arguments without starting a process or listener.
+ * Tokenizing rides `node:util` `parseArgs` (strict, no positionals); numeric
+ * coercion, bounds, and cross-option constraints remain manual below it.
+ * @param argv - arguments after the executable name.
+ * @returns help or validated run configuration.
+ */
+export declare function parseMockLlmCliArgs(argv: readonly string[]): MockLlmCliParseResult;
+//# sourceMappingURL=cli.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Scriptable OpenAI-compatible HTTP/SSE server for transport, protocol, and
+ * semantic-empty LLM recovery tests. Each accepted chat-completions request
+ * consumes one behavior; the server never retries or interprets harness policy.
+ *
+ * @module @deepseek-ai/dsh-llm-mock-server
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+/** Request-scoped behaviors accepted by {@link startMockLlmServer}. */
+export declare const MOCK_LLM_BEHAVIORS: readonly ["connection_reset", "stream_disconnect", "empty", "empty_body", "stream_eof", "partial_eof", "partial_disconnect", "stall", "malformed_json", "malformed_event", "wrong_content_type", "rate_limit", "server_error", "service_unavailable", "auth_error", "invalid_request", "context_overflow", "quota_exceeded", "success", "reasoning_success", "tool_call_success", "max_tokens", "slow_success", "random"];
+/** One scripted mock behavior name; `random` selects a concrete behavior per request. */
+export type MockLlmBehavior = typeof MOCK_LLM_BEHAVIORS[number];
+/** One concrete request behavior after resolving a `random` script entry. */
+export type ConcreteMockLlmBehavior = Exclude<MockLlmBehavior, 'random'>;
+/** Relative non-negative weights for random request behavior selection. */
+export type MockLlmRandomWeights = Partial<Record<ConcreteMockLlmBehavior, number>>;
+/**
+ * Default stress profile for `random`. Weights are configurable test pressure,
+ * not a claim about production incident frequency.
+ */
+export declare const DEFAULT_MOCK_LLM_RANDOM_WEIGHTS: Readonly<MockLlmRandomWeights>;
+/** Largest millisecond delay accepted by Node timers without truncation. */
+export declare const MAX_MOCK_LLM_TIMER_DELAY_MS = 2147483647;
+/** How one accepted request ended at the mock boundary. */
+export type MockLlmRequestOutcome = 'completed' | 'reset' | 'stalled' | 'client_closed' | 'server_error';
+/** Immutable telemetry emitted when a request starts or reaches an outcome. */
+export type MockLlmServerEvent = {
+    readonly type: 'request';
+    readonly attempt: number;
+    readonly scriptBehavior: MockLlmBehavior | 'script_exhausted';
+    readonly behavior: ConcreteMockLlmBehavior | 'script_exhausted';
+    readonly path: string;
+} | {
+    readonly type: 'result';
+    readonly attempt: number;
+    readonly scriptBehavior: MockLlmBehavior | 'script_exhausted';
+    readonly behavior: ConcreteMockLlmBehavior | 'script_exhausted';
+    readonly outcome: MockLlmRequestOutcome;
+    readonly chunksSent: number;
+};
+/** Captured wire request and its final server-side outcome. */
+export interface MockLlmRequestRecord {
+    /** One-based accepted chat-completions request number. */
+    readonly attempt: number;
+    /** Script entry consumed for this request before random resolution. */
+    readonly scriptBehavior: MockLlmBehavior | 'script_exhausted';
+    /** Concrete behavior selected for this request, or exhaustion after the configured script. */
+    readonly behavior: ConcreteMockLlmBehavior | 'script_exhausted';
+    /** Original request path, including a `/v1` prefix when the client supplied one. */
+    readonly path: string;
+    /** Detached request headers. */
+    readonly headers: Readonly<IncomingHttpHeaders>;
+    /** Parsed JSON request body. */
+    readonly body: unknown;
+    /** Number of SSE `data:` events handed to Node before the outcome. */
+    chunksSent: number;
+    /** Final server-side outcome; absent while a stalled request remains open. */
+    outcome?: MockLlmRequestOutcome;
+}
+/** Configuration for one mock server instance. */
+export interface MockLlmServerOptions {
+    /** Loopback host by default. */
+    readonly host?: string;
+    /** TCP port; zero requests an OS-assigned port. */
+    readonly port?: number;
+    /** Optional exact bearer token; omission accepts any authorization header. */
+    readonly apiKey?: string;
+    /** Ordered request behaviors; exhaustion fails loud unless `repeatLast` is true. */
+    readonly sequence: readonly MockLlmBehavior[];
+    /** Reuse the final behavior after the sequence is consumed. */
+    readonly repeatLast?: boolean;
+    /** Optional deterministic unsigned 32-bit seed; omission generates and exposes one. */
+    readonly randomSeed?: number;
+    /** Relative weights used whenever a script entry is `random`. */
+    readonly randomWeights?: Readonly<MockLlmRandomWeights>;
+    /** Complete text returned by success-shaped behaviors. */
+    readonly successText?: string;
+    /** Text emitted before partial EOF/reset behaviors terminate. */
+    readonly partialText?: string;
+    /** Reasoning text emitted by `reasoning_success`. */
+    readonly reasoningText?: string;
+    /** Unicode code-point count per text or reasoning SSE delta. */
+    readonly chunkSize?: number;
+    /** Inter-chunk delay for `slow_success`, in milliseconds. */
+    readonly chunkDelayMs?: number;
+    /** Delay after headers/deltas before a forced disconnect, in milliseconds. */
+    readonly disconnectDelayMs?: number;
+    /** Provider retry delay; the wire `Retry-After` value rounds up to whole seconds. */
+    readonly retryAfterMs?: number;
+    /** Optional provider request id returned on HTTP failures. */
+    readonly requestId?: string;
+    /** Tool name emitted by `tool_call_success`. */
+    readonly toolName?: string;
+    /** Raw JSON arguments emitted by `tool_call_success`. */
+    readonly toolArguments?: string;
+    /** Optional observer for JSONL CLI telemetry; observer failures never affect wire behavior. */
+    readonly onEvent?: (event: MockLlmServerEvent) => void;
+}
+/** Running mock server and captured request state. */
+export interface MockLlmServer {
+    /** Base URL without `/v1`; both root and `/v1` chat-completions paths are accepted. */
+    readonly baseURL: string;
+    /** Actual bound port, including an OS-assigned value. */
+    readonly port: number;
+    /** Seed used for random behavior selection, including the generated default. */
+    readonly randomSeed: number;
+    /** Live request records in arrival order. */
+    readonly requests: readonly MockLlmRequestRecord[];
+    /** Stop accepting requests and force-close stalled/streaming connections; idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Start a local chat-completions server that consumes one configured behavior
+ * per accepted request. Only a `POST` path ending in `/chat/completions` consumes the script;
+ * invalid routes, methods, authorization, and JSON receive ordinary 4xx
+ * responses. Closing the handle terminates stalled connections.
+ *
+ * @param options - listener, script, response content, timing, and telemetry options.
+ * @returns the listening handle after the port is bound.
+ */
+export declare function startMockLlmServer(options: MockLlmServerOptions): Promise<MockLlmServer>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-llm-mock-server`.
+ * @module @deepseek-ai/dsh-llm-mock-server/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "llm-mock-server-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-llm-mock-server",
+  "description": "Scriptable OpenAI-compatible HTTP/SSE fault server for LLM recovery tests",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/support/llm-mock-server"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+  }
+}