morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #4426] [Feature] Support FutureOS as a setup client #1756

New issue

Open

opened 2026-10-16 21:09:53 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:09:53 +00:00

Owner

Originally created by @huichen on GitHub (Oct 16, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/4426

Before submitting

I searched the open and closed issues and pull requests for a related proposal.
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This request does not include credentials, private samples, or sensitive target data.

Area

MCP or agent integration

Current limitation

FutureOS is not among REA's supported setup clients, so a FutureOS user has to
hand-edit the server list and copy the skill by hand. rea setup, rea doctor
and rea uninstall are unaware of the client, so the registration cannot be
created, refreshed or removed through the managed lifecycle.

The client is close to reachable already but not quite with any existing
dialect, which is why this needs a scope decision rather than only a new entry in
SUPPORTED_CLIENT_DEFINITIONS: FutureOS reads its own servers table, denies
unknown fields at both the root and the entry, parses strictly, and defaults
enabled to true. An entry carrying a type: "stdio" discriminator, copied from
the shape REA writes for VS Code/OMP/Pi, makes FutureOS refuse the whole file
rather than that one entry — so writing a registration that REA reports as
aligned can leave FutureOS loading no servers at all.

Use cases

rea setup --client future (or plain rea setup with ~/.future present)
installs the rea MCP entry plus the bundled skill for FutureOS.
rea doctor --client future reports the registration; rea uninstall removes
it and leaves a backup, like every other supported client.
A FutureOS session reaches REA through future mcp call rea <tool> from its
shell tool. FutureOS's agent has no MCP client of its own, so this CLI group
is the only route; the bundled skill already documents the CLI route.

Desired outcome and success criteria

rea setup --client future writes servers.rea into $FUTURE_HOME/mcp.json
(~/.future/mcp.json when FUTURE_HOME is unset), preserving other servers and
keeping the entry to the fields FutureOS accepts (command, args, env,
cwd, enabled). Setup refuses a file FutureOS would reject instead of
certifying a registration it cannot load. rea doctor reports the registration
and rea uninstall removes only REA's entry, leaving a backup. The
supported-agents table lists the client.

One open scope question, below: which skill root setup should own for FutureOS.

Expected interaction with targets

Read existing files or captured data
Write or change files/configuration

Target and scope details (optional)

No analysis provider or target-facing behavior changes: setup writes one
user-owned file and, when --skill applies, a skill directory. The
FUTURE_HOME resolution rule matters here — FutureOS ignores an empty or
relative override, so REA must not resolve a relative value against its own
working directory and write a file FutureOS never reads.

Scope question (one decision). Which skill destination should REA own for
FutureOS: the shared ~/.agents/skills, or the client's own app root
<future home>/agent/skills? This is the same question #4402
asks for DeepSeek Harness, and one answer should cover both: FutureOS resolves
~/.future/agent/skills first and ~/.agents/skills second, and only the
~/.future one follows FUTURE_HOME. Leaving skillPath unset keeps the shared
root, which is what already works today and what kimi, pi, qwen_code, codex, omp
and grok_build do, at the cost of a FutureOS-only install also changing every
shared-root client's catalog. My branch currently leaves it unset; I have no
measurement for either option and will follow whatever #4402 decides.

Verification available so far

I have a prototype or observed results

Verification details (optional)

A working branch adds a future entry to SUPPORTED_CLIENT_DEFINITIONS plus a
client dialect, with boundary tests for the location rules, the exact entry
shape, a disabled entry, uninstall, and the documents FutureOS cannot load.

Observed on macOS 15 (arm64), REA 6.5.0, a locally installed FutureOS CLI, in
an isolated HOME:

rea setup --client future --yes 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 reported registration:future healthy, and
rea setup --all-detected --dry-run detected the client.
rea uninstall removed only the rea entry and left mcp.json.rea.backup.
FutureOS refused, as expected: a root key other than servers, an entry key
other than the five above, a comment, a trailing comma, and a BOM. An empty
file is the state before the first server, not an error.

Ran locally: npm run check:fast, npm run docs:check, and the affected
boundary suites. Not run: npm run check:pr, and no full FutureOS agent
session has driven a REA tool yet.

Source-derived, not observed here: FutureOS's parser and path rules, from the
source links below at main@104b9cd. I have not run FutureOS on Windows.

Alternatives considered

Hand-editing ~/.future/mcp.json — the current workaround; setup, doctor and
uninstall stay unaware and the skill has to be copied by hand.
future mcp add rea --command <rea> --arg mcp — already works today for the
MCP entry, and is what my verification used, but it is a FutureOS-side command:
it does not refresh a stale REA launcher, install or update the skill, or
appear in rea doctor/rea uninstall.
Reusing an existing dialect (vscode, omp, pi, json) — the type
discriminator and any other extra key make FutureOS reject the whole file, so
these would produce a registration that only looks aligned.

Possible direction

Add a future entry (configPath <future home>/mcp.json, marker the future
home, format: "future") and a future dialect alongside the existing ones:
servers as the table key, strict JSON with an empty-file fallback, and an entry
of command/args/env/enabled with no type. Preserve a caller-chosen
cwd across a refresh; treat enabled: false on REA's entry as stale and
re-enable it on the next setup, the way ZCode's enable: false is repaired
today. 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 dialect is the part
of this proposal that needs review here.

The FUTURE_HOME rule should be answered deliberately: FutureOS ignores an empty
or relative override, so REA should fall back to ~/.future in both cases rather
than resolving a relative value.

References

FutureOS is a public MIT project, so its contract is verifiable rather than
inferred: https://github.com/futuregene/future-os

Server list and its strict parser (McpConfig denies unknown fields;
config_path() is <future home>/mcp.json):
cli/src/commands/mcp_servers.rs
Entry fields (ServerSpec denies unknown fields; command, args, env,
cwd, enabled, the last defaulting to true):
cli/src/commands/mcp_client.rs
FUTURE_HOME resolution (empty and non-absolute values ignored):
packages/rpc/src/home.rs
Skill roots and their order (~/.future/agent/skills then
~/.agents/skills; only the first follows FUTURE_HOME):
agent/src/skills/mod.rs
User-facing CLI documentation:
docs/wiki/en/CLI.md

Related REA issues: #4402 (the same
skill-root question for DeepSeek Harness), #2490
(CodeBuddy) and #3243 (FreeBuff)
as further clients awaiting a definition.

Originally created by @huichen on GitHub (Oct 16, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/4426 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal. - [x] I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. - [x] This request does not include credentials, private samples, or sensitive target data. ### Area MCP or agent integration ### Current limitation FutureOS is not among REA's supported setup clients, so a FutureOS user has to hand-edit the server list and copy the skill by hand. `rea setup`, `rea doctor` and `rea uninstall` are unaware of the client, so the registration cannot be created, refreshed or removed through the managed lifecycle. The client is close to reachable already but not quite with any existing dialect, which is why this needs a scope decision rather than only a new entry in `SUPPORTED_CLIENT_DEFINITIONS`: FutureOS reads its own `servers` table, denies unknown fields at both the root and the entry, parses strictly, and defaults `enabled` to true. An entry carrying a `type: "stdio"` discriminator, copied from the shape REA writes for VS Code/OMP/Pi, makes FutureOS refuse the whole file rather than that one entry — so writing a registration that REA reports as `aligned` can leave FutureOS loading no servers at all. ### Use cases - `rea setup --client future` (or plain `rea setup` with `~/.future` present) installs the `rea` MCP entry plus the bundled skill for FutureOS. - `rea doctor --client future` reports the registration; `rea uninstall` removes it and leaves a backup, like every other supported client. - A FutureOS session reaches REA through `future mcp call rea <tool>` from its `shell` tool. FutureOS's agent has no MCP client of its own, so this CLI group is the only route; the bundled skill already documents the CLI route. ### Desired outcome and success criteria `rea setup --client future` writes `servers.rea` into `$FUTURE_HOME/mcp.json` (`~/.future/mcp.json` when `FUTURE_HOME` is unset), preserving other servers and keeping the entry to the fields FutureOS accepts (`command`, `args`, `env`, `cwd`, `enabled`). Setup refuses a file FutureOS would reject instead of certifying a registration it cannot load. `rea doctor` reports the registration and `rea uninstall` removes only REA's entry, leaving a backup. The supported-agents table lists the client. One open scope question, below: which skill root setup should own for FutureOS. ### Expected interaction with targets - Read existing files or captured data - Write or change files/configuration ### Target and scope details (optional) No analysis provider or target-facing behavior changes: setup writes one user-owned file and, when `--skill` applies, a skill directory. The `FUTURE_HOME` resolution rule matters here — FutureOS ignores an empty or relative override, so REA must not resolve a relative value against its own working directory and write a file FutureOS never reads. **Scope question (one decision).** Which skill destination should REA own for FutureOS: the shared `~/.agents/skills`, or the client's own app root `<future home>/agent/skills`? This is the same question [#4402](https://github.com/morluto/rea/issues/4402) asks for DeepSeek Harness, and one answer should cover both: FutureOS resolves `~/.future/agent/skills` first and `~/.agents/skills` second, and only the `~/.future` one follows `FUTURE_HOME`. Leaving `skillPath` unset keeps the shared root, which is what already works today and what kimi, pi, qwen_code, codex, omp and grok_build do, at the cost of a FutureOS-only install also changing every shared-root client's catalog. My branch currently leaves it unset; I have no measurement for either option and will follow whatever #4402 decides. ### Verification available so far I have a prototype or observed results ### Verification details (optional) A working branch adds a `future` entry to `SUPPORTED_CLIENT_DEFINITIONS` plus a client dialect, with boundary tests for the location rules, the exact entry shape, a disabled entry, uninstall, and the documents FutureOS cannot load. **Observed** on macOS 15 (arm64), REA 6.5.0, a locally installed FutureOS CLI, in an isolated `HOME`: - `rea setup --client future --yes` 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` reported `registration:future` healthy, and `rea setup --all-detected --dry-run` detected the client. - `rea uninstall` removed only the `rea` entry and left `mcp.json.rea.backup`. - FutureOS refused, as expected: a root key other than `servers`, an entry key other than the five above, a comment, a trailing comma, and a BOM. An empty file is the state before the first server, not an error. **Ran locally:** `npm run check:fast`, `npm run docs:check`, and the affected boundary suites. **Not run:** `npm run check:pr`, and no full FutureOS agent session has driven a REA tool yet. **Source-derived, not observed here:** FutureOS's parser and path rules, from the source links below at `main@104b9cd`. I have not run FutureOS on Windows. ### Alternatives considered - Hand-editing `~/.future/mcp.json` — the current workaround; setup, doctor and uninstall stay unaware and the skill has to be copied by hand. - `future mcp add rea --command <rea> --arg mcp` — already works today for the MCP entry, and is what my verification used, but it is a FutureOS-side command: it does not refresh a stale REA launcher, install or update the skill, or appear in `rea doctor`/`rea uninstall`. - Reusing an existing dialect (`vscode`, `omp`, `pi`, `json`) — the `type` discriminator and any other extra key make FutureOS reject the whole file, so these would produce a registration that only looks aligned. ### Possible direction Add a `future` entry (`configPath` `<future home>/mcp.json`, marker the future home, `format: "future"`) and a `future` dialect alongside the existing ones: `servers` as the table key, strict JSON with an empty-file fallback, and an entry of `command`/`args`/`env`/`enabled` with no `type`. Preserve a caller-chosen `cwd` across a refresh; treat `enabled: false` on REA's entry as stale and re-enable it on the next setup, the way ZCode's `enable: false` is repaired today. 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 dialect is the part of this proposal that needs review here. The `FUTURE_HOME` rule should be answered deliberately: FutureOS ignores an empty or relative override, so REA should fall back to `~/.future` in both cases rather than resolving a relative value. ### References FutureOS is a public MIT project, so its contract is verifiable rather than inferred: <https://github.com/futuregene/future-os> - Server list and its strict parser (`McpConfig` denies unknown fields; `config_path()` is `<future home>/mcp.json`): [cli/src/commands/mcp_servers.rs](https://github.com/futuregene/future-os/blob/104b9cd195d1d6afbaf81dccfc99b3c2278dd7f9/cli/src/commands/mcp_servers.rs) - Entry fields (`ServerSpec` denies unknown fields; `command`, `args`, `env`, `cwd`, `enabled`, the last defaulting to true): [cli/src/commands/mcp_client.rs](https://github.com/futuregene/future-os/blob/104b9cd195d1d6afbaf81dccfc99b3c2278dd7f9/cli/src/commands/mcp_client.rs) - `FUTURE_HOME` resolution (empty and non-absolute values ignored): [packages/rpc/src/home.rs](https://github.com/futuregene/future-os/blob/104b9cd195d1d6afbaf81dccfc99b3c2278dd7f9/packages/rpc/src/home.rs) - Skill roots and their order (`~/.future/agent/skills` then `~/.agents/skills`; only the first follows `FUTURE_HOME`): [agent/src/skills/mod.rs](https://github.com/futuregene/future-os/blob/104b9cd195d1d6afbaf81dccfc99b3c2278dd7f9/agent/src/skills/mod.rs) - User-facing CLI documentation: [docs/wiki/en/CLI.md](https://github.com/futuregene/future-os/blob/104b9cd195d1d6afbaf81dccfc99b3c2278dd7f9/docs/wiki/en/CLI.md) Related REA issues: [#4402](https://github.com/morluto/rea/issues/4402) (the same skill-root question for DeepSeek Harness), [#2490](https://github.com/morluto/rea/issues/2490) (CodeBuddy) and [#3243](https://github.com/morluto/rea/issues/3243) (FreeBuff) as further clients awaiting a definition.

bsakaguchi referenced this issue

2026-10-31 00:55:09 +00:00

[PR #1756] [MERGED] fix(process): aggregate incomplete trace-spec diagnostics #4796

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#1756

No description provided.

Rows
Columns