abox-live

Files (12)

• SKILL.md
• abox-live
• abox_inbox.py
• abox_live.py
• abox_parse.py
• abox_report.py
• abox_say.py
• abox_snapshot.py
• abox_stop.py
• abox_transcript.py
• abox_web.py
• claude-container-auth.sh

SKILL.md (first lines)

# abox-live — the single container-agent monitor (live sessions ↔ containers)

In-container `claude` (billed via the AMD gateway API key) writes its transcript to
`/root/.claude/projects/<proj>/<id>.jsonl`, bind-mounted to the host's
`~/.claude/projects/...`. So the host watches every container agent by reading those
JSONL files — no docker exec, no resume needed for monitoring.

**This is the one entry point.** It replaced the old standalone `abox` CLI, whose
reader engine (`ps`/`tail`/`watch`/`path`) now lives here (`abox_report.py`,
`abox_parse.py`). Two complementary views:

- **`ps`** — lists transcript **files**, so it includes **finished** sessions; but in
  the legacy shared dir it cannot attribute the container and prints `shared?`.
- **default (live)** — starts from running **processes**, so container attribution is
  **exact** even in the shared dir:

```
claude PID ──► /proc/PID/cgroup ──► docker id ──► container name   (always exact)
claude PID ──► /proc/PID/cwd    ──► project slug ──► session .jsonl (see evidence)
```

## Run

```bash
abox-live               # DEFAULT: LIVE table, my containers ↔ sessions (exact attribution)
abox-live <name>        # only live sessions in the container matching <name> (substring ok)
abox-live --all         # include other people's containers (akao_*, soga_*, …)
abox-live -v            # + each session's latest turn
abox-live --pid         # add the owning PID column
abox-live --group       # grouped-by-container view instead of the table
abox-live --json        # machine-readable (full session id + transcript path; has "mine")
# reader engine (absorbed from `abox`):
abox-live ps [min]      # ALL recent sessions incl. finished (transcript-file view; may show shared?)
abox-live tail <id> [n] # last n turns of a session (id prefix ok)
abox-live watch <id>    # live-follow a session (Ctrl-C to stop)
abox-live path <id>     # print the session's JSONL path
# act on a live session:
abox-live stop <id>     # stop a live session (prints the target; needs --yes to act)
abox-live say <id> "msg"  # send a follow-up to that session via `claude --resume`
abox-live instruct <id> "msg"  # queue instruction (then: abox-live drain --yes)
abox-live drain [--yes]   # execute queued instructions
abox-live inbox           # list instruction queue
abox-live web           # LOCAL web UI — human view + send instructions (POST /api/say)
# remote dashboard (phone / laptop Claude):
abox-live publish       # rebuild the stable HTML + print the Artifact params → then call the Artifact tool
abox-live snapshot -o F # self-contained HTML file for hand-off (SendUserFile), NOT published
```

## How to answer common asks

- **"list agents" / "what's running"** → `abox-live` (live, exact container). Add
  `abox-live ps` if the user wants finished sessions too.
- **"what is <session> doing" / "show me the aiter one"** → `abox-live tail <id> 8`
  (resolve the id from the table first).
- **"is anything stuck / waiting for input"** → `abox-live -v`; a session whose latest
  is a question or `[Request interrupted…]` and is idle is likely waiting; confirm with
  `tail`.

## Talking to a session (`abox-live say`)

Send a follow-up instruction to a specific agent and get its reply, by continuing the
conversation with `claude --resume <session> -p "<msg>"` run in the right place:

```bash
abox-live say fda052ce "往下繼續找 sglang 今天的重點"
abox-live say 5a699b21 "跳過 conc128，先把結果貼出來" --container jacky-…-inferencemax-0714
abox-live say fda052ce "…" --force        # resume even though a live process holds it
abox-live say fda052ce "…" --dangerous    # pass --dangerously-skip-permissions
```

How it routes and guards:
- **cwd** comes from the transcript's recorded `cwd` field (authoritative), not the
  dir-name slug.
- **Container sessions** resume via `docker exec` into the owning container, gated by
  the same bind-mount ownership check as `bridge.sh` (refuses other users' containers).
- **Host sessions** run as **root** with `HOME=/home/yichiche` — host transcripts are
  usually `root:root` (a container wrote them through the bind-mounted `~/.claude`), so
  running as `yichiche` gives "No conversation found". This was the one non-obvious bug
  in building it.
- **Refuses a session with a live process** unless `--force`: two `claude` processes
  appending to one transcript interleave and corrupt it. Stop it first, or `--force`.
- Default timeout 600s; the reply is printed. Long tasks may outlive it — then poll
  with `abox-live tail`.

This overlaps `bridge.sh exec`, but that starts a **fresh** headless agent; `say`
**continues an existing session** so the agent keeps all its context.

## Remote Control instruction flow (`instruct` / `drain`)

From your phone via **Command Center** (Remote Control), you cannot click buttons on
the published Artifact — but RC Claude **can run shell commands**. Two paths:

```bash
abox-live say fda052ce "繼續跑 benchmark"          # immediate (refuses if agent is live)
abox-live instruct fda052ce "繼續跑 benchmark"     # queue for later
abox-live drain --yes                              # execute all pending queued items
abox-live inbox                                    # show queue
```

**Typical RC loop from phone:**
1. Open Command Center Remote Control session
2. Ask: 「列出 container agent 狀態」→ RC runs `abox-live`
3. Ask: 「叫 session fda052ce 繼續」→ RC runs `abox-live instruct fda052ce "…"` then `abox-live drain --yes`
4. Or paste the **instruction panel** from the published dashboard (copy-select blocks)

The published dashboard (`abox-live publish`) shows:
- **Human view** — your instructions + agent replies; internal tool work folded under `⋯ internal steps` (`<details>`)
- **Instruction panel** per live session — copy-paste `say` / `instruct` commands + natural-language RC prompt
- **Inbox section** at top — pending queued instructions awaiting `drain`

## Stopping a session

```bash
abox-live stop 259baf41         # shows container / cwd / pid / last line, kills nothing
abox-live stop 259baf41 --yes   # SIGTERM
abox-live stop 259baf41 --yes --force   # SIGKILL if it ignores SIGTERM
```

It **refuses** when the row's evidence is `ambiguous` or `none` — the pid could belong

From yichiche/agent-box, MIT.

More from yichiche/agent-box