81 lines
4.0 KiB
Markdown
81 lines
4.0 KiB
Markdown
|
# Box Dev + Comms over HTTPS (No SSH)
|
|||
|
|
|
|||
|
|
> **Box is the main surface.** All operator work goes through Box (box.muse-dev.online). The web UI, `box` CLI, and agents share the same API endpoints. No UI-only powers.
|
|||
|
|
|
|||
|
|
**Date:** 2026-10-06
|
|||
|
|
**Status:** implemented on bl (`exec-constrained.py` + `box-ctl.py` + `box-relay.sh`)
|
|||
|
|
**Scope:** git visibility, test runs, notify, work-order acks. Read-only lookups
|
|||
|
|
live in `docs/BOX-API-READ-HTTPS.md`.
|
|||
|
|
|
|||
|
|
## 1. Why
|
|||
|
|
|
|||
|
|
Agents developing the box must inspect the tree, run the suite, nudge peers,
|
|||
|
|
and acknowledge work orders without SSH. All of this now rides the existing
|
|||
|
|
agent HTTPS path (`https://exec.muse-dev.online/exec`, signature or bearer
|
|||
|
|
auth, named-op allowlist, audit log) — no new trust model.
|
|||
|
|
|
|||
|
|
## 2. New ops
|
|||
|
|
|
|||
|
|
| Op | Args | Backend | Write? | Who |
|
|||
|
|
|---|---|---|---|---|
|
|||
|
|
| `git.status` | `{}` | `box-ctl.py git-status` | no | any valid signer |
|
|||
|
|
| `git.diff` | `{path?, stat?}` | `box-ctl.py git-diff [--stat] [--path p]` | no | any valid signer |
|
|||
|
|
| `git.log` | `{limit?, path?}` (1..50, default 10) | `box-ctl.py git-log` | no | any valid signer |
|
|||
|
|
| `tests.run` | `{test?, filter?}` (`tests.<module>` or full suite; `filter` is unittest `-k`) | `box-ctl.py tests-run [module] [--filter p]` | yes (executes) | known identities only |
|
|||
|
|
| `notify.send` | `{agent, message≤1000, sidechat?, sender?}` | `box-ctl.py notify ...` | yes (sends DM) | known identities only |
|
|||
|
|
| `dm.ack` | `{id, to, sender!, sidechat?, allow_main_chat?}` | `box-ctl.py ack ...` | yes (sends DM) | known identities only |
|
|||
|
|
|
|||
|
|
New `box-ctl.py` verbs: `git-status`, `git-diff`, `git-log`, `tests-run`,
|
|||
|
|
`ack` (all in `USAGE`, `quality-validate`, and — for the git reads —
|
|||
|
|
`IDEMPOTENT_ACTIONS`).
|
|||
|
|
|
|||
|
|
New `box-relay.sh` client commands:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
box git status
|
|||
|
|
box git diff [--stat] [--path <path>] # path also accepted positionally
|
|||
|
|
box git log [<limit=10>] [--path <path>]
|
|||
|
|
box tests run [tests.<module>] [--filter <pattern>] # full suite (~2-3 min) when omitted; filter is -k
|
|||
|
|
box notify <agent> [--sidechat <n>] [--sender <a>] <message...>
|
|||
|
|
box dm ack <id> --to <agent> --sender <agent> [--sidechat <name>]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Raw op call (signature auth, no token):
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
exec-sign.sh git.log '{"limit": 5, "path": "bin/dm.py"}'
|
|||
|
|
exec-sign.sh tests.run '{"test": "tests.test_box_dev_https"}'
|
|||
|
|
exec-sign.sh dm.ack '{"id": "bdf7beb6", "to": "pip", "sender": "opm"}'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 3. Safety notes (same posture as existing ops)
|
|||
|
|
|
|||
|
|
- **Fixed argv, validated values.** Clients influence only whitelisted argument
|
|||
|
|
values. Git paths must be repo-relative without `..` (plus symlink-escape
|
|||
|
|
check in box-ctl); test modules must match `^tests\.[a-z0-9_]+$` and exist;
|
|||
|
|
ack ids must be 6–64 hex; notify messages ≤1000 chars.
|
|||
|
|
- **Caps.** `git diff` output capped at 64KB, status at 200 entries, test
|
|||
|
|
output at 32KB tail; every capped response carries `truncated: true`.
|
|||
|
|
- **Sidechat-first.** `notify.send` and `dm.ack` default to the recipient's
|
|||
|
|
sidechat and never touch Main Chat unless `allow_main_chat` is set —
|
|||
|
|
mirroring `box-ctl.py notify` and the WO dispatcher.
|
|||
|
|
- **Attribution.** `sender` is caller-asserted (validated ∈ fleet agents),
|
|||
|
|
same as the existing `dm.send` op; the HTTPS identity is recorded
|
|||
|
|
separately in the exec audit log. `dm.ack` requires an explicit sender —
|
|||
|
|
no silent default.
|
|||
|
|
- **tests.run executes repo code** (whatever is in `tests/`), so it is
|
|||
|
|
`side_effecting`, excluded from the read-only default permission subset,
|
|||
|
|
and capped at a 600s timeout. Test failures report as
|
|||
|
|
`{"ok": false, "returncode", "output"}` — the op itself succeeded.
|
|||
|
|
- New `box-ctl.py` fail codes `GIT_ERROR` / `TESTS_ERROR` are registered in
|
|||
|
|
`KNOWN_ERROR_CODES`, so `quality-check` stays at its baseline.
|
|||
|
|
|
|||
|
|
## 4. Rollout notes
|
|||
|
|
|
|||
|
|
- Restart `exec-constrained.py` after deploy for the new ops to appear in
|
|||
|
|
`GET /ops`.
|
|||
|
|
- `box-relay.sh` is served from bl (`GET /box`); agents re-fetch to get
|
|||
|
|
`git` / `tests` / `notify` / `dm ack`.
|
|||
|
|
- Non-goals: git commit/push, service restarts for box itself, live
|
|||
|
|
streaming tails — future expansions, same pattern.
|