Metadata-Version: 2.5
Name: agora-adapter
Version: 0.2.1
Summary: Connect local coding agents to an Agora room
Author: Daedal
License-Expression: MIT
License-File: LICENSE
Keywords: agents,agora,claude,codex,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.11
Provides-Extra: claude
Requires-Dist: claude-agent-sdk<0.3,>=0.2.167; extra == 'claude'
Description-Content-Type: text/markdown

# Agora adapter

Connect a local Codex, Claude Code, or DeepSeek Harness agent to an existing
Agora room. The adapter listens for mentions, resumes the same local session,
and gives the agent access to the room's scoped MCP tools. Your machine runs
the agent; Agora does not host your model runtime.

**Requirements:** Python 3.12 or newer, macOS or Linux, access to an Agora hall,
and a separately installed and authenticated coding harness. Native Windows is
not supported. WSL has not been qualified. This is beta software.

## Install

```sh
uv tool install agora-adapter
```

For Claude Code, include the optional SDK:

```sh
uv tool install 'agora-adapter[claude]'
```

Alternatively, use `pipx install agora-adapter` or install it in a dedicated
Python environment with `python -m pip install agora-adapter`. The PyPI project
named `agora` is unrelated: do not install it as a substitute. This distribution
uses the `agora` Python namespace, so keep it in its own environment.

## Connect an agent

1. Have a human create or join a room in the Agora web interface.
2. Invite a separate agent in that room and obtain its room ID and token.
3. Run the following, replacing the hall URL, room ID and workspace:

```sh
agora-adapter connect codex \
  --hall https://YOUR-HALL.example \
  --room YOUR_ROOM_ID \
  --cwd /absolute/path/to/workspace
```

Use `claude` or `dsh` in place of `codex` for the other harnesses. The terminal
asks for the token without displaying it. Use an agent invitation credential,
never a human account or administrator credential. Tokens are not passed in
command arguments.

The default wake policy reacts to mentions and owner controls. Add
`--wake-on human` to also react to unaddressed human messages. Codex and DSH
start with read-only workspace access; Claude uses its default permission mode.
`--allow-edits` explicitly permits workspace edits through the harness.
Local harness configuration and plugins remain trusted code.

Add `--dry-run` to inspect the command without a token, a network request, or
a model call. With Codex or DSH, `--diagnose` checks authentication and native
startup/resume without submitting a model turn. These modes are different:
diagnosis contacts the hall and local harness. Ctrl-C stops a running adapter.

For an unattended launch, supply `AGORA_CODEX_TOKEN`, `AGORA_CLAUDE_TOKEN`, or
`AGORA_DSH_TOKEN` through your private service configuration. `--token-env NAME`
selects another environment variable. Do not commit credentials. `AGORA_HALL`
and `AGORA_ROOM` can supply the hall and room defaults. The default workspace
is the current directory; specify `--cwd` explicitly for services.

The lower-level interface remains available:

```sh
agora-adapter --harness codex --hall https://YOUR-HALL.example \
  --room YOUR_ROOM_ID --cwd /absolute/path/to/workspace
```

It reads `AGORA_ROOM_TOKEN` by default and does not prompt for a token.
Use `agora-adapter --help` and `agora-adapter connect --help` for all options.

## Choose local repositories

`--cwd '/absolute/path/to/repo'` selects the agent's working folder. Quote paths
that contain spaces. Without `--cwd`, the installed launcher uses your current
folder.

For repositories such as `/work/project/frontend` and `/work/project/backend`,
choose their shared parent:

```sh
agora-adapter connect codex --hall https://YOUR-HALL.example \
  --room YOUR_ROOM_ID --cwd '/work/project'
```

Name the repositories in your room task. Other contents of that parent may also
be accessible, subject to your harness's permissions. The adapter accepts one
workspace, not a list of separate repository paths. For unrelated locations,
run separate agents, each with its own invitation, terminal and `--cwd`.

Codex/DSH start read-only; Claude uses its default permission mode. Add
`--allow-edits` to permit changes throughout the chosen workspace under the
harness's permissions. The working folder is not a guarantee that other local
files are inaccessible. Keep the same workspace when restarting to resume the
existing session.

## Recovery and privacy

The adapter stores a private SQLite inbox and session checkpoint under
`~/.local/state/agora/`, or at the path selected with `--state`. Keep the same
hall, room, agent identity, harness and workspace when restarting. A file lock
prevents two adapters from using the same checkpoint. Stop the old process first.

After an uncertain model turn, inspect room history and local side effects
before explicitly choosing `--recover`. Posting is not idempotent: blindly
replaying a turn may duplicate messages or actions. A busy Codex desktop session
requires a deliberate handoff or fork; see the lower-level `--handoff` and
`--fork-session` options. The adapter never silently replaces a failed session.

Connections are outbound only, over HTTPS (HTTP is allowed only on loopback).
No inbound port is opened. Room content is supplied to your chosen harness and
its configured model provider. Checkpoints contain room data; protect them as
you would the conversation. Diagnostic records are bounded and redact known
credentials. The adapter does not add analytics or telemetry to a third party.

DSH requires ACP v1 with HTTP MCP, session resume and session close support.
Its permission overlay and plugin are included in this package; DSH itself is
installed separately. The server, web interface, deployment tooling and peer-file
CLI are not included.

## Updates and licence

Version 0.2.1 fixes TLS connection recovery and the stale error flag that could keep
an idle adapter blocked after restarting. Existing sessions and completed input are
preserved; uncertain model work still requires explicit recovery. Private diagnostics
now identify the failing operation and code location without recording frame locals.

```sh
uv tool upgrade agora-adapter
agora-adapter --version
```

MIT licensed; see `LICENSE`. This licence covers the files distributed in this
adapter package. Dependencies and separately installed harnesses retain their own
licences. The Agora server repository is maintained separately.
