Severity: medium (design) · spans repos; normalization at packages/engine/src/engine/nodeContext.ts:35-40; error codes packages/types/src/fleet-wire.ts:311, engine/placement.ts, relay node_control.rs:1651-1658
Three coherence problems that force runtime translation and invite mis-mapping:
-
Same subsystem, two names: "fleet" in relay (fleet_wire.rs, FleetControlEvent, @agent-relay/fleet) and in the canonical types (FleetRelaycastToBrokerMessage) vs "node" in engine/cloud (NodeDO, node-control, /v1/node/ws, node.register). A spawned agent is a worker in the broker but an agent on the wire; provider is a third identity layered on nodes.
-
Three overlapping axes for one concept: node kind (fleet_ws/ws/direct_ws/http_push), node role, and delivery_adapter (fleet.ws.v1/direct.ws.v1/ws.node.v1) — the engine normalizes at runtime: if (adapter === 'fleet.ws.v1' || adapter === 'direct.ws.v1') return 'ws.node.v1' (nodeContext.ts:35-40).
-
Error codes are stringly-typed across the boundary: z.string() on the wire; the engine has a semi-enum (ProviderAttachConflictCode) but the broker treats error.code as an opaque string it only logs — it cannot react semantically (e.g. distinguish node_name_conflict from a transient rejection).
Recommendation: pick one term per concept (the spec's Agent/Node/Broker/Capability), collapse the kind/role/adapter triple, and export the engine's error codes as a shared enum the broker matches on.
Found during a multi-agent cross-repo architecture review of the relay tool/protocol.
Severity: medium (design) · spans repos; normalization at
packages/engine/src/engine/nodeContext.ts:35-40; error codespackages/types/src/fleet-wire.ts:311,engine/placement.ts, relaynode_control.rs:1651-1658Three coherence problems that force runtime translation and invite mis-mapping:
Same subsystem, two names: "fleet" in relay (
fleet_wire.rs,FleetControlEvent,@agent-relay/fleet) and in the canonical types (FleetRelaycastToBrokerMessage) vs "node" in engine/cloud (NodeDO,node-control,/v1/node/ws,node.register). A spawned agent is a worker in the broker but an agent on the wire; provider is a third identity layered on nodes.Three overlapping axes for one concept: node
kind(fleet_ws/ws/direct_ws/http_push), noderole, anddelivery_adapter(fleet.ws.v1/direct.ws.v1/ws.node.v1) — the engine normalizes at runtime:if (adapter === 'fleet.ws.v1' || adapter === 'direct.ws.v1') return 'ws.node.v1'(nodeContext.ts:35-40).Error codes are stringly-typed across the boundary:
z.string()on the wire; the engine has a semi-enum (ProviderAttachConflictCode) but the broker treatserror.codeas an opaque string it only logs — it cannot react semantically (e.g. distinguishnode_name_conflictfrom a transient rejection).Recommendation: pick one term per concept (the spec's Agent/Node/Broker/Capability), collapse the kind/role/adapter triple, and export the engine's error codes as a shared enum the broker matches on.
Found during a multi-agent cross-repo architecture review of the relay tool/protocol.