Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docs/testing/agent-integration-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 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
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
Expand Down Expand Up @@ -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.
60 changes: 54 additions & 6 deletions scripts/vite-config-dev-agent.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -263,17 +264,64 @@ describe('dev server agent routes', () => {
const agentProxy = { target: 'http://127.0.0.1:8095', ws: true }
const backend = { target: 'https://cloud.example.com' }

function resolve(
routes: Record<string, ProxyOptions>,
Comment thread
christian-byrne marked this conversation as resolved.
Resolved
url: string
): ProxyOptions | undefined {
return Object.entries(routes).find(([context]) =>
url.startsWith(context)
)?.[1]
}

function resolveSocket(
routes: Record<string, ProxyOptions>,
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', () => {
expect(devServerAgentRoutes(undefined, backend)).toEqual({
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
)

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
})
})

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)
expect(resolveSocket(routes, '/api/agent/events')).toBe(agentProxy)
})

it('leaves other api traffic to the ComfyUI proxy', () => {
expect(
resolve(devServerAgentRoutes(agentProxy, backend), '/api/prompt')
).toBeUndefined()
})
})
Original file line number Diff line number Diff line change
Expand Up @@ -1643,37 +1643,47 @@ describe('user auth on agent requests', () => {
})
})

const calls: [
string,
(client: AgentRestClient) => Promise<unknown>,
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')

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))

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)
Expand Down
Loading