countinghouse

Direct peer channels

This document describes the direct-peer-channel path: worker threads that need to call each other’s devices connect directly over a MessageChannel port pair instead of routing every call through the main thread. It is the default since 7.1.0 and was opt-in (--directPeerChannels) before; --no-directPeerChannels restores main-thread routing. It also carries the benchmark numbers that justify building it — the only public performance numbers this project should cite for cross-worker calls going forward (see “Retired numbers” at the end).

All three benchmark tables below were re-measured together on 2026-10-26, on a 2-vCPU VMware guest (Intel Core i7-6600U @ 2.60 GHz, 7.2 GB), Node v24.21.0, at commit 3d9599d, otherwise idle, with three independent runs per script (--runs 3). Raw output: perf/results/2026-10-26/.

The problem

Every device module runs in its own worker_threads.Worker (docs/security-model.md covers why). When one module calls another’s action — ServiceClient.invoke(), the mechanism docs/composite-tools.md’s composite-demo uses — the call does not go directly from worker A to worker B. It goes A → main thread → B → main thread → A: four postMessage hops, two of them through the main thread’s own event loop. Every cross-module call in the system serializes through that one thread, regardless of how many workers are actually running.

The fix

On the direct path, the first time worker A calls a device hosted by worker B, the main thread still brokers the connection — it resolves which worker hosts the target device, checks that A’s module is authorized to call it, and hands each side one end of a new MessageChannel. Every call after that goes directly between A and B: two postMessage hops, zero main-thread involvement. The port is cached and reused for later calls to the same worker (even for a different device hosted there), and invalidated automatically if that worker reloads, unloads, or crashes — see design-decisions.md (D1–D5) for the full design and docs/cross-cutting-matrix.md’s two “Direct peer channel” rows for exactly which cross-cutting guarantees (authorization, metering, rate limiting, timeouts) apply on this path versus the main-thread-routed one.

ServiceClient.invoke()’s external contract — callback signature, error shape, timeout behavior — is unchanged either way; the flag only changes which internal path a cross-worker call takes.

What the default means for an operator

Making this path the default (7.1.0) is a trade, not a free speed-up, and the two paths do not check the same things at the same moments:

An operator who needs per-hop authorization, or revocation with no window at all, should run with --no-directPeerChannels. The benchmark sections below say how little that costs for most workloads.

Benchmark: main-thread-routed vs. direct peer channel

Produced by perf/direct-peer-channels-perf.js --runs 3 on a 2-vCPU VMware guest (Intel Core i7-6600U @ 2.60 GHz, 7.2 GB), Node v24.21.0, at commit 3d9599d, module sandbox audit (the default). Two purpose-built fixture modules (pre-installed-packages/perf-caller-demo, perf-callee-demo) round-trip a payload of a given size through ServiceClient.invoke(); “hop latency” below is measured server-side around just that call (excludes HTTP/session overhead on either side of it), and throughput is measured client-side across the full HTTP round trip (that overhead is identical in both conditions, so it doesn’t distort the comparison). 150 requests per cell. Each of the three runs is a fresh process with a fresh server per condition; every cell is the median of the three runs’ values, with the [min–max] range across runs.

Every number below, and every comparative statement about it, is copy-pasted verbatim from that run of perf/direct-peer-channels-perf.js (which computes the comparison itself — see that file’s header comment for why hand-written summaries are not allowed here anymore: an earlier version of this section claimed “1.3–7×” and “match or beat throughput on 7 of 9”, and both were wrong against the very table they described). A cell counts as faster or slower only when the two ranges across runs do not overlap; otherwise it is within noise, whatever the medians say.

Payload Concurrency Main-thread-routed p50 Main-thread-routed p99 Main-thread-routed req/s Direct peer channel p50 Direct peer channel p99 Direct peer channel req/s
1KB 1 1.41 [1.40–1.46] ms 4.40 [3.80–5.11] ms 169 [168–171] 1.38 [1.38–1.40] ms 5.04 [3.10–5.43] ms 204 [181–204]
1KB 16 9.54 [8.37–12.8] ms 24.7 [21.3–27.2] ms 409 [398–413] 9.50 [9.06–11.6] ms 28.2 [20.2–39.6] ms 469 [402–476]
1KB 64 39.2 [27.6–51.7] ms 68.8 [50.5–77.6] ms 476 [463–517] 45.9 [27.1–48.7] ms 70.0 [54.9–96.2] ms 620 [498–644]
100KB 1 1.53 [1.45–1.53] ms 6.98 [5.27–8.20] ms 202 [193–219] 1.49 [1.34–1.55] ms 5.80 [4.09–8.84] ms 203 [196–223]
100KB 16 10.8 [10.4–11.3] ms 22.5 [22.5–33.7] ms 502 [426–575] 10.2 [8.97–10.3] ms 25.0 [17.7–30.6] ms 543 [445–591]
100KB 64 32.2 [28.1–33.5] ms 43.3 [42.9–53.2] ms 636 [573–773] 43.0 [36.3–60.4] ms 67.3 [64.0–120] ms 704 [543–789]
1MB 1 7.60 [7.56–7.89] ms 17.1 [16.2–18.1] ms 93 [91–94] 5.06 [5.06–5.14] ms 14.8 [13.0–15.1] ms 121 [118–122]
1MB 16 77.1 [61.6–80.9] ms 125 [115–151] ms 123 [123–138] 59.1 [58.9–60.1] ms 115 [110–140] ms 156 [146–160]
1MB 64 303 [299–335] ms 361 [360–373] ms 130 [122–131] 235 [214–253] ms 380 [358–402] ms 190 [178–195]

Noise floor: the largest spread of any single configuration across the 3 runs, as (max - min) / median: p50 61% (Main-thread-routed 1KB/c=64); p99 83% (Direct peer channel 100KB/c=64); throughput 35% (Direct peer channel 100KB/c=64).

Errors: none. Sandbox log: 0 violations, 0 would-be-refused under enforce, 0 restarts, 0 suspensions.

p50: direct peer channels are lower than main-thread-routed in 4 of 9 cells, higher in 1 (100KB/c=64 (32.2 [28.1–33.5] ms vs. 43.0 [36.3–60.4] ms), main vs. direct), and within noise in 4; ratio of medians from 0.749× (at 100KB/c=64) to 1.50× (at 1MB/c=1).

Throughput: direct peer channels are higher in 4 of 9 cells, lower in 0, and within noise in 5; ratio of medians from 1.00× (at 100KB/c=1) to 1.47× (at 1MB/c=64).

p99: direct peer channels are lower in 1 of 9 cells, higher (worse) in 1 (100KB/c=64 (43.3 [42.9–53.2] ms vs. 67.3 [64.0–120] ms), main vs. direct), and within noise in 7.

These numbers already include the backpressure fix described below — see that section for what changed and why.

Read the noise floor before the medians. It is the largest spread of any single configuration across the three runs, printed by the script under the table. Mid-concurrency cells move the most from run to run, which is why the summary only calls a difference when the ranges separate. A comparison of two single runs cannot resolve differences of that size; re-run perf/direct-peer-channels-perf.js --runs 3 yourself — it prints its own fresh summary — before relying on precise numbers for capacity planning.

Backpressure

The figures in this section are historical and were not re-measured on 2026-10-26. They were taken on 2026-08-09 (commit be666df); the document did not record the machine at the time. The closest record is the 2026-08-18 re-measurement, on the 2-core reference machine with Node 20.20.2.

The first version of this benchmark (before the fix described here) found a real regression: at 1MB payloads under 64-way concurrency specifically, direct peer channels were slower than main-thread-routed (842ms p50 vs. 360ms). Root cause: both paths ultimately funnel through the same two worker threads (one caller, one callee) — the only difference is whether the main thread is also in the loop. The main-thread hop is itself a bottleneck, but that bottleneck incidentally throttled how much work could pile up waiting at the callee’s single-threaded event loop. Direct peer channels had no such throttle: every ServiceClient.invoke() call fired a postMessage immediately, structured-clone cost and all, regardless of how many were already in flight on that channel.

Fix: lib/peer-channel.js now caps how many invokes a channel will have in flight at once — on both ends. Capping only the callee’s dispatch (onInvoke) was tried first and didn’t help: postMessage’s structured-clone cost for a large payload is paid at send time, so an uncapped caller was still firing (and paying for) every concurrent invoke() call before any callee-side cap could matter. The real fix queues on both sides — outgoing invoke() calls once too many are already in flight, and incoming peer-invoke dispatch to onInvoke the same way — draining each queue as in-flight calls complete.

Controlled by --directPeerChannelsMaxConcurrency (default 16). Tuned empirically at the regressing 1MB/64-way cell, not guessed:

Cap p50 p99
uncapped (pre-fix) 688ms 930ms
4 437ms 1190ms
8 460ms 936ms
16 464ms 1056ms
32 567ms 997ms

4, 8, and 16 land in the same range (a real, roughly 1.5× improvement over uncapped); 32 trends back toward uncapped. 16 was chosen as the default over a lower cap like 4 specifically to avoid needlessly serializing calls at payload sizes where concurrency was never a problem in the first place (1KB/100KB throughput at concurrency 16–64 was already excellent uncapped) — a fixed call-count cap is a blunt instrument that can’t distinguish “many small calls” from “many large calls,” so this picks a value that helps the large-payload case without meaningfully constraining the common case. test/direct-peer-channels/05-backpressure.js covers correctness (a burst well above a low cap all complete correctly, none dropped by the queue) — that test is not a performance assertion, this document is.

Still a known limitation, smaller than before but real: the cap is a fixed call count, not payload-size-aware or adaptive. A deployment expecting sustained, very-large-payload, high-concurrency traffic on a single worker pair should tune --directPeerChannelsMaxConcurrency for its own payload sizes rather than assume the default is optimal, and a genuinely size-aware or adaptive throttle (e.g. capping total bytes in flight, not call count) would likely do better than a fixed cap — not built here, flagged as a further follow-up.

Benchmark: message serialization strategy (D2)

perf/peer-channel-serialization-perf.js compares three ways to move a payload across a MessagePort, independent of the rest of the server: JSON.stringify to a string, posting the raw object (relying on structured clone), and encoding into a Buffer/ArrayBuffer transferred via the postMessage transfer list (zero-copy ownership transfer). 300 round trips per cell.

Table and summary below are copy-pasted verbatim from a --runs 3 run of perf/peer-channel-serialization-perf.js on a 2-vCPU VMware guest (Intel Core i7-6600U @ 2.60 GHz, 7.2 GB), Node v24.21.0, at commit 3d9599d (no countinghouse server involved, so no sandbox mode), which computes the summary itself (see that file’s header comment: an earlier hand-written “2.7–3.7×” claim here silently ignored the 1KB row, which only ever showed a much smaller ratio). A bold cell is the lowest median whose range clears both others.

Payload JSON.stringify p50 Structured clone p50 Transfer list p50
1KB 0.241 [0.123–0.253] ms 0.0509 [0.0487–0.0534] ms 0.278 [0.109–0.283] ms
100KB 0.726 [0.693–0.764] ms 0.245 [0.240–0.259] ms 0.863 [0.854–0.931] ms
1MB 10.9 [10.8–12.4] ms 3.31 [3.29–3.45] ms 11.3 [10.8–11.5] ms

Noise floor: the largest spread of any single configuration across the 3 runs is 62% (transfer list at 1KB), as (max - min) / median.

Lowest median per payload size: 1KB=structuredClone, 100KB=structuredClone, 1MB=structuredClone. Structured clone against JSON.stringify: 1KB faster, 100KB faster, 1MB faster. Structured clone is faster than JSON.stringify at every size tested, with non-overlapping ranges. Ratio of medians (JSON.stringify / structured clone) ranges from 2.97× (at 100KB) to 4.73× (at 1KB).

This is the opposite conclusion from the one lib/worker-message.js’s pre-existing comment cites — a 2016 blog post that measured JSON.stringify as faster for the old, main-thread-routed protocol — confirming this needed re-measuring on the current Node target rather than assumed to still hold, per this project’s own stated rule about not carrying forward unverified performance claims. The transfer-list approach loses specifically because the payloads here start as JS objects: encoding to a Buffer and decoding back on the other side costs more than structured clone’s native object copy saves; transfer-list ownership transfer would likely still win for payloads that are already binary (e.g. actual file/image data passed as a Buffer throughout, never JSON), which this benchmark doesn’t cover and this codebase doesn’t yet have a use case for.

Decision: lib/peer-channel.js keeps posting plain objects (structured clone). This is what it already did before this benchmark was run — the data confirms the existing choice rather than requiring a change.

Benchmark: transport overhead vs. other tool-to-tool mechanisms

The tables above compare countinghouse’s two internal routing paths against each other. This one asks a different question: how much does the transport choice cost at all, compared with the two mechanisms an MCP deployment would otherwise use to get from one tool to another – a stdio subprocess, and localhost HTTP.

Produced by perf/cross-process-comparison.js (see that file’s header for the full methodology). Same discipline as the tables above: the summary below is generated by the script from the numbers it measured, and nothing in this section is hand-computed.

Read the scope before the numbers:

Measured with --runs 3 on a 2-vCPU VMware guest (Intel Core i7-6600U @ 2.60 GHz, 7.2 GB), Node v24.21.0, at commit 3d9599d; no countinghouse server is involved, so no sandbox mode. Cells are the median across the three runs with the [min–max] range.

Payload Hops Direct peer channel
p50 / p99
MCP stdio subprocess
p50 / p99
localhost HTTP
p50 / p99
Per-hop p50
(peer / stdio / http)
Hops/s
(peer / stdio / http)
CPU
(peer / stdio / http)
Peak RSS
(peer / stdio / http)
n
1KB 1 0.254 [0.224–0.260] ms / 1.09 [0.862–1.40] ms 0.286 [0.248–0.287] ms / 1.10 [0.916–1.44] ms 0.746 [0.659–0.785] ms / 2.44 [2.32–3.11] ms 0.254 [0.224–0.260] ms / 0.286 [0.248–0.287] ms / 0.746 [0.659–0.785] ms 3702 [3564–4642] / 3247 [3217–3977] / 1160 [1112–1286] 0.110 [0.100–0.130] s / 0.170 [0.150–0.190] s / 0.510 [0.450–0.530] s 79 [78–79] MB / 121 [121–121] MB / 133 [133–134] MB 500
1KB 10 2.27 [2.26–2.36] ms / 4.29 [3.50–4.47] ms 2.45 [0.975–2.47] ms / 4.42 [4.32–4.94] ms 4.97 [4.91–5.78] ms / 14.3 [12.2–15.0] ms 0.227 [0.226–0.236] ms / 0.245 [0.0975–0.247] ms / 0.497 [0.491–0.578] ms 4731 [4471–4901] / 4722 [4622–7120] / 1942 [1713–1998] 0.670 [0.650–0.730] s / 0.820 [0.570–0.840] s / 2.22 [2.16–2.52] s 93 [92–93] MB / 140 [139–140] MB / 155 [155–157] MB 400
1KB 100 23.5 [23.5–23.7] ms / 28.5 [25.9–29.2] ms 25.5 [25.2–25.9] ms / 30.3 [30.0–32.0] ms 55.8 [49.6–59.0] ms / 81.1 [73.0–84.2] ms 0.235 [0.235–0.237] ms / 0.255 [0.252–0.259] ms / 0.558 [0.496–0.590] ms 4600 [4308–4771] / 4437 [4257–4461] / 1909 [1693–2203] 0.700 [0.670–0.730] s / 0.900 [0.850–0.930] s / 2.17 [1.93–2.50] s 97 [97–98] MB / 145 [144–145] MB / 158 [154–160] MB 40
64KB 1 0.269 [0.186–0.283] ms / 0.982 [0.933–1.33] ms 0.763 [0.763–0.869] ms / 2.54 [2.22–2.71] ms 1.56 [1.55–1.57] ms / 3.94 [3.80–4.18] ms 0.269 [0.186–0.283] ms / 0.763 [0.763–0.869] ms / 1.56 [1.55–1.57] ms 3407 [3371–4751] / 1104 [990–1137] / 578 [570–583] 0.120 [0.100–0.140] s / 0.470 [0.460–0.550] s / 0.980 [0.960–0.980] s 99 [98–100] MB / 152 [152–153] MB / 158 [157–159] MB 500
64KB 10 2.78 [2.75–2.85] ms / 7.19 [7.08–13.1] ms 8.23 [8.19–8.30] ms / 14.5 [14.0–14.8] ms 15.2 [13.7–15.2] ms / 32.7 [31.1–43.8] ms 0.278 [0.275–0.285] ms / 0.823 [0.819–0.830] ms / 1.52 [1.37–1.52] ms 3334 [3284–3388] / 1165 [1156–1192] / 650 [625–706] 0.260 [0.240–0.320] s / 0.880 [0.860–0.890] s / 1.72 [1.56–1.80] s 102 [102–102] MB / 154 [153–155] MB / 174 [172–175] MB 100
64KB 100 27.7 [25.7–27.8] ms / 34.5 [33.3–38.1] ms 82.6 [80.5–99.1] ms / 104 [99.9–136] ms 137 [134–138] ms / 174 [163–179] ms 0.277 [0.257–0.278] ms / 0.826 [0.805–0.991] ms / 1.37 [1.34–1.38] ms 3660 [3469–3733] / 1171 [1001–1199] / 739 [715–745] 0.490 [0.440–0.550] s / 1.74 [1.69–2.20] s / 3.06 [3.01–3.16] s 103 [102–106] MB / 159 [159–162] MB / 176 [176–177] MB 20
1MB 1 3.30 [3.23–4.09] ms / 6.63 [5.13–6.95] ms 44.2 [43.3–46.0] ms / 78.6 [65.7–84.0] ms 16.0 [15.6–16.4] ms / 31.7 [29.5–34.2] ms 3.30 [3.23–4.09] ms / 44.2 [43.3–46.0] ms / 16.0 [15.6–16.4] ms 302 [244–304] / 22 [21–22] / 58 [57–60] 0.660 [0.640–0.820] s / 9.47 [9.23–9.97] s / 3.72 [3.64–3.76] s 117 [116–118] MB / 309 [297–314] MB / 363 [349–372] MB 200
1MB 10 32.9 [32.3–35.8] ms / 37.1 [35.4–51.4] ms 445 [437–445] ms / 503 [498–542] ms 172 [169–177] ms / 214 [213–214] ms 3.29 [3.23–3.58] ms / 44.5 [43.7–44.5] ms / 17.2 [16.9–17.7] ms 301 [270–311] / 22 [22–23] / 57 [57–59] 0.650 [0.640–0.740] s / 9.29 [9.17–9.31] s / 3.76 [3.68–3.82] s 205 [203–217] MB / 369 [341–385] MB / 367 [346–390] MB 20
1MB 100 400 [385–405] ms / 430 [417–430] ms 4.39 [4.38–4.50] s / 4.61 [4.58–6.58] s 1.59 [1.59–1.59] s / 1.78 [1.75–1.87] s 4.00 [3.85–4.05] ms / 43.9 [43.8–45.0] ms / 15.9 [15.9–15.9] ms 257 [257–264] / 23 [21–23] / 62 [62–62] 7.72 [7.54–7.76] s / 91.5 [90.8–98.2] s / 34.6 [34.3–34.6] s 205 [202–217] MB / 390 [342–406] MB / 420 [415–422] MB 20

Noise floor: the largest spread of any single configuration across the 3 runs is 61% (stdio 1KB/10hop p50), as (max - min) / median.

vs. MCP stdio subprocess: the direct peer channel has a lower p50 in 7 of 9 cells, a higher one in 0, and is within noise in 2 (1KB/1hop: 0.254 [0.224–0.260] ms vs. 0.286 [0.248–0.287] ms per hop, 1KB/10hop: 0.227 [0.226–0.236] ms vs. 0.245 [0.0975–0.247] ms per hop); ratio of medians from 1.08× (at 1KB/10hop) to 13.5× (at 1MB/10hop).

vs. localhost HTTP: the direct peer channel has a lower p50 in 9 of 9 cells, a higher one in 0, and is within noise in 0; ratio of medians from 2.19× (at 1KB/10hop) to 5.82× (at 64KB/1hop).

Scale of the difference: the largest per-hop saving measured here is 13.9 [13.7–14.1] ms across the 3 runs (best case for the direct channel, across every cell; at 1MB/10hop). A tool whose own execution takes more than ~139 [137–141] ms per call would see even that saving as under 10% of the hop, and proportionally less the slower it gets. This benchmark measures transport, not tools.

What this does and does not justify

The summary above gives the cell counts. The margin grows with payload size – which is what you would expect, since the direct peer channel is the only one of the three that does not serialize the payload to a byte stream and push it through a kernel boundary. At 1KB the gap against stdio is within noise at 1 and 10 hops, the two cells the summary names; at 1MB it is not.

But the margin only matters when it is a meaningful share of the call. The break-even figure in the summary above is computed by the script from its own measurements, not asserted here: once a tool’s own execution time passes it, that time dominates and the transport difference disappears into the noise. Most real tools – anything that hits a database, an API, a model, or the disk – are far past it.

So the honest reading of this table is narrow. Composition-heavy workloads with large payloads and fast tools are where the transport choice shows up at all. A chain of slow tools will not notice the difference, and nothing here argues that it should.

Retired numbers

Per this project’s own stated discipline: the old “20–30×” performance figures from this codebase’s earlier PPT-era materials must not be cited anywhere going forward. The tables above, produced by perf/direct-peer-channels-perf.js, perf/peer-channel-serialization-perf.js and perf/cross-process-comparison.js on the current Node target, are the only legitimate public numbers for cross-worker call performance as of this writing. Re-run all three scripts and update this document if the underlying code, Node version, or hardware changes meaningfully.

The same rule covers the comparison prose beside each table: every summary in this document is emitted by the script that measured it, copy-pasted from a real run. None of it is hand-computed, and none of it may be edited by hand – a hand-written summary drifted from the table beside it once already, which is why the scripts generate their own.

Replaced on 2026-10-26

The tables and summaries below were the published figures until 2026-10-26. They were replaced because every script now runs three independent times and reports ranges, and because the code (the module sandbox, default audit), the Node version and the machine all changed since they were taken. They are kept, unedited, so that older citations can be checked.

Cross-worker micro-benchmark, 2026-08-18, Node 20.20.2, 2-core reference machine, single run

Payload Concurrency Main-thread-routed p50 / p99 Direct peer channel p50 / p99 Throughput (main-thread / direct)
1KB 1 3.00ms / 7.29ms 2.81ms / 16.12ms 122 / 134 req/s
1KB 16 21.68ms / 40.51ms 21.42ms / 35.92ms 266 / 287 req/s
1KB 64 40.64ms / 73.55ms 35.36ms / 81.04ms 278 / 312 req/s
100KB 1 3.00ms / 9.79ms 3.00ms / 12.49ms 128 / 138 req/s
100KB 16 19.69ms / 36.23ms 19.06ms / 35.17ms 289 / 322 req/s
100KB 64 87.88ms / 116.07ms 86.18ms / 150.31ms 276 / 371 req/s
1MB 1 18.23ms / 37.23ms 11.95ms / 27.34ms 42 / 59 req/s
1MB 16 171.12ms / 274.84ms 117.42ms / 191.33ms 58 / 75 req/s
1MB 64 539.16ms / 804.18ms 305.77ms / 626.33ms 61 / 85 req/s

p50: direct peer channels are faster than main-thread-routed in 8 of 9 cells, ranging from 1.00× (at 100KB/c=1) to 1.76× (at 1MB/c=64).

Throughput: direct peer channels win on 9 of 9 cells (1024/c=1, 1024/c=16, 1024/c=64, 102400/c=1, 102400/c=16, 102400/c=64, 1048576/c=1, 1048576/c=16, 1048576/c=64).

p99: direct peer channels are lower in 5 of 9 cells; higher (worse) in 4: 1KB/c=1 (7.29ms main vs. 16.12ms direct), 1KB/c=64 (73.55ms main vs. 81.04ms direct), 100KB/c=1 (9.79ms main vs. 12.49ms direct), 100KB/c=64 (116.07ms main vs. 150.31ms direct).

Run-to-run variance is large in the mid-concurrency cells, and it is worth knowing which rows to trust. Running this script three times against identical code on the 6.0.0 reference machine (2 cores, otherwise idle) gave a main-thread p50 spread of 3–6% at c=1 and at 1MB/c=64, but 33% at 1KB/c=64, 43% at 100KB/c=16 and 175% at 100KB/c=64. So a single run cannot resolve a 10% difference in those cells, and neither can a comparison of two single runs. Read the relative comparison within one run as the signal, and treat any absolute mid-concurrency figure as indicative only.

A worked example from 6.0.0’s own release measurements, because it shows the effect at a cell you would otherwise trust: at 100KB/c=1 the main-thread p50 read 3.10ms in 6.0.0’s release table and 3.40ms on a re-run of the same commit — +10%, from nothing but background load (the reference machine has 2 cores; the re-run had a CouchDB, a MongoDB and an Appsmith container running alongside). That cell is one of the stable ones: three runs of identical code on the idle machine spread only 5%. So a 10% swing there is load, not code — and a before/after comparison of two single runs, one taken on a busy machine, can manufacture a regression that does not exist. It did during this release, until the same-code control run was added. Re-run perf/direct-peer-channels-perf.js yourself — it prints its own fresh summary — before relying on precise numbers for capacity planning.

Message serialization, 2026-08-18, Node 20.20.2, 2-core reference machine, single run

Payload JSON.stringify p50 Structured clone p50 Transfer list p50
1KB 0.31ms 0.20ms 0.29ms
100KB 0.92ms 0.31ms 1.19ms
1MB 22.50ms 8.11ms 24.82ms

Fastest strategy per payload size: 1KB=structuredClone, 100KB=structuredClone, 1MB=structuredClone. Structured clone wins at every size tested. Structured clone vs. JSON.stringify ratio ranges from 1.49× (at 1KB) to 3.01× (at 100KB).

Transport overhead, 2026-08-18, Node 20.20.2, 2-core reference machine, single run

Payload Hops Direct peer channel
p50 / p99
MCP stdio subprocess
p50 / p99
localhost HTTP
p50 / p99
Per-hop p50
(peer / stdio / http)
Hops/s
(peer / stdio / http)
CPU
(peer / stdio / http)
Peak RSS
(peer / stdio / http)
n
1KB 1 0.341ms / 1.058ms 0.363ms / 1.312ms 0.733ms / 3.367ms 0.341ms / 0.363ms / 0.733ms 2654 / 2368 / 1069 0.17s / 0.23s / 0.56s 59MB / 88MB / 101MB 500
1KB 10 2.846ms / 5.887ms 3.282ms / 6.764ms 6.264ms / 15.022ms 0.285ms / 0.328ms / 0.626ms 3347 / 2827 / 1456 1.12s / 1.49s / 3.08s 72MB / 101MB / 107MB 400
1KB 100 28.428ms / 70.105ms 33.377ms / 50.111ms 69.648ms / 177.247ms 0.284ms / 0.334ms / 0.696ms 3436 / 2961 / 1348 1.13s / 1.37s / 2.94s 75MB / 103MB / 107MB 40
64KB 1 0.371ms / 1.861ms 1.316ms / 6.176ms 2.083ms / 11.273ms 0.371ms / 1.316ms / 2.083ms 2158 / 580 / 358 0.23s / 0.92s / 1.54s 75MB / 104MB / 114MB 500
64KB 10 4.065ms / 14.600ms 13.063ms / 25.913ms 19.853ms / 37.398ms 0.407ms / 1.306ms / 1.985ms 2091 / 734 / 483 0.42s / 1.50s / 2.35s 81MB / 110MB / 119MB 100
64KB 100 43.076ms / 62.142ms 127.590ms / 164.524ms 178.073ms / 260.603ms 0.431ms / 1.276ms / 1.781ms 2274 / 751 / 563 0.82s / 2.87s / 3.95s 82MB / 110MB / 127MB 20
1MB 1 9.124ms / 25.746ms 86.092ms / 124.117ms 38.762ms / 62.200ms 9.124ms / 86.092ms / 38.762ms 107 / 11 / 25 2.00s / 18.12s / 8.35s 88MB / 166MB / 195MB 200
1MB 10 87.253ms / 120.025ms 882.280ms / 928.512ms 394.905ms / 501.599ms 8.725ms / 88.228ms / 39.491ms 112 / 11 / 25 1.90s / 18.05s / 8.47s 113MB / 178MB / 190MB 20
1MB 100 939.081ms / 1206.357ms 8339.424ms / 9330.792ms 3661.641ms / 3771.925ms 9.391ms / 83.394ms / 36.616ms 103 / 12 / 27 21.00s / 172.63s / 76.44s 125MB / 185MB / 200MB 20

vs. MCP stdio subprocess: the direct peer channel has a lower p50 in 9 of 9 cells, from 1.06× (at 1KB/1hop) to 10.11× (at 1MB/10hop).

vs. localhost HTTP: lower p50 in 9 of 9 cells, from 2.15× (at 1KB/1hop) to 5.61× (at 64KB/1hop).

Scale of the difference: the largest per-hop saving measured here is 30.765ms (best case for the direct channel, across every cell). A tool whose own execution takes more than ~308ms per call would see even that saving as under 10% of the hop, and proportionally less the slower it gets. This benchmark measures transport, not tools.

log-triage, 2026-10-26: withdrawn

The 2026-10-26 log-triage run (perf/results/2026-10-26/log-triage.md) measured “runtime adds” against an in-process baseline that ran the handlers one file after another, while the composite runs each file’s chain concurrently; on two CPUs that baseline ran high and the runtime’s share came out low. Its log-triage figures were replaced on 2026-10-27 by a run with a baseline scheduled like the composite (perf/results/2026-10-27/). The raw output stays in the repository; its tables are not repeated here.

log-triage, 2026-10-07, one vCPU, Node 24.21.0, countinghouse 7.1.0 (cb68765)

From docs/log-triage-performance.md as it stood before 2026-10-26: one run of perf/log-triage-perf.js --reps 25, each cell the median of 25 calls (min–max of those calls). The launch posts under docs/ quoted these.

Latency follows the number of files, linearly

400 lines per file. Times in ms, median (min–max).

files hops direct routed in-process
1 4 24.4 (14.0–45.6) 19.0 (15.3–38.8) 6.0
2 6 27.8 (18.5–153) 34.3 (19.3–103) 9.8
4 10 27.8 (22.6–44.6) 38.3 (25.8–54.7) 15.7
8 18 48.0 (40.1–114) 63.2 (47.8–109) 30.7
16 34 78.9 (64.7–107) 92.7 (70.7–160) 59.0
32 66 157 (137–203) 178 (150–221) 97.1

From 1 file to 32, the composite goes from about 24 ms to about 157 ms on the direct path: roughly 4.3 ms for each further file, which is two more hops and one more file’s work. On the routed path it is roughly 5.1 ms per file. The bill grows the same way, by 2 per file, so latency and cost move together and maxFiles bounds both.

With larger files, the work dominates

8 files, 18 hops. Times in ms, median (min–max).

lines per file direct routed in-process runtime adds, direct runtime adds, routed
100 21.9 (17.0–31.6) 24.9 (18.7–75.5) 6.5 15.4 18.4
400 44.0 (33.5–56.8) 52.6 (39.7–84.3) 22.5 21.5 30.0
1,600 125 (110–184) 142 (128–169) 88.6 36.3 53.4
6,400 437 (393–501) 514 (437–577) 357 79.7 157

At 100 lines per file the runtime is most of the call: 15 of 22 ms. At 6,400 lines per file (about 4 MB of logs in total) the handlers’ own work is 357 of 437 ms, about 82%, and the runtime’s share has fallen to 18%.

What the runtime adds is not constant. It grows with payload, from about 15 ms to about 80 ms on the direct path, because every read result and every redact input and output is a batch of lines crossing a worker boundary.

Direct against routed

The direct path is the faster one wherever the difference is larger than the noise:

case direct routed direct is lower by
8 files, 400 lines 48.0 63.2 24%
32 files, 400 lines 157 178 12%
8 files, 6,400 lines 437 514 15%
1 file, 400 lines 24.4 19.0 within noise

The gap is clearest in what the runtime adds with large payloads: 80 ms direct against 157 ms routed at 6,400 lines per file. That fits direct-peer-channels.md, which says the direct path matters most for composition-heavy calls with large payloads, and it is the same trade-off described there: the direct path checks authorization when a channel opens, not on every hop.

One composite call against the same hops made by the client

8 files of 400 lines, 18 tool calls for the client. Times in ms, median (min–max); bytes are JSON request and response bodies.

  tool calls latency, direct server latency, routed server bytes sent bytes received
composite 1 45.6 (34.7–73.4) 50.6 (35.7–73.1) 167 14,436
client-orchestrated 18 109 (86.1–226) 96.7 (78.6–167) 549,495 1,119,438

The composite is about twice as fast, and it moves about 14.6 KB where the client-orchestrated version moves about 1.67 MB, roughly 114 times as much. The difference is the raw lines: the client has to receive every file from read and send it back to redact, then send all the masked lines to cluster.

Three things this comparison does not show. The client here is on the same machine as the server, so network latency, which would widen the gap, is absent. The client-orchestrated calls are sequential, as a model issuing tool calls would make them. And the hop path makes no difference to the client rows, since a client calling leaf tools directly makes no inner hops; the two latency columns differ only by noise.