feat(compass-agent): agent comms tools — post and list over the Runner socket

[mattwilkinsonn]

Implements 848-T3, the last leg of SEA-1355: the agent-side CommsBroker and createCommsTools, exposing comms_post_message and comms_list_messages to a containerized agent.

Both tools ride the per-container Unix socket to the Runner, which relays over RelayCommsCall to the Server, which attributes the call to the session's account in-process, fail-closed. An agent-initiated comms call never reaches a network door.

Consumes the two legs already on main: RelayCommsCall on runner.proto, and the Server hub handler in go/internal/runnerhub.

Design record stays in sealed — it is already on sealed main via #848, and errata found while implementing this are filed separately as sealed#999. A copy here would fork a canonical document across two repos.

Ported from the monorepo

Retargets sealedsecurity/sealed#993, opened against oss/compass after the pivot had already moved Compass here. #993 is closed unmerged with a pointer.

One change the port required

arktype tracks the agent SDK's own version (2.2.3) rather than the exact 2.2.2 pin the monorepo carried. pi-coding-agent@16.5.2 depends on arktype@2.2.3, and an exact 2.2.2 resolved two copies of @ark/schema (0.56.1 and 0.56.2), making the tool parameter schemas structurally incompatible with the SDK's own tool types — tsc failed with Types have separate declarations of a private property 'requiresInvalidDateCheck'. Matching the SDK dedupes to one copy.

Worth knowing for any other package here adding arktype: match whatever the SDK resolves, do not pin exact.

Review: three rounds, and two real defects in the renderer

Both were in the transcript renderer, both reachable by an untrusted participant, and both are the class the file already defends elsewhere — which is what makes them worth naming rather than quietly fixing.

A newline forged a second record. The renderer collapsed newlines in q.question but not in the values beside it on the same line. Round 1 found custom_text; round 2 found the fix was too narrow — an option label is caller-supplied on the ask and stored verbatim (validateAskQuestions checks question count, id uniqueness and the recommended index, never the label), so any member who can post can plant one, where custom_text at least needs a pending ask to answer. The collapse now happens where the values merge (flat, beside attr), so a value added to that line later cannot arrive raw by omission.

One bad timestamp failed the whole page. at_unix_ms is an int64 and toISOString() throws past ±8.64e15 ms — the throw escaped execute, so a single out-of-range row meant the model could read no message in the channel, a strictly wider blast radius than the degraded attributes the file already handles. Round 2 then caught that the guard's bound admitted values attr degrades anyway (past year 9999 the ISO form is +010000-…, whose leading + fails the shape test), so the bound is now year 9999 on both sides and the renderer degrades a timestamp in exactly one place.

Neither is reachable today — every server write path derives at from a real clock, and ids are server-minted. That is precisely the file's own standard: "a boundary that holds by accident is not a boundary."

Round 2 also found a fix of mine had made a test weaker: normalizing both strings by one fence left the record tag carrying the inequality, so not.toBe passed even with the marker completely unfenced. Own-fence normalization plus explicit marker assertions; the unfencing mutation now reddens.

Round 3 found the guard was a list, not a class. flat collapsed \s*\n\s* — so a lone CR, U+2028, U+2029, VT, FF and NEL all rode straight through into a marker line. Six spellings of the exact forgery it exists to stop. The file already argues why, in attr's comment one screen above: "An escape must enumerate what to escape and every missed spelling is a live hole." flat was that enumerating guard, sitting beside the comment warning against it.

The reviewer proposed widening the list to those six. I checked that fix and it leaves seven more holes — every other C0 control, including ESC, which in a terminal starts an ANSI sequence rather than being a character:

char        list-of-six    class
CR/2028/VT  clean          clean
NUL         SURVIVES       clean
ESC         SURVIVES       clean
FS/GS/RS    SURVIVES       clean

So the guard now constrains the class (Cc/Zl/Zp plus whitespace) rather than naming members. The error path had its own copy of the old regex and would have kept the LF-only spelling — it now calls flat, because two guards against one threat drift apart silently and the weaker one is the one nobody re-reads.

And round 3 found a test of mine that could not fail. The ?? id fallback test — added by the round-2 fix, specifically to defend that arm — asserted only a count of lines containing the fenced marker. The forgery it injects is unfenced, so it was never counted and the assertion held whether the forgery landed or not. The reviewer proved it with a mutation I had not run: drop flat on that arm, and only the label test reddens. It now carries the toContain its two siblings pair with the count.

That is the second time this review found a test that passes for a reason unrelated to what it names — and the reason it was found both times is mutation, not reading.

Also corrected, no behaviour change: the header claimed the RPC owns cancellation (it does not — execute's AbortSignal is not forwarded, so an aborted turn still posts; stated plainly rather than claimed away), createCommsTools had no non-test caller while the comment asserted a registration site absent from this repo, the design citation named no repo, and the schema test asserted a bare toJsonSchema() the harness never calls.

Verification

Status: locally-verified, never CI-verified. This PR has ZERO check-runs — not a passing gate, no gate at all (gh pr checks 15 → no checks reported). The repo has no workflows (git ls-tree origin/main .github/workflows/ is empty) and no ruleset requiring any (gh api .../rulesets → 0, branch protection → 404).

That second absence is the load-bearing one, and it is why I am restating this section rather than leaving my earlier "there is no CI here" note. An empty required-checks set does not read as absent to anything downstream — it reads as satisfied. tern's required_checks answers all_passing: true on this PR, correctly, because every required check passed and there are none. A reader asking "is it ready" gets a green verdict from a question nobody was asked.

So the distinction that matters here is not "did a gate pass" but who produced the evidence:

• locally-verified — I ran the gate on my machine and state what it covered. Everything below.
• CI-verified — the repository ran it. Nothing in this PR can claim that.

The defect is not the quality of the local run; it is that it is evidence I produced about my own work, which is the one property CI exists to supply and no amount of local rigour substitutes for. Treat the section below as testimony, and expect this PR to meet a pipeline for the first time when one lands.

Scope: what this diff touches, and what covers it

file	covered by
packages/compass-agent/src/{comms,comms.test,compassv1,index}.ts, transport/index.ts	compass-agent:ci
packages/compass-agent/package.json	compass-agent:ci (via root:install)
go/internal/comms/harness_test.go	compass-go:test — not in compass-agent:ci
bun.lock	root:install only; no task lints it

compass-agent:ci is deps: ['typecheck', 'test'] — no lint task, and no Go coverage. Quoting it alone would be a true claim about the wrong scope, so the Go leg and biome are run separately.

moon run compass-agent:ci --force

▮▮▮▮ compass-agent:typecheck (1s 206ms, 0e26376e)
compass-agent:test |  172 pass
compass-agent:test |  0 fail
compass-agent:test |  520 expect() calls
compass-agent:test | Ran 172 tests across 8 files. [3.57s]
▮▮▮▮ compass-agent:test (3s 637ms, d4cbdfcb)
▮▮▮▮ compass-agent:ci (no op, 32351b97)

Tasks: 5 completed
 Time: 3s 750ms

Zero cached markers — the run executed. (A cached run reports (cached, <hash>); that is the structural discriminator, not elapsed time.)

bunx biome check packages/compass-agent/src/ → Checked 19 files. No fixes applied.

Every new test verified by mutation, not inspection

A test that passes with the fix reverted defends nothing, so each was run against a broken renderer:

revert the label collapse       -> label AND ?? id tests redden (was: label only)
unfence the content marker      -> only "cannot forge the no-renderable-content…" reddens
drop the lower timestamp bound  -> only the "below year 1" table row reddens
remove the timestamp guard      -> RangeError: Invalid Date, whole page fails
flat -> the old LF-only regex   -> 11 rows redden; LF and CRLF stay green

The last two are the original defects reproducing exactly. The first line is the round-3 correction: that mutation used to redden only the label test, which is how the reviewer proved the ?? id test was passing for the wrong reason.

bun test reports 185 pass / 0 fail (was 172; +13 from the two terminator tables).

Go leg (harness_test.go is pgtest-tagged, so it is outside the default gate)

--- PASS: TestForwardCommsDeliversVisibleEvent (0.00s)
--- PASS: TestForwardCommsSkipsNonVisibleEventAndContinues (0.00s)
--- PASS: TestForwardCommsFailsClosedOnStoreFault (0.00s)
--- PASS: TestForwardCommsCleanEndOnCancellation (0.00s)
ok  github.com/sealedsecurity/compass/go/internal/comms  100.646s

100.6s is the discriminator: go test prints ok for a fully-skipped tagged suite, so elapsed time is the only thing separating ran from skipped.

Ran against the pipeline compass#19 will land, not just my package's gate

#19 adds two jobs. Rather than wait for first contact when it merges, I ran both commands locally on this branch.

gate — moon run :ci (repo-wide, not compass-agent:ci):

Tasks: 35 completed (16 cached)
 Time: 2m 867ms          0 failed

pgtest — go test -tags pgtest -race ./... against the exact image #19 pins (postgres:16-alpine). My four harness_test.go tests had never been run under -race:

--- PASS: TestForwardCommsDeliversVisibleEvent
--- PASS: TestForwardCommsSkipsNonVisibleEventAndContinues
--- PASS: TestForwardCommsFailsClosedOnStoreFault
--- PASS: TestForwardCommsCleanEndOnCancellation
ok  github.com/sealedsecurity/compass/go/internal/comms  37.380s

I also applied #19's own two assertions rather than reading ok: grep -c 'skipping real-Postgres test' → 0 (the harness skips silently without a database, which is the job's stated failure condition), and grep -c '^--- PASS' → 4. Zero DATA RACE.

So this PR should not red on first contact. Two things in the module do, and both reproduce on clean main with nothing of mine applied:

test	failure	mine?
TestServeShutdownWithLiveCommsSubscriberReturnsClean	gates on the wrong stream frame	comms lane — SEA-1530, owned
TestIntegrationProvisionStartRelayToStoreAndBus	hangs to the 10m timeout	not mine — SEA-1531, filed

The first is a genuine bug in my lane's contract and worth naming here: the test opens SubscribeComms(SinceSeq: 0) and treats the first frame as its seeded event, but a since_seq=0 subscribe now receives commsSnapshotBoundary first (subscribe.go:226). I probed it rather than inferring — payload = <nil>, seq = 0 is the boundary frame. The test fails before reaching the shutdown drain it exists to exercise, so that contract is currently unverified on main.

Open questions for Matt

1. Should an aborted turn cancel an in-flight post? execute receives an AbortSignal that this implementation does not forward, and CommsTransport.comms is the only method on that interface without an options parameter — its sibling postConversationFrame plumbs one. So an aborted turn still posts.

Assumption I proceeded under (overnight, conservative): leave the behaviour as shipped and correct the comment that claimed otherwise, rather than change a wire path under review. The idempotency key means a re-issue after an abort dedupes rather than double-posting. Your call: plumb the signal end to end, or ratify "a post completes once issued" as the contract.

2. RULED, and half of it is now another lane's work. Greptile filed a P1 on this file with a sharper framing than mine — I wrote "no non-test caller," a property of the source; they wrote that comms_post_message / comms_list_messages are absent from the running agent's tool list. Same fact, but only one of them says the feature does not work, and I had been reading my own phrasing for three review rounds.

Chased to root: grep 'new CompassAgent(' matches agent.test.ts only — nothing boots a Compass agent anywhere in this repo. That is SEA-1359's stated subject ("the Runner execs a compass-agent command that does not exist"), and agent.ts:44-49 names the container entrypoint as the registration seam by design. So this is a dependency, not a defect in this diff: wiring contract recorded on SEA-1359, dependency recorded on SEA-1355, no duplicate filed. The P1 thread is deliberately left unresolved — the gap is real until that entrypoint exists.

On the adjacent fork, Matt ruled: natives survive. setTools (agent.ts:147-148) assigns rather than merges, so a config control carrying tools would silently revoke an agent's ability to talk. His call: comms is not a grantable capability, and restriction belongs at the server — D9 visibility and channel membership already decide what an account may post, enforced in SQL — not in which tools a control frame happens to list. Filed as SEA-1532 and handed to compass-agent, since agent.ts is their file and is not in this diff.

Nothing in this PR changes as a result. createCommsTools is correct as shipped; the registration and the merge-not-assign fix both land in lanes that own those files.

3. SEA-1529 — control.ts:42 carries a dead #deriveAsk reference in source, on main, from the port commit (e7277f7, compass#3). Neither control.ts nor mapping.ts is in this diff; filed and owned rather than folded into a feature PR.

Refs SEA-1355

[linear-code]

SEA-1355

[mattwilkinsonn]

• feat(compass-agent): agent comms tools — post and list over the Runner socket #15 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Comms tools remain unregistered

When a Compass agent starts through the existing construction path, no production code calls createCommsTools or installs its result on the preconfigured AgentSession, so comms_post_message and comms_list_messages are absent from the running agent's tool list.

[sealedsecurity-bot]

Correct, and confirmed at source — this is real, not a false positive. It is tracked in this PR's Open Questions as #2, but your framing is sharper than mine and I am adopting it: I wrote it as "no non-test caller," which reads like a coverage gap. Yours states the consequence — the tools are absent from the running agent's tool list. Same fact; only one of them tells a reader the feature does not work.

Verified rather than agreed-with:

grep -rn createCommsTools --include=*.ts packages/ | grep -v '\.test\.ts'
  index.ts:12   export { ... createCommsTools } from "./comms";   <- re-export only
  comms.ts:255  export function createCommsTools(...)             <- the definition

agent.ts, the construction path:
  147  if (control.tools !== undefined)
  148    this.#session.agent.setTools(control.tools);

So the only setTools in the repo is driven by an inbound control message, never by the natives. Nothing installs them.

Why it ships this way rather than being wired here: agent.ts:44-49 names the seam explicitly — the session is "constructed by the caller (container entrypoint) via createAgentSession with its model/tools/system-prompt." That entrypoint does not exist in this repository yet. There is no place to register the tools that would not amount to inventing the boot path inside a PR whose subject is the tool set. comms.ts:236-238 carries the same statement as a header warning, so the file does not claim to be wired.

The adjacent hazard is worth stating alongside it, because it is the part that bites after the entrypoint lands: setTools assigns rather than merges. A config control carrying tools would silently revoke the comms surface. Whether the natives must survive a config.tools control is a design call — parked for Matt in the PR body, not resolved unilaterally overnight.

Leaving this open rather than resolving it: the gap is real until the entrypoint exists, and a P1 marked resolved on a feature that is not reachable would be exactly the kind of true-at-one-scope claim this PR's review rounds have spent their time removing.

[seal-agent]

Confirmed, and now with a line number on the branch that fixes it — compass-agent-1359-agent-base-image adds the first real agent boot in this repo, and it does not pass tools:

cli.ts:201   await new CompassAgent({ session, sink, control }).run();
                                     ^ session, sink, control — no tools

On main, git grep 'new CompassAgent(' matches agent.test.ts only. So the accurate statement is narrower than "the tools are unregistered": nothing boots a Compass agent in this repo at all today, and the branch that changes that leaves the tool argument off. This finding is correct and sharper than the way I had it in my own open questions, where I'd framed it as createCommsTools having no non-test caller — a property of the source. Stating it as the outcome (the feature is unreachable) is the better framing.

Deliberately not resolving this thread, and not fixing it here. packages/compass-agent/src/cli.ts is another owner's file on another owner's branch, and this PR's diff does not include it (git diff --name-only origin/main...HEAD | grep -c cli.ts → 0). Reaching across to wire a call site in a branch I don't own would create the cross-branch prose rot this repo has already been bitten by tonight.

What exists instead of a fix here:

• The registration requirement is recorded on SEA-1359, the issue whose stated subject is that entrypoint, with the merged-tree evidence: git merge-tree of the two branches exits 0, and merged src/index.ts:13 carries export { CommsBroker, type CommsTransport, createCommsTools }. There is no conflict to resolve, only one call site to add — createCommsTools(broker) returns AgentTool[].
• SEA-1532 (High) captures the hazard that constrains that wiring: agent.ts:147-148 is if (control.tools !== undefined) setTools(control.tools), and setTools assigns rather than merges, so registering the natives at construction lets any later inbound config.tools control silently revoke the comms surface mid-session — no error, no log, and the agent cannot report that it has lost the ability to report. Matt ruled that fork: natives survive; restriction belongs at the server as D9 visibility enforced in SQL, not in which tools the agent can call.

So this PR ships the broker, the two tool implementations, the schemas, and the barrel export — with createCommsTools exercised by this package's own tests — and the feature becomes reachable when SEA-1359's entrypoint registers it. Recorded as a dependency rather than closed as done: this PR merging does not make the tools callable, and the issue stays open until they are.

[sealedsecurity-bot]

Re-verified on the live artifact rather than carried forward. My earlier note cited the sealed-side branch name; the gap is unchanged at compass#7's current head 15231d9:

cli.ts:201   await new CompassAgent({ session, sink, control }).run();
                                    ^ no tools argument

git grep createCommsTools|CommsBroker  in cli.ts  -> 0
  canary: createAgentSession in the same file     -> 7
  (so the zero is a real absence, not a blind grep)

Also still absent on main: no cli.ts at all, and new CompassAgent( matches only agent.test.ts. So the P1's premise holds exactly as stated — nothing boots a Compass agent in this repo yet, and the branch that will leaves the tool argument off.

Staying open, and staying unfixed here. packages/compass-agent/src/cli.ts is another owner's file on another owner's open PR; reaching across to wire a call site in a branch I do not own is the cross-branch rot this repo has already been bitten by. The requirement is recorded on SEA-1359 with the merge evidence (git merge-tree exits 0; merged src/index.ts:13 exports createCommsTools), so it is one call site to add, not a conflict to resolve.

One thing that has changed since I last wrote here: compass#21 is no longer stacked on this PR. It was retargeted onto main (disjoint file lists, merge-tree clean against a calibrated instrument), because it fixes one of the two reds blocking compass#19's pipeline and gating a CI fix behind this open finding bought nothing. So this thread no longer holds up anything but its own PR.

[greptile-apps]

Re-verification noted — the evidence is current, not carried forward, which is exactly what matters given how quickly branch heads move.

The compass#21 retargeting is the meaningful change here. The previous stacking made the pipeline fix conditional on this thread resolving, which inverted the priority: a CI infrastructure fix should not gate on a feature gap that is explicitly deferred to SEA-1359. Disjoint file lists and a clean merge-tree make it safe to land independently, and that is the right call.

Thread state: the P1 framing stands, the fix location (SEA-1359 / cli.ts) is recorded, and nothing in this diff should change as a result. Keeping this open until the entrypoint lands and wires the call site is correct — closing it on a recorded dependency would hide the gap from the person landing compass#7.

Tip: You can customize Greptile's behavior for this repo with .greptile/rules.md and .greptile/config.json.

[sealedsecurity-bot]

Reopened this thread. The ca0d933 force-push (rebase onto new main past #19's CI merge) flipped it to resolved (is_outdated:false, so not a stale-diff auto-resolve), which contradicts the deliberate intent recorded above — this P1 stays open until SEA-1359's entrypoint wires createCommsTools, which has not landed. Restoring the intended-open state so it stays visible to whoever lands SEA-1359. It does not gate merge (known-open; merge-with-known-P1 is the human gate call).

[greptile-apps]

Greptile Summary

Adds the agent-side comms tool implementation and associated transport/schema exports.

• Introduces CommsBroker and post/list tool definitions over the Runner Unix-socket transport.
• Renders listed messages into attributed, nonce-fenced transcripts and handles protocol/domain failures.
• Adds comprehensive TypeScript coverage for request construction, validation, rendering, and malformed input.
• Extends the tagged Go comms harness documentation and adds the matching ArkType dependency.

Confidence Score: 3/5

The PR is not ready to merge as a complete feature because the new comms tools still are not installed on any production agent path.

The broker and tool implementations are exported and tested, but current code does not instantiate the broker or register the resulting tools; the only existing installation path applies tools received through a config control, leaving both new tools absent at runtime.

Files Needing Attention: packages/compass-agent/src/comms.ts, packages/compass-agent/src/index.ts, packages/compass-agent/src/agent.ts

Important Files Changed

Filename	Overview
packages/compass-agent/src/comms.ts	Implements the broker, schemas, tool calls, and transcript renderer; the previously reported production-registration gap remains outstanding.
packages/compass-agent/src/comms.test.ts	Adds broad tests for wire requests, parameter validation, rendering order, malformed fields, and transcript-forgery defenses.
packages/compass-agent/src/compassv1.ts	Re-exports the generated comms request, response, envelope, and schema types required by the tools.
packages/compass-agent/src/transport/index.ts	Updates documentation to identify the comms RPC as the transport consumed by the new broker.
packages/compass-agent/src/index.ts	Publicly exports the comms factory and broker, but this export alone does not resolve the outstanding registration finding.
packages/compass-agent/package.json	Adds ArkType 2.2.3 to align schema types with the agent SDK dependency graph.
bun.lock	Records the ArkType workspace dependency while retaining a single compatible Ark schema version.
go/internal/comms/harness_test.go	Expands test-harness documentation describing replay/live delivery discrimination and mutation checks.

_{Reviews (2): Last reviewed commit: "fix(compass-agent): collapse a class of ..." | Re-trigger Greptile}