Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(host): document z.ai glm-5.3-flash image input

Alfredo Lopez722b15b78c31
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 57e1f20e3..9f9d220a9 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.341",
+ "version": "0.1.342",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.341",
+ "version": "0.1.342",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index cbe5371b8..74be27fa3 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.341",
+ "version": "0.1.342",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/llm/__tests__/zai.test.ts b/mcp-host/src/llm/__tests__/zai.test.ts
index cf2f9c71f..3798898de 100644
--- a/mcp-host/src/llm/__tests__/zai.test.ts
+++ b/mcp-host/src/llm/__tests__/zai.test.ts
@@ -26,4 +26,20 @@ describe('ZaiProvider (OpenAICompatibleProvider)', () => {
it("getProviderType returns 'zai'", () => {
expect(makeZai().getProviderType()).toBe('zai')
})
+
+ it('reports documented image input for glm-5.3-flash on the Coding Plan endpoint', async () => {
+ await expect(makeZai('glm-5.3-flash').getImageInputCapability()).resolves.toEqual({
+ status: 'supported',
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ evidence: 'zai-documented-model-contract',
+ })
+ })
+
+ it('keeps unlisted z.ai models unknown rather than inferring vision', async () => {
+ await expect(makeZai('glm-4.7').getImageInputCapability()).resolves.toEqual({
+ status: 'unknown',
+ })
+ await expect(makeZai().getImageInputCapability()).resolves.toEqual({ status: 'unknown' })
+ })
})
diff --git a/mcp-host/src/llm/openaiCompatible.ts b/mcp-host/src/llm/openaiCompatible.ts
index 53e570315..92c575623 100644
--- a/mcp-host/src/llm/openaiCompatible.ts
+++ b/mcp-host/src/llm/openaiCompatible.ts
@@ -39,7 +39,8 @@ import type {
ToolDefinition,
} from '../core/types'
import { createOpenRouterImageCapabilityResolver } from '../visualInput/capabilities'
-import type { ImageInputCapability } from '../visualInput/policy'
+import { getDocumentedZaiImageCapability } from '../visualInput/documentedZaiCapabilities'
+import { type ImageInputCapability, VisualInputError } from '../visualInput/policy'
import { OpenAIProvider } from './openai'
import type { LlmProvider } from './registryCore'
import type { ClassifiedError } from './types'
@@ -82,6 +83,7 @@ const BILLING_CODES = new Set(['1113', 'Arrearage'])
export class OpenAICompatibleProvider extends OpenAIProvider {
private readonly imageCapabilityResolver?: (signal?: AbortSignal) => Promise<ImageInputCapability>
+ private readonly selectedModel: string
/** Provider temperature upper bound — 1 for Moonshot, else the [0,2] default. */
private readonly temperatureCeiling: number
/**
@@ -104,6 +106,7 @@ export class OpenAICompatibleProvider extends OpenAIProvider {
// fall through to OpenAIProvider's own default ('gpt-5.4-mini'), and this
// provider would request a non-existent model against its baseURL.
super(new OpenAI({ apiKey, baseURL: cfg.baseURL }), model ?? cfg.defaultModel)
+ this.selectedModel = model ?? cfg.defaultModel
this.temperatureCeiling = cfg.id === 'moonshot' ? 1 : 2
this.downgradesRequiredToolChoice = cfg.id === 'moonshot'
if (cfg.id === 'openrouter') {
@@ -127,6 +130,10 @@ export class OpenAICompatibleProvider extends OpenAIProvider {
}
override getImageInputCapability(signal?: AbortSignal): Promise<ImageInputCapability> {
+ if (signal?.aborted) throw new VisualInputError('cancelled')
+ if (this.cfg.id === 'zai') {
+ return Promise.resolve(getDocumentedZaiImageCapability(this.selectedModel, this.cfg.baseURL))
+ }
return this.imageCapabilityResolver?.(signal) ?? Promise.resolve({ status: 'unknown' })
}
diff --git a/mcp-host/src/visualInput/documentedZaiCapabilities.test.ts b/mcp-host/src/visualInput/documentedZaiCapabilities.test.ts
new file mode 100644
index 000000000..1aea878bf
--- /dev/null
+++ b/mcp-host/src/visualInput/documentedZaiCapabilities.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import {
+ DOCUMENTED_ZAI_IMAGE_MODELS,
+ OFFICIAL_ZAI_CODING_BASE_URL,
+ ZAI_DOCUMENTED_EVIDENCE,
+ ZAI_PROVIDER,
+ getDocumentedZaiImageCapability,
+} from './documentedZaiCapabilities'
+
+const OFFICIAL = OFFICIAL_ZAI_CODING_BASE_URL
+const DOCUMENTED_MODEL = 'glm-5.3-flash'
+
+function expectSupported(model: string, baseURL: string | undefined): void {
+ expect(getDocumentedZaiImageCapability(model, baseURL)).toEqual({
+ status: 'supported',
+ provider: 'zai',
+ model,
+ evidence: 'zai-documented-model-contract',
+ })
+}
+
+function expectUnknown(model: string, baseURL: string | undefined = OFFICIAL): void {
+ expect(getDocumentedZaiImageCapability(model, baseURL)).toEqual({ status: 'unknown' })
+}
+
+describe('getDocumentedZaiImageCapability', () => {
+ it('reports the documented contract for every table entry', () => {
+ expect(ZAI_PROVIDER).toBe('zai')
+ expect(ZAI_DOCUMENTED_EVIDENCE).toBe('zai-documented-model-contract')
+ expect(OFFICIAL_ZAI_CODING_BASE_URL).toBe('https://api.z.ai/api/coding/paas/v4')
+ expect(DOCUMENTED_ZAI_IMAGE_MODELS.length).toBeGreaterThan(0)
+
+ for (const entry of DOCUMENTED_ZAI_IMAGE_MODELS) {
+ expectSupported(entry.id, OFFICIAL)
+ expectSupported(entry.id, `${OFFICIAL}/`)
+ expect(getDocumentedZaiImageCapability(entry.id, undefined)).toEqual({ status: 'unknown' })
+ }
+ })
+
+ it('keeps unlisted GLM ids unknown on the official endpoint', () => {
+ expectUnknown('glm-4.7')
+ expectUnknown('glm-5.1')
+ expectUnknown('glm-5.3')
+ expectUnknown(`${DOCUMENTED_MODEL}-preview`)
+ })
+
+ it('does not infer support from whitespace, case, or family prefixes', () => {
+ expectUnknown(` ${DOCUMENTED_MODEL}`)
+ expectUnknown(DOCUMENTED_MODEL.toUpperCase())
+ expectUnknown(`zai/${DOCUMENTED_MODEL}`)
+ })
+
+ it('rejects any transport that is not the official Coding Plan endpoint', () => {
+ expectUnknown(DOCUMENTED_MODEL, 'https://api.z.ai/api/paas/v4')
+ expectUnknown(DOCUMENTED_MODEL, 'https://api.openai.com/v1')
+ expectUnknown(DOCUMENTED_MODEL, 'http://api.z.ai/api/coding/paas/v4')
+ expectUnknown(DOCUMENTED_MODEL, 'https://user:[email protected]/api/coding/paas/v4')
+ expectUnknown(DOCUMENTED_MODEL, 'https://api.z.ai/api/coding/paas/v4?x=1')
+ expectUnknown(DOCUMENTED_MODEL, 'https://api.z.ai/api/coding/paas/v4#frag')
+ expectUnknown(DOCUMENTED_MODEL, 'not-a-url')
+ })
+})
diff --git a/mcp-host/src/visualInput/documentedZaiCapabilities.ts b/mcp-host/src/visualInput/documentedZaiCapabilities.ts
new file mode 100644
index 000000000..c079af0ef
--- /dev/null
+++ b/mcp-host/src/visualInput/documentedZaiCapabilities.ts
@@ -0,0 +1,107 @@
+/**
+ * Documented z.ai image-input capability, resolved offline.
+ *
+ * z.ai's OpenAI-compatible Models API does not publish a modalities flag this
+ * host can treat as authoritative, so there is nothing to read back at runtime.
+ * This module binds one factual table of published model contracts to the one
+ * endpoint those contracts were published for. A model is image-capable only
+ * when both hold:
+ *
+ * 1. the transport targets the official GLM Coding Plan endpoint, and
+ * 2. the exact requested id appears in {@link DOCUMENTED_ZAI_IMAGE_MODELS}.
+ *
+ * Everything else is `unknown`. There is no prefix, family, or size heuristic.
+ * The table is a contract with sources, not a catalog: each entry carries the
+ * official page it was verified against. This is provider-local contract data,
+ * not a replacement for discovery or the broader capability catalog in #654.
+ *
+ * This module performs no I/O, reads no key, and never infers capability from a
+ * model name. Absence of an entry means "not proven", never "not capable".
+ */
+import type { ImageInputCapability } from './policy'
+
+/** The provider identity reported for a supported model. */
+export const ZAI_PROVIDER = 'zai'
+/**
+ * Fixed, bounded provenance string. The model id is echoed back exactly as
+ * requested, so a caller can correlate the answer with its own request; the
+ * evidence never contains upstream text.
+ */
+export const ZAI_DOCUMENTED_EVIDENCE = 'zai-documented-model-contract'
+/** The only endpoint whose model contracts this table describes. */
+export const OFFICIAL_ZAI_CODING_BASE_URL = 'https://api.z.ai/api/coding/paas/v4'
+
+/**
+ * One verified model contract: the documented model id and the official page
+ * it was read from.
+ */
+export interface DocumentedZaiImageModel {
+ /** Documented model id accepted verbatim by the Chat Completions API. */
+ readonly id: string
+ /** Official page this contract was verified against. */
+ readonly source: string
+}
+
+/**
+ * Verified on 2026-09-17. GLM-5.3-Flash is the first native multimodal model
+ * in the GLM-5 series and documents image input via `image_url` content blocks
+ * on the GLM Coding Plan.
+ */
+export const DOCUMENTED_ZAI_IMAGE_MODELS: readonly DocumentedZaiImageModel[] = Object.freeze([
+ Object.freeze({
+ id: 'glm-5.3-flash',
+ source: 'https://docs.z.ai/guides/vlm/glm-5.3-flash',
+ }),
+])
+
+const UNKNOWN = Object.freeze({ status: 'unknown' as const })
+
+const DOCUMENTED_MODEL_IDS: ReadonlySet<string> = new Set(
+ DOCUMENTED_ZAI_IMAGE_MODELS.map(entry => entry.id)
+)
+
+/**
+ * Reads the documented image-input contract for one exact model id. Returns
+ * `supported` with the requested id only when the transport targets the official
+ * Coding Plan endpoint and this module has a verified contract for that id;
+ * otherwise `unknown`, so an unproven model is never handed an image.
+ */
+export function getDocumentedZaiImageCapability(
+ model: string,
+ baseURL: string | undefined
+): ImageInputCapability {
+ if (!targetsOfficialZaiCodingEndpoint(baseURL)) return UNKNOWN
+ // Exact membership only: no trimming, no case folding, no prefix family.
+ if (!DOCUMENTED_MODEL_IDS.has(model)) return UNKNOWN
+
+ return Object.freeze({
+ status: 'supported' as const,
+ provider: ZAI_PROVIDER,
+ model,
+ evidence: ZAI_DOCUMENTED_EVIDENCE,
+ })
+}
+
+/**
+ * True only for the resolved official `https://api.z.ai/api/coding/paas/v4`
+ * base. An absent endpoint is unverified. Any other origin, path, scheme, port,
+ * or a URL carrying userinfo, query, or fragment is a different deployment
+ * whose model contracts this table does not describe.
+ */
+function targetsOfficialZaiCodingEndpoint(baseURL: string | undefined): boolean {
+ if (baseURL === undefined) return false
+
+ let url: URL
+ try {
+ url = new URL(baseURL)
+ } catch {
+ return false
+ }
+ if (url.protocol !== 'https:') return false
+ if (url.username !== '' || url.password !== '') return false
+ if (url.search !== '' || url.hash !== '') return false
+ if (url.hostname !== 'api.z.ai') return false
+ if (url.port !== '' && url.port !== '443') return false
+ const path = url.pathname.endsWith('/') ? url.pathname.slice(0, -1) : url.pathname
+ return path === '/api/coding/paas/v4'
+}