@namzu/deepseek 0.1.0 → 1.1.0

package/src/client.ts

@@ -1,14 +1,19 @@
 import type {
 	ChatCompletionParams,
 	ChatCompletionResponse,
+	ImageAttachment,
 	LLMProvider,
 	ModelInfo,
+	ModelInputModality,
 	ProviderCapabilities,
+	ProviderRoute,
 	ReasoningBlock,
+	ReasoningEffort,
 	StreamChunk,
 	ThinkingConfig,
 	TokenUsage,
 	ToolChoice,
+	ToolResultContent,
 } from '@namzu/sdk'
 import {
 	ProviderRequestError,
@@ -16,7 +21,7 @@ import {
 	isCallerAbortError,
 	isProviderRequestError,
 	providerVendorError,
-	toolResultToText,
+	toToolResultBlocks,
 } from '@namzu/sdk'
 import OpenAI from 'openai'
 import type {
@@ -26,24 +31,29 @@ import type {
 } from 'openai/resources/chat/completions'
 import type { DeepSeekConfig } from './types.js'
 
-/**
- * No vision, no documents.
- *
- * The wire is OpenAI's Chat Completions, which has `image_url` content parts —
- * but the models behind this endpoint are text-only, and a capability set is a
- * claim about what a call will actually do, not about what the request format
- * can express. Claiming vision here would route an image-bearing run to a
- * driver that sends the image and gets prose about nothing.
- */
+/** Driver-level mapping capabilities; model input support is listed separately. */
 export const DEEPSEEK_CAPABILITIES: ProviderCapabilities = {
 	supportsTools: true,
 	supportsStreaming: true,
 	supportsFunctionCalling: true,
-	supportsVision: false,
+	supportsVision: true,
 	supportsDocuments: false,
 }
 
 const DEFAULT_BASE_URL = 'https://api.deepseek.com'
+const VISION_MODEL = 'deepseek-v4-flash-vision-exp'
+const TEXT_MODALITIES = Object.freeze(['text'] as const)
+const VISION_MODALITIES = Object.freeze(['text', 'image'] as const)
+const IMAGE_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
+const KNOWN_MODELS = Object.freeze([
+	{ id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', inputModalities: TEXT_MODALITIES },
+	{ id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro', inputModalities: TEXT_MODALITIES },
+	{
+		id: VISION_MODEL,
+		name: 'DeepSeek-V4-Flash-Vision-Exp',
+		inputModalities: VISION_MODALITIES,
+	},
+] as const)
 
 type DeepSeekFinishReason =
 	| 'stop'
@@ -188,13 +198,87 @@ export function assertEffortUnsupported(params: ChatCompletionParams): void {
 }
 
 /**
- * The reasoning blocks an assistant message carries, in wire form.
+ * Adapter-private state for one completed reasoning response.
+ *
+ * The route is repeated inside the opaque envelope rather than trusted from
+ * `AssistantMessage.source`: durable content is authoritative, and native
+ * metadata is used only after the two independent records agree.
+ */
+interface DeepSeekReplayState {
+	readonly kind: 'namzu-deepseek-reasoning'
+	readonly version: 1
+	readonly route: ProviderRoute
+	readonly reasoningContent: string
+}
+
+function sameRoute(left: ProviderRoute, right: ProviderRoute): boolean {
+	return (
+		left.providerId === right.providerId &&
+		left.model === right.model &&
+		left.chainIndex === right.chainIndex
+	)
+}
+
+function resolveDeepSeekRoute(model: string, candidate: ProviderRoute | undefined): ProviderRoute {
+	if (candidate === undefined) return { providerId: 'deepseek', model, chainIndex: 0 }
+	if (
+		candidate.providerId !== 'deepseek' ||
+		candidate.model !== model ||
+		!Number.isSafeInteger(candidate.chainIndex) ||
+		candidate.chainIndex < 0
+	) {
+		throw new Error(
+			'DeepSeekProvider: providerRoute must name this provider, the requested model, and a non-negative integer chainIndex.',
+		)
+	}
+	return candidate
+}
+
+function isDeepSeekReplayState(value: unknown): value is DeepSeekReplayState {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+	const state = value as Record<string, unknown>
+	const route = state.route
+	return (
+		state.kind === 'namzu-deepseek-reasoning' &&
+		state.version === 1 &&
+		typeof state.reasoningContent === 'string' &&
+		state.reasoningContent.length > 0 &&
+		typeof route === 'object' &&
+		route !== null &&
+		!Array.isArray(route) &&
+		typeof (route as Record<string, unknown>).providerId === 'string' &&
+		typeof (route as Record<string, unknown>).model === 'string' &&
+		Number.isSafeInteger((route as Record<string, unknown>).chainIndex) &&
+		((route as Record<string, unknown>).chainIndex as number) >= 0
+	)
+}
+
+function durableDeepSeekReasoning(
+	reasoning: readonly ReasoningBlock[] | undefined,
+): string | undefined {
+	if (!reasoning || reasoning.length === 0) return undefined
+	if (
+		reasoning.some(
+			(block) =>
+				block.type !== 'thinking' ||
+				typeof block.text !== 'string' ||
+				block.signature !== undefined ||
+				block.encrypted !== undefined,
+		)
+	) {
+		return undefined
+	}
+	const text = reasoning.map((block) => block.text as string).join('')
+	return text.length > 0 ? text : undefined
+}
+
+/**
+ * Restore `reasoning_content` only from a validated same-route envelope.
  *
- * The vendor's rule: with tool calls in play, an assistant turn's
- * `reasoning_content` **must** be replayed in every later turn of the same
- * flow; without tool calls it is ignored if sent. Replayed unconditionally
- * here, which satisfies both halves and matches what `AssistantMessage.reasoning`
- * already promises — "replayed verbatim and ahead of the text/tool blocks".
+ * The vendor's rule: with tool calls in play, an assistant turn's native
+ * reasoning must be echoed on later turns. Matching provider/model names are
+ * not enough: state can come from another chain member or another adapter
+ * format, and legacy messages carry no proof at all.
  *
  * Measured note, because it matters to anyone debugging this: as of
  * 2026-08-17 omitting the replay does NOT produce the documented 400 on either
@@ -202,53 +286,170 @@ export function assertEffortUnsupported(params: ChatCompletionParams): void {
  * a contract the vendor states and does not currently enforce is a contract
  * that can start being enforced in any release.
  */
-function replayReasoning(reasoning: readonly ReasoningBlock[] | undefined): string | undefined {
-	if (!reasoning || reasoning.length === 0) return undefined
-	const text = reasoning
-		.filter((b) => b.type === 'thinking' && typeof b.text === 'string')
-		.map((b) => b.text as string)
-		.join('')
-	return text.length > 0 ? text : undefined
+function replayReasoning(
+	message: Extract<ChatCompletionParams['messages'][number], { role: 'assistant' }>,
+	targetRoute: ProviderRoute,
+): string | undefined {
+	const source = message.source
+	if (!source || source.type !== 'model' || !sameRoute(source, targetRoute)) return undefined
+	const state = source.replayState
+	if (!isDeepSeekReplayState(state) || !sameRoute(state.route, source)) return undefined
+	const durable = durableDeepSeekReasoning(message.reasoning)
+	return durable !== undefined && durable === state.reasoningContent ? durable : undefined
 }
 
 export function toDeepSeekMessages(
 	messages: ChatCompletionParams['messages'],
+	targetRoute: ProviderRoute,
 ): ChatCompletionMessageParam[] {
-	return messages.map((msg): ChatCompletionMessageParam => {
-		if (msg.role === 'system') return { role: 'system', content: msg.content }
+	assertDeepSeekRichContent(messages, targetRoute.model)
+
+	type ImagePart = { type: 'image_url'; image_url: { url: string } }
+	type UserPart = { type: 'text'; text: string } | ImagePart
+	const imagePart = (image: ImageAttachment): ImagePart => ({
+		type: 'image_url',
+		image_url: { url: `data:${image.mediaType};base64,${image.data}` },
+	})
+	const wire: ChatCompletionMessageParam[] = []
+	let pendingToolImages: ImagePart[] = []
+	const flushToolImages = (): void => {
+		if (pendingToolImages.length === 0) return
+		wire.push({
+			role: 'user',
+			content: [
+				{ type: 'text', text: 'Attached image(s) from tool result:' },
+				...pendingToolImages,
+			],
+		})
+		pendingToolImages = []
+	}
+
+	for (const msg of messages) {
+		if (msg.role !== 'tool') flushToolImages()
+		if (msg.role === 'system') {
+			wire.push({ role: 'system', content: msg.content })
+			continue
+		}
 		if (msg.role === 'user') {
-			// No attachment branch, deliberately. `DEEPSEEK_CAPABILITIES` says
-			// this driver has neither vision nor documents, and a driver that
-			// quietly encoded an image the model cannot read would answer about
-			// a picture it never saw.
-			if (msg.attachments && msg.attachments.length > 0) {
-				throw new Error(
-					'DeepSeekProvider: this driver has no vision or document support, and a message carried attachments. Route multimodal turns to a provider whose capabilities include them.',
-				)
+			if (!msg.attachments || msg.attachments.length === 0) {
+				wire.push({ role: 'user', content: msg.content })
+				continue
+			}
+			const content: UserPart[] = []
+			if (msg.content.length > 0) content.push({ type: 'text', text: msg.content })
+			for (const attachment of msg.attachments) {
+				// The preflight above proves these are inline images. This local check
+				// keeps the narrowing explicit instead of casting a public union.
+				if (attachment.type === 'stored' || attachment.type === 'document') continue
+				content.push(imagePart(attachment))
 			}
-			return { role: 'user', content: msg.content }
+			wire.push({ role: 'user', content })
+			continue
 		}
 		if (msg.role === 'tool') {
-			return {
+			const { text, images } = splitToolResult(msg.content)
+			wire.push({
 				role: 'tool',
-				content: toolResultToText(msg.content),
+				content: text || '(no output)',
 				tool_call_id: msg.toolCallId,
-			}
+			})
+			pendingToolImages.push(...images.map(imagePart))
+			continue
+		}
+		const assistant: ChatCompletionMessageParam = {
+			role: 'assistant',
+			content: msg.content,
 		}
-		const assistant: ChatCompletionMessageParam = { role: 'assistant', content: msg.content }
 		if ('toolCalls' in msg && msg.toolCalls && msg.toolCalls.length > 0) {
 			;(assistant as { tool_calls?: unknown }).tool_calls = msg.toolCalls.map((tc) => ({
 				id: tc.id,
 				type: 'function' as const,
-				function: { name: tc.function.name, arguments: tc.function.arguments },
+				function: {
+					name: tc.function.name,
+					arguments: tc.function.arguments,
+				},
 			}))
 		}
-		const replayed = replayReasoning((msg as { reasoning?: readonly ReasoningBlock[] }).reasoning)
+		const replayed = replayReasoning(msg, targetRoute)
 		if (replayed !== undefined) {
 			;(assistant as { reasoning_content?: string }).reasoning_content = replayed
 		}
-		return assistant
-	})
+		wire.push(assistant)
+	}
+	flushToolImages()
+	return wire
+}
+
+function splitToolResult(content: ToolResultContent): {
+	readonly text: string
+	readonly images: readonly ImageAttachment[]
+} {
+	const text: string[] = []
+	const images: ImageAttachment[] = []
+	for (const block of toToolResultBlocks(content)) {
+		if (block.type === 'text') text.push(block.text)
+		else if (block.type === 'image') images.push(block)
+	}
+	return { text: text.join('\n'), images }
+}
+
+/**
+ * Refuse every rich-content shape this exact model/wire cannot represent.
+ *
+ * This runs before the request object is built, so a text model never sees an
+ * image data URL and a document never reaches a wire that would silently drop
+ * it. Stored user refs should have been resolved by the SDK attachment store;
+ * accepting one here would serialize a reference rather than its bytes.
+ */
+function assertDeepSeekRichContent(
+	messages: ChatCompletionParams['messages'],
+	model: string,
+): void {
+	let hasImage = false
+	const acceptImage = (mediaType: string): void => {
+		if (!IMAGE_MEDIA_TYPES.has(mediaType)) {
+			throw new Error(
+				`DeepSeekProvider: image type '${mediaType}' is not supported. Use image/png, image/jpeg, image/webp, or image/gif.`,
+			)
+		}
+		hasImage = true
+	}
+	for (const message of messages) {
+		if (message.role === 'user') {
+			for (const attachment of message.attachments ?? []) {
+				if (attachment.type === 'stored') {
+					throw new Error(
+						'DeepSeekProvider: an unresolved stored attachment reached the driver. Configure an AttachmentStore so Namzu can resolve its bytes before the model request.',
+					)
+				}
+				if (attachment.type === 'document') {
+					throw new Error(
+						'DeepSeekProvider: this Chat Completions driver does not support document input. Route the turn to a document-capable provider.',
+					)
+				}
+				acceptImage(attachment.mediaType)
+			}
+			continue
+		}
+		if (message.role !== 'tool') continue
+		for (const block of toToolResultBlocks(message.content)) {
+			if (block.type === 'document') {
+				throw new Error(
+					'DeepSeekProvider: this Chat Completions driver does not support document tool results. Route the turn to a document-capable provider.',
+				)
+			}
+			if (block.type === 'image') acceptImage(block.mediaType)
+		}
+	}
+	if (hasImage && model !== VISION_MODEL) {
+		throw new Error(
+			`DeepSeekProvider: model '${model}' does not accept image input. Select '${VISION_MODEL}' or remove the images.`,
+		)
+	}
+}
+
+function inputModalitiesFor(model: string): readonly ModelInputModality[] | undefined {
+	return KNOWN_MODELS.find((candidate) => candidate.id === model)?.inputModalities
 }
 
 export function toDeepSeekTools(params: ChatCompletionParams): ChatCompletionTool[] | undefined {
@@ -286,7 +487,10 @@ export class DeepSeekProvider implements LLMProvider {
 			baseURL: config.baseURL ?? DEFAULT_BASE_URL,
 		}
 		if (config.timeout !== undefined) clientOptions.timeout = config.timeout
-		clientOptions.defaultHeaders = { ...attributionHeaders(), ...(config.defaultHeaders ?? {}) }
+		clientOptions.defaultHeaders = {
+			...attributionHeaders(),
+			...(config.defaultHeaders ?? {}),
+		}
 
 		this.client = new OpenAI(clientOptions)
 		this.defaultModel = config.model
@@ -303,8 +507,14 @@ export class DeepSeekProvider implements LLMProvider {
 		return model
 	}
 
+	/** This Chat Completions endpoint explicitly carries no effort control. */
+	reasoningEffortLevelsFor(_model: string): readonly ReasoningEffort[] {
+		return []
+	}
+
 	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
 		const model = this.resolveModel(params)
+		const providerRoute = resolveDeepSeekRoute(model, params.providerRoute)
 		assertEffortUnsupported(params)
 		assertSamplingUsable(params, this.samplingMode)
 
@@ -324,7 +534,7 @@ export class DeepSeekProvider implements LLMProvider {
 		// to the non-streaming overload, whose result has no async iterator.
 		const body = {
 			model,
-			messages: toDeepSeekMessages(params.messages),
+			messages: toDeepSeekMessages(params.messages, providerRoute),
 			stream: true as const,
 			stream_options: { include_usage: true },
 			tools: toDeepSeekTools(params),
@@ -362,6 +572,8 @@ export class DeepSeekProvider implements LLMProvider {
 		// `reasoning_content` as a flat run of deltas with no index and no
 		// block boundaries, so index 0 is the whole of it rather than a guess.
 		let reasoningOpen = false
+		let reasoningContent = ''
+		let replayStateEmitted = false
 
 		try {
 			for await (const chunk of stream) {
@@ -369,7 +581,11 @@ export class DeepSeekProvider implements LLMProvider {
 				try {
 					const choice = chunk.choices[0]
 					const delta = choice?.delta as
-						| { content?: string | null; reasoning_content?: string | null; tool_calls?: unknown[] }
+						| {
+								content?: string | null
+								reasoning_content?: string | null
+								tool_calls?: unknown[]
+						  }
 						| undefined
 
 					const toolCalls = (
@@ -398,9 +614,12 @@ export class DeepSeekProvider implements LLMProvider {
 
 					if (reasoningText) {
 						reasoningOpen = true
+						reasoningContent += reasoningText
 						yield {
 							id: chunk.id,
-							delta: { reasoning: { index: 0, type: 'thinking', text: reasoningText } },
+							delta: {
+								reasoning: { index: 0, type: 'thinking', text: reasoningText },
+							},
 						}
 					}
 
@@ -413,7 +632,10 @@ export class DeepSeekProvider implements LLMProvider {
 						(toolCalls !== undefined && toolCalls.length > 0)
 					if (reasoningOpen && contentStarting) {
 						reasoningOpen = false
-						yield { id: chunk.id, delta: { reasoning: { index: 0, done: true } } }
+						yield {
+							id: chunk.id,
+							delta: { reasoning: { index: 0, done: true } },
+						}
 					}
 
 					const hasDelta =
@@ -421,8 +643,20 @@ export class DeepSeekProvider implements LLMProvider {
 						(toolCalls !== undefined && toolCalls.length > 0)
 					if (!hasDelta && !finishReason && !usage) continue
 
+					const replayState =
+						!replayStateEmitted && finishReason && reasoningContent.length > 0
+							? ({
+									kind: 'namzu-deepseek-reasoning',
+									version: 1,
+									route: providerRoute,
+									reasoningContent,
+								} satisfies DeepSeekReplayState)
+							: undefined
+					if (replayState !== undefined) replayStateEmitted = true
+
 					yield {
 						id: chunk.id,
+						...(replayState !== undefined ? { replayState } : {}),
 						delta: { content: delta?.content ?? undefined, toolCalls },
 						finishReason,
 						usage,
@@ -439,7 +673,10 @@ export class DeepSeekProvider implements LLMProvider {
 			// A turn that was all reasoning and no content — the model thought
 			// and then stopped — still has to close its block.
 			if (reasoningOpen) {
-				yield { id: 'deepseek-reasoning-close', delta: { reasoning: { index: 0, done: true } } }
+				yield {
+					id: 'deepseek-reasoning-close',
+					delta: { reasoning: { index: 0, done: true } },
+				}
 			}
 		} catch (err) {
 			if (isCallerAbortError(err, params.signal)) throw params.signal?.reason ?? err
@@ -448,20 +685,35 @@ export class DeepSeekProvider implements LLMProvider {
 		}
 	}
 
-	async probeCredential(): Promise<void> {
-		await this.client.models.list()
+	async probeCredential(signal?: AbortSignal): Promise<void> {
+		signal?.throwIfAborted()
+		await this.client.models.list(signal ? { signal } : undefined)
+		signal?.throwIfAborted()
 	}
 
-	async listModels(): Promise<ModelInfo[]> {
-		const page = await this.client.models.list()
-		return page.data.map((m) => ({
-			id: m.id,
-			name: m.id,
-			inputPrice: 0,
-			outputPrice: 0,
-			supportsToolUse: true,
-			supportsStreaming: true,
-		}))
+	async listModels(signal?: AbortSignal): Promise<ModelInfo[]> {
+		signal?.throwIfAborted()
+		const page = await this.client.models.list(signal ? { signal } : undefined)
+		signal?.throwIfAborted()
+		const models = new Map<string, { id: string; name: string }>()
+		for (const model of page.data) models.set(model.id, { id: model.id, name: model.id })
+		// The preview model is part of the source adapter's verified default
+		// catalogue but may lag the account listing endpoint. A successful list
+		// therefore augments rather than erases the known selectable catalogue.
+		for (const model of KNOWN_MODELS) {
+			models.set(model.id, { id: model.id, name: model.name })
+		}
+		return [...models.values()].map((model) => {
+			const inputModalities = inputModalitiesFor(model.id)
+			return {
+				...model,
+				...(inputModalities !== undefined ? { inputModalities } : {}),
+				inputPrice: 0,
+				outputPrice: 0,
+				supportsToolUse: true,
+				supportsStreaming: true,
+			}
+		})
 	}
 
 	async healthCheck(): Promise<boolean> {