jeopi-ai 16.2.13

package/src/utils/schema/zod-decontaminate.ts

@@ -0,0 +1,331 @@
+/**
+ * Defensive rewrite for nodes that look like `JSON.stringify(zodSchemaInstance)`
+ * output rather than JSON Schema. MCP servers using Zod 4 sometimes ship a
+ * serialised schema instance directly as a tool's `inputSchema`, because the
+ * fields Zod surfaces on its instances (`type`, `enum`, `options`, `def`) shadow
+ * (and clash with) JSON Schema keywords. The resulting payload is neither valid
+ * Zod nor valid JSON Schema 2020-12 and Anthropic's strict validator rejects
+ * the whole tool list.
+ *
+ * Symptoms we've observed (gitnexus_impact.direction):
+ *   {
+ *     def:   { type: "enum", entries: { upstream: "upstream", ... } },
+ *     type:  "enum",                       // <- invalid `type` value
+ *     enum:  { upstream: "upstream", ... }, // <- `enum` MUST be an array
+ *     options: ["upstream", "downstream"],
+ *   }
+ *
+ * This module recognises the shape (`def.type === node.type` and `def.type` is
+ * a known Zod kind) and rewrites it to clean JSON Schema where deterministic.
+ * For Zod kinds we don't fully model, we strip the toxic siblings (`def`,
+ * `options`, object-shaped `enum`) and drop an invalid `type` so the remainder
+ * passes meta-schema validation as a permissive node.
+ *
+ * Pure / identity-preserving: returns the input reference when nothing changes.
+ */
+
+import { isJsonObject, type JsonObject } from "./types";
+
+const VALID_JSON_SCHEMA_TYPES: Record<string, true> = {
+	string: true,
+	number: true,
+	integer: true,
+	boolean: true,
+	object: true,
+	array: true,
+	null: true,
+};
+
+/**
+ * Known Zod 4 schema kinds as surfaced on `_def.type` / `.type`. Matching this
+ * set (rather than just "has `def`") is what keeps us from rewriting legitimate
+ * JSON Schemas that happen to use `def` as a property name.
+ */
+const ZOD_KINDS: Record<string, true> = {
+	string: true,
+	number: true,
+	int: true,
+	boolean: true,
+	bigint: true,
+	null: true,
+	undefined: true,
+	void: true,
+	any: true,
+	unknown: true,
+	never: true,
+	date: true,
+	symbol: true,
+	nan: true,
+	enum: true,
+	literal: true,
+	object: true,
+	array: true,
+	tuple: true,
+	record: true,
+	map: true,
+	set: true,
+	union: true,
+	discriminatedUnion: true,
+	intersection: true,
+	lazy: true,
+	promise: true,
+	function: true,
+	file: true,
+	custom: true,
+	template_literal: true,
+	optional: true,
+	nullable: true,
+	default: true,
+	prefault: true,
+	catch: true,
+	pipe: true,
+	transform: true,
+	brand: true,
+	readonly: true,
+	success: true,
+	nonoptional: true,
+};
+
+const ZOD_SCALAR_TO_JSON_TYPE: Record<string, string> = {
+	string: "string",
+	number: "number",
+	int: "integer",
+	boolean: "boolean",
+	null: "null",
+	bigint: "string",
+	date: "string",
+	nan: "number",
+};
+
+const ZOD_NOISE_KEYS: Record<string, true> = {
+	def: true,
+	options: true,
+	_zod: true,
+	checks: true,
+};
+
+/**
+ * JSON Schema keywords where `null` is a legal value (literal payload positions).
+ * Anywhere else, a `null`-valued key is a meta-schema violation — Zod scalars
+ * leak `format: null`, `minLength: null`, etc. that we have to scrub.
+ */
+const KEYS_THAT_ACCEPT_NULL: Record<string, true> = {
+	default: true,
+	const: true,
+	examples: true,
+};
+
+function isZodLeak(node: JsonObject): boolean {
+	const def = node.def;
+	if (!isJsonObject(def)) return false;
+	const defType = def.type;
+	if (typeof defType !== "string" || !ZOD_KINDS[defType]) return false;
+	// Both surface and inner `.type` must agree — Zod always mirrors `_def.type`
+	// onto the instance, so this is a near-zero false-positive guard.
+	return node.type === defType;
+}
+
+function inferTypeFromValues(values: readonly unknown[]): string {
+	if (values.length === 0) return "string";
+	const first = values[0];
+	if (typeof first === "number") return Number.isInteger(first) ? "integer" : "number";
+	if (typeof first === "boolean") return "boolean";
+	if (first === null) return "null";
+	return "string";
+}
+
+function unwrapInnerSchema(def: JsonObject): unknown {
+	// Zod uses different fields depending on the wrapper:
+	//   optional/nullable/readonly/brand/default → `innerType`
+	//   pipe → `in` (or `out`)
+	//   lazy → `getter` (a function — gone after JSON.stringify); fall back to {}
+	return def.innerType ?? def.in ?? def.out ?? def.schema ?? def.element ?? {};
+}
+
+function copyWithoutNoise(node: JsonObject): JsonObject {
+	const out: JsonObject = {};
+	for (const key in node) {
+		if (ZOD_NOISE_KEYS[key]) continue;
+		const value = node[key];
+		if (value === null && !KEYS_THAT_ACCEPT_NULL[key]) continue;
+		out[key] = value;
+	}
+	return out;
+}
+
+function rewriteZodNode(node: JsonObject, seen: WeakSet<object>): unknown {
+	const def = node.def as JsonObject;
+	const kind = def.type as string;
+
+	switch (kind) {
+		case "enum": {
+			// Prefer node.options (array form Zod exposes) → def.entries values →
+			// object-shaped node.enum values. All three carry the same data.
+			const optionsArray = Array.isArray(node.options) ? (node.options as unknown[]) : null;
+			const entries = isJsonObject(def.entries) ? Object.values(def.entries) : null;
+			const enumObj = isJsonObject(node.enum) ? Object.values(node.enum) : null;
+			const values = optionsArray ?? entries ?? enumObj ?? [];
+			return { type: inferTypeFromValues(values), enum: values };
+		}
+
+		case "literal": {
+			const values = Array.isArray(def.values) ? (def.values as unknown[]) : [];
+			if (values.length === 1) {
+				return { const: values[0] };
+			}
+			if (values.length > 1) {
+				return { type: inferTypeFromValues(values), enum: values };
+			}
+			return {};
+		}
+
+		case "union":
+		case "discriminatedUnion": {
+			const arms = Array.isArray(def.options)
+				? (def.options as unknown[])
+				: Array.isArray(node.options)
+					? (node.options as unknown[])
+					: [];
+			return { anyOf: arms.map(x => walk(x, seen)) };
+		}
+
+		case "intersection": {
+			return {
+				allOf: [walk(def.left, seen), walk(def.right, seen)],
+			};
+		}
+
+		case "array": {
+			return { type: "array", items: walk(def.element, seen) };
+		}
+
+		case "set": {
+			const element = def.valueType ?? def.element;
+			return { type: "array", uniqueItems: true, items: walk(element, seen) };
+		}
+
+		case "tuple": {
+			const items = Array.isArray(def.items) ? (def.items as unknown[]) : [];
+			const out: JsonObject = { type: "array", prefixItems: items.map(x => walk(x, seen)) };
+			const rest = def.rest;
+			if (rest != null) out.items = walk(rest, seen);
+			return out;
+		}
+
+		case "record":
+		case "map": {
+			return { type: "object", additionalProperties: walk(def.valueType, seen) };
+		}
+
+		case "object": {
+			const shape = isJsonObject(def.shape) ? def.shape : ({} as JsonObject);
+			const properties: JsonObject = {};
+			const required: string[] = [];
+			for (const key in shape) {
+				const inner = walk(shape[key], seen);
+				properties[key] = inner;
+				if (!isOptionalEntry(shape[key])) required.push(key);
+			}
+			const out: JsonObject = { type: "object", properties };
+			if (required.length > 0) out.required = required;
+			return out;
+		}
+
+		case "nonoptional":
+		case "optional":
+		case "nullable":
+		case "default":
+		case "prefault":
+		case "catch":
+		case "readonly":
+		case "brand":
+		case "lazy":
+		case "pipe":
+		case "transform": {
+			const inner = walk(unwrapInnerSchema(def), seen);
+			if (kind === "nullable" && isJsonObject(inner)) {
+				if (typeof inner.type === "string") {
+					return { ...inner, type: [inner.type, "null"] };
+				}
+				if (Array.isArray(inner.type)) {
+					return (inner.type as string[]).includes("null")
+						? inner
+						: { ...inner, type: [...(inner.type as string[]), "null"] };
+				}
+				// anyOf / allOf / $ref shapes — no scalar `type` field
+				return { anyOf: [inner, { type: "null" }] };
+			}
+			return inner;
+		}
+
+		default: {
+			// Best-effort: drop the noise, map the kind to a JSON Schema type if
+			// we know one, otherwise drop `type` so the node validates as
+			// permissive.
+			const cleaned = copyWithoutNoise(node);
+			const mapped = ZOD_SCALAR_TO_JSON_TYPE[kind];
+			if (mapped) {
+				cleaned.type = mapped;
+			} else if (typeof cleaned.type === "string" && !VALID_JSON_SCHEMA_TYPES[cleaned.type]) {
+				delete cleaned.type;
+			}
+			// Object-shaped `enum` survives as a noise field — remove if present.
+			if (cleaned.enum !== undefined && !Array.isArray(cleaned.enum)) {
+				delete cleaned.enum;
+			}
+			return cleaned;
+		}
+	}
+}
+
+function isOptionalEntry(value: unknown): boolean {
+	if (!isJsonObject(value)) return false;
+	if (!isZodLeak(value)) return false;
+	const kind = (value.def as JsonObject).type;
+	return kind === "optional" || kind === "default" || kind === "prefault";
+}
+
+/**
+ * Walks a JSON value and rewrites every Zod-instance-shaped node into clean
+ * JSON Schema 2020-12. Identity-preserving when no rewrite fires. Tolerates
+ * self-referential graphs — a revisited node returns as-is.
+ */
+export function decontaminateZodInstance(value: unknown): unknown {
+	return walk(value, new WeakSet());
+}
+
+function walk(value: unknown, seen: WeakSet<object>): unknown {
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return value;
+		seen.add(value);
+		let changed = false;
+		const out = value.map(entry => {
+			const rewritten = walk(entry, seen);
+			if (rewritten !== entry) changed = true;
+			return rewritten;
+		});
+		return changed ? out : value;
+	}
+	if (!isJsonObject(value)) return value;
+	if (seen.has(value)) return value;
+	seen.add(value);
+
+	if (isZodLeak(value)) {
+		// Rewrite the node itself, then recurse into the rewrite so any nested
+		// Zod-instance children get cleaned in the same pass.
+		const rewritten = rewriteZodNode(value, seen);
+		return rewritten === value ? value : walk(rewritten, seen);
+	}
+
+	// Plain JSON Schema node: recurse into children, preserving identity when
+	// nothing under us changed.
+	let changed = false;
+	const out: JsonObject = {};
+	for (const key in value) {
+		const child = value[key];
+		const rewritten = walk(child, seen);
+		if (rewritten !== child) changed = true;
+		out[key] = rewritten;
+	}
+	return changed ? out : value;
+}

package/src/utils/sdk-stream-timeout.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared helpers for mapping `StreamOptions.streamFirstEventTimeoutMs` onto
+ * underlying SDK request-timeout options.
+ *
+ * The hint is intentionally not a watchdog — it just narrows the SDK's
+ * "transport timeout" window so a stuck pre-stream request fails fast
+ * instead of hanging on the default (often multi-minute) SDK timeout. Once
+ * the stream actually starts, silence is not failure; callers must abort
+ * to interrupt a quiet stream.
+ */
+
+/**
+ * Coerce a caller-supplied `streamFirstEventTimeoutMs` into a positive integer suitable
+ * for the SDK's `timeout` option. Returns `undefined` when the caller passed nothing,
+ * a non-finite value, or a non-positive value (preserving the SDK's default).
+ */
+export function resolveSdkTimeoutMs(streamFirstEventTimeoutMs: number | undefined): number | undefined {
+	if (streamFirstEventTimeoutMs === undefined) return undefined;
+	if (!Number.isFinite(streamFirstEventTimeoutMs)) return undefined;
+	if (streamFirstEventTimeoutMs <= 0) return undefined;
+	return Math.trunc(streamFirstEventTimeoutMs);
+}
+
+/**
+ * Build per-request SDK options that combine an abort signal with the optional
+ * `streamFirstEventTimeoutMs` request-timeout hint.
+ *
+ * The returned `{ signal, timeout?, maxRetries? }` shape is compatible with both
+ * OpenAI's and Anthropic's `RequestOptions` (and any other SDK that follows the
+ * Stainless conventions), so callers from any of those providers can spread the
+ * result directly into `client.X.create(params, requestOptions)`.
+ *
+ * When the hint is set, retries are forced to zero so the SDK does not silently
+ * extend the caller's explicit deadline by re-attempting after a timeout.
+ */
+export function createSdkStreamRequestOptions(
+	signal: AbortSignal,
+	streamFirstEventTimeoutMs: number | undefined,
+): { signal: AbortSignal; timeout?: number; maxRetries?: number } {
+	const timeout = resolveSdkTimeoutMs(streamFirstEventTimeoutMs);
+	if (timeout === undefined) return { signal };
+	return { signal, timeout, maxRetries: 0 };
+}

package/src/utils/sse-debug.ts

@@ -0,0 +1,18 @@
+import type { ServerSentEvent } from "jeopi-utils";
+import type { RawSseEvent } from "../types";
+
+type RawSseObserver = (event: RawSseEvent) => void;
+
+export function notifyRawSseEvent(observer: RawSseObserver | undefined, event: ServerSentEvent | RawSseEvent): void {
+	if (!observer) return;
+	try {
+		// Pass the event through without cloning `raw`. The only wired observer
+		// (`RawSseDebugBuffer.recordEvent`) treats `raw` as owned and never
+		// mutates it; new observers must adhere to the same contract.
+		// `ServerSentEvent` and `RawSseEvent` are structurally identical
+		// (`event: string | null`, `data: string`, `raw: string[]`).
+		observer(event as RawSseEvent);
+	} catch {
+		// Raw stream observers are diagnostic only and must not affect generation.
+	}
+}

package/src/utils/stream-markup-healing.ts

@@ -0,0 +1,247 @@
+/**
+ * Streaming-safe filters for leaked chat-template tool-call and thinking markup.
+ *
+ * Hosted models sometimes leak raw template markup into visible `content` instead
+ * of returning structured events. Tool-call healing delegates to the same
+ * dialect scanners used by owned in-band tool calling; this file keeps the
+ * provider-facing compatibility wrapper and model/provider gating.
+ */
+
+import { isDeepseekModelIdOrName } from "jeopi-catalog/identity";
+
+import { createInbandScanner } from "../dialect/factory";
+import { ThinkingInbandScanner } from "../dialect/thinking";
+import type { InbandScanEvent, InbandScanner } from "../dialect/types";
+
+const KIMI_SECTION_END = "<|tool_calls_section_end|>";
+const DSML_TOOL_CALLS_CLOSE_FULLWIDTH = "</｜DSML｜tool_calls>";
+const DSML_TOOL_CALLS_CLOSE_ASCII = "</|DSML|tool_calls>";
+
+export interface HealedToolCall {
+	readonly id: string;
+	readonly name: string;
+	readonly arguments: string;
+}
+
+export type StreamMarkupHealingPattern = "kimi" | "dsml" | "thinking";
+
+export interface StreamMarkupHealingOptions {
+	readonly pattern: StreamMarkupHealingPattern;
+}
+
+export type StreamMarkupHealingEvent =
+	| { readonly type: "text"; readonly text: string }
+	| { readonly type: "thinking"; readonly thinking: string }
+	| { readonly type: "toolCall"; readonly call: HealedToolCall };
+
+/**
+ * State machine that consumes streamed visible text and emits cleaned text,
+ * thinking deltas, and reconstructed tool calls.
+ *
+ * A {@link ThinkingInbandScanner} always heals leaked reasoning idioms
+ * (`<think>`, `<thinking>`, ` ```thinking `, Gemma/Harmony channels, …) out of
+ * the visible channel. For Kimi / DeepSeek-DSML the provider tool-call grammar
+ * runs first and its cleaned text is piped through that thinking healer, so a
+ * model can leak tool-call markup and reasoning in the same stream.
+ *
+ * Feed only one stream channel (usually `delta.content` / `message.content`).
+ * Mixing reasoning and visible text into the same instance can corrupt held-back
+ * partial tag buffers.
+ */
+export class StreamMarkupHealing {
+	readonly #pattern: StreamMarkupHealingPattern;
+	/** Provider tool-call grammar (Kimi tokens / DSML envelope); absent for plain text streams. */
+	readonly #toolScanner: InbandScanner | undefined;
+	/** Always-on healer for leaked reasoning idioms in the visible text channel. */
+	readonly #thinkingScanner = new ThinkingInbandScanner();
+	#sectionTerminated = false;
+	readonly #completed: HealedToolCall[] = [];
+
+	constructor(options: StreamMarkupHealingOptions) {
+		this.#pattern = options.pattern;
+		this.#toolScanner =
+			options.pattern === "kimi"
+				? createInbandScanner("kimi")
+				: options.pattern === "dsml"
+					? createInbandScanner("xml", { xmlTagset: "dsml" })
+					: undefined;
+	}
+
+	get pattern(): StreamMarkupHealingPattern {
+		return this.#pattern;
+	}
+
+	/**
+	 * Feed a chunk and return visible text only. Reconstructed tool calls are
+	 * stored for {@link drainCompleted}; thinking blocks are intentionally not
+	 * returned by this compatibility helper. Use {@link feedEvents} when the caller
+	 * needs ordered text/thinking/tool-call events.
+	 */
+	feed(text: string): string {
+		let clean = "";
+		for (const event of this.feedEvents(text)) {
+			if (event.type === "text") {
+				clean += event.text;
+			} else if (event.type === "toolCall") {
+				this.#completed.push(event.call);
+			}
+		}
+		return clean;
+	}
+
+	/** Feed a chunk and return cleaned text/thinking/tool-call events in stream order. */
+	feedEvents(text: string): StreamMarkupHealingEvent[] {
+		if (text.length === 0) return [];
+		this.#markSectionClosed(text);
+		if (!this.#toolScanner) return this.#convertScannerEvents(this.#thinkingScanner.feed(text));
+		return this.#convertScannerEvents(this.#healThinking(this.#toolScanner.feed(text)));
+	}
+
+	/**
+	 * Feed a chunk and return cleaned events, excluding synthesized tool calls.
+	 * Used when the upstream chunk also carries structured `tool_calls`, keeping
+	 * that structured payload as the single source of truth while preserving
+	 * adjacent text and thinking events.
+	 */
+	feedEventsWithoutCalls(text: string): StreamMarkupHealingEvent[] {
+		const events = this.feedEvents(text);
+		let out: StreamMarkupHealingEvent[] | undefined;
+		for (let i = 0; i < events.length; i++) {
+			const event = events[i]!;
+			if (event.type === "toolCall") {
+				out ??= events.slice(0, i);
+			} else if (out) {
+				out.push(event);
+			}
+		}
+		return out ?? events;
+	}
+
+	/** Drain accumulated tool calls from calls to {@link feed}. */
+	drainCompleted(): HealedToolCall[] {
+		if (this.#completed.length === 0) return [];
+		return this.#completed.splice(0, this.#completed.length);
+	}
+
+	/**
+	 * Flush held-back stream-end fragments as ordered events. Partial tool-call
+	 * sections/envelopes are dropped by the delegated scanners; unterminated
+	 * thinking blocks are emitted as thinking, matching the previous MiniMax parser
+	 * behavior.
+	 */
+	flushEvents(): StreamMarkupHealingEvent[] {
+		const tail = this.#toolScanner ? this.#healThinking(this.#toolScanner.flush()) : [];
+		tail.push(...this.#thinkingScanner.flush());
+		return this.#convertScannerEvents(tail);
+	}
+
+	/** Flush held-back text only. Reconstructed calls are retained for {@link drainCompleted}. */
+	flushPending(): string {
+		let clean = "";
+		for (const event of this.flushEvents()) {
+			if (event.type === "text") {
+				clean += event.text;
+			} else if (event.type === "toolCall") {
+				this.#completed.push(event.call);
+			}
+		}
+		return clean;
+	}
+
+	/** True once any configured tool-call section/envelope has fully closed. */
+	get sectionClosed(): boolean {
+		return this.#sectionTerminated;
+	}
+
+	#markSectionClosed(text: string): void {
+		if (this.#sectionTerminated || !this.#toolScanner) return;
+		if (this.#pattern === "kimi") {
+			this.#sectionTerminated = text.includes(KIMI_SECTION_END);
+			return;
+		}
+		this.#sectionTerminated =
+			text.includes(DSML_TOOL_CALLS_CLOSE_FULLWIDTH) || text.includes(DSML_TOOL_CALLS_CLOSE_ASCII);
+	}
+
+	/**
+	 * Re-scan the tool scanner's visible text through the always-on thinking
+	 * healer: `text` events are healed for leaked reasoning idioms, while the tool
+	 * scanner's own thinking / tool-call events pass through in stream order.
+	 */
+	#healThinking(toolEvents: readonly InbandScanEvent[]): InbandScanEvent[] {
+		const out: InbandScanEvent[] = [];
+		for (const event of toolEvents) {
+			if (event.type === "text") out.push(...this.#thinkingScanner.feed(event.text));
+			else out.push(event);
+		}
+		return out;
+	}
+
+	#convertScannerEvents(events: readonly InbandScanEvent[]): StreamMarkupHealingEvent[] {
+		const out: StreamMarkupHealingEvent[] = [];
+		for (const event of events) {
+			switch (event.type) {
+				case "text":
+					out.push({ type: "text", text: event.text });
+					break;
+				case "thinkingDelta":
+					if (event.delta.length > 0) out.push({ type: "thinking", thinking: event.delta });
+					break;
+				case "toolEnd":
+					out.push({
+						type: "toolCall",
+						call: {
+							id: generateHealedToolCallId(),
+							name: event.name,
+							arguments: JSON.stringify(event.arguments),
+						},
+					});
+					break;
+				case "thinkingStart":
+				case "thinkingEnd":
+				case "toolStart":
+				case "toolArgDelta":
+					break;
+			}
+		}
+		return out;
+	}
+}
+
+function generateHealedToolCallId(): string {
+	return `call_${crypto.randomUUID().replace(/-/g, "").slice(0, 24)}`;
+}
+
+/** Cheap model/provider gate for Kimi-K2 chat-template token leaks. */
+export function modelMayLeakKimiToolCalls(provider: string, modelId: string): boolean {
+	if (provider === "kimi-code" || provider === "moonshot") return true;
+	return /kimi[-/_.]?k2/i.test(modelId);
+}
+
+/** Cheap model/provider gate for DeepSeek DSML envelope leaks. */
+export function modelMayLeakDsmlToolCalls(provider: string, modelId: string): boolean {
+	if (!isDeepseekModelIdOrName(modelId)) return false;
+	return (
+		provider === "ollama" ||
+		provider === "ollama-cloud" ||
+		provider === "nvidia" ||
+		provider === "deepseek" ||
+		provider === "fireworks" ||
+		provider === "nanogpt" ||
+		provider === "opencode-go" ||
+		provider === "openrouter"
+	);
+}
+
+/**
+ * Pick the leaked-markup healer for an OpenAI-compatible / Ollama visible-text
+ * stream. Kimi chat-template tokens and DeepSeek DSML envelopes need their
+ * dedicated tool-call grammars; every other model uses `"thinking"`. All three
+ * patterns run the generic {@link ThinkingInbandScanner}, so leaked reasoning
+ * idioms (e.g. a Gemini ` ```thinking ` fence on OpenRouter) are always healed.
+ */
+export function getStreamMarkupHealingPattern(provider: string, modelId: string): StreamMarkupHealingPattern {
+	if (modelMayLeakKimiToolCalls(provider, modelId)) return "kimi";
+	if (modelMayLeakDsmlToolCalls(provider, modelId)) return "dsml";
+	return "thinking";
+}