idagents-admin-control

Files (6)

• SKILL.md
• admin-session.js
• management-loop.sh
• remote-command.sh
• start-listener.js
• talk-to-manager.sh

SKILL.md (first lines)

# ID Agents Admin Control Skill

## Overview

This skill enables Claude Code to act as an **admin agent** for the ID Agents manager. It provides:

1. **Temporary listener** — Receives replies from the manager (like a regular agent)
2. **Chat with manager** — Send messages via daemon `/talk` into the manager inbox
3. **Remote commands** — Execute CLI commands via `POST /remote` on the manager daemon (`:4100`)

## When you want to ...

| Goal | Command | Notes |
|---|---|---|
| Add a new agent | `id-agents spawn <name> [model]`, or `POST /agents/spawn` | The database is the source of truth — editing YAML does NOT add an agent. `/agents rebuild` will not pick it up either. There is no `/agents spawn`. |
| Change a model | `/model <agent> <model>` | Surgical commands only. `/sync` is REMOVED: a config file may no longer overwrite the database. |
| Remove an agent | `/delete <agent>` | Hard-deletes the row and stops the process. |
| Restart agents (no config change) | `/agents rebuild` | restarts existing agents from DB |
| Start clean from YAML | `/deploy <team>` | nuke and recreate |
| Wipe working dirs too | `/agents reset` | destructive — confirms before running |
| Manager not responding on `:4100`, or CLI says "Manager did not start in time" | see "Restarting the manager" below | self-kill + auto-spawn-race are known modes |

Every `/remote` call should carry `X-Id-Team: <team>` (or set `ID_TEAM` env var). Without it, the manager uses its current default team, which is rarely what scripted callers want.

## Architecture

```
Claude Code (Admin)                  Manager Daemon (:4100)       Human at CLI (optional)
      │                                      │                            │
      │  1. POST /remote ───────────────────▶│                            │
      │     {command:"/ask ecs ..."}          │                            │
      │◀──── 202 {ok,result:{queryId}} ──────│                            │
      │                                      │                            │
      │  2. GET /query/:id?wait=30 ─────────▶│                            │
      │◀──── 200 {status:delivered,result} ──│                            │
      │                                      │                            │
      │  3. POST /talk (optional, human) ───▶│                            │
      │                                      │◀──── reads/replies in CLI ─│
      │◀──── POST /news (reply endpoint) ────│                            │
```

**One manager surface.** `/remote`, `/talk`, `/query/:id`, and `/news` all live on the manager daemon (`:4100`). The interactive CLI is a client of that daemon; it does not expose a manager HTTP surface of its own.

## Restarting the manager

The manager daemon is down whenever any of these happen:

- `curl http://127.0.0.1:4100/agents` refuses the connection.
- `id-agents` (the interactive CLI) prints `Manager did not start in time`. The CLI tries to auto-spawn the daemon, waits for `:4100`, and exits on failure; start it yourself and rerun the CLI.
- A previous `/agent rebuild` killed it. The port-kill logic occasionally catches the manager's own PID.

```bash
# Force-kill any stale CLI / daemon processes first
ps -ef | grep -E "interactive-agent|start-agent-manager" | grep -v grep | awk '{print $2}' | xargs -r kill -9
sleep 2
# Start daemon standalone (no CLI required for dispatch/polling)
cd /Users/nxt3d/projects/id2/id-agents && nohup node dist/start-agent-manager.js > /tmp/id-agents-daemon.log 2>&1 &
```

The standalone daemon reads the same SQLite state, rehydrates the team, and does not need the interactive CLI. Verify:

```bash
until curl -sS --max-time 2 http://127.0.0.1:4100/agents >/dev/null 2>&1; do sleep 2; done; echo "UP"
curl -sS http://127.0.0.1:4100/agents | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d['agents']),'agents')"
```

The full launcher (`npm run id-agents`) starts the daemon and opens the interactive CLI prompt — use it when a human is going to type at the prompt. For scripted or Claude-session work you only need the daemon.

## Ports

| Port | What lives there | Use for |
|------|------------------|---------|
| `4050` | Admin reply listener (optional) | **Callback target.** `start-listener.js` or `admin-session.js` can bind here to receive `/news` replies from the manager. |
| `4100` | Manager daemon | **Dispatch and polling.** `POST /remote`, `POST /talk`, `GET /query/:id` (supports `?wait=<sec>` long-poll), `GET /agents`, `POST /talk-to`, public-team admin. |

### IPv6 vs IPv4 gotcha (macOS especially)

On macOS, `localhost` frequently resolves to `::1` (IPv6) first. Our servers bind to `0.0.0.0` / `127.0.0.1` (IPv4), so a `curl localhost:4100` can **silently hit a different process** if some other dev tool (Vite, Next.js, etc.) happens to be listening on `[::1]:4100` in IPv6. Symptom: the JSON you get back has nothing to do with id-agents.

Always use `127.0.0.1` (not `localhost`) in every curl example, or pass `-4` to force IPv4. The snippets below follow this rule.

### Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `MANAGER_URL` | `http://127.0.0.1:4100` | Manager daemon base URL. All dispatch (`/remote`) and polling (`/query/:id`) go here. |
| `ID_TEAM` | *(unset)* | Optional team header (`X-Id-Team`) for daemon requests. Default team is used if unset. |
| `ADMIN_LISTENER_PORT` | `4050` | Local listener port when using the reply-listener scripts. |

## Usage

### Start Admin Session

```bash
node skills/idagents-admin-control/admin-session.js
```

Or use individual scripts:

### 1. Start Listener

```bash
node skills/idagents-admin-control/start-listener.js [port]
# Default port: 4050
```

### 2. Talk to the Manager (daemon-owned inbox)

`POST :4100/talk` writes to the manager inbox, which is persisted in the shared DB. The message lands regardless of whether a human is at the REPL. Any reader — the CLI REPL, this skill, a future dashboard — sees the same inbox via `GET :4100/news`. If a human is at the REPL, they can respond; replies come back to your listener at `ADMIN_LISTENER_PORT`.

```bash
./skills/idagents-admin-control/talk-to-manager.sh "What agents are running?" http://127.0.0.1:4050
```

### 3. Execute Remote Command

```bash
./skills/idagents-admin-control/remote-command.sh "/agents"
./skills/idagents-admin-control/remote-command.sh "/deploy idchain"

From idchain-world/id-agents, MIT.

More from idchain-world/id-agents