countinghouse

Composite tools

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.

What this is

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.

Two ways to call another module

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.

How composite-demo works

composite-demo exposes one tool, compositeService/run, that:

  1. Takes {text: string}.
  2. Calls transform-demo’s uppercase action on text, via a ServiceClient created at module-init time (pre-installed-packages/composite-demo/handlers/compositeService/run.js).
  3. Feeds the uppercased result into echo-device-module’s echo action, via a second ServiceClient, to demonstrate a second independent hop.
  4. Returns {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.

Running it

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.

In-composition metering

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.

Example

$ 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}
  ]
}

Every composing module needs its internal identity granted

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.

Known simplifications (demo scope, not hidden)

This demo cuts several corners deliberately, so that the mechanism is easy to read. A production composition feature would need to address these:

Files