61 lines
3.2 KiB
Markdown
61 lines
3.2 KiB
Markdown
---
|
|
name: inbox
|
|
description: Durable agent-to-agent coordination through a bundled inbox CLI. Use when an agent needs to fetch work, claim a thread, report progress, ask blocked questions, wait for replies, inspect thread history, or return done/fail results through a SQLite-backed inbox instead of ad hoc chat.
|
|
---
|
|
|
|
# Inbox
|
|
|
|
Use the bundled `./assets/inbox` CLI to communicate through a durable SQLite-backed inbox.
|
|
|
|
## Quick Start
|
|
|
|
- Invoke `./assets/inbox` relative to this skill directory.
|
|
- Pass `--db` explicitly for every command.
|
|
- Prefer `--json` whenever another agent or script will read the output.
|
|
- Run `init` before first use on a new database path.
|
|
|
|
## Rules
|
|
|
|
- Treat `fetch` as discovery only; only `claim` grants ownership.
|
|
- Do not start work without a valid lease.
|
|
- Use `update --status in_progress` for progress and `update --status blocked` for precise questions.
|
|
- Prefer `wait-reply` over manual sleep loops when blocked.
|
|
- Use `done` for terminal success and `fail` for terminal failure.
|
|
- Keep scheduling and dependency decisions out of this layer; those belong to `orch`.
|
|
|
|
## Typical Commands
|
|
|
|
```bash
|
|
./assets/inbox --db ./coord.db --json init
|
|
./assets/inbox --db ./coord.db --json fetch --agent backend-worker --status pending
|
|
./assets/inbox --db ./coord.db --json claim --agent backend-worker --thread thr_123 --lease-seconds 900
|
|
./assets/inbox --db ./coord.db --json update --agent backend-worker --thread thr_123 --status in_progress --summary "Implementing post CRUD routes"
|
|
./assets/inbox --db ./coord.db --json update --agent backend-worker --thread thr_123 --status blocked --summary "Need auth decision" --payload-json '{"question":"Should admin auth use email/password in MVP?"}'
|
|
./assets/inbox --db ./coord.db --json wait-reply --agent backend-worker --thread thr_123 --after-event 51 --timeout-seconds 1800
|
|
./assets/inbox --db ./coord.db --json reply --from leader --to backend-worker --thread thr_123 --summary "Use email/password for MVP" --body "Use a simple credential flow for the first iteration."
|
|
./assets/inbox --db ./coord.db --json done --agent backend-worker --thread thr_123 --summary "Post CRUD implemented" --body-file result.md
|
|
```
|
|
|
|
## Command Map
|
|
|
|
- `init`: initialize schema and pragmas on a database path
|
|
- `send`: create a new thread or append a message
|
|
- `fetch`: list candidate threads for an agent without claiming them
|
|
- `claim`: acquire a lease on a thread
|
|
- `renew`: extend an active lease
|
|
- `update`: send progress or blocked updates
|
|
- `reply`: send an answer, control message, or follow-up inside a thread
|
|
- `done`: mark a thread complete with final result data
|
|
- `fail`: mark a thread failed with failure details
|
|
- `cancel`: cancel a thread
|
|
- `list`: list threads by filters
|
|
- `show`: inspect thread state and message history
|
|
- `watch`: block until matching thread activity arrives
|
|
- `wait-reply`: block until a reply arrives for a specific thread
|
|
|
|
## Notes
|
|
|
|
- `body-file` and artifact-heavy flows are supported; prefer them over long inline strings when sending reports or patches.
|
|
- `fetch --unread` and `show --mark-read` depend on per-agent read cursors.
|
|
- If the bundled binary cannot execute on the current host, stop and report the compatibility issue instead of guessing a replacement path or workflow.
|