feat(provider): add Vercel fx as a provider#18277

T3 Code can't run Vercel's fx coding agent. fx ships an Agent Client Protocol server, fx acp, but Settings → Providers → Add provider has no fx entry.

This adds packages/provider-fx, a thin flavor on the shared ACP adapter in the shape of provider-grok. It started as @agadzik's rebuild of https://git.cafe/pingdotgg/t3code/pulls/16962 and was taken over by a maintainer; see Takeover below.

What fx does in T3 Code

• Off by default. The health check runs fx --version, fx status --json and fx models --json. It never opens an ACP session. All fx instances on a machine share its fx login.
• Modes: Supervised (fx ask) and Auto. Auto runs fx code on fx 0.0.13 and auto from 0.0.14 (vercel-labs/fx#1189). Full access and Auto-accept edits aren't offered; a thread already in one runs Supervised. fx 0.0.14 adds a full-access mode, and mapping T3's Full access to it is a follow-up.
  • The mode is written every time a session starts or loads. fx 0.0.13 reports ask on a new session while it still enforces its saved default until a client writes the mode.
  • In Auto, every prompt fx raises goes to the user, because fx's own review asks only about what it refused.
• Models. fx lists its backend option provider before model, so only config id model is written.
  • Default runs the model fx status reports. It's carried as the alias of the snapshot's default entry, the way Kiro and Antigravity do it. If the session's backend doesn't list that model (after fx provider codex, or a loaded older session), the session keeps its own model, so the thread still starts.
  • A model the thread picked goes out even when the session doesn't list it, using the shared runtime's new setConfigOption(..., { allowUnlistedValue }). fx's gateway accepts any id, and its other backends reply with their own error.
  • Effort writes Medium when a thread has none.
• Skills. The $ menu lists the skills fx can actually invoke, scanned from fx's skill folders in fx's own menu order (checked against fx 0.0.13's source):
  • SKILL.md frontmatter is read with fx's line-based rules, not YAML. All 30 cases from fx's own parser tests produce the same result.
  • When two skills share a name (ignoring ASCII case), the menu lists the one fx loads for it. fx gives the model every copy in scan order and it takes the first, so the first copy is listed.
  • Nothing is loaded through links in fx's managed ~/.fx/skills, as in fx.
• Sub-agents open in their own threads. fx reports each one as a subagent tool call (run or message, wrapped in request on 0.0.14 and flat on fx main), and the flavor maps it to a T3 sub-agent with its task, live status and reply. fx streams none of the child's own frames over ACP and clips tool results to 199 bytes, so the child thread holds the task and the readable prefix of fx's reply.
• Notices. fx's warnings, such as a skipped skill, show as notices rather than reply text, through the ACP session notices support on main (#25704).
• Not supported. Steering is interrupt-and-restart, plan mode is hidden, and text generation is unsupported, because every fx acp session is saved under ~/.fx and ACP can't delete one.
• Docs. docs/user/providers-fx.md, plus rows in the install table, permission modes and the docs index.

Shared changes:

• AcpSessionRuntime.setConfigOption gains allowUnlistedValue. https://git.cafe/pingdotgg/t3code/pulls/14693 (Kiro) adds the same option, so whichever lands second has a trivial conflict.
• scripts/release-smoke.ts lists the new workspace package.
• The ACP replay runtime passes cancelBehavior through.

Takeover

@agadzik's PR got the design right: a thin ACP flavor, forcing the mode write for fx 0.0.13, writing only model, the Medium default, and fx 0.0.13 replay recordings with a recorder. The recordings and recorder are kept as they were. The rebuild:

• Tests: 58 → 17 (8 replays + 9). The 8 recorded replays are the main proof; they already pinned the forced mode write and the Medium default. The 50 unit tests that restated them are gone. What's left covers only what the replays can't reach:
  • Auto mode ids on 0.0.13 and fx main.
  • Default on a loaded session, and on another backend.
  • A custom model and the switch back from it.
  • Provider status.
  • Auto prompts reaching the user.
  • Skill order and invocability, including a linked ~/.fx/skills.
• Default model comes from the snapshot instead of a mutable ref the driver set after each health check. The custom adapter type is gone.
• Status collapsed to one snapshot helper (436 → 230 lines). The version-advisory enrichment pass is dropped, since fx has no npm package; the driver kind still gives the advisory.
• Mode handling is a small runtime wrapper. Only the first mode write after a session starts or loads is forced; later writes, such as one from a model switch, take the normal path.
• Skills rewritten to match fx: menu order, line-based frontmatter, ambiguity, HOME and real-path handling, and managed-root links. The yaml dependency is gone.
• Shared test harness: the per-provider runtimeMode and the interrupt step's release label are removed. Neither changed anything for fx.
• Marketing harness tile dropped. Built-in providers that are off by default, such as Muse and Pi, aren't on the homepage; adding fx there is a separate product call.

Review

Six rounds of independent full-diff review (Claude Opus 5.5 and GPT 6.1 Sol in parallel), fixing confirmed findings between rounds, until a round came back clean from both. Real bugs they found and this head fixes:

• The release-smoke CI job was missing the new package, so it would have failed.
• A custom model was silently dropped.
• Default broke threads on a non-gateway fx backend.
• The skills menu offered skills fx can't invoke.
• Auto's prompt routing was untested.

Known gaps, deliberately left:

• Linked skill folders outside fx's managed root: fx follows these only within its allowed locations; T3 follows any link.
• Persistent fx status failure: Default then stays on the session's model. The provider card already warns.
• Sub-agent approvals in Supervised (fx bug): fx 0.0.14 parks a sub-agent that needs permission (awaiting_approval) and never forwards the request over ACP; only fx's terminal UI drains those approvals, and fx main hasn't changed that. The turn then waits until Stop. The user guide says so and suggests Auto for delegation. Reported upstream as vercel-labs/fx#1465, with the ACP transcript.

Verification

At this head (4d3c8e4589, main merged in again on Oct 27):

• Update onto main with session notices (Oct 27). Main gained ACP session notices (#25704), so initialize now advertises session.notices, and the 9 fx transcripts that pin that frame gain it on that one line; no agent frames changed. The merge was clean. After it: provider-fx 5, provider-grok 83, provider-acp-registry 55, contracts 145, server ACP family 179, every replay file 196, typecheck clean. provider-acp passed 86 of 87: clientTerminals.test.ts, which this PR doesn't touch, timed out once while a typecheck ran alongside; alone it takes 3.4s of its 5s budget and passed 3 of 3 reruns. fx 0.0.14's notice was checked live in #25704: a skipped skill showed as one notice and the reply stayed clean.
• Second update onto main (Oct 26). 19 new commits on main conflicted in the model manifest (kept main's updatedAt; fx's compatibility entry merged cleanly) and settings search (main moved "Provider update checks" to Maintenance; kept that plus the fx term). Every check below was re-run on the merge, plus ModelManifest.test.ts (14).
• Sub-agents (Oct 26). fx sub-agents showed as plain tool rows. A new fx_subagent replay, recorded live on fx 0.0.14 in Auto with the shared two-sub-agent prompt, passes; with the mapping removed it fails (expected [ 'tool_call', 'tool_call', …] to include 'subagent'). In Supervised, three live runs (a direct ACP probe, the recorder, and a dev-server thread) each left one child in awaiting_approval with no request on the wire. After this commit: provider-fx 5, provider-acp 87, provider-grok 83, provider-acp-registry 55, contracts 146, server ACP family 178, every replay file 196, knip passes, typecheck and lint clean.
• Update onto main (Oct 26). Two small conflicts, both kept from each side: the knip workspace list (main added source-control-definitions) and setConfigOption (fx's allowUnlistedValue, main's Effect.andThen). Main bumped vite-plus, so the lockfile is main's again plus the fx package, and vp install --frozen-lockfile passes. fx's comments now fit main's new 4-line no-low-value-comments rule, and its settings defaults decode with Schema.decodeSync for the new preferTypedSchemaDecoder check, as Grok's do. After the merge: provider-fx 5, provider-acp 87, provider-grok 83, provider-acp-registry 55, contracts 146, server ACP family 177, every replay file 195, knip passes, typecheck clean, lint clean on the changed files.
• Update onto main (Oct 22). Main pinned its patched packages (#23798), which broke the merged lockfile (ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY on every CI job), so the lockfile is main's again plus the fx package, and vp install --frozen-lockfile passes. The package's typecheck script uses tsc, as main's other packages do since #23023. After the merge: provider-fx 5, provider-acp 89, provider-grok 93, provider-acp-registry 55, contracts 141, server ACP family 169, every replay file 193, knip passes, typecheck clean.
• Update onto main. Main dropped builtInProviderAdapterDrivers.ts (each driver builds its own adapter), so fx no longer exports a standalone adapter driver. Main also split the replay fixtures into one file per provider, so fx gets FxReplayFixtures.integration.test.ts. Main already writes the replay agent's status atomically, so fx's copy of that fix gave way. fx's Effect helpers now use Effect.fn for main's new prefer-effect-fn lint rule.
• Typecheck: no errors in apps/server, apps/web, apps/mobile, packages/contracts, packages/provider-acp, packages/provider-acp-registry, packages/provider-grok and packages/provider-fx.
• Tests, run in the sandbox:
  • provider-fx: 5. provider-acp: 89. provider-grok: 93. provider-acp-registry: 55. contracts: 139.
  • Server: the fx adapter, the fx, Grok and ACP Registry replay files, the Grok, ACP Registry, Antigravity and shared ACP adapters, ProviderRegistry and settingsSecrets: 169. Every replay file (all providers): 193.
• Checks: vp run knip:check passes. Lint is clean on changed files apart from an unused-helper warning that main also has.
• Live, on this head, against fx 0.0.14 (the latest release) and 0.0.13, signed in to AI Gateway. Real fx drove the T3 orchestrator in a scratch git workspace. Both versions passed all four cases:
  • Provider card: ready, 265 models. Default carries openai/gpt-5.2, the model fx status reports.
  • Supervised: the write asked first. The approved file was written; the declined one wasn't.
  • Auto: a write went through without a prompt. On 0.0.14 that is fx's renamed auto mode, which no release had when this PR was last verified.
  • Models: a picked model (openai/gpt-5.4-nano) ran, then Default.
  • Stop: a running sleep 60 was interrupted, and the next turn completed.
• fx 0.0.14 saves the mode as fx's own default. Each mode T3 sets is written to ~/.fx/settings.json as permission_mode, as docs/user/providers-fx.md already says; 0.0.13 left the file alone. A direct ACP probe on 0.0.14 checked that this stays a default and doesn't change a running session: session A was set to ask, then a second fx acp process set auto, and A's next file write still asked for permission.
• Not run live: the app UI with fx enabled. @agadzik's desktop pass on the original head covered approve/decline, rollback, Stop and the provider card, and its recording below shows the Add provider tile, which this rebuild didn't change.

Before, Add provider has no fx entry. After (recorded by @agadzik on the original head):

https://github.com/user-attachments/assets/5f4e3790-2060-44b4-81a3-59f0e316ca41

Original implementation by @agadzik with fx (spacexai/grok-4.7, reviewed by anthropic/claude-opus-5.5). Takeover by Claude Opus 5.5 in Claude Code, with Claude Fable 5.1 for the implementation rebuild and GPT 6.1 Sol as the second reviewer.

🤖 Generated with Claude Code