From 266e2a049e7a82558ecb3d2143c31f63604fc881 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Mon, 26 Oct 2026 20:59:34 +0000 Subject: [PATCH 1/4] chore(agent): retire two self-asserting tests and document the dev proxy flag Three pieces of test and documentation debt around the agent dev harness. No production code changes. docs/testing/agent-integration-development.md never named VITE_DEV_AGENT_PROXY_CREDENTIAL, so a contributor who saw a signed-out panel send anyway had nothing to grep for. The flag is derived, not set by hand, so it is documented as such: vite.config.mts defines it from the presence of the agent proxy plus DEV_AGENT_COMFY_TOKEN, and the token itself stays in the proxy. The same doc told readers to use Node 25 while package.json requires >=26.8.2 <27. The dev-server route test asserted an '/api/agent/events' table entry that no request can reach once a local agent is configured: Vite takes the first proxy context the path starts with, and '/api/agent' precedes it. The entry is still needed for the no-local-agent case, so it stays; the test now resolves sample URLs the way Vite does and states that a local agent serves the socket too. The 'user auth on agent requests' table ran four verbs through requestResult, the single caller of withAgentAuth, and then read back the Authorization header its own mock had just set. It now pins what that seam owes: the request's own method, headers and body reach withAgentAuth, and the init that reaches the network is identically the authorized one rather than a rebuilt copy that could drop a credential. refreshCredential keeps coverage through an assertion on the route it actually spends. --- docs/testing/agent-integration-development.md | 13 +++- scripts/vite-config-dev-agent.test.ts | 40 ++++++++-- .../services/agent/agentRestClient.test.ts | 75 ++++++++++++------- 3 files changed, 93 insertions(+), 35 deletions(-) diff --git a/docs/testing/agent-integration-development.md b/docs/testing/agent-integration-development.md index a4ac7629d8a..ba0ac59f5df 100644 --- a/docs/testing/agent-integration-development.md +++ b/docs/testing/agent-integration-development.md @@ -72,7 +72,8 @@ Paste the recorder command it prints, one `--prompt` per turn. ## Setup -1. Use Node 25 and install this repository with `pnpm install`. +1. Use Node 26 (`package.json` requires `>=26.8.2 <27`; see `.nvmrc`) and install + this repository with `pnpm install`. 2. Check out `Comfy-Org/cloud` next to this repository, or pass its location with `--cloud-repo`. 3. Install the agent's file watcher: @@ -104,6 +105,12 @@ Paste the recorder command it prints, one `--prompt` per turn. `X-API-KEY`, anything else as a bearer token. The panel then sends without asking a signed-out user to sign in. Without it, a signed-out send opens the sign-in dialog. + The browser learns this from `VITE_DEV_AGENT_PROXY_CREDENTIAL`, which + `vite.config.mts` defines as `'true'` whenever the agent proxy is configured and + `DEV_AGENT_COMFY_TOKEN` is set. Do not set it yourself: it is derived, it is read + only in development mode, and the token itself never leaves the proxy. It is the + name to grep for when a signed-out panel sends anyway. + The root dependency on `@comfyorg/comfy-multi-player` may use the published npm package or `workspace:`. The launcher warns that package source edits will not hot-reload when the published package is selected, and refuses `pnpm link`; use @@ -180,6 +187,10 @@ the turn's first frame; replay sends back to back by default and an in-process event bus rather than Postgres, Redis, ingest, or Temporal. - **Vite proxy:** the development-only same-origin bridge that forwards agent requests and injects the standalone session credential outside browser code. +- **`VITE_DEV_AGENT_PROXY_CREDENTIAL`:** the build-time flag Vite derives from + `DEV_AGENT_COMFY_TOKEN` to tell the browser that the proxy supplies a user + credential, so a signed-out send skips the sign-in dialog. Derived, never set by + hand, and never the token. - **`agent.json`:** the discovery file the standalone agent writes into its data directory on every start — `{ port, token, pid }`, mode 0600. It is how a local client finds the running agent and its current token without scanning ports. diff --git a/scripts/vite-config-dev-agent.test.ts b/scripts/vite-config-dev-agent.test.ts index 9a19a2743ae..7eb5447be2f 100644 --- a/scripts/vite-config-dev-agent.test.ts +++ b/scripts/vite-config-dev-agent.test.ts @@ -6,6 +6,7 @@ import { join } from 'node:path' import { promisify } from 'node:util' import { afterAll, describe, expect, it } from 'vitest' +import type { ProxyOptions } from 'vite' import { createDevAgentConfig, @@ -263,17 +264,44 @@ describe('dev server agent routes', () => { const agentProxy = { target: 'http://127.0.0.1:8095', ws: true } const backend = { target: 'https://cloud.example.com' } + // Vite walks the proxy table in insertion order and takes the first context + // the path starts with, so a route's position is the whole of its meaning. + // Asserting the table's shape alone would pass for an '/api/agent/events' + // entry that no request can ever reach. + function resolve( + routes: Record, + url: string + ): ProxyOptions | undefined { + return Object.entries(routes).find(([context]) => + url.startsWith(context) + )?.[1] + } + it('upgrades the events socket on the backend without a local agent', () => { - expect(devServerAgentRoutes(undefined, backend)).toEqual({ + const routes = devServerAgentRoutes(undefined, backend) + + expect(routes).toEqual({ '/api/agent/events': { target: 'https://cloud.example.com', ws: true } }) + expect(resolve(routes, '/api/agent/events')).toMatchObject({ + target: 'https://cloud.example.com', + ws: true + }) }) it('routes the agent and the saved-workflow index to a local agent first', () => { - expect(Object.entries(devServerAgentRoutes(agentProxy, backend))).toEqual([ - ['/api/workflows', agentProxy], - ['/api/agent', agentProxy], - ['/api/agent/events', { target: 'https://cloud.example.com', ws: true }] - ]) + const routes = devServerAgentRoutes(agentProxy, backend) + + expect(resolve(routes, '/api/workflows?limit=20')).toBe(agentProxy) + expect(resolve(routes, '/api/agent/threads/new/messages')).toBe(agentProxy) + // The backend events entry is behind '/api/agent', so a local agent serves + // the socket as well; it exists for the no-local-agent case above only. + expect(resolve(routes, '/api/agent/events')).toBe(agentProxy) + }) + + it('leaves other api traffic to the ComfyUI proxy', () => { + expect( + resolve(devServerAgentRoutes(agentProxy, backend), '/api/prompt') + ).toBeUndefined() }) }) diff --git a/src/workbench/extensions/agent/services/agent/agentRestClient.test.ts b/src/workbench/extensions/agent/services/agent/agentRestClient.test.ts index ff2ed04063e..128838448af 100644 --- a/src/workbench/extensions/agent/services/agent/agentRestClient.test.ts +++ b/src/workbench/extensions/agent/services/agent/agentRestClient.test.ts @@ -1634,6 +1634,10 @@ const emptyThreadPage = { pagination: { offset: 0, limit: 1, total: 0, has_more: false } } +// Every client method reaches the network through the one `requestResult` +// helper, which is the only caller of `withAgentAuth`. Reading back the header +// the mock just set, once per verb, would only restate the mock; what is worth +// pinning is the contract across that single seam. describe('user auth on agent requests', () => { beforeEach(() => { vi.mocked(withAgentAuth).mockImplementation(async (init) => { @@ -1643,37 +1647,52 @@ describe('user auth on agent requests', () => { }) }) - const calls: [ - string, - (client: AgentRestClient) => Promise, - unknown - ][] = [ - [ - 'POST messages', - (c) => c.postMessage('new', { content: 'hi' }), - turnAccepted - ], - ['GET messages', (c) => c.getMessages('t1'), []], - [ - 'POST answer', - (c) => c.answerAsk('t1', 'ask-1', { selected: ['allow'] }), - { status: 'answered' } - ], - ['the credential refresh', (c) => c.refreshCredential(), emptyThreadPage] - ] + it('hands the request its own method, headers and body to be authorized', async () => { + respond(jsonResponse(202, turnAccepted)) + + await makeClient().postMessage('new', { content: 'hi' }) - it.for(calls)( - 'sends the user auth header with %s', - async ([, call, body]) => { - respond(jsonResponse(200, body)) + expect(withAgentAuth).toHaveBeenCalledOnce() + const [authorizing] = vi.mocked(withAgentAuth).mock.calls[0] + expect(authorizing.method).toBe('POST') + expect(new Headers(authorizing.headers).get('Content-Type')).toBe( + 'application/json' + ) + expect(JSON.parse(String(authorizing.body))).toMatchObject({ + content: 'hi' + }) + }) - await call(makeClient()) + it('fetches with the authorized init rather than rebuilding one', async () => { + respond(jsonResponse(200, [])) - expect(new Headers(lastCall().init.headers).get('Authorization')).toBe( - 'Bearer id-token' - ) - } - ) + await makeClient().getMessages('t1') + + // Identity, not equality: a client that copied headers out of the + // authorized init and back into a fresh object could silently drop the + // credential a future `withAgentAuth` adds. + expect(lastCall().init).toBe( + await vi.mocked(withAgentAuth).mock.results[0].value + ) + expect(new Headers(lastCall().init.headers).get('Authorization')).toBe( + 'Bearer id-token' + ) + }) + + it('refreshes the credential with the cheapest authorized request', async () => { + respond(jsonResponse(200, emptyThreadPage)) + + // The call exists only to drive a credential refresh, so the route it + // spends and the fact that it is authorized at all are its whole contract. + await makeClient().refreshCredential() + + const { route, init } = lastCall() + expect(route).toBe('/agent/threads?limit=1') + expect(init.method).toBe('GET') + expect(new Headers(init.headers).get('Authorization')).toBe( + 'Bearer id-token' + ) + }) it('sends no auth header for a signed-out user', async () => { vi.mocked(withAgentAuth).mockImplementation(async (init) => init) From bb30119e3a2208309b369e23109f44be692cf1e9 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Wed, 28 Oct 2026 06:02:39 +0000 Subject: [PATCH 2/4] test(agent): model the websocket upgrade rule separately from HTTP routing Vite's upgrade handler skips a matching context that cannot carry a socket and keeps walking, which is not the first-prefix-wins rule the single resolver modelled. The socket assertions agreed with real routing only because every fixture sets ws: true, so they would have missed the events socket falling through to the backend once agentProxy lost ws. That case now has a test. --- scripts/vite-config-dev-agent.test.ts | 41 +++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/scripts/vite-config-dev-agent.test.ts b/scripts/vite-config-dev-agent.test.ts index 7eb5447be2f..224387b5bbf 100644 --- a/scripts/vite-config-dev-agent.test.ts +++ b/scripts/vite-config-dev-agent.test.ts @@ -277,13 +277,47 @@ describe('dev server agent routes', () => { )?.[1] } + // The upgrade handler does not follow the HTTP rule. A matching context that + // cannot carry a socket -- no `ws`, and no ws:/wss: target -- is skipped and the + // walk continues, so a socket can land on a later entry than HTTP would pick. + // Modelling both with one resolver agreed with real routing only because every + // fixture here sets `ws: true`. + function resolveSocket( + routes: Record, + url: string + ): ProxyOptions | undefined { + return Object.entries(routes).find(([context, options]) => { + if (!url.startsWith(context)) return false + const target = typeof options.target === 'string' ? options.target : '' + return options.ws === true || /^wss?:/.test(target) + })?.[1] + } + it('upgrades the events socket on the backend without a local agent', () => { const routes = devServerAgentRoutes(undefined, backend) expect(routes).toEqual({ '/api/agent/events': { target: 'https://cloud.example.com', ws: true } }) + expect(resolveSocket(routes, '/api/agent/events')).toMatchObject({ + target: 'https://cloud.example.com', + ws: true + }) + }) + + it('falls the events socket through to the backend when the agent route cannot carry one', () => { + const routes = devServerAgentRoutes( + { target: 'http://127.0.0.1:8095' }, + backend + ) + + // HTTP stops at '/api/agent', which matches first. The upgrade handler skips it + // for having no `ws` and reaches the backend entry, so the socket survives an + // agentProxy that loses `ws` even though the HTTP route does not change. expect(resolve(routes, '/api/agent/events')).toMatchObject({ + target: 'http://127.0.0.1:8095' + }) + expect(resolveSocket(routes, '/api/agent/events')).toMatchObject({ target: 'https://cloud.example.com', ws: true }) @@ -294,9 +328,10 @@ describe('dev server agent routes', () => { expect(resolve(routes, '/api/workflows?limit=20')).toBe(agentProxy) expect(resolve(routes, '/api/agent/threads/new/messages')).toBe(agentProxy) - // The backend events entry is behind '/api/agent', so a local agent serves - // the socket as well; it exists for the no-local-agent case above only. - expect(resolve(routes, '/api/agent/events')).toBe(agentProxy) + // The backend events entry is behind '/api/agent', so a local agent that can + // carry a socket serves it as well; the backend entry exists for the + // no-local-agent case above only. + expect(resolveSocket(routes, '/api/agent/events')).toBe(agentProxy) }) it('leaves other api traffic to the ComfyUI proxy', () => { From 43734fd18cfde124ffae552b1119cc904850cf54 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Wed, 28 Oct 2026 06:55:58 +0000 Subject: [PATCH 3/4] docs(agent): say the dev token never reaches the browser Vite forwards DEV_AGENT_COMFY_TOKEN to the standalone agent, as this same page says two paragraphs earlier, so "never leaves the proxy" was literally false. The property that matters is that it is never exposed to the browser. --- docs/testing/agent-integration-development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/testing/agent-integration-development.md b/docs/testing/agent-integration-development.md index ba0ac59f5df..dec4d142ebc 100644 --- a/docs/testing/agent-integration-development.md +++ b/docs/testing/agent-integration-development.md @@ -108,7 +108,7 @@ Paste the recorder command it prints, one `--prompt` per turn. The browser learns this from `VITE_DEV_AGENT_PROXY_CREDENTIAL`, which `vite.config.mts` defines as `'true'` whenever the agent proxy is configured and `DEV_AGENT_COMFY_TOKEN` is set. Do not set it yourself: it is derived, it is read - only in development mode, and the token itself never leaves the proxy. It is the + only in development mode, and the token itself never reaches the browser. It is the name to grep for when a signed-out panel sends anyway. The root dependency on `@comfyorg/comfy-multi-player` may use the published npm From d5080db142c4857a9878711286e1674fd590b95e Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Wed, 28 Oct 2026 22:11:23 -0700 Subject: [PATCH 4/4] test(agent): remove prohibited test comments --- scripts/vite-config-dev-agent.test.ts | 15 --------------- .../agent/services/agent/agentRestClient.test.ts | 9 --------- 2 files changed, 24 deletions(-) diff --git a/scripts/vite-config-dev-agent.test.ts b/scripts/vite-config-dev-agent.test.ts index 224387b5bbf..c868eeed0ab 100644 --- a/scripts/vite-config-dev-agent.test.ts +++ b/scripts/vite-config-dev-agent.test.ts @@ -264,10 +264,6 @@ describe('dev server agent routes', () => { const agentProxy = { target: 'http://127.0.0.1:8095', ws: true } const backend = { target: 'https://cloud.example.com' } - // Vite walks the proxy table in insertion order and takes the first context - // the path starts with, so a route's position is the whole of its meaning. - // Asserting the table's shape alone would pass for an '/api/agent/events' - // entry that no request can ever reach. function resolve( routes: Record, url: string @@ -277,11 +273,6 @@ describe('dev server agent routes', () => { )?.[1] } - // The upgrade handler does not follow the HTTP rule. A matching context that - // cannot carry a socket -- no `ws`, and no ws:/wss: target -- is skipped and the - // walk continues, so a socket can land on a later entry than HTTP would pick. - // Modelling both with one resolver agreed with real routing only because every - // fixture here sets `ws: true`. function resolveSocket( routes: Record, url: string @@ -311,9 +302,6 @@ describe('dev server agent routes', () => { backend ) - // HTTP stops at '/api/agent', which matches first. The upgrade handler skips it - // for having no `ws` and reaches the backend entry, so the socket survives an - // agentProxy that loses `ws` even though the HTTP route does not change. expect(resolve(routes, '/api/agent/events')).toMatchObject({ target: 'http://127.0.0.1:8095' }) @@ -328,9 +316,6 @@ describe('dev server agent routes', () => { expect(resolve(routes, '/api/workflows?limit=20')).toBe(agentProxy) expect(resolve(routes, '/api/agent/threads/new/messages')).toBe(agentProxy) - // The backend events entry is behind '/api/agent', so a local agent that can - // carry a socket serves it as well; the backend entry exists for the - // no-local-agent case above only. expect(resolveSocket(routes, '/api/agent/events')).toBe(agentProxy) }) diff --git a/src/workbench/extensions/agent/services/agent/agentRestClient.test.ts b/src/workbench/extensions/agent/services/agent/agentRestClient.test.ts index 128838448af..b1a2cfeee23 100644 --- a/src/workbench/extensions/agent/services/agent/agentRestClient.test.ts +++ b/src/workbench/extensions/agent/services/agent/agentRestClient.test.ts @@ -1634,10 +1634,6 @@ const emptyThreadPage = { pagination: { offset: 0, limit: 1, total: 0, has_more: false } } -// Every client method reaches the network through the one `requestResult` -// helper, which is the only caller of `withAgentAuth`. Reading back the header -// the mock just set, once per verb, would only restate the mock; what is worth -// pinning is the contract across that single seam. describe('user auth on agent requests', () => { beforeEach(() => { vi.mocked(withAgentAuth).mockImplementation(async (init) => { @@ -1668,9 +1664,6 @@ describe('user auth on agent requests', () => { await makeClient().getMessages('t1') - // Identity, not equality: a client that copied headers out of the - // authorized init and back into a fresh object could silently drop the - // credential a future `withAgentAuth` adds. expect(lastCall().init).toBe( await vi.mocked(withAgentAuth).mock.results[0].value ) @@ -1682,8 +1675,6 @@ describe('user auth on agent requests', () => { it('refreshes the credential with the cheapest authorized request', async () => { respond(jsonResponse(200, emptyThreadPage)) - // The call exists only to drive a credential refresh, so the route it - // spends and the fact that it is authorized at all are its whole contract. await makeClient().refreshCredential() const { route, init } = lastCall()