[PR #3028] feat(cli): run ordered tool batches in one provider session #5567

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

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3028
Author: @matbrgz
Created: 10/13/2026
Status: 🔄 Open

Base: main ← Head: feat/cli-batch-session


📝 Commits (3)

  • 4c3a7d9 feat(cli): run ordered tool batches in one provider session
  • d934f80 chore(cli): sync batch work with current upstream
  • 4e17ac8 fix(cli): preserve batch ordering and cancellation through finalization

📊 Changes

20 files changed (+1558 additions, -11 deletions)

View changed files

📝 docs/architecture.mermaid (+1 -1)
📝 docs/cli.md (+85 -0)
➕ docs/specs/cli/batch-session/plan.md (+48 -0)
➕ docs/specs/cli/batch-session/spec.md (+31 -0)
➕ docs/specs/cli/batch-session/tasks.md (+16 -0)
📝 package.json (+1 -0)
➕ scripts/verify-real-ghidra-batch.mjs (+187 -0)
📝 src/application/JsonFiles.ts (+8 -1)
📝 src/cli.ts (+16 -2)
➕ src/cli/batchCommands.ts (+106 -0)
📝 src/cli/jsonOutput.ts (+28 -2)
➕ src/cli/runBatchCommand.ts (+231 -0)
📝 src/cliCommandNames.ts (+1 -0)
📝 src/cliOutput.ts (+37 -2)
➕ src/composition/batchSession.ts (+244 -0)
➕ src/domain/batchCalls.ts (+30 -0)
📝 src/domain/flutter/flutterBuildAnalysis.ts (+1 -1)
📝 src/server/http/NodeHttpRequestOwner.ts (+2 -2)
➕ tests/boundary/cli/batchSession.test.ts (+422 -0)
➕ tests/boundary/mcp/batchOrdering.test.ts (+63 -0)

📄 Description

Summary

Fixes #2927. Add rea batch calls.json|- to run an ordered list of MCP tool calls in one production session, amortizing provider import/analysis across queries.

Problem and expected behavior

Separate CLI commands create separate native sessions. Batch opens through the first open_binary call or --target, emits one timed JSONL record per call (or an exclusively created DIR/<id>.json), optionally saves --snapshot, then closes the session. Default/--stop-on-error stops at the first failure; --continue preserves later results and still exits unsuccessfully.

Change and scope

The composition uses the existing server registry and SDK InMemoryTransport, retaining canonical validation, dispatch and Evidence. Successes contain the structured result once with MCP metadata; tool errors keep their original envelope. Input and output IDs are validated before acquiring resources. Timeouts/cancellation drain the canonical tracked server handler before the next call. Blocked stdout writes are abortable; the executable exits only after session cleanup and sends the final control error to stderr. Snapshot/result conflicts and typed filesystem failures are checked before dispatch; stdin and file input share canonical JSON memory admission/immutable arguments.

Contract and boundary impact

  • Semantic owner: batch input at the CLI boundary; one BinarySession and canonical MCP dispatcher own execution.
  • Contribution scope: additive adapter within existing tool/provider authority; a new maintainer scope decision is not applicable.
  • CLI/MCP: new batch command; existing MCP names, schemas and tools remain authoritative.
  • Compatibility: provider-neutral; real native verification used Ghidra 12.1.4 on macOS arm64.
  • Evidence/provenance: original structured values and _meta preserved; error documents retained.
  • Selection/cleanup: explicit target/tool choices; serialized calls; SDK/session/server resources closed, cleanup failures reported.
  • Package: one verifier script entry; ignored metadata regenerated; no build outputs committed.

Expected effects depend on the selected existing tools:

  • 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.

The latter effects require an explicitly selected existing tool and its current authority contract. Batch itself adds no target-execution or network-listener path.

Evidence and regression coverage

22 executed CLI/session, tool-coverage and transport-ordering tests cover file/stdin input, ordering, retained session Evidence, original errors, stop/continue, exclusive files, portable IDs/collisions, incompatible output options and SIGTERM during stdin consumption. Real Ghidra verifies one open/three queries, equivalent normalized results, saved snapshot, immutable target and empty owned runtime. Active native cancellation and other providers/OSes were not newly verified.

Representative output: {"id":"query","tool":"procedure_info","status":"ok","duration_ms":12,"result":{...},"_meta":{...}}.

  • 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 — passed.
  • npm run verify:package — passed, including install/update, CLI, MCP, setup/uninstall and verified empty process lineage.
  • Focused batch/session, CLI tool-coverage and transport-ordering tests — 22 passed on upstream 1629266e3.
  • node scripts/verify-real-ghidra-batch.mjs after build — passed with real Ghidra 12.1.4, darwin/arm64.
  • npm run docs:check — passed; old Greek README drift #3022 is resolved in main.

Measured illustrative run on the updated branch: three separate imports 26.503 s versus batch 8.736 s; user/system CPU 38.32/3.57 s versus 13.44/1.23 s. Host caches were warmed, so this is not a controlled cold/warm speed benchmark. Peak individual RSS: 1.28 GB versus 1.13 GB; process-family peak memory unmeasured. Output-only token estimates: 6,501 versus 6,801 including batch-open/metadata; live model/input-schema tokens unmeasured.

Compatibility, safety, and release

No migration or breaking change. Output is fixed JSONL or per-ID files; global presentation/filter options are rejected. Existing output files are never overwritten. Calls retain existing tool authority and effects; tests used source-owned inputs. Real Windows/Linux/Hopper and snapshot replay are not newly verified. Specifications: docs/specs/cli/batch-session/.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved.
  • The PR has one focused outcome and a conventional title.
  • Related issue is linked.
  • Tests cover changed behavior and meaningful failure paths.
  • Owning docs, contracts, and metadata are updated where needed.
  • Representative user-visible output is included.
  • Final diff reviewed 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/3028 **Author:** [@matbrgz](https://github.com/matbrgz) **Created:** 10/13/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/cli-batch-session` --- ### 📝 Commits (3) - [`4c3a7d9`](https://github.com/morluto/rea/commit/4c3a7d9cbc7ea86fac53737faa861d2e9b2b0873) feat(cli): run ordered tool batches in one provider session - [`d934f80`](https://github.com/morluto/rea/commit/d934f80cfd82ca7684cfbdd4d12a2655aa76dbe9) chore(cli): sync batch work with current upstream - [`4e17ac8`](https://github.com/morluto/rea/commit/4e17ac8fc133478cc20a5d6bebf6e6d6ed49d32d) fix(cli): preserve batch ordering and cancellation through finalization ### 📊 Changes **20 files changed** (+1558 additions, -11 deletions) <details> <summary>View changed files</summary> 📝 `docs/architecture.mermaid` (+1 -1) 📝 `docs/cli.md` (+85 -0) ➕ `docs/specs/cli/batch-session/plan.md` (+48 -0) ➕ `docs/specs/cli/batch-session/spec.md` (+31 -0) ➕ `docs/specs/cli/batch-session/tasks.md` (+16 -0) 📝 `package.json` (+1 -0) ➕ `scripts/verify-real-ghidra-batch.mjs` (+187 -0) 📝 `src/application/JsonFiles.ts` (+8 -1) 📝 `src/cli.ts` (+16 -2) ➕ `src/cli/batchCommands.ts` (+106 -0) 📝 `src/cli/jsonOutput.ts` (+28 -2) ➕ `src/cli/runBatchCommand.ts` (+231 -0) 📝 `src/cliCommandNames.ts` (+1 -0) 📝 `src/cliOutput.ts` (+37 -2) ➕ `src/composition/batchSession.ts` (+244 -0) ➕ `src/domain/batchCalls.ts` (+30 -0) 📝 `src/domain/flutter/flutterBuildAnalysis.ts` (+1 -1) 📝 `src/server/http/NodeHttpRequestOwner.ts` (+2 -2) ➕ `tests/boundary/cli/batchSession.test.ts` (+422 -0) ➕ `tests/boundary/mcp/batchOrdering.test.ts` (+63 -0) </details> ### 📄 Description ## Summary Fixes #2927. Add `rea batch calls.json|-` to run an ordered list of MCP tool calls in one production session, amortizing provider import/analysis across queries. ## Problem and expected behavior Separate CLI commands create separate native sessions. Batch opens through the first `open_binary` call or `--target`, emits one timed JSONL record per call (or an exclusively created `DIR/<id>.json`), optionally saves `--snapshot`, then closes the session. Default/`--stop-on-error` stops at the first failure; `--continue` preserves later results and still exits unsuccessfully. ## Change and scope The composition uses the existing server registry and SDK InMemoryTransport, retaining canonical validation, dispatch and Evidence. Successes contain the structured result once with MCP metadata; tool errors keep their original envelope. Input and output IDs are validated before acquiring resources. Timeouts/cancellation drain the canonical tracked server handler before the next call. Blocked stdout writes are abortable; the executable exits only after session cleanup and sends the final control error to stderr. Snapshot/result conflicts and typed filesystem failures are checked before dispatch; stdin and file input share canonical JSON memory admission/immutable arguments. ## Contract and boundary impact - Semantic owner: batch input at the CLI boundary; one BinarySession and canonical MCP dispatcher own execution. - Contribution scope: additive adapter within existing tool/provider authority; a new maintainer scope decision is not applicable. - CLI/MCP: new `batch` command; existing MCP names, schemas and tools remain authoritative. - Compatibility: provider-neutral; real native verification used Ghidra 12.1.4 on macOS arm64. - Evidence/provenance: original structured values and `_meta` preserved; error documents retained. - Selection/cleanup: explicit target/tool choices; serialized calls; SDK/session/server resources closed, cleanup failures reported. - Package: one verifier script entry; ignored metadata regenerated; no build outputs committed. Expected effects depend on the selected existing tools: - [x] Read existing files or captured data. - [x] Launch or attach to a process. - [x] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. - [x] Contact network services. The latter effects require an explicitly selected existing tool and its current authority contract. Batch itself adds no target-execution or network-listener path. ## Evidence and regression coverage 22 executed CLI/session, tool-coverage and transport-ordering tests cover file/stdin input, ordering, retained session Evidence, original errors, stop/continue, exclusive files, portable IDs/collisions, incompatible output options and SIGTERM during stdin consumption. Real Ghidra verifies one open/three queries, equivalent normalized results, saved snapshot, immutable target and empty owned runtime. Active native cancellation and other providers/OSes were not newly verified. Representative output: `{"id":"query","tool":"procedure_info","status":"ok","duration_ms":12,"result":{...},"_meta":{...}}`. - [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` — passed. - `npm run verify:package` — passed, including install/update, CLI, MCP, setup/uninstall and verified empty process lineage. - Focused batch/session, CLI tool-coverage and transport-ordering tests — 22 passed on upstream `1629266e3`. - `node scripts/verify-real-ghidra-batch.mjs` after build — passed with real Ghidra 12.1.4, darwin/arm64. - `npm run docs:check` — passed; old Greek README drift #3022 is resolved in main. Measured illustrative run on the updated branch: three separate imports 26.503 s versus batch 8.736 s; user/system CPU 38.32/3.57 s versus 13.44/1.23 s. Host caches were warmed, so this is not a controlled cold/warm speed benchmark. Peak individual RSS: 1.28 GB versus 1.13 GB; process-family peak memory unmeasured. Output-only token estimates: 6,501 versus 6,801 including batch-open/metadata; live model/input-schema tokens unmeasured. ## Compatibility, safety, and release No migration or breaking change. Output is fixed JSONL or per-ID files; global presentation/filter options are rejected. Existing output files are never overwritten. Calls retain existing tool authority and effects; tests used source-owned inputs. Real Windows/Linux/Hopper and snapshot replay are not newly verified. Specifications: `docs/specs/cli/batch-session/`. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved. - [x] The PR has one focused outcome and a conventional title. - [x] Related issue is linked. - [x] Tests cover changed behavior and meaningful failure paths. - [x] Owning docs, contracts, and metadata are updated where needed. - [x] Representative user-visible output is included. - [x] Final diff reviewed 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#5567
No description provided.