test(agent): pin the agent-outputs hooks - useAgentOutputs, useAgentTurnFiles, useInvalidateAgentOutputs, useRefreshAgentOutputs (Closes #1670)

[dmitrii-f-t27]

Closes #1670

What changed

One new file: trios/agent-server/apps/agent/lib/agent-files/useAgentOutputs.test.ts (the path the issue's Success Criteria names). The subject useAgentOutputs.ts is untouched.

All 4 exported symbols are exercised (4 it( blocks; 0 blocked). Every export is a React Query hook, so the suite runs each one inside a fresh QueryClientProvider with renderToStaticMarkup; outside the BrowserOS shell there is no base URL, so the queries stay disabled and no fetch ever happens - a disabled query still reads the cache, and that is how the data-path pins drive everything:

• useAgentOutputs (1 test): no groups without a base URL; the cached groups flow through once the cache holds them under the hook's declared key.
• useAgentTurnFiles (1 test): no files without a base URL; the cached turn files flow through for the very turn asked about - and a different turn answers nothing, because the turn id is part of the key.
• useInvalidateAgentOutputs (1 test): captured from the render and driven against the real cache - invalidating one agent marks that agent's outputs and only the turn asked about, leaving every other agent and every other turn untouched (read from each entry's isInvalidated; the default stale time of zero makes isStale meaningless here).
• useRefreshAgentOutputs (1 test): the refresh mutation is answered ready and idle, and it resolves when there is nothing in the cache to refetch.

The pins read only what holds no matter which stand-ins other suites of this job register for the URL hook (the base URL is null either way); the loading flag is the one thing that varies, so it is not pinned. Not pinned, and why: the fetch paths themselves (queryFn through agentsFetch) - they need the live agent server. No mocks at all.

How it was verified (FR-004)

• Passing run against the unmodified subject: 4 pass / 0 fail / 16 expect() calls, Ran 4 tests across 1 file.
• Deliberately broken copy (the outputs invalidation predicate inverted, valid syntax): 3 pass / 1 fail / 10 expect() calls - the invalidation pin fails on the scoping. The subject was restored byte-identical (git checkout; git diff --name-only prints nothing) and the suite passes again.
• No network, database or container; no existing test modified or weakened. The file is biome-check clean. The local typecheck reports 59 errors - the pre-existing local base of this tree - and 0 mentions of the new file.
• Local reproducibility note (issue bun test cannot resolve @/ aliases once .wxt/tsconfig.json exists (wxt prepare output breaks the bun 1.3.6 runtime resolver) #1909): bun run typecheck runs wxt prepare, whose generated .wxt/tsconfig.json makes bun 1.3.6 stop resolving @/ aliases for test runs until that generated directory is removed. CI's Tests jobs never run wxt prepare; every run quoted above is from a checkout without .wxt/.

Not verified

• Nothing beyond the quoted local runs; the CI Tests / agent job re-runs the suite on this SHA.

Dmitrii Fedorov (@dmitrii-f-t27)

[tri-claw]

Summary by t27-bees

This PR adds a contract test file that pins the current behavior of four React Query hooks (useAgentOutputs, useAgentTurnFiles, useInvalidateAgentOutputs, useRefreshAgentOutputs) by exercising them against a real QueryClient cache with queries disabled (no base URL). The tests seed cache entries under the exact keys the hooks declare and verify data flow, invalidation scoping, and mutation readiness without any network calls.

Worth a look

• trios/agent-server/apps/agent/lib/agent-files/useAgentOutputs.test.ts:26 — process.env.VITE_BROWSEROS_SERVER_PORT ??= '43210' mutates the global environment before dynamic imports. If another test file runs first and loads the env module, the snapshot may freeze a different value (or none), making these tests flaky in a different CI order. The comment acknowledges this coupling to the helpers suite's afterAll cleanup.

• trios/agent-server/apps/agent/lib/agent-files/useAgentOutputs.test.ts:97–118 — The invalidation test asserts isInvalidated on query states after calling the invalidator. This relies on React Query's default staleTime: 0 (making isStale always true) and the hook calling invalidateQueries with exact key matches. If the subject hook later changes to use queryClient.invalidateQueries({ predicate }) with a broader predicate, the test would still pass because it only checks the four specific keys it seeded — it wouldn't catch over-invalidation of other turns/agents not present in the test cache.

• trios/agent-server/apps/agent/lib/agent-files/useAgentOutputs.test.ts:125–142 — The refresh test only verifies the mutation resolves when the cache is empty. It does not exercise the actual refetch path (which requires a live agent server per the description). A future change that breaks the refetch logic but keeps the mutation "ready and idle" would not be caught.

• trios/agent-server/apps/agent/lib/agent-files/useAgentOutputs.test.ts:34–35 — Dynamic imports of @/entrypoints/app/agents/useAgents and ./useAgentOutputs are used to defer loading until after the env var is set. If the module graph changes so either import is hoisted (e.g., by a bundler or test runner), the env snapshot could freeze before the assignment, causing the port helpers to fail in hard-to-debug ways.

• trios/agent-server/apps/agent/lib/agent-files/useAgentOutputs.test.ts:55–56 — railGroup and producedFile factories use as const on detectedBy but not on other fields. If the hook's return types narrow based on literal types (e.g., turnPrompt), the test objects may not match the expected shape, though current assertions only check turnId and id.

---

_{Read: 1 files, +227 -0, the whole diff. Head ef39fa1. Model: openai-compatible/nvidia/nemotron-3-ultra-550b-a55b. Commands: @t27-bees review | summary | help | pause | resume. Free for every repository.}

[github-actions]

✅ Tests passed — 3544/3614

Suite	Passed	Failed	Skipped
✅ agent	186/186	0	0
✅ build	9/9	0	0
✅ cdp-protocol	5/5	0	0
✅ eval	93/93	0	0
✅ server-agent	280/280	0	0
✅ server-api	2145/2214	0	69
✅ server-browser	6/6	0	0
✅ server-integration	10/11	0	1
✅ server-lib	279/279	0	0
✅ server-pglive	166/166	0	0
✅ server-root	68/68	0	0
✅ server-sim	8/8	0	0
✅ server-skills	31/31	0	0
✅ server-tools	244/244	0	0
✅ shared	14/14	0	0

View workflow run

[dmitrii-f-t27]

The first head failed Tests / agent with the three port-helper pins refusing (AgentPortError/McpPortError). Root cause, measured: lib/env.ts parses import.meta.env ONCE at module load, and this suite's import graph is what first loads that module in the CI file order - the snapshot froze without a port, so the helpers suite's own env seam could no longer reach the helpers it pins. Reproduced locally by running the two files in the CI order; fixed by seeding the same seam value (43210) before any import that can reach the env module - both the key import and the subject import are dynamic for that reason - exactly the way the helpers suite seeds it for its own dynamic import. Verified in all three orders (this-first: 11 tests / 0 fail, helpers-first: 0 fail, alone: 0 fail); the full local group is unchanged (183 pass / 3 fail, the 3 being the pre-existing local-only env failures, green in CI).

Dmitrii Fedorov (@dmitrii-f-t27)

[dmitrii-f-t27]

CI gates on this SHA (head ef39fa1):

• Tests / agent: pass — the four hook pins run green, and the port-helper pins of the helpers suite stay green beside them (the env-snapshot seeding holds in the CI file order).
• All other Tests/ matrix jobs pass*, including server-pglive (no flake rerun needed).
• Typecheck job: 19 errors = the known base count; 0 mentions of useAgentOutputs.test.ts in the job log.
• Biome job: red from base findings; 0 mentions of useAgentOutputs.test.ts in the job log.

Dmitrii Fedorov (@dmitrii-f-t27)