This document describes pre-installed-packages/composite-demo, a demo
module that chains two other modules’ actions together inside a single
tools/call, and shows how metering attributes revenue across the chain.
countinghouse makes hosted tools composable. A device module can call
another device module’s action directly, in-process, over the existing
worker message channel — the same mechanism ServiceClient already uses
for any cross-module call (see docs/security-model.md’s description of
the WorkerMessage protocol). Intermediate results never leave the
process: they don’t go over HTTP, and they never enter the calling MCP
client’s model context. From the outside, an MCP client sees one
tools/call request and one response.
This is not an MCP protocol extension. MCP itself has no notion of
tool-to-tool calls; nothing here changes JSON-RPC framing, the
tools/list/tools/call contract, or anything a client-side MCP library
needs to know about. Composition is entirely a platform-side capability:
one device module’s action handler, running inside its own worker, invokes
another module’s action the same way any other in-process caller would,
via CHUtil.createServiceClient(...).
Do not describe this feature as “we extended MCP.” It is a capability of the hosting platform, exposed to MCP clients as an ordinary tool that happens to do more work per call.
Old performance numbers (“20-30x”) describing this codebase’s prior
worker-thread architecture must not be cited here or anywhere else until
they are re-benchmarked on the current Node target (see
direct-peer-channels.md). This
document makes no performance claims.
There are two module-facing APIs for calling another module, and they answer different needs — this is not “old way, new way.”
ctx.call(address, input, opts) — call by name, the default choice.
The target is addressed as <module>/<service>.<action>
(repo-scan/scanService.scan), what the module is allowed to call is
declared in its own package.json (countinghouse.calls), and which auth
identity its hops are authorized as is bound separately, by the operator, in
the auth config (runsModules). Everything — address resolution, the
identity binding, and the grant to each target — is verified once at load
time, so a misconfigured chain fails the module at startup rather than on
first call. examples/repo-review/repo-review is the live example: it calls
repo-scan, secret-detect and dep-audit this way.
examples/log-triage/log-triage is the example with concurrent hops: it
starts a read-then-redact chain per file with Promise.all, and each hop is
still metered once. Full reference:
module-development.md.
ctx.serviceClient(opts, cb) — call by deviceID, the escape hatch.
ctx.call deliberately doesn’t cover two cases: authorizing a single hop as
an identity other than the one identity bound to this module
(runsModules binds exactly one), or a module that legitimately needs to
act as two different identities for different targets. composite-demo,
this document’s subject, stays on ctx.serviceClient on purpose so both
paths keep a live example and test coverage — see
Running it below.
Either way, in worker mode (the default) a module reaches only what it
declared. The main thread checks every hop against the calling module’s
countinghouse.calls, read from its package.json on the main thread and
resolved at load, whatever API the module used: ctx.call,
ctx.serviceClient by raw deviceID, or a message built by hand. (Under
--no-workerThread modules share one process and nothing isolates them;
there ctx.call and ctx.serviceClient check the target,
CHUtil.createServiceClient with a raw key does not.) A hop to anything
else is refused CTX_CALL_UNDECLARED, runs no handler and costs nothing.
On the direct peer path the channel opens only to a declared device, and
the callee serves only the declared actions on it. A worker runs one
module: a second load into it is refused.
The main thread reads the declarations before any of the module’s code
runs: when it starts the module’s worker, or before
countinghouse_validate_module runs the module, in which case the load of
that path that follows takes that copy. An operator’s load, reload or
restart reads the file again; a supervised restart keeps the last copy.
Under --moduleSandbox enforce the module can’t write the file, so the
declaration holds. Under audit this raises the bar and records the
change: the file broker refuses writes to the file by any name it sees,
and to every directory above it, above <moduleDataPath>/.pins and above
the identity secret, so none can be renamed away and back; routes it
doesn’t see remain (a child process, a worker thread), so each time the
file is read again, every call added
since the last read is logged as an error (module sandbox: <module>
declared call added since its last pin: "<address>" (adopted), or (not
adopted: ...) when the previous copy stays). The last copy’s calls are
kept under <moduleDataPath>/.pins, which no module can write through the
file broker, so a server restart compares too. Under audit a module that
uses child_process or worker_threads can still change its declarations
and those records: that use is itself logged, and only enforce holds the
declarations. This covers countinghouse.calls only: the module’s
permissions and remotes are read from disk at every start, a supervised
restart’s included.
ctx.call('remote:<name>/<tool>', args) — a remote MCP server, not a
module. A module that declares a remote in countinghouse.remotes
calls it through the same ctx.call. It is not a device, so neither
countinghouse.calls nor runsModules takes part. The main thread holds
the credential and finds the remote by the module that owns the call. The
answer is the server’s raw CallToolResult, and the hop is billed to
ctx.caller like any other. Each call is also a usage record under the
outer tools/call, from a part too when the hop to it was routed (a direct
peer channel does not carry the call id); see
module-authoring.md.
See module-development.md.
Both keep the same two-identity split: the inner hop is authorized as the
module’s own identity, and billed to ctx.caller, the real outer caller —
see In-composition metering.
composite-demo exposes one tool, compositeService/run, that:
{text: string}.transform-demo’s uppercase action on text, via a
ServiceClient created at module-init time
(pre-installed-packages/composite-demo/handlers/compositeService/run.js).echo-device-module’s echo action,
via a second ServiceClient, to demonstrate a second independent hop.{finalText, bill}, where bill is an array with one entry per
inner hop.Both inner calls are ordinary cross-worker invocations, through whichever
path ServiceClient.invoke() is currently configured to use. By default
(since 7.1.0) the calls go directly worker-to-worker over a
MessageChannel, bypassing the main thread entirely — see
direct-peer-channels.md for how that path
works. With --no-directPeerChannels they take the main-thread-routed path
instead: composite-demo’s worker sends an invokeforeignaction-style
message to the main thread, which routes it to the target module’s worker
and relays the reply back. Either way, composite-demo’s own code is unchanged:
which path is taken is entirely ServiceClient’s concern, transparent to
the module calling it.
Target modules are addressed by their deterministic deviceID
(UUID.v5 of a fixed namespace and the target module’s api.json
friendlyName), computed offline and hardcoded in its handler file, the same
pattern used by echo-device-client-module. No runtime discovery is
needed to call a known module.
composite-demo’s two inner hops are authorized as a fixed internal
identity, composite-demo-internal, separate from whatever key you call the
outer tool with. Grant that identity access before starting the server, or
every call fails with DEVICE_ACTION_CALL_FAIL — AuthProvider rejecting an
identity it has never seen, not a bug in the composition itself. This applies
to every bundled module that calls other modules; see
Every composing module needs its internal identity granted
below for the full list and a one-liner that grants all of them.
node -e "var c=JSON.parse(require('fs').readFileSync('auth.json'));
c['composite-demo-internal']={userName:'composite-demo-identity',devices:['*']};
require('fs').writeFileSync('auth.json', JSON.stringify(c, null, 2));"
--mcpToolCallCost defaults to 0 (nothing is charged unless you opt in), so
set it to something non-zero to actually see the bill move:
node ./framework.js --workerThread --bindAddr 127.0.0.1 --mcpToolCallCost 1 \
--loadModule ./pre-installed-packages/echo-device-module \
--loadModule ./pre-installed-packages/transform-demo \
--loadModule ./pre-installed-packages/composite-demo
curl -s -X POST http://127.0.0.1:9527/mcp -H "Content-Type: application/json" \
-H "X-CH-Key: <your key>" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
"name":"composite_demo_compositeservice_run",
"arguments":{"text":"hello from the composite demo"}}}'
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": false,
"content": [
{"type": "text", "text": "{\"finalText\":\"HELLO FROM THE COMPOSITE DEMO\",\"bill\":[...]}"}
],
"structuredContent": {
"finalText": "HELLO FROM THE COMPOSITE DEMO",
"bill": [
{"hop": 1, "tool": "transform-demo/uppercase", "charged": 1, "balance": -1},
{"hop": 2, "tool": "echo-device-module/echo", "charged": 1, "balance": -2}
]
}
}
}
That is the shape MCP’s tools/call wraps every response in —
jsonrpc/id/result are the JSON-RPC 2.0 envelope, content is the same
payload serialized as text (for clients that only read that), and
structuredContent is the return value itself, conforming to the tool’s
advertised outputSchema, worth reading directly rather than re-parsing
content[0].text. (The module returned {output: …}; ctx.call and HTTP
invoke-action keep that wrapper, MCP does not. A tool that declares no
output schema returns text only. Before 8.0.0, MCP results kept the wrapper
too, as structuredContent.output.) finalText is transform-demo
uppercasing the input, then echo-device-module echoing that result back —
two independent modules, called one after another entirely inside the server
process, with neither intermediate result ever entering the MCP client’s
context.
bill is one entry per inner hop: which tool ran, what it cost, and the
running balance afterward for the apiKey that made the outer call — per-hop
metering is not skipped just because the calls happen module-to-module
instead of client-to-server. A fresh identity starts at balance 0 and each
hop subtracts its cost, so a balance going more negative over successive
calls is expected, not an error.
Billing authority principle: platform automatic metering is the sole
thing that ever deducts balance for a cross-worker call — on both the
main-thread-routed path (DeviceManager.prototype.sendInvokeActionMessageToWorker)
and the direct-peer-channel path (the default since 7.1.0)
(PeerChannelBroker.prototype.handleMeteringRequest), unconditionally.
Every module composing other modules’ actions (like this one) gets billing
for free, automatically, once per hop, without calling anything itself —
and cannot double-bill a hop by also metering it, because the module-facing
API for that (CHUtil.recordUsage, see below) no longer touches balance at
all.
The two paths also now agree on error shape. A rejected inner hop’s
.fault — the callee’s own structured fault payload, when it supplied one —
was already identical on both paths. Its .code, the locale-independent
error code, was not: it rode through on the
direct-peer-channel path but arrived null on the main-thread-routed
(then default) path, because only the direct channel’s own dispatch carried it
across the worker boundary. DeviceManager.prototype.sendInvokeActionMessageToWorker
now sends errCode alongside errMsg on its reply envelope the same way, so
a caller (including ctx.call’s own rejection — see
module-development.md) sees
the same .code regardless of which path is in effect.
Each inner hop is still metered independently, but the metering now
originates from the platform, not from composite-demo’s own handler. The
real {tool, charged, balance} result (with remainingFreeCalls when the
caller has free calls; never the key a hop billed, R2-1) is threaded back
to the calling module as a 3rd, additive argument on ServiceClient.invoke()’s
callback — function(err, data, platformMetering) {...} — deliberately
never merged into data itself: data is the hop’s own action output,
and some modules (e.g. echo-device-client-module) pass it straight
through as their own action’s return value, so an extra field injected
into it would fail that pass-through’s own output schema validation. The
handler
(pre-installed-packages/composite-demo/com-countinghouse-compositeService-run.js)
reads platformMetering.charged/.balance off that 3rd argument to build
the bill array that becomes part of the tool’s own MCP-visible output,
so a caller can see exactly which inner modules were invoked and what each
hop cost, without needing separate observability tooling.
Separately, composite-demo also calls ctx.recordUsage(tool, cost,
callback) per hop (it answers {id, tool, cost, ts}, the caller’s opaque
id) — purely as its own app-layer audit trail. This
is not what produces bill’s numbers and has no effect on balance (see
lib/countinghouse-util.js’s own comment on recordUsage); a module that
doesn’t want its own bookkeeping trail can skip calling it entirely and
still bill correctly, since the platform’s own metering is unconditional.
A metering failure on one hop does not fail the whole composite call: the
inner action has already succeeded by the time the platform’s metering
runs, so a gap is recorded in the bill (charged/balance set to null)
rather than returning an error for what the caller experiences as a
successful request.
A hop’s result the caller cannot read is still billed (lean worker step 2; the reviewer, 2026-11-14). On the main-thread-routed path a hop’s result crosses as bytes: the callee’s worker serializes it, a validator checks it against the callee’s output schema, and only then does the calling worker decode it. The hop is metered once the callee has answered and its result has passed that check, before the bytes reach the caller. So if the caller’s own worker cannot decode bytes that passed (its heap is exhausted, for example), the hop is still billed: the callee served the call, and the failure is on the caller’s side.
The caller gets a clear error, never a crash. ctx.call (or
ServiceClient.invoke) rejects with DEVICE_INVOKE_EXCEPTION, “a module’s
result could not be read”. If the decode instead runs the caller’s worker
out of memory, that worker ends, as any out-of-memory worker does: its
pending calls are answered with the code that says why, and the supervisor
restarts it. A hop refused before it reaches the caller is not billed, as
before. That covers a result over --maxOutputBytes, one that fails the
callee’s output schema, and one whose check timed out.
$ curl -s -X POST http://127.0.0.1:9527/mcp -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
"name":"composite_demo_compositeservice_run",
"arguments":{"text":"hello from the composite demo"}}}'
returns a bill with two independent entries, one per inner module:
{
"finalText": "HELLO FROM THE COMPOSITE DEMO",
"bill": [
{"hop": 1, "tool": "transform-demo/uppercase", "charged": 1, "balance": -1},
{"hop": 2, "tool": "echo-device-module/echo", "charged": 1, "balance": -2}
]
}
A module that calls other modules does so as some apiKey, and that apiKey
goes through the same AuthProvider check any external caller would. So on
a real (non---debug) server, a composing module does not work until its
internal identity is granted access to the modules it calls — otherwise
every inner hop fails with USER_HAS_NO_DEVICE, surfacing at the outer tool
as DEVICE_ACTION_CALL_FAIL (or, if the module passes the inner result
straight through, as MISSING_OUTPUT_ARGUMENT). This is AuthProvider
correctly refusing an identity it has never seen, not a bug in composition.
Every bundled module that composes has one, and all of them need this,
not just composite-demo. Each declares its calls in countinghouse.calls,
so each identity must also run its module (runsModules, by the module’s
name: the name in its package.json, which the server loads it under, not
a device’s friendly name the module states): a declaring module that no
identity runs is unloaded at startup with MODULE_COMPOSITION_INVALID.
One identity runs a module, all its devices.
| Module | Internal apiKey | Runs (runsModules) |
Calls |
|---|---|---|---|
composite-demo |
composite-demo-internal |
composite-demo |
transform-demo, echo-device-module |
echo-device-client-module |
aabbcc |
echo-device-client-module |
echo-device-module |
perf-caller-demo |
perf-caller-demo-internal |
perf-caller-demo |
perf-callee-demo |
Grant whichever ones you load, before starting the server:
node -e "var f='auth.json',fs=require('fs');
var c=JSON.parse(fs.readFileSync(f));
[['composite-demo-internal','composite-demo-identity','composite-demo'],
['aabbcc','echo-client-identity','echo-device-client-module'],
['perf-caller-demo-internal','perf-caller-demo-identity','perf-caller-demo']].forEach(function(p){
c[p[0]]={userName:p[1], devices:['*'], runsModules:[p[2]]};
});
fs.writeFileSync(f, JSON.stringify(c,null,2));"
With --authProvider sqlite, the same binding is a CLI command:
node bin/countinghouse-auth-sqlite.js --dbPath auth.sqlite3 bind-module composite-demo-internal composite-demo
node bin/countinghouse-auth-sqlite.js --dbPath auth.sqlite3 unbind-module composite-demo # removes it
Under --debug with no auth file (the file provider with no
--authConfigPath and no COUNTINGHOUSE_API_KEY: single-tenant, admin), a
declaring module that no identity runs is bound to the debug key instead
(to the session identity debug when there is no --debugKey), so it
loads. The module is not handed the key: its worker sees a placeholder,
which the main thread reads as the call’s own identity. The log says so
once per module: “<module>: its declared calls authorize as
the debug key (–debug, no auth file)”. Its hops still authorize as the
identity the module itself names (as), which under --debug with a
--debugKey must be that key, as before; billing is unchanged: the
caller’s token decides who pays. Under --debug with an auth file, a
declaration no identity runs is the startup error it is everywhere else.
Each gets a userName different from its key: user names are shown to callers
(bills, check_balance), so a key must not double as one, and the file auth
provider warns at startup when it does.
echo-device-client-module’s key is the literal string aabbcc because it
predates this convention and doubles as the --debugKey this repo’s test
suite runs with — under --debug the two have to match or the module’s own
calls are refused. It is a test fixture, not a pattern to copy: a new module
should use a descriptive <module-name>-internal identity like the other
two, and no module should ship a guessable internal key to a real
deployment.
This demo cuts several corners deliberately, so that the mechanism is easy to read. A production composition feature would need to address these:
Resolved in 6.0.0 — the outer caller’s real API key now reaches inner
hops. This used to read: composite-demo uses a fixed internal identity
for every inner ServiceClient, so all composite billing showed up under
one key regardless of who actually called the tool.
What changed: authorization and billing became two identities instead of
one. A hop authorizes as the composing module’s own identity and bills
the authenticated outer caller. Since R2-1 (8.0) neither is named by the
module: the identity is the operator’s runsModules binding (as is
refused), and the main thread authorizes and bills every hop, on both
paths, by the per-call token it issued with the call, whatever the
module’s worker states (see Security model).
Keeping authorization with the module is deliberate. Threading the caller through both questions would have been the obvious reading of “pass the caller’s apiKey down”, and it would have broken encapsulation: every end user would suddenly need their own grant to every module a composing tool calls internally. Authorization stays with the module; only the bill moves.
The sharp edge this entry used to warn about is closed rather than
inherited. A hop whose billing identity cannot be resolved is now refused
with HOP_IDENTITY_UNRESOLVED, on both paths, instead of being metered for
free with no caller-visible signal. That check sits before recordCall, not
on its error, because a recordCall failure can also mean Redis is down —
and this codebase deliberately fails open on infrastructure. Unresolvable
identity is not an infrastructure failure; it is a call nobody can be
charged for.
Test: test/auth/13-ctx-billing-identity.js, non---debug and
multi-tenant, where the caller is granted the composing device but not the
inner one. It asserts the hop still succeeds, that ctx.caller is the real
caller, and — the assertion that actually matters — that the module identity
was billed nothing.
Still open here: checkBalance/rateLimit are applied at the outer call,
not independently per hop.
HOP_COST = 1 in
com-countinghouse-compositeService-run.js), not looked up from each
target module’s own declared pricing.meteringProvider on db 0, the balance
ledger, and module code reaches its worker’s CdifInterface
(CHUtil.ci), so a module could record a negative charge to credit any
key, or a positive one to debit anyone. Nothing in a worker needs one
since D5 moved billing to the main thread, so a worker builds none:
recordCall and checkBalance answer SYSTEM_ERROR there.--directPeerChannels path metered a
cross-worker call automatically; the main-thread-routed (then default) path
didn’t, so composite-demo metered itself explicitly via
CHUtil.recordCall. Once --directPeerChannels’s automatic metering
was added (D5), turning the flag on made composite-demo double-bill
every hop — its own recordCall and the platform’s new automatic
metering both fired for the same call, dropping
composite-demo-internal’s balance by 3× the per-hop cost for a 2-hop
call, not 2×. The real fix (see the “billing authority” principle
above): platform automatic metering was extended to the
main-thread-routed path too, so it is unconditionally the only thing
that ever deducts balance on either path; the module-facing
CHUtil.recordCall was removed and replaced with CHUtil.recordUsage,
which is app-layer bookkeeping only and never touches balance, so a
module literally cannot double-bill itself through that API anymore.
test/direct-peer-channels/06-no-double-billing.js asserts a 2-hop
composite call deducts exactly 2× cost (not 3×) and bill still shows
2 independent records, in both flag states. See
docs/cross-cutting-matrix.md’s direct-peer-channel rows for the
updated per-path guarantee.pre-installed-packages/transform-demo/ — minimal second module
(uppercase action), exists only so composite-demo has two distinct
inner modules to chain, rather than calling echo-device-module twice.pre-installed-packages/composite-demo/ — the composite tool itself.lib/countinghouse-interface.js — the meteringProvider, built on the
main thread only.lib/countinghouse-util.js — CHUtil.recordUsage (app-layer bookkeeping,
no balance effect; replaces the removed CHUtil.recordCall).lib/device-manager.js, lib/peer-channel-broker.js,
lib/peer-channel.js, lib/session.js, lib/worker-message.js,
lib/lean-worker.js — automatic platform metering on both cross-worker call
paths (the “billing authority” principle above) and the platformMetering
3rd callback argument that carries it back to a calling module without
touching data.test/direct-peer-channels/06-no-double-billing.js — the double-billing
regression test, both flag states.