feat: add subscription bridge example harness

- add a documented subscription bridge example with local demo agent
- verify Codex and Claude CLI-backed tool loops through the bridge
- cover prompt shaping, structured output parsing, and demo helpers with tests
- keep current limits explicit: non-streaming focus, partial responses parity, no handoff validation yet

Author: OdinBot33

examples/subscription_bridge/README.md

@@ -0,0 +1,86 @@
+# Subscription bridge
+
+This example shows how to drive `openai-agents-python` through a local OpenAI-compatible bridge that routes requests into the authenticated vendor CLIs instead of raw provider APIs:
+
+- `codex/...` -> `codex exec`
+- `claude/...` or `anthropic/...` -> `claude -p`
+
+This is useful when you want local agent loops to land on ChatGPT/Codex or Claude Max CLI-backed usage where supported.
+
+Important limitation: this does not make arbitrary raw OpenAI or Anthropic API calls bill to those app plans. The working path is:
+
+`openai-agents-python` -> local bridge -> `codex` / `claude` CLI
+
+## What is included
+
+- `server.py`
+  - exposes `/health`, `/v1/chat/completions`, and `/v1/responses`
+  - supports non-streaming text responses and structured tool-call loops
+- `demo_agent.py`
+  - starts an embedded local bridge or connects to an existing one
+  - runs a simple tool-using `Agent` through `OpenAIChatCompletionsModel`
+
+## Quick start
+
+Run the embedded demo with Codex:
+
+```bash
+uv run --python 3.11 python examples/subscription_bridge/demo_agent.py --backend codex
+```
+
+Run the embedded demo with Claude:
+
+```bash
+uv run --python 3.11 python examples/subscription_bridge/demo_agent.py --backend claude
+```
+
+Use an already-running bridge instead of starting an embedded one:
+
+```bash
+uv run --python 3.11 python examples/subscription_bridge/server.py --backend codex --port 8787
+uv run --python 3.11 python examples/subscription_bridge/demo_agent.py --backend codex --base-url http://127.0.0.1:8787
+```
+
+Override the model or prompt:
+
+```bash
+uv run --python 3.11 python examples/subscription_bridge/demo_agent.py \
+  --backend codex \
+  --model codex/gpt-5.4 \
+  --prompt "What is the weather in Tokyo?"
+```
+
+## Expected behavior
+
+The demo agent includes a simple `get_weather(city)` function tool. A working run should:
+
+1. ask the bridge for the next assistant turn
+2. emit a tool call
+3. execute the local tool
+4. call the bridge again
+5. return plain final assistant text
+
+Example final outputs seen on ATHAME:
+
+- Codex: `The weather in Tokyo is sunny and 72 F.`
+- Claude: `The weather in Tokyo is currently sunny with a temperature of 72°F.`
+
+## Verification
+
+Run the targeted tests:
+
+```bash
+uv run --python 3.11 pytest tests/examples/test_subscription_bridge.py tests/examples/test_subscription_bridge_demo_agent.py -q
+```
+
+## Current limits
+
+Validated:
+- chat-completions-compatible tool loop through the bridge
+- Codex-backed local tool loop
+- Claude-backed local tool loop
+
+Not yet validated:
+- streaming responses
+- full Responses API parity beyond the current minimal implementation
+- multi-agent handoffs and handoff semantics

examples/subscription_bridge/__init__.py

@@ -0,0 +1,4 @@
+from . import demo_agent
+from .server import main, make_server
+
+__all__ = ["demo_agent", "main", "make_server"]

examples/subscription_bridge/demo_agent.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import threading
+import time
+from pathlib import Path
+from typing import Literal
+
+from openai import AsyncOpenAI
+
+from agents import Agent, OpenAIChatCompletionsModel, Runner, function_tool, set_tracing_disabled
+
+try:
+    from .server import make_server
+except ImportError:  # pragma: no cover - script execution path
+    import sys
+
+    sys.path.append(str(Path(__file__).resolve().parents[2]))
+    from examples.subscription_bridge.server import make_server
+
+Backend = Literal["codex", "claude"]
+
+
+def default_model_for_backend(backend: Backend) -> str:
+    if backend == "claude":
+        return "claude/claude-sonnet-4-6"
+    return "codex/gpt-5.4"
+
+
+def resolve_model(backend: Backend, model: str | None) -> str:
+    return model or default_model_for_backend(backend)
+
+
+def normalize_api_base_url(base_url: str) -> str:
+    stripped = base_url.rstrip("/")
+    if stripped.endswith("/v1"):
+        return stripped
+    return f"{stripped}/v1"
+
+
+@function_tool
+def get_weather(city: str) -> str:
+    return f"The weather in {city} is sunny and 72 F."
+
+
+async def run_demo(*, prompt: str, backend: Backend, model: str | None, api_base_url: str) -> str:
+    set_tracing_disabled(disabled=True)
+    client = AsyncOpenAI(base_url=normalize_api_base_url(api_base_url), api_key="dummy")
+    agent = Agent(
+        name="Subscription Bridge Demo",
+        instructions="Use tools when useful, then answer clearly.",
+        model=OpenAIChatCompletionsModel(
+            model=resolve_model(backend, model),
+            openai_client=client,
+        ),
+        tools=[get_weather],
+    )
+    result = await Runner.run(agent, prompt)
+    return str(result.final_output)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run a local openai-agents-python demo through the subscription bridge."
+    )
+    parser.add_argument(
+        "--backend",
+        choices=["codex", "claude"],
+        default="codex",
+        help="Which CLI-backed bridge backend to use.",
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        help="Optional full model name override, e.g. codex/gpt-5.4 or claude/claude-sonnet-4-6.",
+    )
+    parser.add_argument(
+        "--prompt",
+        default="What is the weather in Tokyo?",
+        help="Prompt to send to the demo agent.",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="Bridge host for local embedded mode.")
+    parser.add_argument(
+        "--port", type=int, default=8787, help="Bridge port for local embedded mode."
+    )
+    parser.add_argument(
+        "--base-url",
+        default=None,
+        help="Use an already-running bridge instead of starting a local embedded bridge.",
+    )
+    parser.add_argument(
+        "--workdir",
+        default=str(Path.cwd()),
+        help="Working directory to pass to the local embedded bridge.",
+    )
+    return parser
+
+
+async def _main_async(args: argparse.Namespace) -> str:
+    if args.base_url:
+        return await run_demo(
+            prompt=args.prompt,
+            backend=args.backend,
+            model=args.model,
+            api_base_url=args.base_url,
+        )
+
+    httpd = make_server(
+        args.host,
+        args.port,
+        default_backend=args.backend,
+        workdir=Path(args.workdir).resolve(),
+    )
+    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    thread.start()
+    time.sleep(0.2)
+    try:
+        return await run_demo(
+            prompt=args.prompt,
+            backend=args.backend,
+            model=args.model,
+            api_base_url=f"http://{args.host}:{args.port}",
+        )
+    finally:
+        httpd.shutdown()
+        httpd.server_close()
+        thread.join(timeout=2)
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+    print(asyncio.run(_main_async(args)))
+
+
+if __name__ == "__main__":
+    main()