inter-agent-core 0.2.0__tar.gz → 0.3.0__tar.gz

{inter_agent_core-0.2.0 → inter_agent_core-0.3.0}/ARCHITECTURE.md

@@ -19,9 +19,17 @@ The protocol contract lives in [spec/](spec/):
 
 `core.version` is a protocol capability, not the package version.
 
+### Persistent custom messages
+
+`AgentSession.send_custom(custom_type, payload, to)` is a typed host-neutral API for a targeted generic custom envelope. It reuses the persistent authenticated connection, session identity, reader, inbox, and serialized command lock. The request contains only the generic custom type, pass-through payload, and routing target; Core does not define the receiver's custom schema or semantics and does not expose a caller-supplied sender identity through this API.
+
+After writing the custom frame, the session writes an application-level `ping` and waits for its ordered `pong`. Server frame ordering makes that `pong` a response barrier: routing errors from the preceding custom operation are consumed and returned before the barrier, while unrelated inbound frames remain in the inbox. The local result reports `submitted` only after the barrier arrives without a routing error. This is evidence of local server-side submission processing, not evidence of delivery, receiver acceptance, or application completion.
+
+A barrier timeout, connection failure, or cancellation closes the session before the operation returns or propagates. This fail-closed teardown prevents a late routing error or barrier from leaking into the ordinary inbound queue. Custom envelopes remain bounded by the existing custom-type, payload, and WebSocket frame limits; the private local adapter bridge additionally retains its strict 64 KiB request/response bound.
+
 ## Extension boundary
 
-Host extensions own host interaction, listener lifetime, rendering, and host-local state. Python extensions use the typed core command and listener APIs. The narrow `inter_agent.core.adapter_control` module provides a same-user local control socket for a host listener's subscribe/unsubscribe operations; it does not carry the bus secret.
+Host extensions own host interaction, listener lifetime, rendering, and host-local state. Python extensions use the typed core command and listener APIs. The narrow `inter_agent.core.adapter_control` module provides a same-user local control socket for a host listener's subscribe/unsubscribe operations and an optional strict generic custom-send operation; it does not carry the bus secret. Existing channel handlers keep their original `(op, channel)` signature and behavior. The custom bridge accepts only `op`, `custom_type`, `payload`, and `to`, with no caller-supplied identity or other operation.
 
 Core does not ship host plugins, host adapters, marketplace metadata, or host-specific setup.
 

{inter_agent_core-0.2.0 → inter_agent_core-0.3.0}/CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to `inter-agent-core` are recorded here.
 
 The Python distribution version in `pyproject.toml` is the source of truth for core artifacts. The protocol capability `core.version` is a compatibility value and is versioned independently from the Python distribution.
 
+## 0.3.0
+
+Release-ready host-neutral custom-message support adds a persistent-session `send_custom` API and a strict local adapter bridge operation. Custom sends preserve the authenticated session identity, use an ordered response barrier to isolate routing errors, and fail closed on barrier or connection failure without claiming delivery. The generic core continues to pass through custom type and payload data without defining host-specific semantics.
+
+No publication, tag, or push is implied by this entry.
+
 ## 0.2.0
 
 Clean standalone baseline for the host-neutral inter-agent runtime. It includes the local authenticated server, generic command-line clients, protocol contract, TLS/authentication/state behavior, and the typed `inter_agent.core.adapter_control` extension-support API.

inter_agent_core-0.3.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: inter-agent-core
+Version: 0.3.0
+Summary: A local websocket-based message bus that allows your agentic coding harnesses to talk to each other.
+Author-email: Nicholas Moen <arcanemachine@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arcanemachine/inter-agent-core
+Project-URL: Repository, https://github.com/arcanemachine/inter-agent-core
+Project-URL: Issues, https://github.com/arcanemachine/inter-agent-core/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: cryptography==46.0.3
+Requires-Dist: websockets==16.0
+Dynamic: license-file
+
+# inter-agent-core
+
+`inter-agent-core` is the host-neutral Python runtime for a local authenticated message bus. It provides the WebSocket server, protocol, routing, channels, TLS, shared state, and generic command-line clients used by host integrations such as [Pi](https://github.com/arcanemachine/inter-agent-pi), [Claude Code](https://github.com/arcanemachine/inter-agent-claude-code), and [OpenCode](https://github.com/arcanemachine/inter-agent-opencode).
+
+## Requirements
+
+- Python 3.10 or newer
+- [`uv`](https://docs.astral.sh/uv/) for the installation and development commands below
+
+## Install
+
+Create an isolated environment and install the released `0.3.0` package:
+
+```bash
+uv venv .venv
+source .venv/bin/activate
+uv pip install inter-agent-core==0.3.0
+```
+
+The package installs the `inter-agent-*` command-line clients and the `inter-agent` Python API. On Windows, activate `.venv` with the equivalent PowerShell or Command Prompt command. Contributors working from a checkout should use the separate development procedure below instead of installing the registry package into that checkout’s environment.
+
+## Quick start
+
+Start the bus in one terminal:
+
+```bash
+inter-agent-server
+```
+
+In a second terminal, connect a named client and leave it listening:
+
+```bash
+inter-agent-connect alice
+```
+
+In a third terminal, inspect the bus and send a direct message:
+
+```bash
+inter-agent-status
+inter-agent-list
+inter-agent-send alice "hello from the command line"
+```
+
+The `alice` terminal receives the message as a JSON protocol frame. Stop a foreground server with `Ctrl-C`. Use `inter-agent-shutdown` only when you intend to disconnect every client on that shared bus.
+
+By default, local clients use `127.0.0.1:16837` and discover the same generated secret from the shared state directory. If you configure a different endpoint, data directory, or secret, use the same values for every client and server.
+
+### Persistent custom messages
+
+A host integration with an established `AgentSession` can send a generic targeted custom envelope with `send_custom(custom_type, payload, to)`. The method reuses that session's authenticated connection, routing identity, reader, inbox, and serialized command lock; it does not create another connection or accept a caller-supplied sender identity. `to` is a target routing name or an unambiguous target prefix, and `payload` is passed through for the receiving integration to interpret.
+
+The method sends the custom frame followed by an ordered application-level `ping` barrier. A routing error observed before the matching `pong` is returned as an unsuccessful local result. `submitted` is true only after the barrier is observed without such an error: it means the server finished processing the preceding frame on that connection, not that a target received, accepted, or acted on the payload. The generic core does not define the custom type or payload schema.
+
+If the barrier times out, the connection closes, or the operation is cancelled, the session fails closed before returning or propagating the failure. The late routing error and barrier cannot enter the ordinary inbound queue; a listener may establish a replacement session according to its own lifecycle. Custom envelopes and local bridge exchanges remain subject to the existing protocol, frame, and 64 KiB local-bridge limits.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `inter-agent-server` | Run the message bus. Use `--idle-timeout N` for an idle auto-shutdown. |
+| `inter-agent-connect <name>` | Join as a named agent and print incoming protocol frames. |
+| `inter-agent-send <name> <text>` | Send a direct message. Omit the target and use `--text` to broadcast. |
+| `inter-agent-list` | List connected agent sessions. |
+| `inter-agent-status` | Show endpoint resolution and server reachability. Use `--json` for structured output. |
+| `inter-agent-publish <channel> <text>` | Publish to an existing channel. |
+| `inter-agent-channels` | List channels and their subscribers. |
+| `inter-agent-kick <name>` | Disconnect an agent session. |
+| `inter-agent-shutdown` | Stop the server and disconnect every session. |
+
+Every command supports `--help`. Endpoint-aware commands also accept `--host`, `--port`, `--tls` or `--no-tls`, and TLS certificate overrides.
+
+Use direct messages for normal coordination. Use broadcasts only when every connected session needs the message. Channels are in-memory groups owned by one server and disappear when that server stops.
+
+## Configuration and security
+
+Configuration resolves in this order: command-line options, environment variables, the JSON configuration file, then built-in defaults. The main environment variables are:
+
+- `INTER_AGENT_HOST` and `INTER_AGENT_PORT` — endpoint overrides;
+- `INTER_AGENT_SECRET` — an explicit shared secret;
+- `INTER_AGENT_DATA_DIR` — state, generated secret, and generated TLS material;
+- `INTER_AGENT_CONFIG` — an alternate JSON configuration file;
+- `INTER_AGENT_TLS`, `INTER_AGENT_TLS_CERT`, and `INTER_AGENT_TLS_KEY` — TLS settings.
+
+Loopback endpoints default to plaintext `ws://`. Non-loopback endpoints default to TLS `wss://`; clients never downgrade a failed TLS connection automatically.
+
+The default trust boundary is one trusted operating-system user on one machine. HMAC-SHA-256 authentication prevents clients without the shared secret from joining, and TLS protects network transport, but neither protects against hostile code running as the same user. Do not commit or share secrets, private keys, certificates, or state. See [`SECURITY.md`](SECURITY.md) and the detailed [`threat model`](docs/THREAT_MODEL.md).
+
+For a common failure, run `inter-agent-status` first. If clients cannot authenticate, check that they resolve the same endpoint, state directory, and secret. Use a separate endpoint and data directory for tests or isolated buses rather than disturbing an existing one.
+
+## Reference and development
+
+- [`spec/`](spec/) — protocol definition, schemas, examples, and error codes
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — runtime and extension boundaries
+- [`CHANGELOG.md`](CHANGELOG.md) — released changes
+- [`README.md#commands`](#commands) — generic CLI reference
+- [inter-agent-pi](https://github.com/arcanemachine/inter-agent-pi) — Pi integration
+- [inter-agent-claude-code](https://github.com/arcanemachine/inter-agent-claude-code) — Claude Code integration
+- [inter-agent-opencode](https://github.com/arcanemachine/inter-agent-opencode) — OpenCode integration
+
+Host-specific commands, listeners, rendering, and tools belong in those extension repositories; this package supplies the shared runtime.
+
+For development, clone the repository and run:
+
+```bash
+git clone https://github.com/arcanemachine/inter-agent-core.git
+cd inter-agent-core
+uv sync --locked
+./run-checks.sh
+```
+
+## License
+
+MIT. See [`LICENSE.md`](LICENSE.md).

inter_agent_core-0.3.0/README.md

@@ -0,0 +1,113 @@
+# inter-agent-core
+
+`inter-agent-core` is the host-neutral Python runtime for a local authenticated message bus. It provides the WebSocket server, protocol, routing, channels, TLS, shared state, and generic command-line clients used by host integrations such as [Pi](https://github.com/arcanemachine/inter-agent-pi), [Claude Code](https://github.com/arcanemachine/inter-agent-claude-code), and [OpenCode](https://github.com/arcanemachine/inter-agent-opencode).
+
+## Requirements
+
+- Python 3.10 or newer
+- [`uv`](https://docs.astral.sh/uv/) for the installation and development commands below
+
+## Install
+
+Create an isolated environment and install the released `0.3.0` package:
+
+```bash
+uv venv .venv
+source .venv/bin/activate
+uv pip install inter-agent-core==0.3.0
+```
+
+The package installs the `inter-agent-*` command-line clients and the `inter-agent` Python API. On Windows, activate `.venv` with the equivalent PowerShell or Command Prompt command. Contributors working from a checkout should use the separate development procedure below instead of installing the registry package into that checkout’s environment.
+
+## Quick start
+
+Start the bus in one terminal:
+
+```bash
+inter-agent-server
+```
+
+In a second terminal, connect a named client and leave it listening:
+
+```bash
+inter-agent-connect alice
+```
+
+In a third terminal, inspect the bus and send a direct message:
+
+```bash
+inter-agent-status
+inter-agent-list
+inter-agent-send alice "hello from the command line"
+```
+
+The `alice` terminal receives the message as a JSON protocol frame. Stop a foreground server with `Ctrl-C`. Use `inter-agent-shutdown` only when you intend to disconnect every client on that shared bus.
+
+By default, local clients use `127.0.0.1:16837` and discover the same generated secret from the shared state directory. If you configure a different endpoint, data directory, or secret, use the same values for every client and server.
+
+### Persistent custom messages
+
+A host integration with an established `AgentSession` can send a generic targeted custom envelope with `send_custom(custom_type, payload, to)`. The method reuses that session's authenticated connection, routing identity, reader, inbox, and serialized command lock; it does not create another connection or accept a caller-supplied sender identity. `to` is a target routing name or an unambiguous target prefix, and `payload` is passed through for the receiving integration to interpret.
+
+The method sends the custom frame followed by an ordered application-level `ping` barrier. A routing error observed before the matching `pong` is returned as an unsuccessful local result. `submitted` is true only after the barrier is observed without such an error: it means the server finished processing the preceding frame on that connection, not that a target received, accepted, or acted on the payload. The generic core does not define the custom type or payload schema.
+
+If the barrier times out, the connection closes, or the operation is cancelled, the session fails closed before returning or propagating the failure. The late routing error and barrier cannot enter the ordinary inbound queue; a listener may establish a replacement session according to its own lifecycle. Custom envelopes and local bridge exchanges remain subject to the existing protocol, frame, and 64 KiB local-bridge limits.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `inter-agent-server` | Run the message bus. Use `--idle-timeout N` for an idle auto-shutdown. |
+| `inter-agent-connect <name>` | Join as a named agent and print incoming protocol frames. |
+| `inter-agent-send <name> <text>` | Send a direct message. Omit the target and use `--text` to broadcast. |
+| `inter-agent-list` | List connected agent sessions. |
+| `inter-agent-status` | Show endpoint resolution and server reachability. Use `--json` for structured output. |
+| `inter-agent-publish <channel> <text>` | Publish to an existing channel. |
+| `inter-agent-channels` | List channels and their subscribers. |
+| `inter-agent-kick <name>` | Disconnect an agent session. |
+| `inter-agent-shutdown` | Stop the server and disconnect every session. |
+
+Every command supports `--help`. Endpoint-aware commands also accept `--host`, `--port`, `--tls` or `--no-tls`, and TLS certificate overrides.
+
+Use direct messages for normal coordination. Use broadcasts only when every connected session needs the message. Channels are in-memory groups owned by one server and disappear when that server stops.
+
+## Configuration and security
+
+Configuration resolves in this order: command-line options, environment variables, the JSON configuration file, then built-in defaults. The main environment variables are:
+
+- `INTER_AGENT_HOST` and `INTER_AGENT_PORT` — endpoint overrides;
+- `INTER_AGENT_SECRET` — an explicit shared secret;
+- `INTER_AGENT_DATA_DIR` — state, generated secret, and generated TLS material;
+- `INTER_AGENT_CONFIG` — an alternate JSON configuration file;
+- `INTER_AGENT_TLS`, `INTER_AGENT_TLS_CERT`, and `INTER_AGENT_TLS_KEY` — TLS settings.
+
+Loopback endpoints default to plaintext `ws://`. Non-loopback endpoints default to TLS `wss://`; clients never downgrade a failed TLS connection automatically.
+
+The default trust boundary is one trusted operating-system user on one machine. HMAC-SHA-256 authentication prevents clients without the shared secret from joining, and TLS protects network transport, but neither protects against hostile code running as the same user. Do not commit or share secrets, private keys, certificates, or state. See [`SECURITY.md`](SECURITY.md) and the detailed [`threat model`](docs/THREAT_MODEL.md).
+
+For a common failure, run `inter-agent-status` first. If clients cannot authenticate, check that they resolve the same endpoint, state directory, and secret. Use a separate endpoint and data directory for tests or isolated buses rather than disturbing an existing one.
+
+## Reference and development
+
+- [`spec/`](spec/) — protocol definition, schemas, examples, and error codes
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — runtime and extension boundaries
+- [`CHANGELOG.md`](CHANGELOG.md) — released changes
+- [`README.md#commands`](#commands) — generic CLI reference
+- [inter-agent-pi](https://github.com/arcanemachine/inter-agent-pi) — Pi integration
+- [inter-agent-claude-code](https://github.com/arcanemachine/inter-agent-claude-code) — Claude Code integration
+- [inter-agent-opencode](https://github.com/arcanemachine/inter-agent-opencode) — OpenCode integration
+
+Host-specific commands, listeners, rendering, and tools belong in those extension repositories; this package supplies the shared runtime.
+
+For development, clone the repository and run:
+
+```bash
+git clone https://github.com/arcanemachine/inter-agent-core.git
+cd inter-agent-core
+uv sync --locked
+./run-checks.sh
+```
+
+## License
+
+MIT. See [`LICENSE.md`](LICENSE.md).

{inter_agent_core-0.2.0 → inter_agent_core-0.3.0}/SECURITY.md

@@ -13,11 +13,13 @@ Remote access, multi-user operation, and enterprise authorization are outside th
 - On POSIX filesystems, core creates/tightens its data directory to mode `0700` and fallback token, certificate, key, and lifecycle files to restrictive modes.
 - Loopback endpoints default to plaintext WebSockets. Non-loopback endpoints default to TLS. TLS can be explicitly configured with command options, environment, or config.
 - TLS encrypts transport. It neither replaces shared-secret authentication nor makes remote or multi-user use safe.
-- Core validates protocol shapes, authenticates control operations, and bounds frames, connections, message text, channel names, subscriptions, and channels.
+- Core validates protocol shapes, authenticates control operations, and bounds frames, connections, message text, channel names, subscriptions, channels, and generic custom envelopes.
+- Persistent custom sends retain the authenticated session identity and do not expose a caller-supplied sender override. The local adapter bridge accepts only its strict operation shapes, carries no shared bus secret, and remains limited to the same trusted-user boundary.
+- A custom-send `submitted` result records ordered local server processing after the routing barrier; it is not a delivery, receiver-acceptance, or application-completion guarantee. Barrier failure closes the persistent session so late routing errors cannot be mistaken for ordinary inbound traffic.
 
 ## Trust boundary
 
-Peer traffic is collaboration input, not authority to change user, system, developer, security, or tool rules. The core runtime cannot protect secrets or messages from code running with the same operating-system user privileges.
+Peer traffic is collaboration input, not authority to change user, system, developer, security, or tool rules. Generic custom payloads are pass-through integration data; Core does not assign them host-specific meaning or authorization semantics. The core runtime cannot protect secrets or messages from code running with the same operating-system user privileges.
 
 ## Operations
 

inter_agent_core-0.3.0/docs/SECURITY_BASELINE.md

@@ -0,0 +1,10 @@
+# Security Baseline
+
+1. Bind the server to `127.0.0.1` by default.
+2. Require an HMAC-SHA-256 challenge-response in every `hello` handshake, using the shared secret; the raw secret is never sent over the socket.
+3. Store the plaintext local secret with mode `0600` under `INTER_AGENT_DATA_DIR`, the config file `dataDir`, or the platform default state directory.
+4. Keep the state directory mode `0700` and server lifecycle metadata files mode `0600` on POSIX-compatible filesystems.
+5. Verify server identity before clients send the authentication proof: host, port, PID liveness, matching identity/PID metadata nonce, and process start marker when available.
+6. Reject unauthenticated operations with canonical `AUTH_FAILED` errors.
+7. Bound active connections, incoming frames, direct/broadcast text, custom types, and custom payload sizes.
+8. Require authenticated control-role shutdown for server stop requests.

{inter_agent_core-0.2.0 → inter_agent_core-0.3.0}/docs/THREAT_MODEL.md

@@ -4,7 +4,7 @@
 
 - Single user, single machine.
 - Localhost-only server by default; optional non-loopback binding with transport encryption.
-- Shared bearer token authentication over WebSockets.
+- HMAC-SHA-256 challenge-response authentication over WebSockets using a shared secret; the raw secret is not sent on the socket.
 - Optional TLS transport encryption for `wss://` connections.
 - Server proof verification by clients before sending authentication responses.
 - Defensive controls against accidental or mild local misuse: restrictive state-file permissions, resource limits, duplicate-session rejection, and authenticated shutdown.

{inter_agent_core-0.2.0 → inter_agent_core-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "inter-agent-core"
-version = "0.2.0"
-description = "Local authenticated message bus runtime and command-line tools"
+version = "0.3.0"
+description = "A local websocket-based message bus that allows your agentic coding harnesses to talk to each other."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"

{inter_agent_core-0.2.0 → inter_agent_core-0.3.0}/src/inter_agent/core/adapter_control.py

@@ -1,14 +1,18 @@
 """Private local Unix-domain socket control bridge.
 
-Short-lived adapter commands (``subscribe``, ``unsubscribe``) talk to the
-matching live agent listener through a local Unix-domain socket instead of
-opening a new agent or control identity on the bus. One newline-delimited
-JSON request and response are exchanged per connection.
+Short-lived adapter commands (``subscribe``, ``unsubscribe``, and the strict
+``custom`` send) talk to the matching live agent listener through a local
+Unix-domain socket instead of opening a new agent or control identity on the
+bus. One newline-delimited JSON request and response are exchanged per
+connection.
 
 The bridge is strictly local and private: it never carries the shared server
-secret and never accepts anything but ``subscribe`` and ``unsubscribe``
-requests. Each endpoint is derived from the adapter, normalized endpoint,
-and routing name so distinct listeners never collide on the socket path.
+secret and never accepts anything but ``subscribe``, ``unsubscribe``, and the
+strict targeted ``custom`` request (exactly ``op``, ``custom_type``,
+``payload``, and ``to``). Caller-supplied ``from_name``, secret material, and
+any other key are rejected. Each endpoint is derived from the adapter,
+normalized endpoint, and routing name so distinct listeners never collide on
+the socket path.
 """
 
 from __future__ import annotations
@@ -30,10 +34,15 @@ SUPPORTED_OPS = frozenset({"subscribe", "unsubscribe"})
 #: oversized line raises ``LimitOverrunError`` before the length check.
 _READ_LIMIT = CONTROL_MAX_REQUEST_BYTES + 1
 
-#: Exactly the request keys the bridge accepts. Any other key is rejected so a
-#: compromised or buggy command cannot exfiltrate state through the bridge.
+#: Exactly the request keys the bridge accepts for channel ops. Any other
+#: key is rejected so a compromised or buggy command cannot exfiltrate state
+#: through the bridge.
 _REQUEST_KEYS = frozenset({"op", "channel"})
 
+#: Exactly the request keys the bridge accepts for the strict custom send.
+#: ``from_name``, secrets, and any other key are rejected outright.
+_CUSTOM_REQUEST_KEYS = frozenset({"op", "custom_type", "payload", "to"})
+
 #: Amount of the SHA-256 digest carried in the socket filename so the path
 #: stays bounded regardless of name length.
 _SOCKET_HASH_LEN = 16
@@ -45,6 +54,12 @@ class ControlError(Exception):
 
 RequestHandler = Callable[[str, str], Awaitable[dict[str, object]]]
 
+#: Optional handler for the strict targeted ``custom`` send: receives the
+#: custom type, the pass-through payload, and the required routing target.
+#: Kept separate from ``RequestHandler`` so the existing subscribe/unsubscribe
+#: signature stays unchanged for existing listeners.
+CustomRequestHandler = Callable[[str, object, str], Awaitable[dict[str, object]]]
+
 
 def _normalize_host(host: str) -> str:
     return host.strip().lower()
@@ -126,9 +141,15 @@ class ControlServer:
     rather than left in a permissive state or allowed to break the listener.
     """
 
-    def __init__(self, path: Path, handle: RequestHandler) -> None:
+    def __init__(
+        self,
+        path: Path,
+        handle: RequestHandler,
+        custom_handler: CustomRequestHandler | None = None,
+    ) -> None:
         self._path = path
         self._handle = handle
+        self._custom_handle = custom_handler
         self._server: asyncio.Server | None = None
         self._inode: int | None = None
         self._dev: int | None = None
@@ -229,6 +250,9 @@ class ControlServer:
                     writer, _local_error("BAD_REQUEST", "control request must be an object")
                 )
                 return
+            if payload.get("op") == "custom":
+                await self._handle_custom_request(writer, payload)
+                return
             if set(payload.keys()) != _REQUEST_KEYS:
                 await _write_line(
                     writer,
@@ -243,14 +267,7 @@ class ControlServer:
             if not isinstance(channel, str) or not channel:
                 await _write_line(writer, _local_error("BAD_CHANNEL", "channel required"))
                 return
-            try:
-                response = await asyncio.wait_for(
-                    self._handle(op, channel), timeout=CONTROL_TIMEOUT_S
-                )
-            except TimeoutError:
-                response = _local_error("TIMEOUT", "listener did not respond in time")
-            except Exception as exc:  # listener-side failure, never propagate as traceback
-                response = _local_error("LISTENER_UNAVAILABLE", str(exc))
+            response = await self._run_handler(self._handle(op, channel))
             await _write_line(writer, response)
         finally:
             try:
@@ -259,6 +276,47 @@ class ControlServer:
             except (OSError, asyncio.CancelledError, BrokenPipeError):
                 pass
 
+    async def _handle_custom_request(
+        self, writer: asyncio.StreamWriter, payload: dict[str, object]
+    ) -> None:
+        """Validate and dispatch one strict targeted custom-send request.
+
+        The op is already known to be ``custom``. The request must contain
+        exactly ``op``, ``custom_type``, ``payload``, and ``to``; anything else
+        (including ``from_name`` or secret material) is rejected before any
+        handler runs. The custom handler is optional: a server without one
+        rejects the request without touching the channel handler.
+        """
+        if self._custom_handle is None:
+            await _write_line(writer, _local_error("BAD_OP", "unsupported control op"))
+            return
+        if set(payload.keys()) != _CUSTOM_REQUEST_KEYS:
+            message = "control request must contain only op, custom_type, payload, and to"
+            await _write_line(writer, _local_error("BAD_REQUEST", message))
+            return
+        custom_type = payload.get("custom_type")
+        if not isinstance(custom_type, str) or not custom_type:
+            await _write_line(writer, _local_error("BAD_CUSTOM_TYPE", "custom_type required"))
+            return
+        to = payload.get("to")
+        if not isinstance(to, str) or not to:
+            await _write_line(writer, _local_error("BAD_TO", "to required"))
+            return
+        response = await self._run_handler(
+            self._custom_handle(custom_type, payload.get("payload"), to)
+        )
+        await _write_line(writer, response)
+
+    async def _run_handler(self, handler: Awaitable[dict[str, object]]) -> dict[str, object]:
+        """Await a listener handler with the same timeout/exception mapping for
+        every request kind."""
+        try:
+            return await asyncio.wait_for(handler, timeout=CONTROL_TIMEOUT_S)
+        except TimeoutError:
+            return _local_error("TIMEOUT", "listener did not respond in time")
+        except Exception as exc:  # listener-side failure, never propagate as traceback
+            return _local_error("LISTENER_UNAVAILABLE", str(exc))
+
     async def stop(self) -> None:
         await self._close_server()
         await self._unlink_owned(self._inode, self._dev)
@@ -284,25 +342,13 @@ class ControlServer:
                 pass
 
 
-async def request(
-    adapter: str,
-    host: str,
-    port: int,
-    name: str,
-    base_data_dir: Path,
-    op: str,
-    channel: str,
-) -> dict[str, object]:
-    """Send one control request to the listener owning ``name``'s socket.
+async def _request_payload(path: Path, payload: dict[str, object]) -> dict[str, object]:
+    """Exchange one strict request/response over ``path`` with clean error mapping.
 
-    Path/setup, connect, read, and decode failures are converted to clean
+    Path/connect, read, and decode failures are converted to clean
     ``ControlError`` diagnostics; oversized or malformed responses raise rather
-    than returning partial data.
+    than returning partial data. ``payload`` must be JSON-serializable.
     """
-    try:
-        path = control_socket_path(adapter, host, port, name, base_data_dir)
-    except OSError as exc:
-        raise ControlError(f"control socket unavailable: {exc}") from exc
     try:
         reader, writer = await asyncio.wait_for(
             asyncio.open_unix_connection(str(path), limit=_READ_LIMIT),
@@ -318,8 +364,7 @@ async def request(
         raise ControlError(f"listener control connection failed: {exc}") from exc
 
     try:
-        request_payload = json.dumps({"op": op, "channel": channel}) + "\n"
-        writer.write(request_payload.encode("utf-8"))
+        writer.write((json.dumps(payload, ensure_ascii=False) + "\n").encode("utf-8"))
         try:
             await asyncio.wait_for(writer.drain(), timeout=CONTROL_TIMEOUT_S)
         except TimeoutError as exc:
@@ -342,9 +387,64 @@ async def request(
     if len(raw) > CONTROL_MAX_REQUEST_BYTES:
         raise ControlError("oversized response from listener")
     try:
-        payload: object = json.loads(raw.decode("utf-8"))
+        response_value: object = json.loads(raw.decode("utf-8"))
     except (json.JSONDecodeError, UnicodeDecodeError) as exc:
         raise ControlError("malformed response from listener") from exc
-    if not isinstance(payload, dict):
+    if not isinstance(response_value, dict):
         raise ControlError("response from listener must be an object")
-    return {str(key): value for key, value in payload.items()}
+    return {str(key): value for key, value in response_value.items()}
+
+
+async def request(
+    adapter: str,
+    host: str,
+    port: int,
+    name: str,
+    base_data_dir: Path,
+    op: str,
+    channel: str,
+) -> dict[str, object]:
+    """Send one channel control request to the listener owning ``name``'s socket.
+
+    Path/setup, connect, read, and decode failures are converted to clean
+    ``ControlError`` diagnostics; oversized or malformed responses raise rather
+    than returning partial data.
+    """
+    try:
+        path = control_socket_path(adapter, host, port, name, base_data_dir)
+    except OSError as exc:
+        raise ControlError(f"control socket unavailable: {exc}") from exc
+    return await _request_payload(path, {"op": op, "channel": channel})
+
+
+async def request_custom(
+    adapter: str,
+    host: str,
+    port: int,
+    name: str,
+    base_data_dir: Path,
+    custom_type: str,
+    payload: object,
+    to: str,
+) -> dict[str, object]:
+    """Send one strict targeted custom-send request to ``name``'s listener.
+
+    Carries a custom type, a pass-through JSON payload, and a required routing
+    target. The listener rejects any other key (``from_name``, secret material,
+    or anything else) before a handler runs; the bridge never carries the
+    shared server secret. Failures map to the same clean ``ControlError``
+    diagnostics as ``request``.
+    """
+    try:
+        path = control_socket_path(adapter, host, port, name, base_data_dir)
+    except OSError as exc:
+        raise ControlError(f"control socket unavailable: {exc}") from exc
+    return await _request_payload(
+        path,
+        {
+            "op": "custom",
+            "custom_type": custom_type,
+            "payload": payload,
+            "to": to,
+        },
+    )