Metadata-Version: 2.4
Name: teamclaw-agent-proxy
Version: 0.1.0
Summary: A FastAPI-based manager-first agent backend and CLI
Author-email: Leo <leoustc@icloud.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.23

# Agent Proxy

`agent-proxy` is a Python CLI for persistent agent workspaces and Codex session coordination.

The primary commands are:

- `agent-proxy enable`
- `agent-proxy restart`
- `agent-proxy init <role>`
- `agent-proxy hire <role> <name>`
- `agent-proxy list`
- `agent-proxy status`
- `agent-proxy connect <agent> [working_dir]`
- `agent-proxy stop <role>`

There is also an internal `agent-proxy daemon` command used by the `systemd` service.

## Features

- `agent-proxy init <role>` creates a role workspace with memory and daily notes
- `agent-proxy init <role>` asks the daemon to spawn Codex and returns the managed PID
- `agent-proxy hire <role> <name>` creates or reuses a named agent and returns its managed PID
- `agent-proxy enable` installs and starts the `systemd` daemon service
- `agent-proxy restart` restarts the `systemd` daemon service
- `agent-proxy restart` also allows desired roles to come back under the restarted master
- if a managed autostart role dies, the daemon will try to restart it after about 10 seconds
- `agent-proxy list` shows initialized agents
- `agent-proxy status` shows the daemon/agent process tree
- `agent-proxy connect <agent> [working_dir]` opens a command-line chatbot for the managed role session
- `agent-proxy stop <role>` queues a stop request for the monitor daemon
- the master also serves an OpenAI Responses-style `POST /v1/responses` API and a browser chat UI at `GET /`
- the master also serves `POST /hire` for creating named agents
- when the daemon starts, it also starts the default `manager` agent

## Installation

```bash
cd agent-proxy
make install
```
Installation does not automatically enable the daemon. Use `agent-proxy enable` explicitly.

Or directly:

```bash
pip install -e .
```

## Usage

Initialize a role workspace:

```bash
agent-proxy init researcher
```

This creates:

```text
~/.agent_proxy/researcher/
├── SOUL.md
├── AGENTS.md
├── memory/memory.md
└── notes/daily-YYYY-MM-DD.md
```

The generated instructions tell the agent to write important long-term information into `memory/memory.md` and write task summaries into the daily note.

After the workspace is created, `agent-proxy init <role>` asks the daemon to spawn the role process and prints the managed PID.

Hire a named agent from the CLI:

```bash
agent-proxy hire engineer alice
```

This prints:

```text
engineer_alice 12345
```

Install and start the systemd service:

```bash
agent-proxy enable
agent-proxy enable --ip 0.0.0.0 --port 7011
agent-proxy restart
```

The command uses `sudo` internally for the privileged install and `systemctl` operations.
When the daemon comes up, it also creates or reuses `~/.agent_proxy/manager/` and keeps the `manager` agent running.

List available agents:

```bash
agent-proxy list
agent-proxy status
```

When the master is running, it also serves:

```text
http://0.0.0.0:7011
```

HTTP responses API:

```bash
curl -N http://127.0.0.1:7011/v1/responses \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"model":"engineer_alice","input":"hello","stream":true}'
```

`/v1/responses` follows the OpenAI Responses API shape for request and response payloads.
If `AGENT_PROXY_API_KEY` is configured for the service, API requests must send `Authorization: Bearer <key>`.

Open `http://127.0.0.1:7011/` in a browser for the streaming chat UI.

Hire a named agent:

```bash
curl -s http://127.0.0.1:7011/hire \
  -H 'Content-Type: application/json' \
  -d '{"role":"engineer","name":"alice"}'
```

This creates a workspace like:

```text
~/.agent_proxy/engineer_alice/
```

Queue a connection request for an agent, defaulting to the current directory:

```bash
agent-proxy connect researcher
agent-proxy connect researcher /home/li/project/collection-pip
```

If the agent becomes ready, `connect` returns its managed PID. If the daemon cannot make it ready, `connect` exits with `not ready`.
If the agent becomes ready, `connect` opens a command-line chatbot loop. If the daemon cannot make it ready, `connect` exits with `not ready`.

The optional `working_dir` argument is task context for the agent. Codex itself still runs from the agent workspace. On connect, the CLI first sends:

```text
Now let us work on working dir: <working_dir>
```

Queue a stop request for an agent:

```bash
agent-proxy stop researcher
```

## Notes

- `connect` targets a daemon-managed pseudo-terminal session. The daemon records the message `Now let us working on <working_dir>` and launches Codex from that directory inside the managed session.
- after a daemon restart, roles marked for autostart are spawned again by the master
- the daemon also ensures the default `manager` agent is running after startup or restart
- if an autostart role crashes, the master retries it after about 10 seconds instead of leaving it down permanently
- `stop` queues a stop request. The daemon terminates the tracked Codex process for that role if it still exists.
- `init` is daemon-managed. It returns a PID instead of entering an interactive shell.
