Skip to content

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

TypeScript

fix(gfs): align image read admission with dispatch catalog

Alfredo Lopez41dcfbcd74bf
diff --git a/desktop-app/src/main.ts b/desktop-app/src/main.ts
index 4cccafc29..6e49c7527 100644
--- a/desktop-app/src/main.ts
+++ b/desktop-app/src/main.ts
@@ -358,10 +358,18 @@ function handleClerumUrl(rawUrl: string): void {
// An isolated run leaves the machine-wide default handler exactly as it is: the
// normal app keeps owning `evenfire:`/`clerum:` deep links.
-if (
- devIsolationPolicy.registerOsProtocols &&
- shouldRegisterOsProtocols(process.argv, app.isPackaged)
-) {
+let registerOsProtocols = false
+try {
+ registerOsProtocols =
+ devIsolationPolicy.registerOsProtocols &&
+ shouldRegisterOsProtocols(process.argv, app.isPackaged)
+} catch (error) {
+ console.error(
+ `[Desktop] ${error instanceof Error ? error.message : 'Protocol registration refused'}`
+ )
+ process.exit(1)
+}
+if (registerOsProtocols) {
registerCustomProtocols()
}
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 412f0840f..38ed97aaf 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.372",
+ "version": "0.1.373",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.372",
+ "version": "0.1.373",
"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 c6d454df5..4f4971423 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.372",
+ "version": "0.1.373",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/core/adapters/__tests__/failoverLlmPort.test.ts b/mcp-host/src/core/adapters/__tests__/failoverLlmPort.test.ts
index 865700bfb..307992ae6 100644
--- a/mcp-host/src/core/adapters/__tests__/failoverLlmPort.test.ts
+++ b/mcp-host/src/core/adapters/__tests__/failoverLlmPort.test.ts
@@ -234,7 +234,7 @@ describe('FailoverLlmPort — visual destination failover', () => {
status: 'supported' as const,
provider,
model,
- evidence: `${provider}-model-metadata`,
+ evidence: 'https://example.com/image-input',
})
function visionAdapter(provider: SingleTurnProvider, model: string, providerName: string) {
diff --git a/mcp-host/src/core/adapters/__tests__/llmPortAdapter.imageInput.test.ts b/mcp-host/src/core/adapters/__tests__/llmPortAdapter.imageInput.test.ts
index 127f2753f..bbad6623a 100644
--- a/mcp-host/src/core/adapters/__tests__/llmPortAdapter.imageInput.test.ts
+++ b/mcp-host/src/core/adapters/__tests__/llmPortAdapter.imageInput.test.ts
@@ -159,6 +159,113 @@ describe('#654 LlmPortAdapter image guard', () => {
expect(messages[0].contentParts[0].type).toBe('image')
})
+ it('uses catalog and transport evidence for GFS read admission, not provider metadata', async () => {
+ const provider = fakeProvider('openai')
+ const providerCapability = vi.fn(async () => ({ status: 'unknown' as const }))
+ provider.getImageInputCapability = providerCapability
+ const adapter = new LlmPortAdapter(
+ provider,
+ 'new-vision-model',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({ state: 'supported', evidence: CURATED_EVIDENCE })
+ )
+
+ await expect(adapter.getImageInputCapability()).resolves.toMatchObject({
+ status: 'supported',
+ provider: 'openai',
+ model: 'new-vision-model',
+ })
+ expect(providerCapability).not.toHaveBeenCalled()
+ })
+
+ it('does not admit a GFS read from provider metadata when the catalog row is missing', async () => {
+ const provider = fakeProvider('openai')
+ const providerCapability = vi.fn(async () => ({
+ status: 'supported' as const,
+ provider: 'openai',
+ model: 'gpt-4.1',
+ evidence: 'provider metadata',
+ }))
+ provider.getImageInputCapability = providerCapability
+ const adapter = new LlmPortAdapter(provider, 'gpt-4.1', 'openai')
+
+ await expect(adapter.getImageInputCapability()).resolves.toEqual({ status: 'unknown' })
+ expect(providerCapability).not.toHaveBeenCalled()
+ })
+
+ it('admits Codex GFS input only for a present catalog row with a supported transport', async () => {
+ const provider = fakeProvider('codex-subscription')
+ const catalogued = new LlmPortAdapter(
+ provider,
+ 'gpt-5.6-luna',
+ 'codex-subscription',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ () => ({})
+ )
+ const missing = new LlmPortAdapter(provider, 'gpt-5.6-luna', 'codex-subscription')
+
+ await expect(catalogued.getImageInputCapability()).resolves.toMatchObject({
+ status: 'supported',
+ provider: 'codex-subscription',
+ model: 'gpt-5.6-luna',
+ })
+ await expect(missing.getImageInputCapability()).resolves.toEqual({ status: 'unknown' })
+ })
+
+ it('rejects an aborted GFS admission request asynchronously', async () => {
+ const adapter = new LlmPortAdapter(fakeProvider('openai'), 'gpt-4.1', 'openai')
+ await expect(adapter.getImageInputCapability(AbortSignal.abort())).rejects.toMatchObject({
+ code: 'cancelled',
+ })
+ })
+
+ it('fails closed for expired catalog evidence or an unavailable resolver', async () => {
+ const provider = fakeProvider('openai')
+ const expired = new LlmPortAdapter(
+ provider,
+ 'gpt-4.1',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ allow({
+ state: 'supported',
+ evidence: {
+ ...CURATED_EVIDENCE,
+ checkedAt: '2020-01-01T00:00:00Z',
+ validUntil: '2020-01-02T00:00:00Z',
+ },
+ })
+ )
+ const unavailable = new LlmPortAdapter(
+ provider,
+ 'gpt-4.1',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ () => {
+ throw new Error('catalog unavailable')
+ }
+ )
+
+ await expect(expired.getImageInputCapability()).resolves.toEqual({ status: 'unknown' })
+ await expect(unavailable.getImageInputCapability()).resolves.toEqual({ status: 'unknown' })
+ })
+
it('refuses the tool-less plain path that would drop the image (OpenAI family)', async () => {
const provider = fakeProvider('openai')
const adapter = new LlmPortAdapter(
diff --git a/mcp-host/src/core/adapters/llmPortAdapter.ts b/mcp-host/src/core/adapters/llmPortAdapter.ts
index 1513889a0..cacbed8f4 100644
--- a/mcp-host/src/core/adapters/llmPortAdapter.ts
+++ b/mcp-host/src/core/adapters/llmPortAdapter.ts
@@ -155,8 +155,18 @@ export class LlmPortAdapter implements LlmPort {
return this.tokenCounter
}
- getImageInputCapability(signal?: AbortSignal): Promise<ImageInputCapability> {
- return this.provider.getImageInputCapability?.(signal) ?? Promise.resolve({ status: 'unknown' })
+ async getImageInputCapability(signal?: AbortSignal): Promise<ImageInputCapability> {
+ if (signal?.aborted) throw new VisualInputError('cancelled')
+ // GFS tool results enter the loop as user visual parts through completeWithTools.
+ // This is read admission only; dispatch rechecks the actual method and pair.
+ const decision = this.decideImageInputForAttempt('completeWithTools', ['user'])
+ if (decision.state !== 'supported') return { status: decision.state }
+ return {
+ status: 'supported',
+ provider: this.providerName,
+ model: this.model,
+ evidence: decision.evidence?.reference ?? 'live-catalog-row',
+ }
}
async complete(request: CompletionRequest): Promise<CompletionResponse> {
diff --git a/mcp-host/src/internalTools/gfs.ts b/mcp-host/src/internalTools/gfs.ts
index b89708067..c47e8ed76 100644
--- a/mcp-host/src/internalTools/gfs.ts
+++ b/mcp-host/src/internalTools/gfs.ts
@@ -135,7 +135,7 @@ export function buildGfsReadTools(client: GfscReadClient): InternalToolDefinitio
{
name: 'clerum__gfs_read',
description:
- 'Read a GFS file by drive + resourceId. Returns UTF-8 text, or a bounded JPEG/PNG image when the active model supports image input. Other formats return a reference and an explicit limitation.',
+ 'Read a GFS file by drive + resourceId. Returns UTF-8 text, or a bounded JPEG/PNG image when the active model supports image input. Other binary formats return a reference; malformed or unsupported JPEG/PNG returns an error.',
parameters: driveResourceParams,
execute: async (args, _outputDir, options): Promise<InternalToolResult> => {
let file: GfsFileContent | undefined
diff --git a/mcp-host/src/internalTools/gfsImageInput.integration.test.ts b/mcp-host/src/internalTools/gfsImageInput.integration.test.ts
index a0efb3562..fc49309a1 100644
--- a/mcp-host/src/internalTools/gfsImageInput.integration.test.ts
+++ b/mcp-host/src/internalTools/gfsImageInput.integration.test.ts
@@ -7,6 +7,8 @@ import { appendToolResults } from '../core/orchestration/toolUseLoopMessages'
import { NativeToolRegistry } from '../core/tools/nativeToolRegistry'
import type { Attachment, ChatMessage, ToolResult } from '../core/types'
import { ClaudeProvider } from '../llm/claude'
+import { CodexSubscriptionProvider } from '../llm/codexSubscription'
+import type { ImageInputResolver } from '../llm/imageInput'
import { OpenAIProvider } from '../llm/openai'
import { OpenAICompatibleProvider } from '../llm/openaiCompatible'
import type { LlmProvider } from '../llm/registryCore'
@@ -35,6 +37,7 @@ vi.mock('./gfsClient', async importOriginal => ({
const rid = '1234567890abcdef1234567890abcdef'
const uri = `gfs://main/${rid}`
const model = 'example/vision-model'
+type CatalogState = 'supported' | 'unsupported' | 'unknown' | 'missing' | 'codex-present'
const config: NativeToolConfig = {
workspacePath: '/tmp',
shellTimeout: 5000,
@@ -49,8 +52,7 @@ async function setup(
bytes: Buffer,
options: {
name?: string
- modalities?: string[]
- missing?: boolean
+ catalogState?: CatalogState
llm?: { provider: SingleTurnProvider; model: string; name: LlmProvider }
} = {}
) {
@@ -95,9 +97,7 @@ async function setup(
JSON.stringify({
data: {
id: model,
- ...(options.missing
- ? {}
- : { architecture: { input_modalities: options.modalities ?? ['text', 'image'] } }),
+ architecture: { input_modalities: ['text', 'image'] },
},
}),
{ headers: { 'content-type': 'application/json' } }
@@ -120,16 +120,18 @@ async function setup(
model
)
const budget = new VisualInputBudget()
- const imageInputResolver = () => ({
- capability: {
- state: 'supported' as const,
- evidence: {
- source: 'curated' as const,
- reference: 'https://example.com/image-input',
- checkedAt: '2026-09-18T00:00:00Z',
- },
- },
- })
+ let catalogState = options.catalogState ?? 'supported'
+ const evidence = {
+ source: 'curated' as const,
+ reference: 'https://example.com/image-input',
+ checkedAt: '2026-09-18T00:00:00Z',
+ }
+ const imageInputResolver: ImageInputResolver = () => {
+ if (catalogState === 'missing') return undefined
+ if (catalogState === 'codex-present') return { capability: undefined }
+ if (catalogState === 'unknown') return { capability: { state: 'unknown' } }
+ return { capability: { state: catalogState, evidence } }
+ }
const adapter = new LlmPortAdapter(
provider,
options.llm?.model ?? model,
@@ -166,7 +168,19 @@ async function setup(
]
const collected: Attachment[] = []
appendToolResults(messages, [result], collected)
- return { adapter, messages, output, gfsFetch, metadataFetch, budget, collected, tool }
+ return {
+ adapter,
+ messages,
+ output,
+ gfsFetch,
+ metadataFetch,
+ budget,
+ collected,
+ tool,
+ setCatalogState: (state: CatalogState) => {
+ catalogState = state
+ },
+ }
}
afterEach(() => {
@@ -212,6 +226,101 @@ describe('GFS bytes to actual provider request', () => {
subject.budget.close()
}
)
+
+ it('delivers GFS pixels to a catalog-supported OpenAI model without provider allowlist evidence', async () => {
+ const client = {
+ baseURL: 'https://api.openai.com/v1',
+ chat: { completions: { create: sdkCreate } },
+ }
+ const provider = new OpenAIProvider(client as never, 'future-vision-model')
+ await expect(provider.getImageInputCapability()).resolves.toEqual({ status: 'unknown' })
+ const bytes = createCanvas(2, 2).toBuffer('image/png')
+ const subject = await setup(bytes, {
+ llm: { provider, model: 'future-vision-model', name: 'openai' },
+ })
+
+ expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+ expect(JSON.stringify(sdkCreate.mock.calls[0][0])).toContain(bytes.toString('base64'))
+ expect(subject.metadataFetch).not.toHaveBeenCalled()
+ subject.budget.close()
+ })
+
+ it('returns a reference when the catalog omits a documented vision model', async () => {
+ const client = {
+ baseURL: 'https://api.openai.com/v1',
+ chat: { completions: { create: sdkCreate } },
+ }
+ const provider = new OpenAIProvider(client as never, 'gpt-4.1')
+ await expect(provider.getImageInputCapability()).resolves.toMatchObject({ status: 'supported' })
+ const subject = await setup(createCanvas(2, 2).toBuffer('image/png'), {
+ catalogState: 'missing',
+ llm: { provider, model: 'gpt-4.1', name: 'openai' },
+ })
+
+ expect(JSON.parse(subject.output.content)).toMatchObject({
+ delivery: 'reference_only',
+ reason: 'model_image_input_unknown',
+ })
+ expect(subject.output.attachments).toBeUndefined()
+ expect(sdkCreate).not.toHaveBeenCalled()
+ subject.budget.close()
+ })
+
+ it('withholds an admitted GFS image if catalog support is revoked before dispatch', async () => {
+ const subject = await setup(createCanvas(2, 2).toBuffer('image/png'))
+ expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
+ subject.setCatalogState('unsupported')
+
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+
+ expect(
+ subject.messages.some(message => message.contentParts?.some(part => part.type === 'image'))
+ ).toBe(true)
+ expect(JSON.stringify(sdkCreate.mock.calls[0][0])).not.toContain('image_url')
+ expect(JSON.stringify(sdkCreate.mock.calls[0][0])).toContain('not forwarded')
+ subject.budget.close()
+ })
+
+ it('delivers a GFS image through Codex V2 for a present catalog row', async () => {
+ const authorize = vi.fn(
+ async (_input: {
+ request: { messages: Array<{ contentParts?: Array<{ type: string }> }> }
+ }) => ({
+ providerAttemptId: 'attempt-1',
+ requestHash: 'a'.repeat(64),
+ executionTicket: 'ticket-123456',
+ expiresAt: '2099-01-01T00:00:00.000Z',
+ })
+ )
+ const stream = vi.fn(async () => ({ text: 'seen', toolCalls: [], outcome: 'success' as const }))
+ const provider = new CodexSubscriptionProvider('gpt-5.6-luna', {
+ authorizer: { authorize },
+ proxy: { stream },
+ attemptContext: () => ({ policyRevision: 1, policyHash: 'b'.repeat(64), hostRef: 'chatllm' }),
+ } as never)
+ const bytes = createCanvas(2, 2).toBuffer('image/png')
+ const subject = await setup(bytes, {
+ catalogState: 'codex-present',
+ llm: { provider, model: 'gpt-5.6-luna', name: 'codex-subscription' },
+ })
+
+ expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+
+ const authorized = authorize.mock.calls[0][0].request
+ const image = authorized.messages
+ .flatMap((message: { contentParts?: Array<{ type: string }> }) => message.contentParts ?? [])
+ .find((part: { type: string }) => part.type === 'image')
+ expect(image).toMatchObject({
+ type: 'image',
+ data: bytes.toString('base64'),
+ source: { kind: 'tool', toolCallId: 'read-image' },
+ })
+ expect(stream).toHaveBeenCalledOnce()
+ subject.budget.close()
+ })
+
it.each([
['image/png', false],
['image/jpeg', false],
@@ -271,11 +380,8 @@ describe('GFS bytes to actual provider request', () => {
: {}),
})
expect(subject.metadataFetch).not.toHaveBeenCalled()
- expect(buildRequest).toHaveBeenCalledWith({
- method: 'get',
- path: `/v1/models/${targetModel}`,
- })
- expect(fetchWithTimeout).toHaveBeenCalledOnce()
+ expect(buildRequest).not.toHaveBeenCalled()
+ expect(fetchWithTimeout).not.toHaveBeenCalled()
const request = (create.mock.calls as unknown as Array<[Record<string, any>]>)[0][0]
const blocks = request.messages.flatMap((m: any) =>
Array.isArray(m.content) ? m.content : []
@@ -471,10 +577,7 @@ describe('GFS bytes to actual provider request', () => {
const toolMessage = request.messages.find((m: { role: string }) => m.role === 'tool')
expect(typeof toolMessage.content).toBe('string')
expect(toolMessage.content).not.toContain(bytes.toString('base64'))
- expect(subject.metadataFetch).toHaveBeenCalledTimes(1)
- expect(subject.metadataFetch.mock.calls[0][0]).toBe(
- `https://openrouter.ai/api/v1/model/example/vision-model`
- )
+ expect(subject.metadataFetch).not.toHaveBeenCalled()
expect(subject.gfsFetch).toHaveBeenCalledTimes(2)
subject.budget.close()
expect(subject.budget.residentBytes).toBe(0)
@@ -488,7 +591,7 @@ describe('GFS bytes to actual provider request', () => {
'{"ok":false,"data":"text"}',
'PK is a text prefix. RIFF is also a word. Unicode: 🌴\r\n',
])('keeps UTF-8 text usable without requiring vision: %j', async text => {
- const subject = await setup(Buffer.from(text), { name: 'note.txt', modalities: ['text'] })
+ const subject = await setup(Buffer.from(text), { name: 'note.txt', catalogState: 'missing' })
expect(subject.output.content).toBe(text.replace(/^\ufeff/, ''))
expect(subject.output.attachments).toBeUndefined()
await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
@@ -513,8 +616,12 @@ describe('GFS bytes to actual provider request', () => {
subject.budget.close()
})
- it.each([{ modalities: ['text'] }, { missing: true }])(
- 'returns an explicit reference when image capability is not established: %j',
+ it.each([
+ { catalogState: 'unsupported' },
+ { catalogState: 'unknown' },
+ { catalogState: 'missing' },
+ ] as const)(
+ 'returns an explicit reference when catalog image capability is not established: %j',
async options => {
const subject = await setup(createCanvas(1, 1).toBuffer('image/png'), options)
expect(JSON.parse(subject.output.content).delivery).toBe('reference_only')
diff --git a/mcp-host/src/llm/__tests__/openaiCompatible.classifyError.test.ts b/mcp-host/src/llm/__tests__/openaiCompatible.classifyError.test.ts
index f5d2e63f4..9bd687233 100644
--- a/mcp-host/src/llm/__tests__/openaiCompatible.classifyError.test.ts
+++ b/mcp-host/src/llm/__tests__/openaiCompatible.classifyError.test.ts
@@ -24,6 +24,10 @@ describe('OpenAICompatibleProvider.classifyError', () => {
)
await expect(compatible.getImageInputCapability()).resolves.toEqual({ status: 'unknown' })
})
+ it('rejects an aborted image capability lookup asynchronously', async () => {
+ const lookup = zai.getImageInputCapability(AbortSignal.abort())
+ await expect(lookup).rejects.toMatchObject({ code: 'cancelled' })
+ })
it('maps z.ai model-not-available codes (1211/1220) to ModelNotAvailable', () => {
for (const code of ['1211', '1220']) {
const c = zai.classifyError(openaiApiError(404, { code, message: 'model not available' }))
diff --git a/mcp-host/src/llm/openaiCompatible.ts b/mcp-host/src/llm/openaiCompatible.ts
index 92c575623..8afc2c858 100644
--- a/mcp-host/src/llm/openaiCompatible.ts
+++ b/mcp-host/src/llm/openaiCompatible.ts
@@ -129,7 +129,7 @@ export class OpenAICompatibleProvider extends OpenAIProvider {
return this.cfg.id as LlmProvider
}
- override getImageInputCapability(signal?: AbortSignal): Promise<ImageInputCapability> {
+ override async 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))