Cycles Agent Bridge

Name: Cycles Agent Bridge
Rating: 3.5 (1 reviews)
Author: takhir-iota

By takhir-iota 👁 39 views ▲ 0 votes

Codex plugin for delegating tasks to ACP-compatible OpenClaw, Hermes, and home agents

GitHub

Install

npm install
npm

Configuration Example

{
  "provider": "openclaw",
  "cwd": "/absolute/path/to/workspace"
}

README

# Cycles Agent Bridge

Cycles Agent Bridge is a Codex plugin that delegates bounded tasks to an ACP-compatible agent harness while keeping Codex as the primary interface.

The plugin packages:

- a routing skill for deciding when and how to delegate;
- a bundled MCP server that acts as an ACP client;
- session discovery and resume support;
- asynchronous task runs with event polling;
- cancellation and explicit ACP permission handling.

OpenClaw and Hermes both expose ACP entry points. The bridge can launch either one locally or through a command such as SSH, so the agent and its model provider can remain on a home server.

## Install in Codex

Add the GitHub marketplace and install the plugin:

```bash
codex plugin marketplace add takhir-iota/cycles-agent-bridge
codex plugin add cycles-agent-bridge@takhir-iota
```

Start a new Codex task after installation so Codex can load the skill and MCP tools.

## Status

This is a pre-alpha vertical slice. The ACP contract is covered by deterministic integration tests. OpenClaw and Hermes end-to-end compatibility still needs to be validated against installed, supported harness versions before a stable release.

## Requirements

- Node.js 20 or newer;
- Codex with plugin and bundled MCP support;
- an authenticated ACP-compatible agent command;
- an absolute working directory visible to the agent host.

## Configure an agent

The bundled MCP server reads non-secret launch configuration from `~/.config/cycles/agent-bridge.json`. Environment variables with the same settings override the file for development and managed deployments.

The configuration file accepts only `provider`, `command`, `args`, `cwd`, and bounded runtime limits. It rejects environment maps, unknown fields, and inline credential flags.

### Local OpenClaw

```bash
mkdir -p ~/.config/cycles
```

```json
{
  "provider": "openclaw",
  "cwd": "/absolute/path/to/workspace"
}
```

The default command is `openclaw acp`.

For a remote OpenClaw Gateway, keep the credential in a file and configure the ACP command without placing the token in plugin metadata:

```json
{
  "provider": "openclaw",
  "args": [
    "acp",
    "--url",
    "wss://agent.example.com",
    "--token-file",
    "/absolute/path/to/gateway.token",
    "--session",
    "agent:main:main"
  ],
  "cwd": "/absolute/path/to/workspace"
}
```

### Local Hermes

```json
{
  "provider": "hermes",
  "cwd": "/absolute/path/to/workspace"
}
```

The default command is `hermes acp`.

### Agent on a home server over SSH

Authenticate SSH outside Codex first and use key-based, non-interactive access:

```json
{
  "provider": "custom",
  "command": "ssh",
  "args": ["-o", "BatchMode=yes", "home-agent", "hermes", "acp"],
  "cwd": "/absolute/path/to/workspace/on-the-agent-host"
}
```

Do not place passwords, bearer tokens, or private keys in the configuration file. Inline `--token`, `--password`, `--secret`, and `--api-key` arguments are rejected.

## Optional settings

| Variable | Default | Purpose |
|---|---:|---|
| `CYCLES_AGENT_CONFIG_FILE` | `~/.config/cycles/agent-bridge.json` | Alternate non-secret config path |
| `CYCLES_AGENT_PROVIDER` | config file or `openclaw` | `openclaw`, `hermes`, or `custom` |
| `CYCLES_AGENT_COMMAND` | provider default | ACP executable or transport command |
| `CYCLES_AGENT_ARGS_JSON` | provider default | JSON array overriding command arguments |
| `CYCLES_AGENT_CWD` | Codex process directory | Default absolute ACP working directory |
| `CYCLES_AGENT_STARTUP_TIMEOUT_MS` | `15000` | ACP initialize timeout |
| `CYCLES_AGENT_RUN_RETENTION_MS` | `3600000` | Completed run retention in bridge memory |
| `CYCLES_AGENT_MAX_RUNS` | `100` | Maximum retained runs |
| `CYCLES_AGENT_MAX_EVENTS` | `250` | Maximum retained events per run |

## MCP tools

| Tool | Behavior |
|---|---|
| `agent_health` | Connect and inspect safe ACP capability metadata |
| `agent_sessions_list` | List resumable agent sessions |
| `agent_task_start` | Start an asynchronous prompt in a new or existing session |
| `agent_run_get` | Read a run snapshot and events |
| `agent_run_wait` | Long-poll until an event, approval, or completion |
| `agent_run_cancel` | Cancel active work without deleting the session |
| `agent_approval_resolve` | Resolve one pending permission after explicit user consent |

## Security model

- The bridge does not store credentials.
- Child processes inherit the operator's existing environment and authentication.
- Tool input and agent stderr are redacted before errors are returned.
- Agent thought chunks are not returned as hidden reasoning.
- Permission requests pause until an exact option is selected through a separate tool call.
- Additional workspace roots must be absolute and explicitly supplied per task.

The remote agent remains a separate trust boundary. Its model, memory, tools, connected services, and workspace permissions are not automatically shared with Codex.

## Development

```bash
npm install
npm run verify
```

The test suite launches a mock ACP agent and verifies connection, new and resumed sessions, asynchronous output, approval suspension, approval resolution, and cancellation.

## License

MIT. Bundled dependency attributions are listed in `THIRD_PARTY_NOTICES.md`.

integration