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.tsindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 | undefineddiff --git a/mcp-host/src/internalTools/gfsImageInput.integration.test.ts b/mcp-host/src/internalTools/gfsImageInput.integration.test.tsindex 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?: CatalogStatellm?: { 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.tsindex 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.tsindex 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))