inter-agent-core 0.2.0__tar.gz

inter_agent_core-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,32 @@
+# Architecture
+
+`inter-agent-core` is a local WebSocket message bus for cooperating sessions.
+
+## Runtime
+
+The `inter_agent.core` package owns transport, TLS, authentication, endpoint and shared-secret resolution, session identity, routing, resource limits, server lifecycle, and generic command APIs. The default endpoint is `127.0.0.1:16837`.
+
+The server authenticates every connection with an HMAC-SHA-256 challenge-response using a shared secret. A connection becomes an agent session only after authentication. Direct messages route by name, broadcasts route to other agent sessions, and channels are in-memory pub/sub groups scoped to one server.
+
+## Protocol
+
+The protocol contract lives in [spec/](spec/):
+
+- `asyncapi.yaml` describes the transport contract.
+- `schemas/` contains operation schemas.
+- `examples/` contains canonical payloads.
+- `error-codes.md` defines machine-readable failures.
+
+`core.version` is a protocol capability, not the package version.
+
+## 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.
+
+Core does not ship host plugins, host adapters, marketplace metadata, or host-specific setup.
+
+## Lifecycle and transport
+
+Manual servers remain running until authenticated shutdown unless `--idle-timeout` is supplied. Loopback endpoints default to `ws://`; non-loopback endpoints default to `wss://` unless TLS is explicitly disabled. Clients must not downgrade a failed TLS connection to plaintext.
+
+Configuration resolves from explicit command options, environment, the inter-agent config file, then defaults. Secret resolution prefers `INTER_AGENT_SECRET`, then config `secret`, then a generated state-file token. Details and security assumptions are in [SECURITY.md](SECURITY.md).

inter_agent_core-0.2.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `inter-agent-core` are recorded here.
+
+## Versioning policy
+
+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.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.
+
+No protocol behavior changes are introduced by this repository extraction.

inter_agent_core-0.2.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arcanemachine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

inter_agent_core-0.2.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include ARCHITECTURE.md
+include SECURITY.md
+include CHANGELOG.md
+include LICENSE.md
+recursive-include docs *.md
+recursive-include spec *.yaml *.json *.md
+prune tests

inter_agent_core-0.2.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: inter-agent-core
+Version: 0.2.0
+Summary: Local authenticated message bus runtime and command-line tools
+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
+
+This project provides a way for agentic applications (e.g. coding harnesses) to talk to each other.
+
+`inter-agent-core` is a host-neutral Python runtime for a local, authenticated message bus. It provides the server, generic clients and commands, protocol contract, shared endpoint/secret state, routing, TLS, and lifecycle controls used by host extensions.
+
+Pi and Claude Code integrations are separate repositories:
+
+- [inter-agent-pi](https://github.com/arcanemachine/inter-agent-pi)
+- [inter-agent-claude-code](https://github.com/arcanemachine/inter-agent-claude-code)
+
+## Source checkout quick start
+
+```bash
+git clone https://github.com/arcanemachine/inter-agent-core.git
+cd inter-agent-core
+uv sync --locked
+uv run inter-agent-server
+```
+
+In another terminal, inspect the local bus:
+
+```bash
+uv run inter-agent-status
+uv run inter-agent-list
+```
+
+The default endpoint is `127.0.0.1:16837`. Local clients share endpoint and secret discovery through the same configuration/state rules. Use `inter-agent-shutdown` only when you intend to stop the shared server; it affects every connected client.
+
+## Generic commands
+
+```text
+inter-agent-server
+inter-agent-connect
+inter-agent-send
+inter-agent-list
+inter-agent-status
+inter-agent-shutdown
+inter-agent-kick
+inter-agent-publish
+inter-agent-channels
+```
+
+Use `--help` on a command for its options. Host-specific setup and session UX belong to the extension repositories.
+
+## Security
+
+The default design is one user on one machine. Connections authenticate with a shared secret. Loopback connections default to plaintext WebSockets; non-loopback connections default to TLS. TLS encrypts transport but does not protect against hostile code running as the same operating-system user.
+
+See [SECURITY.md](SECURITY.md) for the full model and [ARCHITECTURE.md](ARCHITECTURE.md) for protocol/runtime details.
+
+## Development
+
+```bash
+./run-checks.sh
+```
+
+Protocol schemas, examples, and canonical error codes are in [spec/](spec/).
+
+## License
+
+MIT

inter_agent_core-0.2.0/README.md

@@ -0,0 +1,62 @@
+# inter-agent-core
+
+This project provides a way for agentic applications (e.g. coding harnesses) to talk to each other.
+
+`inter-agent-core` is a host-neutral Python runtime for a local, authenticated message bus. It provides the server, generic clients and commands, protocol contract, shared endpoint/secret state, routing, TLS, and lifecycle controls used by host extensions.
+
+Pi and Claude Code integrations are separate repositories:
+
+- [inter-agent-pi](https://github.com/arcanemachine/inter-agent-pi)
+- [inter-agent-claude-code](https://github.com/arcanemachine/inter-agent-claude-code)
+
+## Source checkout quick start
+
+```bash
+git clone https://github.com/arcanemachine/inter-agent-core.git
+cd inter-agent-core
+uv sync --locked
+uv run inter-agent-server
+```
+
+In another terminal, inspect the local bus:
+
+```bash
+uv run inter-agent-status
+uv run inter-agent-list
+```
+
+The default endpoint is `127.0.0.1:16837`. Local clients share endpoint and secret discovery through the same configuration/state rules. Use `inter-agent-shutdown` only when you intend to stop the shared server; it affects every connected client.
+
+## Generic commands
+
+```text
+inter-agent-server
+inter-agent-connect
+inter-agent-send
+inter-agent-list
+inter-agent-status
+inter-agent-shutdown
+inter-agent-kick
+inter-agent-publish
+inter-agent-channels
+```
+
+Use `--help` on a command for its options. Host-specific setup and session UX belong to the extension repositories.
+
+## Security
+
+The default design is one user on one machine. Connections authenticate with a shared secret. Loopback connections default to plaintext WebSockets; non-loopback connections default to TLS. TLS encrypts transport but does not protect against hostile code running as the same operating-system user.
+
+See [SECURITY.md](SECURITY.md) for the full model and [ARCHITECTURE.md](ARCHITECTURE.md) for protocol/runtime details.
+
+## Development
+
+```bash
+./run-checks.sh
+```
+
+Protocol schemas, examples, and canonical error codes are in [spec/](spec/).
+
+## License
+
+MIT

inter_agent_core-0.2.0/SECURITY.md

@@ -0,0 +1,26 @@
+# Security model
+
+## Scope
+
+`inter-agent-core` is designed for one user on one machine. It binds to localhost by default. Localhost reduces network exposure but does not protect against hostile code running as the same operating-system user.
+
+Remote access, multi-user operation, and enterprise authorization are outside this model.
+
+## Controls
+
+- Every connection completes an HMAC-SHA-256 challenge-response using the resolved shared secret. The raw secret is not sent on the socket.
+- Secret resolution prefers `INTER_AGENT_SECRET`, then config `secret`, then a generated fallback token in the data directory.
+- 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.
+
+## 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.
+
+## Operations
+
+Use `inter-agent-shutdown` only to stop the shared server intentionally. It closes all active sessions. Use a separate endpoint and data directory for tests or isolated buses rather than reusing an existing bus.
+
+See [docs/SECURITY_BASELINE.md](docs/SECURITY_BASELINE.md) and [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) for the detailed baseline and boundaries.

inter_agent_core-0.2.0/docs/SECURITY_BASELINE.md

@@ -0,0 +1,10 @@
+# Security Baseline
+
+1. Bind the server to `127.0.0.1` by default.
+2. Require the shared bearer token in every `hello` handshake.
+3. Store the plaintext local token 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 token: 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/docs/THREAT_MODEL.md

@@ -0,0 +1,18 @@
+# Threat Model
+
+## In scope
+
+- Single user, single machine.
+- Localhost-only server by default; optional non-loopback binding with transport encryption.
+- Shared bearer token authentication over WebSockets.
+- 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.
+
+## Out of scope
+
+- Protection against malicious code already running as the same OS user.
+- Cross-machine trust, PKI lifecycle, mTLS, or remote transport hardening beyond transport encryption.
+- Multi-tenant permission isolation or enterprise RBAC.
+- Protection from a local process that can read or modify the user's inter-agent state directory contents.
+- Treating TLS as sufficient for safe remote or multi-user operation.

inter_agent_core-0.2.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "inter-agent-core"
+version = "0.2.0"
+description = "Local authenticated message bus runtime and command-line tools"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+  { name = "Nicholas Moen", email = "arcanemachine@gmail.com" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications",
+]
+dependencies = [
+  "cryptography==46.0.3",
+  "websockets==16.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/arcanemachine/inter-agent-core"
+Repository = "https://github.com/arcanemachine/inter-agent-core"
+Issues = "https://github.com/arcanemachine/inter-agent-core/issues"
+
+[project.scripts]
+inter-agent-server = "inter_agent.core.server:main"
+inter-agent-connect = "inter_agent.core.client:main"
+inter-agent-send = "inter_agent.core.send:main"
+inter-agent-list = "inter_agent.core.list:main"
+inter-agent-status = "inter_agent.core.status:main"
+inter-agent-shutdown = "inter_agent.core.shutdown:main"
+inter-agent-kick = "inter_agent.core.kick:main"
+inter-agent-publish = "inter_agent.core.publish:main"
+inter-agent-channels = "inter_agent.core.channels:main"
+
+[dependency-groups]
+dev = [
+  "pytest==9.0.3",
+  "pytest-asyncio==1.3.0",
+  "ruff==0.15.12",
+  "black==26.3.1",
+  "mypy==1.20.2",
+  "jsonschema==4.26.0",
+  "pyyaml==6.0.3",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+inter_agent = ["py.typed"]
+
+[tool.setuptools.data-files]
+"share/inter-agent/spec" = ["spec/asyncapi.yaml", "spec/error-codes.md"]
+"share/inter-agent/spec/schemas" = ["spec/schemas/*.json"]
+"share/inter-agent/spec/examples" = ["spec/examples/*.json"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.black]
+line-length = 100
+target-version = ["py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["yaml"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disallow_untyped_defs = false

inter_agent_core-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

inter_agent_core-0.2.0/spec/asyncapi.yaml

@@ -0,0 +1,225 @@
+asyncapi: 2.6.0
+id: urn:inter-agent:protocol
+info:
+  title: inter-agent protocol
+  version: 0.1.0
+  description: >
+    Minimal universal-friendly protocol for an inter-agent bus. Clients connect
+    over WebSocket (`ws://` or `wss://`) and start with `hello`, complete an
+    HMAC-SHA-256 challenge-response using a shared secret, then receive
+    `welcome`. Loopback hosts default to plaintext `ws://` unless TLS is
+    explicitly enabled; non-loopback hosts default to TLS `wss://` unless TLS
+    is explicitly disabled. Handshake capabilities are JSON objects: clients
+    declare optional known or extension keys in `hello`, and the server
+    advertises supported baseline capabilities in `welcome`. Unknown client
+    capability keys may be ignored.
+  contact:
+    name: Arcane Machine
+    url: https://github.com/arcanemachine/inter-agent
+    email: arcanemachine@gmail.com
+  license:
+    name: MIT
+    url: https://opensource.org/license/mit
+tags:
+  - name: agent-coordination
+defaultContentType: application/json
+servers:
+  default:
+    url: '{host}:{port}'
+    protocol: ws
+    description: >
+      The resolved local endpoint. Use wss with the same host and port when
+      TLS is enabled.
+    variables:
+      host:
+        default: 127.0.0.1
+      port:
+        default: '16837'
+channels:
+  /:
+    publish:
+      operationId: clientToServer
+      message:
+        oneOf:
+          - $ref: '#/components/messages/Hello'
+          - $ref: '#/components/messages/AuthResponse'
+          - $ref: '#/components/messages/Send'
+          - $ref: '#/components/messages/Broadcast'
+          - $ref: '#/components/messages/Ping'
+          - $ref: '#/components/messages/Bye'
+          - $ref: '#/components/messages/List'
+          - $ref: '#/components/messages/Shutdown'
+          - $ref: '#/components/messages/Kick'
+          - $ref: '#/components/messages/Custom'
+          - $ref: '#/components/messages/Subscribe'
+          - $ref: '#/components/messages/Unsubscribe'
+          - $ref: '#/components/messages/Publish'
+          - $ref: '#/components/messages/Channels'
+    subscribe:
+      operationId: serverToClient
+      message:
+        oneOf:
+          - $ref: '#/components/messages/AuthChallenge'
+          - $ref: '#/components/messages/Welcome'
+          - $ref: '#/components/messages/Msg'
+          - $ref: '#/components/messages/Pong'
+          - $ref: '#/components/messages/Error'
+          - $ref: '#/components/messages/ListOk'
+          - $ref: '#/components/messages/ShutdownOk'
+          - $ref: '#/components/messages/KickOk'
+          - $ref: '#/components/messages/SubscribeOk'
+          - $ref: '#/components/messages/UnsubscribeOk'
+          - $ref: '#/components/messages/ChannelsOk'
+components:
+  schemas:
+    Hello:
+      $ref: './schemas/hello.json'
+    AuthChallenge:
+      $ref: './schemas/auth_challenge.json'
+    AuthResponse:
+      $ref: './schemas/auth_response.json'
+    Welcome:
+      $ref: './schemas/welcome.json'
+    Send:
+      $ref: './schemas/send.json'
+    Broadcast:
+      $ref: './schemas/broadcast.json'
+    Ping:
+      $ref: './schemas/ping.json'
+    Pong:
+      $ref: './schemas/pong.json'
+    Bye:
+      $ref: './schemas/bye.json'
+    Msg:
+      $ref: './schemas/msg.json'
+    Error:
+      $ref: './schemas/error.json'
+    List:
+      $ref: './schemas/list.json'
+    ListOk:
+      $ref: './schemas/list_ok.json'
+    Shutdown:
+      $ref: './schemas/shutdown.json'
+    ShutdownOk:
+      $ref: './schemas/shutdown_ok.json'
+    Kick:
+      $ref: './schemas/kick.json'
+    KickOk:
+      $ref: './schemas/kick_ok.json'
+    Custom:
+      $ref: './schemas/custom.json'
+    Subscribe:
+      $ref: './schemas/subscribe.json'
+    SubscribeOk:
+      $ref: './schemas/subscribe_ok.json'
+    Unsubscribe:
+      $ref: './schemas/unsubscribe.json'
+    UnsubscribeOk:
+      $ref: './schemas/unsubscribe_ok.json'
+    Publish:
+      $ref: './schemas/publish.json'
+    Channels:
+      $ref: './schemas/channels.json'
+    ChannelsOk:
+      $ref: './schemas/channels_ok.json'
+  messages:
+    Hello:
+      messageId: inter-agent.hello
+      payload:
+        $ref: '#/components/schemas/Hello'
+    AuthChallenge:
+      messageId: inter-agent.auth-challenge
+      payload:
+        $ref: '#/components/schemas/AuthChallenge'
+    AuthResponse:
+      messageId: inter-agent.auth-response
+      payload:
+        $ref: '#/components/schemas/AuthResponse'
+    Welcome:
+      messageId: inter-agent.welcome
+      payload:
+        $ref: '#/components/schemas/Welcome'
+    Send:
+      messageId: inter-agent.send
+      payload:
+        $ref: '#/components/schemas/Send'
+    Broadcast:
+      messageId: inter-agent.broadcast
+      payload:
+        $ref: '#/components/schemas/Broadcast'
+    Ping:
+      messageId: inter-agent.ping
+      payload:
+        $ref: '#/components/schemas/Ping'
+    Pong:
+      messageId: inter-agent.pong
+      payload:
+        $ref: '#/components/schemas/Pong'
+    Bye:
+      messageId: inter-agent.bye
+      payload:
+        $ref: '#/components/schemas/Bye'
+    Msg:
+      messageId: inter-agent.msg
+      payload:
+        $ref: '#/components/schemas/Msg'
+    Error:
+      messageId: inter-agent.error
+      payload:
+        $ref: '#/components/schemas/Error'
+    List:
+      messageId: inter-agent.list
+      payload:
+        $ref: '#/components/schemas/List'
+    ListOk:
+      messageId: inter-agent.list-ok
+      payload:
+        $ref: '#/components/schemas/ListOk'
+    Shutdown:
+      messageId: inter-agent.shutdown
+      payload:
+        $ref: '#/components/schemas/Shutdown'
+    ShutdownOk:
+      messageId: inter-agent.shutdown-ok
+      payload:
+        $ref: '#/components/schemas/ShutdownOk'
+    Kick:
+      messageId: inter-agent.kick
+      payload:
+        $ref: '#/components/schemas/Kick'
+    KickOk:
+      messageId: inter-agent.kick-ok
+      payload:
+        $ref: '#/components/schemas/KickOk'
+    Custom:
+      messageId: inter-agent.custom
+      payload:
+        $ref: '#/components/schemas/Custom'
+    Subscribe:
+      messageId: inter-agent.subscribe
+      payload:
+        $ref: '#/components/schemas/Subscribe'
+    SubscribeOk:
+      messageId: inter-agent.subscribe-ok
+      payload:
+        $ref: '#/components/schemas/SubscribeOk'
+    Unsubscribe:
+      messageId: inter-agent.unsubscribe
+      payload:
+        $ref: '#/components/schemas/Unsubscribe'
+    UnsubscribeOk:
+      messageId: inter-agent.unsubscribe-ok
+      payload:
+        $ref: '#/components/schemas/UnsubscribeOk'
+    Publish:
+      messageId: inter-agent.publish
+      payload:
+        $ref: '#/components/schemas/Publish'
+    Channels:
+      messageId: inter-agent.channels
+      payload:
+        $ref: '#/components/schemas/Channels'
+    ChannelsOk:
+      messageId: inter-agent.channels-ok
+      payload:
+        $ref: '#/components/schemas/ChannelsOk'

inter_agent_core-0.2.0/spec/error-codes.md

@@ -0,0 +1,28 @@
+# Error Codes
+
+Protocol errors are returned as `{"op":"error","code":"...","message":"..."}`. The `code` field is stable for clients and adapters; `message` is human-readable context and may vary.
+
+| Code | Trigger condition | Client expectation |
+| --- | --- | --- |
+| `PROTOCOL_ERROR` | The first frame is not `hello`, a frame is invalid JSON, a frame is not a JSON object, or authenticated `hello.capabilities` is missing or not an object. | Treat the connection as invalid and reconnect with a valid protocol frame. |
+| `AUTH_FAILED` | Challenge-response auth is missing, malformed, or proves the client does not know the shared secret. | Do not retry until server and client secret configuration has been corrected; see the secret rotation procedure in `SECURITY.md`. |
+| `TOO_MANY_CONNECTIONS` | A valid connection attempt would exceed the configured active connection limit. | Close unused sessions or increase the local connection limit. |
+| `BAD_ROLE` | `hello.role` is missing or is not `agent` or `control`, or an agent-role session attempts a control-only operation such as `shutdown`. | Send a valid role or use a control-role connection for control-only operations. |
+| `BAD_SESSION` | `hello.session_id` is missing, empty, or not a string. | Generate and send a string session ID. |
+| `SESSION_TAKEN` | `hello.session_id` is already active on another connection. | Reconnect after the previous connection closes or generate a new session ID. |
+| `BAD_NAME` | An agent `hello.name` is missing or fails routing-name validation. | Choose a lowercase routing name matching the documented name format. |
+| `BAD_LABEL` | `hello.label` is present but is neither a string nor `null`. | Omit the label, send `null`, or send a string display label. |
+| `NAME_TAKEN` | An agent routing name is already connected. | Choose a different routing name or disconnect the existing session. |
+| `UNKNOWN_OP` | A post-handshake frame uses an unsupported `op`. | Use a supported core operation or an extension envelope. |
+| `BAD_TEXT` | A `send`, `broadcast`, or `publish` operation has a non-string `text`. | Send message text as a string. |
+| `BAD_FROM_NAME` | A message operation has a non-string `from_name`. | Omit `from_name` or send it as a string. |
+| `BAD_CUSTOM_TYPE` | A `custom` operation has a missing, empty, non-string, or oversized `custom_type`. | Send a non-empty custom type within the configured byte limit. |
+| `TEXT_TOO_LARGE` | A direct or broadcast message exceeds configured UTF-8 byte text limits (`INTER_AGENT_DIRECT_MAX` or `INTER_AGENT_BROADCAST_MAX`). | Shorten or split the message. |
+| `CUSTOM_PAYLOAD_TOO_LARGE` | A `custom.payload` exceeds the configured JSON-encoded UTF-8 byte limit (`INTER_AGENT_CUSTOM_PAYLOAD_MAX`). | Shorten or split the custom payload. |
+| `UNKNOWN_TARGET` | A direct `send` or targeted `custom` operation names no connected target. | Refresh session presence and retry with a connected routing name. |
+| `AMBIGUOUS_TARGET` | A direct `send` or targeted `custom` operation uses a prefix that matches multiple connected targets. | Retry with a longer prefix or exact routing name. |
+| `BAD_CHANNEL` | A channel operation has a missing, non-string, syntactically invalid, or oversized `channel` value. | Send a valid channel name matching the documented format and byte limit. |
+| `CHANNEL_LIMIT_REACHED` | A subscription would exceed the per-session subscription limit (`INTER_AGENT_SUBSCRIPTIONS_MAX`) or creating a channel would exceed the server channel limit (`INTER_AGENT_CHANNELS_MAX`). | Leave unused channels or increase the configured limit. |
+| `NOT_SUBSCRIBED` | An `unsubscribe` targets a channel the session is not subscribed to. | Subscribe before unsubscribing, or ignore if already unsubscribed. |
+| `UNKNOWN_CHANNEL` | A `publish` targets a channel with no active subscribers. | Subscribe at least one session to the channel before publishing. |
+| `KICKED` | A control-role caller removed this connection with `kick`. The error is sent immediately before the target WebSocket is closed. | Treat the error as terminal for this listener process: stop automatic reconnects. The routing name is free immediately and may register again through an explicit later connect or host/session reload/restart; there is no ban or blocklist. |

inter_agent_core-0.2.0/spec/examples/auth_challenge.json

@@ -0,0 +1,6 @@
+{
+  "op": "auth_challenge",
+  "method": "hmac-sha256",
+  "server_nonce": "server-nonce",
+  "server_proof": "server-proof-hex"
+}

inter_agent_core-0.2.0/spec/examples/auth_response.json

@@ -0,0 +1,4 @@
+{
+  "op": "auth_response",
+  "client_proof": "client-proof-hex"
+}

inter_agent_core-0.2.0/spec/examples/broadcast.json

@@ -0,0 +1,4 @@
+{
+  "op": "broadcast",
+  "text": "build is green"
+}

inter_agent_core-0.2.0/spec/examples/bye.json

@@ -0,0 +1,3 @@
+{
+  "op": "bye"
+}

inter_agent_core-0.2.0/spec/examples/channels.json

@@ -0,0 +1,3 @@
+{
+  "op": "channels"
+}