node-red-contrib-ax25 1.0.0

package/.eslintignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+build/
+coverage/
+*.min.js

package/.prettierignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+build/
+coverage/
+package-lock.json
+yarn.lock
+pnpm-lock.yaml

package/ARCHITECTURE.md

@@ -0,0 +1,174 @@
+# Architecture: node-red-contrib-ax25
+
+## Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Node-RED flow                                              │
+│  (inject, function, debug, etc.)                            │
+└──────────────────────┬──────────────────────────────────────┘
+                       │ msg
+┌──────────────────────▼──────────────────────────────────────┐
+│  Node layer  (nodes/)                                       │
+│  agwpe-client · connect · send · disconnect                 │
+│  ui-out · ui-in · monitor-in · raw-out · raw-in             │
+│  decode · encode                                            │
+└──────┬───────────────────────────┬──────────────────────────┘
+       │ transport calls           │ routed frames
+┌──────▼──────────┐   ┌────────────▼──────────────────────────┐
+│ AgwpeClient     │   │ FrameRouter                           │
+│ Transport       │   │ (lib/frame-router.js)                 │
+│ (lib/agwpe-     │   │ routes parsed frames to per-instance  │
+│  client-        │   │ handler callbacks by frame kind       │
+│  transport.js)  │   └──────────────┬────────────────────────┘
+│                 │                  │ handler callbacks
+│  Node.js        │   ┌──────────────▼────────────────────────┐
+│  net.Socket     │   │ SessionRegistry                       │
+│  EventEmitter   │   │ (lib/session-registry.js)             │
+└──────┬──────────┘   │ tracks Ax25Session lifecycle per      │
+       │ raw bytes    │ instance; maps serverSessionId ↔      │
+       │              │ sessionId                             │
+       │              └───────────────────────────────────────┘
+       │
+┌──────▼──────────────────────────────────────────────────────┐
+│  AGWPE server (external)                                    │
+│  TCP port 8000 (default)                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Shared lib modules
+
+| Module | Role |
+|--------|------|
+| `agwpe-client-transport.js` | Wraps `net.Socket`; emits `connected`, `error`, `close`, and raw `frame` events; injectable `socketFactory` for testing |
+| `agwpe-frame-builder.js` | Builds AGWPE binary frame headers for each frame kind (P, X, C, D, U, K, m, M) |
+| `agwpe-frame-pretty.js` | Debug-friendly AGWPE frame formatting for transport logging |
+| `ax25-codec.js` | AX.25 frame encode/decode (callsign bit-shifting, via path, control, PID, payload) |
+| `frame-router.js` | Parses raw AGWPE bytes into typed frame objects; dispatches to per-instance handler maps |
+| `frame-segmentation.js` | Splits outbound payloads into ≤255-byte chunks; attaches `messageId`/`chunkIndex`/`chunkCount` metadata |
+| `message-utils.js` | `nowTimestamp()`, `makeMessageId()` — shared across nodes and lib |
+| `runtime-store.js` | In-memory store for per-instance context objects; also hosts a module-level `globalBus` (EventEmitter forwarding `conn-data`, `conn-lifecycle`, `conn-timeout-set` from all instances) and a `sessionIndex` map (`sessionId → instanceId`) that lets `send` resolve the correct instance at runtime without a static client reference |
+| `session-registry.js` | CRUD for `Ax25Session` records; indexes by `instanceId` + `sessionId` and by `serverSessionId` |
+
+## Node internals pattern
+
+Most nodes follow this structural pattern:
+
+```
+node constructor
+  ├── validate config
+  ├── resolve agwpe-client instance (RED.nodes.getNode) ← all nodes except send
+  ├── register handler callbacks on agwpe-client's FrameRouter
+      node.on("input", ...)   ← triggers on any message
+        ├── connect           (connect node — uses msg.destination)
+        ├── send              (send, ui-out, raw-out — uses msg.payload)
+        └── disconnect        (disconnect node — uses msg.sessionId)
+
+node.on("close", ...)
+  └── deregister from FrameRouter; destroy transport if agwpe-client
+```
+
+## AGWPE frame kind to Node-RED node routing
+
+| AGWPE frame kind | Emitted to node |
+|------------------|-----------------|
+| D (connected data) | `connect` or `send` — matched by session callsign pair |
+| C (connect/disconnect lifecycle) | `connect` — lifecycle event |
+| U / K (UI/raw) | `ui-in` or `raw-in` — gated by mode flag |
+| M / m (monitor) | `monitor-in` — gated by `monitorEnabled` flag |
+| X (callsign registration ACK) | consumed by `agwpe-client` internally |
+| P (login/auth) | consumed by `agwpe-client` internally |
+
+## Session index and global bus
+
+`runtime-store` maintains a module-level `sessionIndex` map (`sessionId → instanceId`). The `connect` node writes to this index when a session is created and removes the entry on disconnect. The `send` node uses `instanceIdForSession(sessionId)` at message-handling time to look up the correct instance — no static client reference is needed.
+
+`runtime-store` also hosts a `globalBus` EventEmitter. Each instance `bus` forwards `conn-data`, `conn-lifecycle`, and `conn-timeout-set` events to `globalBus` so `send` nodes can subscribe once for all instances.
+
+## connect node transport status
+
+The `connect` node mirrors the transport state of its `agwpe-client` as a Node-RED status badge:
+
+| agwpe-client state | connect node status |
+|--------------------|---------------------|
+| connecting | yellow dot — `connecting` |
+| connected | green dot — `ready` |
+| reconnecting | yellow ring — `reconnecting...` |
+| disconnected | grey ring — `disconnected` |
+| failed | red dot — `failed` |
+
+On startup, the connect node reads `context.state` to set the initial status immediately. Ongoing changes are driven by `transport-connecting`, `transport-connected`, `transport-reconnecting`, `transport-closed`, and `failed` events on the instance bus.
+
+## Session lifecycle state machine
+
+```
+connecting → connected → disconnecting → disconnected
+     ├──────────────────────────────────────→ failed
+     └──────────────────────────────────────→ connect-failed (d-frame before C-frame confirmed)
+```
+
+Transitions are driven by AGWPE C-frame events and transport errors. On any transport failure all sessions in the owning instance transition to `failed` immediately.
+
+## Message shape contracts
+
+### connect node input
+
+```json
+{ "source": "N0CALL", "destination": "REMOTE-1" }
+```
+
+### send node input
+
+```json
+{ "sessionId": "sess-abc", "payload": "hello" }
+```
+
+### disconnect node input
+
+```json
+{ "sessionId": "sess-abc" }
+```
+
+### Standard success output envelope
+
+```json
+{ "timestamp": "…", "status": "ok", "instanceId": "…",
+  "sessionId": "opt", "event": "connected" }
+```
+
+### Standard error output envelope
+
+```json
+{ "timestamp": "…", "status": "error",
+  "errorCode": "AUTH_FAILED", "errorText": "…",
+  "instanceId": "…", "sessionId": "opt" }
+```
+
+### Outbound chunk envelope (attached per segment by send, ui-out)
+
+```json
+{ "messageId": "msg-abc", "chunkIndex": 0, "chunkCount": 3, "payload": "…" }
+```
+
+Payloads ≤255 bytes produce a single chunk (`chunkIndex: 0`, `chunkCount: 1`).
+
+### Inbound data envelope (connect, send, ui-in)
+
+```json
+{ "timestamp": "…", "instanceId": "…", "sessionId": "…",
+  "event": "data", "payload": "…",
+  "source": "REMOTE-1", "destination": "N0CALL", "via": [] }
+```
+
+Each received AGWPE frame is emitted immediately. No grouping metadata is added — there is no way to know whether the remote intended several frames as one logical payload.
+
+## Testability design
+
+- `AgwpeClientTransport` accepts an injectable `socketFactory` — tests pass a fake factory that returns a mock socket
+- `FrameRouter` and `SessionRegistry` are stateless relative to the transport and can be instantiated and exercised independently
+- `node-red-node-test-helper` is used for all integration-level tests; no live AGWPE server required
+
+## Extension points for future work
+
+- **Inbound reassembly**: an optional reassembly buffer keyed on a session + sequence, with a configurable flush timeout
+- **TLS transport**: replacing `net.createConnection` with `tls.connect` via the existing `socketFactory` injection point

package/CONTEXT.md

@@ -0,0 +1,90 @@
+# Project Context: node-red-contrib-ax25
+
+## What this is
+
+A Node-RED contrib package that enables AX.25 packet radio connectivity through an AGWPE (AGW Packet Engine) server. Radio amateurs use it to integrate packet radio into Node-RED flows — connecting to BBSs, digipeaters, and other AX.25 stations.
+
+The package provides ten custom nodes covering connected sessions, unconnected UI frames, monitor mode, raw frames, and AX.25 encode/decode. It manages two distinct connection layers: one TCP connection to the AGWPE server, and multiple concurrent AX.25 protocol sessions to remote stations.
+
+## Target users
+
+Radio amateurs and enthusiasts running Node-RED who want to interact with AX.25 packet radio networks without writing socket code.
+
+## Runtime environment
+
+- Node.js 20 LTS, CommonJS modules
+- Node-RED 3.x+
+- No external runtime dependencies (only Node.js `net` and `events`)
+
+## Key design decisions
+
+**Auto-reconnect is on by default.** When the AGWPE transport drops, all owned sessions are marked disconnected and the node automatically attempts to reconnect after a configurable delay (default 5000 ms). Auto-reconnect can be disabled via the "Auto-Reconnect" checkbox in the config editor. When disabled, all sessions fail and the flow must re-deploy or restart to reconnect.
+
+**`agwpe-client` is a config node.** It does not receive messages. All configuration (host, port, callsigns, auth, monitor/raw mode, reconnect settings) is set in the Node-RED editor. The connection is established automatically when the flow deploys. There is no `open`/`close` command interface.
+
+**Per-instance connection ownership.** Each `agwpe-client` node manages one AGWPE TCP connection. All downstream nodes (`conn-out`, `conn-in`, `ui-in`, `ui-out`, `monitor-in`, `raw-in`, `raw-out`) bind to a specific `agwpe-client` instance by `instanceId`. Cross-instance routing is not allowed.
+
+**Inbound data follows the last active node.** Received data for a connected session is routed to whichever `connect` or `send` node most recently processed a command for that session. When a `send` node handles a command, it takes over the data output for that session; when the session is first established by `connect`, data goes to `connect`'s output. This lets flows chain request/response steps naturally: each node in the chain receives the reply to its own send.
+
+**Binary and line modes.** The `connect` node's `mode` setting (default: `line`) controls how inbound data is delivered on output port 2:
+
+- **binary** — each received frame emitted immediately; `payload` is a Buffer.
+- **line** — fragments are buffered and split on CR or CR+LF; each complete line is emitted with `payload` as a string. If `waitFor` (a regex) is set, lines accumulate until one matches; the output message then contains `payload` (array of preceding lines) and `match` (the matching line). If the timeout fires before a match, a `timeout` event is emitted on port 1 along with whatever has buffered so far.
+
+`mode` and `waitFor` can be set on the node and overridden per-message via `msg.mode` and `msg.waitFor`.
+
+**Payload output type.** Several nodes have a `payloadOutput` editor option (`"string"` or `"buffer"`, default `"string"`) that controls whether the AX.25 data payload is delivered as a UTF-8 string or a raw Buffer:
+
+- `ui-in` — decoded AX.25 UI frame payload
+- `decode` — decoded AX.25 frame payload
+
+`raw-in` always emits payload as a Buffer (raw AX.25 wire bytes, leading AGWPE port byte stripped). `connect` and `send` payload type is governed by `mode` as described above.
+
+**Outbound segmentation at 255 bytes.** Payloads larger than 255 bytes are segmented into multiple AGWPE frames before transmission.
+
+**Optional auth.** `username` and `password` fields in the config node editor pass AGWPE-level credentials. Many LAN deployments omit them.
+
+## Message contract summary
+
+All output messages include `timestamp` (ISO-8601). Errors always include `errorCode` and `errorText`. Connected session events include `instanceId`, `sessionId`, and `event` (`connected`, `disconnecting`, `disconnected`, `failed`, `timeout`). Inbound data messages include `instanceId`, `sessionId`, `event: "data"`, `payload`, `source`, `destination`, and `via`. Outbound segmented sends attach `messageId`, `chunkIndex`, and `chunkCount` to each chunk.
+
+Full contract details are in [README.md](README.md).
+
+## Node list
+
+| Node | Direction | Role |
+|------|-----------|------|
+| `agwpe-client` | config | Owns the AGWPE TCP connection; configured in the editor; connects on deploy |
+| `connect` | in + 2 out | Establish an AX.25 session; output 1: lifecycle events; output 2: received data |
+| `send` | in + 2 out | Send data or disconnect on an established session; output 1: events; output 2: received data |
+| `ui-out` | data in | Encode and send AX.25 UI frames via AGWPE K raw transport |
+| `ui-in` | data out | Decode incoming AGWPE K raw traffic to AX.25 UI frame fields |
+| `monitor-in` | data out | Passive monitor stream (monitor mode must be enabled) |
+| `raw-out` | data in | Send raw AGWPE frames (raw mode must be enabled) |
+| `raw-in` | data out | Receive raw AGWPE frames (raw mode must be enabled) |
+| `decode` | transform | AX.25 frame bytes → JSON (source, destination, via, control, PID, payload) |
+| `encode` | transform | Structured JSON → raw AX.25 frame bytes |
+
+## Test strategy
+
+Three test layers under `test/`:
+
+- **contract/** — message shape and field validation, independent of Node-RED wiring
+- **integration/** — full node loading + wiring with `node-red-node-test-helper`; covers open/close flows, session lifecycle, routing, segmentation, mode toggling
+- **unit/** — isolated lib module behavior (codec, segmentation, router, registry)
+
+Transport boundaries are mocked; no live AGWPE server is required for any test.
+
+## Project layout
+
+```text
+nodes/          runtime JS + editor HTML for all ten node types
+lib/            shared internals (transport, router, registry, codec, segmentation)
+test/           contract / integration / unit test suites
+examples/       importable Node-RED example flows
+docs/           development guidance (AI working agreement, Node-RED patterns)
+```
+
+## Known limitations and deferred work
+
+- No TLS support for the AGWPE TCP transport

package/MESSAGES.md

@@ -0,0 +1,314 @@
+# Node Messages Reference
+
+All messages include a `timestamp` (ISO 8601 string).  
+Messages with `status: "ok"` are built by `okEnvelope(fields)`.  
+Messages with `status: "error"` are built by `errorEnvelope(errorCode, errorText, fields)` and always include `errorCode` and `errorText`.
+
+---
+
+## agwpe-client
+
+Configuration node. No inputs or outputs.
+
+---
+
+## connect
+
+Initiates an AX.25 connected session. Two outputs: **output 1** (events), **output 2** (data).
+
+### Input
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `source` | string | no¹ | Calling callsign. Falls back to node config, then first registered callsign. |
+| `destination` | string | no¹ | Called callsign. Falls back to node config. |
+| `via` | string \| string[] | no | Digipeater path. Falls back to node config. |
+| `sessionId` | string | no | Override the auto-generated session ID. |
+| `mode` | `"line"` \| `"binary"` | no | Data framing mode. Falls back to node config (default: `"line"`). |
+| `timeout` | number | no | Inactivity timeout in milliseconds. Falls back to node config. |
+| `waitFor` | string | no | Regex pattern. Buffers inbound lines until a match; then emits all at once. Falls back to node config. |
+
+¹ Required unless provided by node config or registered callsign.
+
+### Output 1 — events
+
+#### `status: "ok"` messages
+
+| `event` | Additional fields | When |
+|---|---|---|
+| `connecting` | `instanceId`, `sessionId`, `source`, `destination`, `via` | C frame sent to TNC |
+| `connected` | `instanceId`, `sessionId`, `source`, `destination`, `called` | TNC confirmed connection |
+| `disconnecting` | `instanceId`, `sessionId`, `source`, `destination` | Disconnect initiated |
+| `disconnected` | `instanceId`, `sessionId`, `source`, `destination` | TNC confirmed disconnect |
+
+#### `status: "error"` messages
+
+| `errorCode` | `errorText` | Additional fields | When |
+|---|---|---|---|
+| `CLIENT_NOT_CONNECTED` | `AGWPE Client is not open` | `instanceId` | Input received while transport is not connected |
+| `CONNECT_INVALID` | `connect requires source and destination` | `instanceId` | Source or destination could not be resolved |
+| `SESSION_ID_CONFLICT` | `Session already exists` | `instanceId` | Supplied `sessionId` is already in use |
+| `SESSION_ID_REUSED` | `Server session ID collision detected` | `instanceId`, `sessionId`, `serverSessionId` | TNC reused a session ID for a different session |
+| `CONNECT_FAILED` | `Connection attempt failed` | `instanceId`, `sessionId`, `source`, `destination` | TNC sent a `d` frame before ever confirming with a `C` frame |
+| `TIMEOUT` | `Inactivity timeout` | `instanceId`, `sessionId`, `event: "timeout"` | Inactivity timer expired (binary mode) |
+| `TIMEOUT` | `Inactivity timeout` | `instanceId`, `sessionId`, `event: "timeout"`, `waitFor`, `lineBuffer`, `waitForBuffer` | waitFor timer expired before the regex matched (line mode) |
+
+> **Note:** Timeout messages may be emitted by a **send** node instead of the connect node if a send node currently holds the output claim for the session.
+
+### Output 2 — data
+
+All data messages have `status: "ok"`, `event: "data"`, `instanceId`, `sessionId`, `source`, `destination`, `via`.
+
+| Mode | `payload` type | `match` field | When |
+|---|---|---|---|
+| `binary` | `Buffer` | — | Inbound D frame received |
+| `line` (no waitFor) | `string` | — | One complete line received (CR or CR+LF delimited) |
+| `line` (waitFor active) | `string[]` — lines before the match | `string` — the matching line or fragment | First line matching the waitFor regex arrives |
+| `line` (disconnect flush) | `string[]` — buffered lines | — | Session disconnects while lines are buffered |
+
+---
+
+## send
+
+Sends data over an existing AX.25 connected session. Two outputs: **output 1** (events), **output 2** (data).
+
+### Input
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `sessionId` | string | yes | ID of the target session |
+| `payload` | string \| Buffer \| Array<string\|Buffer> | yes | Data to send. Arrays are sent as separate D frames. |
+| `waitFor` | string | no | Regex pattern. Claims data output and buffers until a match. Falls back to node config. |
+| `timeout` | number | no | Override inactivity timeout in milliseconds. Falls back to node config. |
+
+### Output 1 — events
+
+#### `status: "ok"` messages
+
+| `event` | Additional fields | When |
+|---|---|---|
+| `sent` | `instanceId`, `sessionId`, `messageId`, `chunkCount` | All payload items delivered to TNC |
+
+#### `status: "error"` messages
+
+| `errorCode` | `errorText` | Additional fields | When |
+|---|---|---|---|
+| `SESSION_NOT_FOUND` | `Session not found` | `sessionId` | `msg.sessionId` not in the session registry |
+| `SESSION_NOT_CONNECTED` | `Session is not connected` | `sessionId` | Session exists but state is not `"connected"` |
+| `PAYLOAD_INVALID` | `payload items must be string or Buffer` | `sessionId` | A payload item is not a string or Buffer |
+| `TIMEOUT` | `Inactivity timeout` | (same as connect timeout) | Timer fired while this node holds the output claim |
+
+### Output 2 — data
+
+Same shape as connect output 2. The send node takes the data output claim when it processes an input; data arrives on this output until the session disconnects or a different send node claims it.
+
+---
+
+## disconnect
+
+Initiates graceful disconnect of an existing session. One output (events).
+
+### Input
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `sessionId` | string | yes | ID of the session to disconnect |
+
+### Output — events
+
+#### `status: "ok"` messages
+
+| `event` | Additional fields | When |
+|---|---|---|
+| `disconnecting` | `instanceId`, `sessionId` | Disconnect frame sent to TNC |
+
+#### `status: "error"` messages
+
+| `errorCode` | `errorText` | Additional fields | When |
+|---|---|---|---|
+| `SESSION_NOT_FOUND` | `Session not found` | `sessionId` | `msg.sessionId` not in the session registry |
+
+> The corresponding `disconnected` event is emitted by the **connect** node when the TNC confirms with a `d` frame.
+
+---
+
+## raw-in
+
+Receives raw AX.25 frames (K frames) from the TNC. No input. One output.
+
+Raw mode must be enabled on the agwpe-client node.
+
+### Output
+
+| `status` | `event` | Fields | Description |
+|---|---|---|---|
+| `ok` | `raw` | `instanceId`, `payload` (Buffer), `agwpePort`, `source`, `destination`, `via` | Raw AX.25 wire frame received from TNC |
+
+---
+
+## raw-out
+
+Transmits a raw AX.25 frame (K frame) via the TNC. One output.
+
+Raw mode must be enabled on the agwpe-client node.
+
+### Input
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `payload` | Buffer \| Uint8Array \| byte array \| hex string \| encode envelope | yes | AX.25 wire frame to transmit |
+| `agwpePort` | number | no | AGWPE port (0–255). Falls back to `msg.flag`, then node config (default: `0`). |
+
+### Output
+
+#### `status: "ok"` messages
+
+| `event` | Additional fields | When |
+|---|---|---|
+| `raw-sent` | `instanceId` | Frame handed to transport |
+
+#### `status: "error"` messages
+
+| `errorCode` | `errorText` | When |
+|---|---|---|
+| `CLIENT_NOT_FOUND` | `AGWPE Client instance not found` | agwpe-client config node is missing |
+| `RAW_MODE_DISABLED` | `Raw mode is disabled` | Raw mode not enabled on agwpe-client |
+| `RAW_FRAME_INVALID` | `Raw frame payload/agwpePort is invalid; payload must be Buffer, byte array, Uint8Array, hex string, or encode envelope` | Payload could not be parsed or `agwpePort` is out of range |
+
+---
+
+## monitor-in
+
+Receives monitored AX.25 frames from the TNC (all traffic, not just connected sessions). No input. One output.
+
+Monitor mode must be enabled on the agwpe-client node.
+
+### Output
+
+| `status` | `event` | Fields | Description |
+|---|---|---|---|
+| `ok` | `monitor` | `instanceId`, `payload` (Buffer), `source`, `destination`, `via` | Monitored frame received |
+
+---
+
+## encode
+
+Encodes an AX.25 frame from field inputs into a wire-format Buffer. One output.
+
+### Input
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `source` | string | no¹ | Source callsign. Falls back to node config (default: `"N0CALL"`). |
+| `destination` | string | no¹ | Destination callsign. Falls back to node config (default: `"CQ"`). |
+| `via` | string \| string[] \| object[] | no | Digipeater path. Falls back to node config. |
+| `frameType` | `"I"` \| `"S"` \| `"U"` | no | Determines control byte if `control` is not set. Falls back to node config (default: `"U"`). |
+| `control` | number (0–255) | no | Explicit control byte. Overrides `frameType`. Falls back to node config (default: `3`). |
+| `pid` | number (0–255) | no | Protocol identifier byte. Falls back to node config (default: `240` / `0xF0`). |
+| `payload` | string \| Buffer | no | Frame payload. Falls back to node config. |
+| `agwpePort` | number | no | Passed through to output for use by raw-out. |
+
+¹ Required unless provided by node config.
+
+### Output
+
+#### `status: "ok"` messages
+
+| `event` | Additional fields | When |
+|---|---|---|
+| `encoded` | `payload` (Buffer), `agwpePort` | Frame successfully encoded |
+
+#### `status: "error"` messages
+
+| `errorCode` | `errorText` | When |
+|---|---|---|
+| `ENCODE_INPUT_INVALID` | `source, destination, and control/frameType are required` | Required fields missing |
+| `ENCODE_FAILED` | codec error message | Codec rejected the input |
+
+---
+
+## decode
+
+Decodes a wire-format AX.25 frame Buffer into structured fields. One output.
+
+### Input
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `payload` | Buffer | yes | AX.25 wire-format frame |
+| `agwpePort` | number | no | Passed through to output. Falls back to `msg.agwpePrefix`, then `0`. |
+
+### Output
+
+#### `status: "ok"` messages
+
+Fields from the decoded frame, plus:
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | `"ok"` | |
+| `agwpePort` | number | Normalized AGWPE port |
+| `source` | string | Source callsign |
+| `destination` | string | Destination callsign |
+| `via` | object[] | Digipeater path |
+| `control` | number | Control byte |
+| `pid` | number | PID byte |
+| `payload` | string \| Buffer | Frame payload (string if node config `payloadOutput` is `"string"`) |
+
+#### `status: "error"` messages
+
+| `errorCode` | `errorText` | When |
+|---|---|---|
+| `DECODE_INPUT_INVALID` | `payload must be Buffer` | Input payload is not a Buffer |
+| `DECODE_FAILED` | codec error message | Codec rejected the frame |
+
+---
+
+## ui-in
+
+Receives UI (unproto) AX.25 frames from raw traffic. No input. One output.
+
+Raw mode must be enabled on the agwpe-client node.
+
+### Output
+
+| `status` | `event` | Fields | Description |
+|---|---|---|---|
+| `ok` | `ui` | `instanceId`, `source`, `destination`, `via`, `payload` (string or Buffer) | UI frame received (`payload` is string if node config `payloadOutput` is `"string"`) |
+
+---
+
+## ui-out
+
+Transmits a UI (unproto) AX.25 frame via the TNC. One output.
+
+Raw mode must be enabled on the agwpe-client node.
+
+### Input
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `source` | string | no¹ | Source callsign. Falls back to node config. |
+| `destination` | string | no¹ | Destination callsign. Falls back to node config. |
+| `via` | string \| string[] \| object[] | no | Digipeater path. Falls back to node config. |
+| `payload` | string \| Buffer | no¹ | Frame payload. Falls back to node config. |
+| `agwpePort` | number | no | AGWPE port. Falls back to `0`. |
+
+¹ Required unless provided by node config.
+
+### Output
+
+#### `status: "ok"` messages
+
+| `event` | Additional fields | When |
+|---|---|---|
+| `ui-sent` | `instanceId` | UI frame handed to transport |
+
+#### `status: "error"` messages
+
+| `errorCode` | `errorText` | When |
+|---|---|---|
+| `CLIENT_NOT_FOUND` | `AGWPE Client instance not found` | agwpe-client config node is missing |
+| `RAW_MODE_DISABLED` | `Raw mode is disabled` | Raw mode not enabled on agwpe-client |
+| `UI_SEND_INVALID` | `ui-out requires source, destination, and payload (set in editor or input message)` | Required fields missing or empty |
+| `UI_SEND_INVALID` | codec error message | Frame encoding failed |