relayforge 0.1.0__tar.gz

relayforge-0.1.0/.env.example

@@ -0,0 +1,2 @@
+DISCORD_BOT_TOKEN=
+RELAY_CONFIG=relay.config.json

relayforge-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - run: uv run python -m build
+      - run: uv publish

relayforge-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.env
+.venv/
+.relay/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+*.log
+.DS_Store

relayforge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Sharma
+
+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.

relayforge-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: relayforge
+Version: 0.1.0
+Summary: Route chat channels to agent targets.
+Project-URL: Homepage, https://github.com/AlmanacCode/relayforge
+Project-URL: Issues, https://github.com/AlmanacCode/relayforge/issues
+Author: Rohan Sharma
+License: MIT
+License-File: LICENSE
+Keywords: agents,automation,codex,discord,relay
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: certifi>=2024.7.4
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: websockets<15,>=13
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8.2; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Requires-Dist: twine<7,>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Relayforge
+
+Relayforge routes chat channels to agent targets.
+
+The first provider is Discord. The first targets are a Codex app-server binding
+and a Codex JSONL fallback inbox. The package is Python and PyPI-ready, with
+provider-neutral core types so Slack, WhatsApp, and other agent APIs can be
+added later.
+
+## Install
+
+After the package is published:
+
+```bash
+pip install relayforge
+```
+
+The installed CLI command is `relayforge`.
+
+Installed wheels add a small managed Relayforge block to:
+
+- `~/.codex/AGENTS.md`
+- `~/.claude/CLAUDE.md`
+
+Set `RELAYFORGE_SKIP_AGENT_GUIDES=1` before starting Python with the installed
+package on `sys.path` to skip this.
+
+From this checkout:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Configuration
+
+```json
+{
+  "channels": [
+    {
+      "name": "rohan-codex",
+      "provider": "discord",
+      "id": "1520170530148192466",
+      "owner": "rohan"
+    }
+  ],
+  "bindings": [
+    {
+      "name": "rohan-almanac-main",
+      "source": "rohan-codex",
+      "target": "codex-app-server",
+      "codexThreadId": "replace-with-codex-thread-id",
+      "cwd": "/Users/rohan/Desktop/Projects/almanac",
+      "machine": "replace-with-hostname",
+      "transport": "codex app-server --config mcp_servers={} --listen stdio://"
+    }
+  ],
+  "routes": [
+    {
+      "channel": "rohan-codex",
+      "target": "codex-jsonl",
+      "inboxPath": ".relay/rohan-codex-inbox.jsonl"
+    }
+  ]
+}
+```
+
+Each founder can use the same Discord bot token with a different named channel.
+A binding delivers to that founder's Codex thread on the right machine. A route
+keeps JSONL fallback delivery available when the direct target fails.
+
+See [docs/channels.md](docs/channels.md) for the multi-founder pattern.
+See [docs/research/codex-thread-routing-2026-06-26.md](docs/research/codex-thread-routing-2026-06-26.md)
+for the Codex thread binding direction.
+
+## Commands
+
+```bash
+export DISCORD_BOT_TOKEN=...
+
+relayforge init --config relay.config.json
+relayforge channel-set --name rohan-codex --provider discord --id 1520...
+relayforge route-set --channel rohan-codex --target codex-jsonl --inbox-path .relay/rohan-codex-inbox.jsonl
+relayforge binding-set --name rohan-almanac-main --source rohan-codex --target codex-app-server --codex-thread-id 019f... --cwd /Users/rohan/Desktop/Projects/almanac --transport "codex app-server --config mcp_servers={} --listen stdio://"
+relayforge check --config relay.config.json
+relayforge listen --config relay.config.json
+relayforge listen --config relay.config.json --include-bots --max-messages 1 --timeout 20
+relayforge check --config relay.config.json --json
+relayforge channels --config relay.config.json
+relayforge routes --config relay.config.json
+relayforge bindings --config relay.config.json
+relayforge codex-smoke --binding rohan-almanac-main --message "smoke test"
+relayforge binding-send --binding rohan-almanac-main --message "reply in Discord"
+relayforge send --channel rohan-codex --message "hello"
+relayforge read --channel rohan-codex --limit 10
+relayforge inbox --path .relay/rohan-codex-inbox.jsonl --limit 10
+relayforge inbox --path .relay/rohan-codex-inbox.jsonl --cursor .relay/rohan.cursor.json --ack
+```
+
+Raw Discord channel IDs work for `read` and `send` even before a config file
+exists. Named channels require the config.
+
+The `listen` command uses Discord Gateway events. That means Discord pushes new
+messages to this process instead of the process polling the channel.
+
+By default, Discord bot-authored messages are ignored to avoid loops. Use
+`--include-bots` only for controlled smoke tests or deliberate bot-to-agent
+routing.
+
+`codex-smoke` sends a synthetic message through a configured Codex app-server
+binding. Use it only with a rollout-backed Codex thread that is safe to receive
+a test turn.

relayforge-0.1.0/README.md

@@ -0,0 +1,113 @@
+# Relayforge
+
+Relayforge routes chat channels to agent targets.
+
+The first provider is Discord. The first targets are a Codex app-server binding
+and a Codex JSONL fallback inbox. The package is Python and PyPI-ready, with
+provider-neutral core types so Slack, WhatsApp, and other agent APIs can be
+added later.
+
+## Install
+
+After the package is published:
+
+```bash
+pip install relayforge
+```
+
+The installed CLI command is `relayforge`.
+
+Installed wheels add a small managed Relayforge block to:
+
+- `~/.codex/AGENTS.md`
+- `~/.claude/CLAUDE.md`
+
+Set `RELAYFORGE_SKIP_AGENT_GUIDES=1` before starting Python with the installed
+package on `sys.path` to skip this.
+
+From this checkout:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Configuration
+
+```json
+{
+  "channels": [
+    {
+      "name": "rohan-codex",
+      "provider": "discord",
+      "id": "1520170530148192466",
+      "owner": "rohan"
+    }
+  ],
+  "bindings": [
+    {
+      "name": "rohan-almanac-main",
+      "source": "rohan-codex",
+      "target": "codex-app-server",
+      "codexThreadId": "replace-with-codex-thread-id",
+      "cwd": "/Users/rohan/Desktop/Projects/almanac",
+      "machine": "replace-with-hostname",
+      "transport": "codex app-server --config mcp_servers={} --listen stdio://"
+    }
+  ],
+  "routes": [
+    {
+      "channel": "rohan-codex",
+      "target": "codex-jsonl",
+      "inboxPath": ".relay/rohan-codex-inbox.jsonl"
+    }
+  ]
+}
+```
+
+Each founder can use the same Discord bot token with a different named channel.
+A binding delivers to that founder's Codex thread on the right machine. A route
+keeps JSONL fallback delivery available when the direct target fails.
+
+See [docs/channels.md](docs/channels.md) for the multi-founder pattern.
+See [docs/research/codex-thread-routing-2026-06-26.md](docs/research/codex-thread-routing-2026-06-26.md)
+for the Codex thread binding direction.
+
+## Commands
+
+```bash
+export DISCORD_BOT_TOKEN=...
+
+relayforge init --config relay.config.json
+relayforge channel-set --name rohan-codex --provider discord --id 1520...
+relayforge route-set --channel rohan-codex --target codex-jsonl --inbox-path .relay/rohan-codex-inbox.jsonl
+relayforge binding-set --name rohan-almanac-main --source rohan-codex --target codex-app-server --codex-thread-id 019f... --cwd /Users/rohan/Desktop/Projects/almanac --transport "codex app-server --config mcp_servers={} --listen stdio://"
+relayforge check --config relay.config.json
+relayforge listen --config relay.config.json
+relayforge listen --config relay.config.json --include-bots --max-messages 1 --timeout 20
+relayforge check --config relay.config.json --json
+relayforge channels --config relay.config.json
+relayforge routes --config relay.config.json
+relayforge bindings --config relay.config.json
+relayforge codex-smoke --binding rohan-almanac-main --message "smoke test"
+relayforge binding-send --binding rohan-almanac-main --message "reply in Discord"
+relayforge send --channel rohan-codex --message "hello"
+relayforge read --channel rohan-codex --limit 10
+relayforge inbox --path .relay/rohan-codex-inbox.jsonl --limit 10
+relayforge inbox --path .relay/rohan-codex-inbox.jsonl --cursor .relay/rohan.cursor.json --ack
+```
+
+Raw Discord channel IDs work for `read` and `send` even before a config file
+exists. Named channels require the config.
+
+The `listen` command uses Discord Gateway events. That means Discord pushes new
+messages to this process instead of the process polling the channel.
+
+By default, Discord bot-authored messages are ignored to avoid loops. Use
+`--include-bots` only for controlled smoke tests or deliberate bot-to-agent
+routing.
+
+`codex-smoke` sends a synthetic message through a configured Codex app-server
+binding. Use it only with a rollout-backed Codex thread that is safe to receive
+a test turn.

relayforge-0.1.0/docs/channels.md

@@ -0,0 +1,115 @@
+# Channels
+
+Channels are named routing endpoints. A channel belongs to a provider and has a
+provider-specific ID.
+
+The shared Discord bot token is not tied to one person. Each founder gets a
+separate channel entry. A binding maps that channel to one machine-local Codex
+thread; a route can remain as the JSONL fallback.
+
+```json
+{
+  "channels": [
+    {
+      "name": "rohan-codex",
+      "provider": "discord",
+      "id": "1520170530148192466",
+      "owner": "rohan"
+    },
+    {
+      "name": "kush-codex",
+      "provider": "discord",
+      "id": "replace-with-kush-channel-id",
+      "owner": "kush"
+    }
+  ],
+  "bindings": [
+    {
+      "name": "rohan-almanac-main",
+      "source": "rohan-codex",
+      "target": "codex-app-server",
+      "codexThreadId": "replace-with-codex-thread-id",
+      "cwd": "/Users/rohan/Desktop/Projects/almanac",
+      "machine": "replace-with-hostname"
+    }
+  ],
+  "routes": [
+    {
+      "channel": "rohan-codex",
+      "target": "codex-jsonl",
+      "inboxPath": ".relay/rohan-codex-inbox.jsonl"
+    },
+    {
+      "channel": "kush-codex",
+      "target": "codex-jsonl",
+      "inboxPath": ".relay/kush-codex-inbox.jsonl"
+    }
+  ]
+}
+```
+
+Use `relayforge channels --config relay.config.json` to inspect configured
+channels. This command does not need Discord credentials because it only reads
+local config.
+
+Use `relayforge bindings --config relay.config.json` to inspect which channels
+are bound to agent targets.
+
+Use `relayforge init` once when no config exists yet:
+
+```bash
+relayforge init --config relay.config.json
+```
+
+Use `relayforge channel-set` to create or update a channel without
+hand-editing JSON:
+
+```bash
+relayforge channel-set \
+  --name rohan-codex \
+  --provider discord \
+  --id 1520170530148192466 \
+  --owner rohan
+```
+
+Use `relayforge route-set` to create or update the JSONL fallback route:
+
+```bash
+relayforge route-set \
+  --channel rohan-codex \
+  --target codex-jsonl \
+  --inbox-path .relay/rohan-codex-inbox.jsonl
+```
+
+Use `relayforge binding-set` to create or update a binding:
+
+```bash
+relayforge binding-set \
+  --name rohan-almanac-main \
+  --source rohan-codex \
+  --target codex-app-server \
+  --codex-thread-id 019f05b3-575b-7eb2-a5c3-ff91266b4815 \
+  --cwd /Users/rohan/Desktop/Projects/almanac
+```
+
+Use `relayforge codex-smoke --binding rohan-almanac-main` to verify that a
+configured Codex app-server binding can resume its thread and start a test turn.
+Run it only against a rollout-backed Codex thread that can safely receive a
+smoke message.
+
+Commands that talk to providers accept either a named channel or a raw provider
+ID:
+
+```bash
+relayforge read --channel rohan-codex
+relayforge send --channel rohan-codex --message "hello"
+```
+
+Raw provider IDs do not require a config file. Named channels do.
+
+Agents can send through a configured binding without knowing the provider
+channel ID:
+
+```bash
+relayforge binding-send --binding rohan-almanac-main --message "Done."
+```

relayforge-0.1.0/docs/completion-audit.md

@@ -0,0 +1,59 @@
+# Completion Audit
+
+Date: 2026-06-27
+
+This audit tracks the active goal: a clean, PR-ready Python package with a
+Codex app-server target and binding-based Discord-to-Codex thread routing.
+
+## Verdict
+
+Complete for the current package goal. The package is locally verified, the core
+product shape is implemented, and the direct Codex wakeup path has live
+`turn/start` proof against an idle rollout-backed Codex thread fork.
+
+## Requirement Audit
+
+| Requirement | Current Evidence | Status |
+| --- | --- | --- |
+| Python package prepared for PyPI | `pyproject.toml`, `src/relayforge`, `src/relayforge/py.typed`, console script, auto guide `.pth`, example config in sdist, local config excluded from sdist, `python -m build`, `twine check dist/*` | Proven locally |
+| Clean, small package boundaries | `core/`, `providers/discord/`, `targets/codex/`, `targets/codex_app_server/`, boundary tests | Proven by structure and tests |
+| Provider-neutral core | Core uses string provider/target names and does not import provider or target implementations | Proven by `tests/test_boundaries.py` |
+| Discord provider | REST read/send and Gateway listener exist under `providers/discord/` | Proven by unit tests and prior live Discord read/send/Gateway smoke |
+| Binding-based routing | `Binding`, machine scoping, provider thread scoping, binding precedence, and fallback routing are implemented | Proven by router tests |
+| Configurable channels, routes, and bindings | `relayforge init`, `channel-set`, `route-set`, `binding-set`, `channels`, `routes`, `bindings`, `check`, and config save/load support setup without hand-editing JSON | Proven by app and CLI tests, including the full local setup flow |
+| Agent outbound replies | `relayforge binding-send` sends through the configured binding source or provider thread, using the source channel provider's sender | Proven by tests; live bound send remains optional evidence |
+| Codex JSONL fallback | JSONL target and cursor-backed inbox reads exist | Proven by unit tests |
+| Codex app-server target | Target initializes app-server, resumes an existing thread, and can start a turn with a notification envelope | Proven by fake-transport tests, live resume-only smoke, and live `turn/start` smoke |
+| Per-binding Codex transport | `Binding.transport` selects a separate app-server stdio command per transport string | Proven by unit tests |
+| Raw default agent guides | Wheel install writes managed Relayforge guidance blocks to `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` on Python startup | Proven by installed-wheel packaging tests, including opt-out |
+| Steering docs current | Live agreement, ownership map, verification matrix, worklog, and next-agent brief describe the current system | Proven by direct inspection |
+| Final live direct wakeup proof | Full `relayforge codex-smoke --binding <name>` against safe idle fork `019f069b-3ac6-7470-b502-4135061914c6` | Proven live |
+
+## Live Evidence
+
+The final smoke used a temporary config created through public CLI setup
+commands:
+
+```bash
+relayforge init --force --config "$tmp_config"
+relayforge channel-set --config "$tmp_config" --name smoke-discord --provider discord --id smoke-channel
+relayforge binding-set --config "$tmp_config" --name smoke-codex-fork --source smoke-discord --target codex-app-server --codex-thread-id 019f069b-3ac6-7470-b502-4135061914c6 --cwd /Users/rohan/Desktop/Projects/almanac
+relayforge check --config "$tmp_config"
+relayforge codex-smoke --config "$tmp_config" --binding smoke-codex-fork --message "Relayforge live Codex app-server smoke test. Please reply briefly that the smoke test reached this fork."
+```
+
+The command returned:
+
+```json
+{"threadId": "019f069b-3ac6-7470-b502-4135061914c6", "method": "turn/start"}
+```
+
+`codex_app.read_thread` then showed a new turn on the fork and the thread was
+idle afterward.
+
+## Optional Future Evidence
+
+1. Run one live `relayforge binding-send --binding <name>` smoke against a safe
+   Discord channel/thread to prove bound outbound sends outside unit tests.
+2. Run a live human-authored Discord Gateway message through the listener to
+   prove non-bot message routing.

relayforge-0.1.0/docs/design.md

@@ -0,0 +1,57 @@
+# Relayforge Design
+
+Relayforge is a small message router. Chat providers produce inbound messages.
+Agent targets receive normalized messages and may send outbound replies through
+the same provider.
+
+The initial implementation supports Discord Gateway events, a Codex JSONL
+fallback inbox, and a Codex app-server target for existing Codex threads. JSONL
+is deliberately simple because it works without a running Codex app-server.
+
+Core provider and target names are strings. Concrete provider behavior lives
+under `providers/`; concrete target behavior lives under `targets/`.
+
+## Boundaries
+
+- Providers know how to read and send messages on one platform.
+- Targets know how to deliver a normalized message to an agent system.
+- The router owns channel-to-target configuration and binding selection.
+- The core types do not mention Discord, Slack, WhatsApp, or Codex internals.
+
+## Message Flow
+
+```text
+Discord Gateway MESSAGE_CREATE
+-> Discord provider normalizes message
+-> Router matches provider + channel id to a named channel
+-> Router resolves the matching binding or fallback route
+-> Codex app-server starts a turn with a Relayforge notification, or Codex
+   JSONL appends one event
+```
+
+The Codex app-server prompt is an explicit notification envelope. It includes
+the binding name, provider source, message ID, author, timestamp, and message
+body. The prompt tells the agent that a new chat message arrived and that any
+reply should go back through the relay binding.
+
+If a binding target fails and a route exists for the same channel, the router
+uses the route as fallback. If no fallback route exists, the direct target error
+is preserved.
+
+Outbound messages use the provider adapter directly:
+
+```text
+relayforge send --channel <id> --message "..."
+-> Discord provider posts to the channel
+```
+
+Bound outbound messages resolve through the binding first:
+
+```text
+relayforge binding-send --binding <name> --message "..."
+-> Relay resolves the binding source channel or source thread
+-> Discord provider posts to that destination
+```
+
+Bindings can be updated through `relayforge binding-set`. This keeps setup
+scriptable for agents while preserving JSON config as the source of truth.

relayforge-0.1.0/docs/idea-evolution.md

@@ -0,0 +1,18 @@
+# Idea Evolution
+
+## 2026-06-26
+
+Old hypothesis: A TypeScript `relayforge` package is enough because Discord
+support is easy through `discord.js`.
+
+New hypothesis: The package should be Python and PyPI-ready because the desired
+artifact is a reusable agent relay package, not a local Node script.
+
+Evidence that forced the change: The user explicitly requested slow development,
+good code, Python, and PyPI deployment, with channels as a first-class concern.
+
+Code or product assumption affected: The initial TypeScript scaffold should be
+replaced rather than ported in place.
+
+Follow-up test: Build a Python package where Discord is isolated under
+`providers/discord` and routing tests do not import Discord.

relayforge-0.1.0/docs/live-agreement.md

@@ -0,0 +1,46 @@
+# Live Agreement
+
+Relayforge is a Python package for routing chat messages between human
+channels and agent targets. It will be published to PyPI.
+
+The product model is channel-first. A channel is a routable conversation endpoint
+owned by a provider such as Discord, Slack, or WhatsApp. A target is an agent
+delivery mechanism such as a Codex inbox file or direct Codex app-server
+delivery.
+
+## Current Contract
+
+- Python is the implementation language.
+- Packaging must be PyPI-ready.
+- Discord is the first provider.
+- Slack and WhatsApp are future providers, so core names must not mention
+  Discord unless the file is inside the Discord provider.
+- Codex JSONL inbox is the fallback target because it works without a running
+  Codex app-server process.
+- Codex app-server is the direct Codex target. It resumes a configured Codex
+  thread and starts a turn through JSON-RPC.
+- Codex app-server bindings can override the stdio command with `transport`.
+  Different transport strings use separate initialized app-server processes.
+- Channel IDs are configuration data. The bot token can be shared by many
+  channels.
+- Channels are named objects. Routes refer to channel names, not raw provider
+  IDs, so a multi-founder setup remains readable.
+- Bindings are machine-local delivery rules. A binding maps a named source
+  channel, and optionally a provider thread ID, to an agent target.
+- Bindings are bidirectional at the product level. Inbound provider messages can
+  wake the bound agent thread, and the agent can explicitly send a message back
+  through the same binding.
+- Binding replies use the source channel's provider sender. Discord is the first
+  registered sender, but the app service is not hardcoded to Discord-only
+  binding replies.
+- Config setup is command-driven. Agents can create the config, upsert channels,
+  upsert JSONL fallback routes, and upsert bindings without hand-editing JSON.
+- The relay must support both event-driven listening and one-shot read/send
+  commands.
+
+## Non-Goals For The First Package Slice
+
+- No hosted service.
+- No database.
+- No direct Codex Desktop UI automation.
+- No hard dependency on Almanac.