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/.
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.
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.
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:
userAuth before it is
routed. Here the same check runs once, at brokering time, and the channel
it grants is good for every device the callee worker hosts (D3).--peerChannelAuthRecheckSeconds, 5 by default. On a
denial, or when the AuthProvider cannot be reached, it closes the channel
on both workers; the caller’s next hop is brokered again and refused with
the ordinary authorization error, and calls in flight when the channel
closes fail with PEER_GONE. A revoked module identity can therefore keep
reaching a device for up to one interval; on the main-thread-routed path
the revocation applies to the very next hop. Restoring the grant needs no
restart. 0 turns the re-check off, and an open channel then outlives a
revocation until its worker restarts. With the file AuthProvider none of
this can arise, because the auth file is read once at startup. Test:
test/auth/19-peer-channel-revocation.js, against sqlite and its real
CLI.PEER_GONE,
PEER_CHANNEL_TIMEOUT, PEER_SELF_TARGET, PEER_NO_HANDLER.docs/cross-cutting-matrix.md.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.
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.
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.
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.
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:
initialize handshake, no capability
negotiation and no tools/list. A real MCP server does strictly more per
call, so this is the best case for stdio, not a typical one.lib/peer-channel.js. That process/thread difference is the thing
being measured, not an artifact of the harness./proc. Peer startup is excluded from all three conditions: each
one warms up before sampling begins.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.
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.
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.
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.
| 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.
| 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).
| 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.
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.
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.
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.
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.
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.
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.