[PR #4427] feat(setup): add FutureOS client support #6234

Open
opened 2026-10-31 01:12:53 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4427
Author: @huichen
Created: 10/16/2026
Status: 🔄 Open

Base: main ← Head: feat/future-setup-client


📝 Commits (2)

  • 67100d6 feat(setup): add FutureOS client support
  • 19aaaa4 docs(future): document the per-call connection the FutureOS CLI group gives REA

📊 Changes

7 files changed (+407 additions, -2 deletions)

View changed files

📝 docs/client-configuration.md (+69 -0)
📝 docs/installation.md (+3 -0)
📝 src/application/ClientConfigurationDocument.ts (+59 -2)
📝 src/application/SetupClientConfiguration.ts (+12 -0)
📝 src/application/SupportedClients.ts (+24 -0)
📝 tests/boundary/filesystem/clientLifecycle.test.ts (+1 -0)
➕ tests/boundary/filesystem/futureClientConfiguration.test.ts (+239 -0)

📄 Description

Summary

Adds FutureOS as a supported setup client so rea setup, rea doctor and
rea uninstall can create, report and remove the rea MCP registration in the
FutureOS server list, instead of the user hand-editing ~/.future/mcp.json.

Fixes #4426.

Problem and expected behavior

FutureOS was not among REA's supported clients. Its server list is close to
reachable with an existing dialect but not actually compatible with any of them:
FutureOS reads a servers table, denies unknown fields at both the root and the
entry, parses strictly, and defaults enabled to true. Registering with the
shape REA writes for VS Code/OMP/Pi would add type: "stdio", which makes
FutureOS refuse the whole file — REA would report the registration as aligned
while FutureOS loaded no servers at all.

Expected behavior: rea setup --client future writes servers.rea into
$FUTURE_HOME/mcp.json (~/.future/mcp.json by default), preserving other
servers; rea doctor --client future reports it; rea uninstall removes only
REA's entry and leaves a backup.

Change and scope

  • SupportedClients.ts: a future/FutureOS definition whose home resolves
    FUTURE_HOME only when it is absolute, matching FutureOS's own resolver. An
    empty or relative override falls back to ~/.future; resolving a relative
    value against REA's working directory would write a file FutureOS never reads.
  • ClientConfigurationDocument.ts: a future dialect. servers as the table
    key, strict JSON.parse with the empty-file fallback (no comments, trailing
    commas or BOM), and an entry of command/args/env/enabled with no
    type. A file FutureOS would reject is refused with a repair instruction
    rather than certified as aligned.
  • SetupClientConfiguration.ts: cwd, a caller-owned working directory for the
    server process, survives a launcher refresh. enabled: false on REA's entry is
    reported as stale and re-enabled on the next setup, following ZCode's
    enable: false repair rather than preserving a disabled entry.

Not included: a skillPath for this client, so --skill keeps installing
into the shared ~/.agents/skills. That is deliberate and is the one open
decision (see below). No analysis-provider or target-facing change.

Scope decision requested. Which skill root REA should own for FutureOS — the
shared ~/.agents/skills, or the client's app root <future home>/agent/skills,
which FutureOS resolves first and which alone follows FUTURE_HOME. This is the
same question #4402 is deciding for
DeepSeek Harness, so one answer should cover both; this branch takes the shared
root because that is what works today and what kimi, pi, qwen_code, codex, omp
and grok_build do. The precedent for adding a client this way is
#3041 (WorkBuddy,
#3040) — that one was a plain
definition because WorkBuddy reuses the json dialect; the new dialect is the
part that needs review here.

Contract and boundary impact

  • Semantic owner and earliest changed stage: client identity remains owned by
    SUPPORTED_CLIENT_DEFINITIONS; the document shape is owned by
    parseClientConfiguration/serializeClientConfiguration, extended with one
    dialect. Earliest changed stage is setup planning (a new --client value and
    a new detection marker).
  • Contribution scope fit and linked maintainer decision: a setup client
    definition, already an established contribution shape. The skill-destination
    scope decision above is requested, and #4402 covers the same boundary.
  • CLI and MCP/tool-catalog contract: adds the future value to --client,
    --skill-client and doctor --client, derived from the definition array. No
    tool contract change.
  • Provider, bridge, target-format, or platform compatibility: none.
  • Evidence, artifact, provenance, or reconstruction contract: none.
  • Target selection, authority, upstream behavior, and cleanup details: writes one
    user-owned configuration file and (with --skill) a skill directory; no target
    execution, no process control. No quitBeforeSetup: FutureOS loads the list on
    demand per CLI call. Uninstall removes only REA's entry and keeps a backup.
  • Generated metadata: docs/public/product-catalog.json regenerated (one new
    setup_clients entry); skills/ untouched.

Expected effects (known effects).

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: tests/boundary/filesystem/futureClientConfiguration.test.ts
    (location rules including relative/empty FUTURE_HOME, the exact entry shape,
    preserved cwd and sibling servers, disabled-entry staleness and repair,
    uninstall, marker detection, and the documents FutureOS rejects). The detection
    list in clientLifecycle.test.ts gains the client.

  • Base reproduction or other evidence: on the base revision, FutureOS is not a
    supported client (rea setup --client future is rejected as an unsupported
    agent integration) and no dialect produces a loadable entry, which the
    rejection tests below pin down.

  • User-visible CLI/MCP output: see validation below.

  • Remaining proof gaps: no full FutureOS agent session has driven a REA tool; no
    Windows run; npm run check:pr was not run.

  • Observed, derived, and inferred claims remain distinguishable.

  • Artifact identity, source provenance, and failed attempts remain preserved.

  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm run check:fast — passed (typecheck, lint, pre-push check).
  • npm run docs:check — passed, including the generated product catalog and
    documentation fact checks.
  • npm run build:cached — passed.
  • All 35 client/setup boundary and acceptance suites with the product-catalog
    check — 567 tests passed.
  • rea setup --client future --yes in an isolated HOME — wrote
    {"servers":{"rea":{"command":"…/rea.mjs","args":["mcp"],"enabled":true}}}.
  • future mcp list with FUTURE_HOME pointed at that home — named the entry;
    future mcp tools rea returned REA's advertised 207-tool catalog;
    future mcp call rea list_documents reached REA and returned REA's own
    target_unavailable payload.
  • rea doctor --client future — registration:future healthy;
    rea setup --all-detected --dry-run — detected the client.
  • rea uninstall — removed only the rea entry, left mcp.json.rea.backup,
    and future mcp list then reported no configured servers.
  • The real FutureOS CLI was also used to establish the contract: it refused a
    root key other than servers, an entry key outside the five, a comment, a
    trailing comma and a BOM, and treated an empty file as "no servers
    configured".

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable; no provider path
    changes. macOS 15 (arm64) only.
  • Package or release metadata impact: the client is not in the published
    rea-agents@6.5.0 package, so the supported-agents note records that it needs
    a later release.
  • Security, privacy, process, or containment review: writes one user config file
    (mode 0600, atomic, with a backup) and refuses files FutureOS itself would
    reject instead of overwriting them.

Author readiness

Human owner:

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4427 **Author:** [@huichen](https://github.com/huichen) **Created:** 10/16/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/future-setup-client` --- ### 📝 Commits (2) - [`67100d6`](https://github.com/morluto/rea/commit/67100d6db8ff39a98524e3b9f51f46aabe5e3d6a) feat(setup): add FutureOS client support - [`19aaaa4`](https://github.com/morluto/rea/commit/19aaaa4ae8db3025aa81b225b81763815abc56af) docs(future): document the per-call connection the FutureOS CLI group gives REA ### 📊 Changes **7 files changed** (+407 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `docs/client-configuration.md` (+69 -0) 📝 `docs/installation.md` (+3 -0) 📝 `src/application/ClientConfigurationDocument.ts` (+59 -2) 📝 `src/application/SetupClientConfiguration.ts` (+12 -0) 📝 `src/application/SupportedClients.ts` (+24 -0) 📝 `tests/boundary/filesystem/clientLifecycle.test.ts` (+1 -0) ➕ `tests/boundary/filesystem/futureClientConfiguration.test.ts` (+239 -0) </details> ### 📄 Description ## Summary Adds FutureOS as a supported setup client so `rea setup`, `rea doctor` and `rea uninstall` can create, report and remove the `rea` MCP registration in the FutureOS server list, instead of the user hand-editing `~/.future/mcp.json`. Fixes #4426. ## Problem and expected behavior FutureOS was not among REA's supported clients. Its server list is close to reachable with an existing dialect but not actually compatible with any of them: FutureOS reads a `servers` table, denies unknown fields at both the root and the entry, parses strictly, and defaults `enabled` to true. Registering with the shape REA writes for VS Code/OMP/Pi would add `type: "stdio"`, which makes FutureOS refuse the whole file — REA would report the registration as `aligned` while FutureOS loaded no servers at all. Expected behavior: `rea setup --client future` writes `servers.rea` into `$FUTURE_HOME/mcp.json` (`~/.future/mcp.json` by default), preserving other servers; `rea doctor --client future` reports it; `rea uninstall` removes only REA's entry and leaves a backup. ## Change and scope - `SupportedClients.ts`: a `future`/`FutureOS` definition whose home resolves `FUTURE_HOME` only when it is absolute, matching FutureOS's own resolver. An empty or relative override falls back to `~/.future`; resolving a relative value against REA's working directory would write a file FutureOS never reads. - `ClientConfigurationDocument.ts`: a `future` dialect. `servers` as the table key, strict `JSON.parse` with the empty-file fallback (no comments, trailing commas or BOM), and an entry of `command`/`args`/`env`/`enabled` with no `type`. A file FutureOS would reject is refused with a repair instruction rather than certified as aligned. - `SetupClientConfiguration.ts`: `cwd`, a caller-owned working directory for the server process, survives a launcher refresh. `enabled: false` on REA's entry is reported as stale and re-enabled on the next setup, following ZCode's `enable: false` repair rather than preserving a disabled entry. **Not included:** a `skillPath` for this client, so `--skill` keeps installing into the shared `~/.agents/skills`. That is deliberate and is the one open decision (see below). No analysis-provider or target-facing change. **Scope decision requested.** Which skill root REA should own for FutureOS — the shared `~/.agents/skills`, or the client's app root `<future home>/agent/skills`, which FutureOS resolves first and which alone follows `FUTURE_HOME`. This is the same question [#4402](https://github.com/morluto/rea/issues/4402) is deciding for DeepSeek Harness, so one answer should cover both; this branch takes the shared root because that is what works today and what kimi, pi, qwen_code, codex, omp and grok_build do. The precedent for adding a client this way is [#3041](https://github.com/morluto/rea/pull/3041) (WorkBuddy, [#3040](https://github.com/morluto/rea/issues/3040)) — that one was a plain definition because WorkBuddy reuses the `json` dialect; the new dialect is the part that needs review here. ## Contract and boundary impact - Semantic owner and earliest changed stage: client identity remains owned by `SUPPORTED_CLIENT_DEFINITIONS`; the document shape is owned by `parseClientConfiguration`/`serializeClientConfiguration`, extended with one dialect. Earliest changed stage is setup planning (a new `--client` value and a new detection marker). - Contribution scope fit and linked maintainer decision: a setup client definition, already an established contribution shape. The skill-destination scope decision above is requested, and #4402 covers the same boundary. - CLI and MCP/tool-catalog contract: adds the `future` value to `--client`, `--skill-client` and `doctor --client`, derived from the definition array. No tool contract change. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: none. - Target selection, authority, upstream behavior, and cleanup details: writes one user-owned configuration file and (with `--skill`) a skill directory; no target execution, no process control. No `quitBeforeSetup`: FutureOS loads the list on demand per CLI call. Uninstall removes only REA's entry and keeps a backup. - Generated metadata: `docs/public/product-catalog.json` regenerated (one new `setup_clients` entry); `skills/` untouched. Expected effects (known effects). - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: `tests/boundary/filesystem/futureClientConfiguration.test.ts` (location rules including relative/empty `FUTURE_HOME`, the exact entry shape, preserved `cwd` and sibling servers, disabled-entry staleness and repair, uninstall, marker detection, and the documents FutureOS rejects). The detection list in `clientLifecycle.test.ts` gains the client. - Base reproduction or other evidence: on the base revision, FutureOS is not a supported client (`rea setup --client future` is rejected as an unsupported agent integration) and no dialect produces a loadable entry, which the rejection tests below pin down. - User-visible CLI/MCP output: see validation below. - Remaining proof gaps: no full FutureOS agent session has driven a REA tool; no Windows run; `npm run check:pr` was not run. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run check:fast` — passed (typecheck, lint, pre-push check). - `npm run docs:check` — passed, including the generated product catalog and documentation fact checks. - `npm run build:cached` — passed. - All 35 client/setup boundary and acceptance suites with the product-catalog check — 567 tests passed. - `rea setup --client future --yes` in an isolated `HOME` — wrote `{"servers":{"rea":{"command":"…/rea.mjs","args":["mcp"],"enabled":true}}}`. - `future mcp list` with `FUTURE_HOME` pointed at that home — named the entry; `future mcp tools rea` returned REA's advertised 207-tool catalog; `future mcp call rea list_documents` reached REA and returned REA's own `target_unavailable` payload. - `rea doctor --client future` — `registration:future` healthy; `rea setup --all-detected --dry-run` — detected the client. - `rea uninstall` — removed only the `rea` entry, left `mcp.json.rea.backup`, and `future mcp list` then reported no configured servers. - The real FutureOS CLI was also used to establish the contract: it refused a root key other than `servers`, an entry key outside the five, a comment, a trailing comma and a BOM, and treated an empty file as "no servers configured". ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: not applicable; no provider path changes. macOS 15 (arm64) only. - Package or release metadata impact: the client is not in the published `rea-agents@6.5.0` package, so the supported-agents note records that it needs a later release. - Security, privacy, process, or containment review: writes one user config file (mode 0600, atomic, with a backup) and refuses files FutureOS itself would reject instead of overwriting them. ## Author readiness Human owner: <!-- @GitHub-handle --> - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#6234
No description provided.