relayforge 0.1.0__py3-none-any.whl

relayforge/__init__.py

@@ -0,0 +1,5 @@
+"""Provider-neutral chat-to-agent relay."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

relayforge/_auto_guides.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from contextlib import suppress
+
+from relayforge.agent_guides import auto_install_agent_guides
+
+with suppress(Exception):
+    auto_install_agent_guides()

relayforge/agent_guides.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+GUIDE_START = "<!-- relayforge:start -->"
+GUIDE_END = "<!-- relayforge:end -->"
+LEGACY_GUIDE_START = "<!-- agent-relay:start -->"
+LEGACY_GUIDE_END = "<!-- agent-relay:end -->"
+
+GUIDE_BODY = (
+    "When this agent receives a Relayforge notification, treat it as user "
+    """context from the configured chat binding.
+
+To reply to the source channel, use:
+
+relayforge binding-send --binding <binding-name> --message "..."
+
+Use the binding name from the Relayforge notification.
+
+If the user asks you to automatically listen for chat updates, validate setup
+and start the listener:
+
+relayforge check --config relay.config.json
+relayforge listen --config relay.config.json
+
+The listener is what turns new Discord messages into agent notifications.
+"""
+)
+
+GUIDE_BLOCK = f"{GUIDE_START}\n{GUIDE_BODY}{GUIDE_END}\n"
+
+
+def install_agent_guides(home: Path | None = None) -> list[Path]:
+    root = home or Path.home()
+    touched: list[Path] = []
+    touched.extend(_ensure_managed_block(root / ".codex" / "AGENTS.md"))
+    touched.extend(_ensure_managed_block(root / ".claude" / "CLAUDE.md"))
+    return touched
+
+
+def auto_install_agent_guides() -> None:
+    if os.getenv("RELAYFORGE_SKIP_AGENT_GUIDES"):
+        return
+    install_agent_guides()
+
+
+def _ensure_managed_block(path: Path) -> list[Path]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existing = path.read_text() if path.exists() else ""
+    updated = _replace_or_append_block(existing)
+    if updated == existing:
+        return []
+    path.write_text(updated)
+    return [path]
+
+
+def _replace_or_append_block(existing: str) -> str:
+    start = existing.find(LEGACY_GUIDE_START)
+    end = existing.find(LEGACY_GUIDE_END)
+    if start != -1 and end != -1 and end > start:
+        after_end = end + len(LEGACY_GUIDE_END)
+        existing = f"{existing[:start]}{GUIDE_BLOCK}{existing[after_end:].lstrip()}"
+
+    start = existing.find(GUIDE_START)
+    end = existing.find(GUIDE_END)
+    if start != -1 and end != -1 and end > start:
+        after_end = end + len(GUIDE_END)
+        updated = f"{existing[:start]}{GUIDE_BLOCK}{existing[after_end:].lstrip()}"
+        return _remove_extra_managed_blocks(updated)
+
+    if existing.strip() == "":
+        return GUIDE_BLOCK
+
+    sep = "\n" if existing.endswith("\n") else "\n\n"
+    return f"{existing}{sep}{GUIDE_BLOCK}"
+
+
+def _remove_extra_managed_blocks(existing: str) -> str:
+    first_end = existing.find(GUIDE_END)
+    if first_end == -1:
+        return existing
+
+    search_from = first_end + len(GUIDE_END)
+    while True:
+        start = existing.find(GUIDE_START, search_from)
+        end = existing.find(GUIDE_END, search_from)
+        if start == -1 or end == -1 or end < start:
+            return existing
+        after_end = end + len(GUIDE_END)
+        existing = f"{existing[:start]}{existing[after_end:].lstrip()}"
+        search_from = first_end + len(GUIDE_END)

relayforge/app.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from relayforge.core.config import empty_config, load_config, save_config
+from relayforge.core.models import Binding, Channel, RelayMessage, Route
+from relayforge.core.providers import ChannelSender
+from relayforge.core.router import RelayRouter
+from relayforge.core.validation import BindingValidator, check_config
+from relayforge.providers.discord.gateway import (
+    DiscordGatewayClient,
+    GatewayListenResult,
+)
+from relayforge.providers.discord.rest import DiscordRestClient
+from relayforge.targets.codex.jsonl import (
+    CodexJsonlTarget,
+    read_inbox,
+    read_inbox_with_cursor,
+)
+from relayforge.targets.codex_app_server import (
+    CodexAppServerTarget,
+)
+from relayforge.targets.codex_app_server.target import (
+    CodexThreadResumeResult,
+    CodexTurnStartResult,
+)
+from relayforge.targets.codex_app_server.transport import CodexAppServerTransport
+
+
+def build_router(config_path: str) -> RelayRouter:
+    config = load_config(config_path)
+    codex_jsonl = CodexJsonlTarget()
+    return RelayRouter(
+        config,
+        {"codex-jsonl": codex_jsonl},
+        {
+            "codex-jsonl": codex_jsonl,
+            "codex-app-server": CodexAppServerTarget(),
+        },
+    )
+
+
+def init_config(config_path: str, *, force: bool = False) -> Path:
+    path = Path(config_path)
+    if path.exists() and not force:
+        raise FileExistsError(f"Config already exists: {path}")
+    save_config(path, empty_config())
+    return path
+
+
+def list_channels(config_path: str) -> list[Channel]:
+    return load_config(config_path).channels
+
+
+def list_routes(config_path: str) -> list[Route]:
+    return load_config(config_path).routes
+
+
+def list_bindings(config_path: str) -> list[Binding]:
+    return load_config(config_path).bindings
+
+
+def check_config_path(config_path: str) -> list[str]:
+    return check_config(
+        load_config(config_path),
+        binding_validators=_binding_validators(),
+    )
+
+
+def set_binding(
+    config_path: str,
+    *,
+    name: str,
+    source: str,
+    target: str,
+    source_thread_id: str | None = None,
+    codex_thread_id: str | None = None,
+    cwd: str | None = None,
+    machine: str | None = None,
+    transport: str | None = None,
+    inbox_path: str | None = None,
+) -> Binding:
+    config = load_config(config_path)
+    binding = Binding(
+        name=name,
+        source=source,
+        target=target,
+        sourceThreadId=source_thread_id,
+        codexThreadId=codex_thread_id,
+        cwd=Path(cwd) if cwd is not None else None,
+        machine=machine,
+        transport=transport,
+        inboxPath=Path(inbox_path) if inbox_path is not None else None,
+    )
+    config.binding_channel(binding)
+    save_config(config_path, config.with_binding(binding))
+    return binding
+
+
+def set_channel(
+    config_path: str,
+    *,
+    name: str,
+    provider: str,
+    channel_id: str,
+    owner: str | None = None,
+    description: str | None = None,
+) -> Channel:
+    config = load_config(config_path)
+    channel = Channel(
+        name=name,
+        provider=provider,
+        id=channel_id,
+        owner=owner,
+        description=description,
+    )
+    save_config(config_path, config.with_channel(channel))
+    return channel
+
+
+def set_route(
+    config_path: str,
+    *,
+    channel: str,
+    target: str,
+    inbox_path: str,
+) -> Route:
+    config = load_config(config_path)
+    route = Route(
+        channel=channel,
+        target=target,
+        inboxPath=Path(inbox_path),
+    )
+    config.route_channel(route)
+    save_config(config_path, config.with_route(route))
+    return route
+
+
+def _binding_validators() -> dict[str, BindingValidator]:
+    return {
+        "codex-app-server": _validate_codex_app_server_binding,
+        "codex-jsonl": _validate_codex_jsonl_binding,
+    }
+
+
+def _validate_codex_app_server_binding(binding: Binding) -> list[str]:
+    issues: list[str] = []
+    if binding.codex_thread_id is None:
+        issues.append(
+            f"Binding {binding.name} targets codex-app-server but lacks codexThreadId"
+        )
+    if binding.cwd is not None and not binding.cwd.is_dir():
+        issues.append(
+            f"Binding {binding.name} cwd does not exist or is not a directory: "
+            f"{binding.cwd}"
+        )
+    return issues
+
+
+def _validate_codex_jsonl_binding(binding: Binding) -> list[str]:
+    if binding.inbox_path is not None:
+        return []
+    return [f"Binding {binding.name} targets codex-jsonl but lacks inboxPath"]
+
+
+async def smoke_codex_binding(
+    config_path: str,
+    binding_name: str,
+    *,
+    message: str,
+    resume_only: bool = False,
+    transport: CodexAppServerTransport | None = None,
+) -> CodexThreadResumeResult | CodexTurnStartResult:
+    config = load_config(config_path)
+    binding = config.binding_by_name(binding_name)
+    if binding.target != "codex-app-server":
+        raise ValueError(
+            f"Binding {binding.name} targets {binding.target}, not codex-app-server"
+        )
+    target = CodexAppServerTarget(transport)
+    if resume_only:
+        return await target.resume_thread(binding)
+    return await target.start_turn(
+        RelayMessage(
+            channel=config.binding_channel(binding),
+            message_id="relayforge-smoke",
+            author_id="relayforge",
+            author_name="Relayforge Smoke",
+            content=message,
+            created_at=datetime.now(UTC),
+            thread_id=binding.source_thread_id,
+        ),
+        binding,
+    )
+
+
+def resolve_channel_id(config_path: str, channel: str) -> str:
+    if not Path(config_path).exists():
+        return channel
+    config = load_config(config_path)
+    for candidate in config.channels:
+        if candidate.name == channel or candidate.id == channel:
+            return candidate.id
+    return channel
+
+
+async def listen(
+    config_path: str,
+    discord_token: str,
+    *,
+    max_messages: int | None = None,
+    timeout_seconds: float | None = None,
+    include_bots: bool = False,
+) -> GatewayListenResult:
+    router = build_router(config_path)
+    gateway = DiscordGatewayClient(discord_token)
+    return await gateway.listen(
+        router.route,
+        max_messages=max_messages,
+        timeout_seconds=timeout_seconds,
+        include_bots=include_bots,
+    )
+
+
+async def send_discord(channel_id: str, message: str, discord_token: str) -> None:
+    client = DiscordRestClient(discord_token)
+    await client.send_message(channel_id, message)
+
+
+async def send_binding(
+    config_path: str,
+    binding_name: str,
+    message: str,
+    discord_token: str,
+    *,
+    senders: dict[str, ChannelSender] | None = None,
+) -> None:
+    config = load_config(config_path)
+    binding = config.binding_by_name(binding_name)
+    channel = config.binding_channel(binding)
+    provider_senders = senders or {"discord": DiscordRestClient(discord_token)}
+    sender = provider_senders.get(channel.provider)
+    if sender is None:
+        raise LookupError(f"No sender registered for provider {channel.provider}")
+    await sender.send_message(binding.source_thread_id or channel.id, message)
+
+
+async def read_discord(
+    channel_id: str,
+    discord_token: str,
+    limit: int = 10,
+) -> list[RelayMessage]:
+    client = DiscordRestClient(discord_token)
+    return await client.read_messages(channel_id, limit)
+
+
+def read_codex_inbox(
+    path: str,
+    limit: int | None = None,
+    *,
+    cursor_path: str | None = None,
+    ack: bool = False,
+) -> list[RelayMessage]:
+    if cursor_path is not None:
+        return read_inbox_with_cursor(path, cursor_path, limit=limit, ack=ack)
+    messages = read_inbox(path)
+    if limit is None:
+        return messages
+    return messages[-limit:]

relayforge/cli.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+from collections.abc import Sequence
+
+from relayforge.app import (
+    check_config_path,
+    init_config,
+    list_bindings,
+    list_channels,
+    list_routes,
+    listen,
+    read_codex_inbox,
+    read_discord,
+    resolve_channel_id,
+    send_binding,
+    send_discord,
+    set_binding,
+    set_channel,
+    set_route,
+    smoke_codex_binding,
+)
+from relayforge.cli_output import print_json_object, print_model, print_models
+from relayforge.cli_parser import build_parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "channels":
+        _print_channels(args.config)
+        return
+
+    if args.command == "init":
+        _init_config(args.config, force=args.force)
+        return
+
+    if args.command == "routes":
+        _print_routes(args.config)
+        return
+
+    if args.command == "bindings":
+        _print_bindings(args.config)
+        return
+
+    if args.command == "channel-set":
+        _set_channel(args)
+        return
+
+    if args.command == "route-set":
+        _set_route(args)
+        return
+
+    if args.command == "binding-set":
+        _set_binding(args)
+        return
+
+    if args.command == "check":
+        _check_config(args.config, json_output=args.json)
+        return
+
+    if args.command == "inbox":
+        _print_inbox(
+            args.path,
+            args.limit,
+            cursor_path=args.cursor,
+            ack=args.ack,
+        )
+        return
+
+    if args.command == "codex-smoke":
+        _run_codex_smoke(
+            args.config,
+            args.binding,
+            message=args.message,
+            resume_only=args.resume_only,
+        )
+        return
+
+    token = _required_env("DISCORD_BOT_TOKEN")
+
+    if args.command == "listen":
+        _run_listen(
+            args.config,
+            token,
+            max_messages=args.max_messages,
+            timeout_seconds=args.timeout,
+            include_bots=args.include_bots,
+        )
+        return
+
+    if args.command == "read":
+        _print_discord_messages(args.config, args.channel, token, args.limit)
+        return
+
+    if args.command == "send":
+        _send_discord_message(args.config, args.channel, token, args.message)
+        return
+
+    if args.command == "binding-send":
+        _send_binding_message(args.config, args.binding, token, args.message)
+        return
+
+
+def _print_channels(config_path: str) -> None:
+    print_models(list_channels(config_path))
+
+
+def _init_config(config_path: str, *, force: bool) -> None:
+    try:
+        path = init_config(config_path, force=force)
+    except FileExistsError as exc:
+        raise SystemExit(str(exc)) from exc
+    print(f"created {path}")
+
+
+def _print_routes(config_path: str) -> None:
+    print_models(list_routes(config_path), by_alias=True)
+
+
+def _print_bindings(config_path: str) -> None:
+    print_models(list_bindings(config_path), by_alias=True)
+
+
+def _set_channel(args: argparse.Namespace) -> None:
+    channel = set_channel(
+        args.config,
+        name=args.name,
+        provider=args.provider,
+        channel_id=args.id,
+        owner=args.owner,
+        description=args.description,
+    )
+    print_model(channel)
+
+
+def _set_route(args: argparse.Namespace) -> None:
+    try:
+        route = set_route(
+            args.config,
+            channel=args.channel,
+            target=args.target,
+            inbox_path=args.inbox_path,
+        )
+    except LookupError as exc:
+        raise SystemExit(str(exc)) from exc
+    print_model(route, by_alias=True)
+
+
+def _set_binding(args: argparse.Namespace) -> None:
+    try:
+        binding = set_binding(
+            args.config,
+            name=args.name,
+            source=args.source,
+            target=args.target,
+            source_thread_id=args.source_thread_id,
+            codex_thread_id=args.codex_thread_id,
+            cwd=args.cwd,
+            machine=args.machine,
+            transport=args.transport,
+            inbox_path=args.inbox_path,
+        )
+    except LookupError as exc:
+        raise SystemExit(str(exc)) from exc
+    print_model(binding, by_alias=True)
+
+
+def _check_config(config_path: str, *, json_output: bool) -> None:
+    issues = check_config_path(config_path)
+    if json_output:
+        print_json_object({"ok": not issues, "issues": issues})
+        if issues:
+            raise SystemExit(1)
+        return
+    if not issues:
+        print("ok")
+        return
+    for issue in issues:
+        print(issue)
+    raise SystemExit(1)
+
+
+def _print_inbox(
+    path: str,
+    limit: int | None,
+    *,
+    cursor_path: str | None,
+    ack: bool,
+) -> None:
+    for message in read_codex_inbox(
+        path,
+        limit,
+        cursor_path=cursor_path,
+        ack=ack,
+    ):
+        print_model(message)
+
+
+def _run_codex_smoke(
+    config_path: str,
+    binding: str,
+    *,
+    message: str,
+    resume_only: bool,
+) -> None:
+    try:
+        result = asyncio.run(
+            smoke_codex_binding(
+                config_path,
+                binding,
+                message=message,
+                resume_only=resume_only,
+            )
+        )
+    except (LookupError, ValueError) as exc:
+        raise SystemExit(str(exc)) from exc
+    print_json_object({"threadId": result.thread_id, "method": result.method})
+
+
+def _run_listen(
+    config_path: str,
+    discord_token: str,
+    *,
+    max_messages: int | None,
+    timeout_seconds: float | None,
+    include_bots: bool,
+) -> None:
+    count = asyncio.run(
+        listen(
+            config_path,
+            discord_token,
+            max_messages=max_messages,
+            timeout_seconds=timeout_seconds,
+            include_bots=include_bots,
+        )
+    )
+    print(f"received={count.received} routed={count.routed}")
+
+
+def _print_discord_messages(
+    config_path: str,
+    channel: str,
+    discord_token: str,
+    limit: int,
+) -> None:
+    channel_id = resolve_channel_id(config_path, channel)
+    messages = asyncio.run(read_discord(channel_id, discord_token, limit))
+    print_models(messages)
+
+
+def _send_discord_message(
+    config_path: str,
+    channel: str,
+    discord_token: str,
+    message: str,
+) -> None:
+    channel_id = resolve_channel_id(config_path, channel)
+    asyncio.run(send_discord(channel_id, message, discord_token))
+
+
+def _send_binding_message(
+    config_path: str,
+    binding: str,
+    discord_token: str,
+    message: str,
+) -> None:
+    try:
+        asyncio.run(send_binding(config_path, binding, message, discord_token))
+    except LookupError as exc:
+        raise SystemExit(str(exc)) from exc
+
+
+def _required_env(name: str) -> str:
+    value = os.getenv(name)
+    if not value:
+        raise SystemExit(f"Missing {name}")
+    return value

relayforge/cli_output.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def print_json_object(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload))
+
+
+def print_model(model: BaseModel, *, by_alias: bool = False) -> None:
+    print(model.model_dump_json(by_alias=by_alias))
+
+
+def print_models(models: Iterable[BaseModel], *, by_alias: bool = False) -> None:
+    for model in models:
+        print_model(model, by_alias=by_alias)