59 lines
3.2 KiB
Markdown
59 lines
3.2 KiB
Markdown
|
# In-Band Internal Messaging: Directives, Parsing, Exec Surface
|
|||
|
|
|
|||
|
|
> **Status: Final** — accepted by the owner on 2026-10-06
|
|||
|
|
> ("i accept the scope contract, mark it Final").
|
|||
|
|
|
|||
|
|
> **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.
|
|||
|
|
|
|||
|
|
## Background (researched facts, not decisions)
|
|||
|
|
|
|||
|
|
- Agents receive timer/job DMs wrapped by `bin/prompt_envelope.py` (`wrap()`),
|
|||
|
|
currently advertising `[TOOL swarm.spawn]`, `[TOOL cron.create]`,(tmux
|
|||
|
|
worker pointer, `[RESULT]` verdict rule.
|
|||
|
|
- Agents reply with in-band directives. `bin/response-harvester.py`
|
|||
|
|
`parse_tool_calls()` extracts `[TOOL op {json}]` / `[EXEC …]`, fenced
|
|||
|
|
```box|tool|exec blocks, and curl-to-/exec payloads; each call runs through
|
|||
|
|
the `exec-constrained` HTTPS daemon (`op` allowlist + per-op
|
|||
|
|
validate/build) and the result is posted back into the originating thread.
|
|||
|
|
- Implemented this session, uncommitted: balanced-brace JSON scanning (no
|
|||
|
|
more first-`]` truncation), `[DM {…}]` shorthand for `dm.send`, new
|
|||
|
|
`box.exec` (read-only box-ctl actions) and `tools.list` (dynamic op
|
|||
|
|
discovery) ops, native aliases (`dm`, `box`, `tools`, …), expanded
|
|||
|
|
envelope/tool-hint verb lists, `tests/test_tool_calls.py` (38 tests).
|
|||
|
|
- Related specs: `docs/DM_SPEC.md` (WO + logging layer), `docs/DM_SPEC.md`
|
|||
|
|
(control plane), `docs/JOB-SPEC.md` (scheduler/distributor),
|
|||
|
|
`CHAT_POLICY.md` (sidechat-first).
|
|||
|
|
|
|||
|
|
## Scope contract (accepted)
|
|||
|
|
|
|||
|
|
- Artifact boundary: this record covers directive syntax/parsing
|
|||
|
|
(`[TOOL]`/`[EXEC]`/`[DM]`, fenced blocks), the exec op surface
|
|||
|
|
(`box.exec`, `tools.list`, native aliases), and timer-message/envelope
|
|||
|
|
content. Out of scope: gateway/browser transport, swarm worker
|
|||
|
|
reliability and the failed-slot backlog, new `box` CLI verbs,
|
|||
|
|
`CHAT_POLICY.md` changes.
|
|||
|
|
- Done means: D1–D5 settled in writing below; owner explicitly accepts
|
|||
|
|
this record (Draft → Final). Nothing else is a completion dependency.
|
|||
|
|
- Deferred stages (each needs its own interview): swarm reliability
|
|||
|
|
target, `box` CLI inspection verbs for in-band traffic.
|
|||
|
|
|
|||
|
|
## Decisions
|
|||
|
|
|
|||
|
|
| # | Decision | Status |
|
|||
|
|
|---|----------|--------|
|
|||
|
|
| D1 | Scope boundary = A (directives + exec surface + envelope; transport, swarm reliability, new CLI verbs, chat policy out) | settled |
|
|||
|
|
| D2 | `box.exec` = read-only v1 (19 no-arg + 8 one-arg reads); side-effecting box actions stay out, dedicated ops cover writes | settled |
|
|||
|
|
| D3 | `[DM …]` = strict JSON-only; bare forms without a JSON object are silently ignored | settled |
|
|||
|
|
| D4 | Broken-JSON directives are skipped silently (no reply, no record) | settled |
|
|||
|
|
| D5 | `tools.list` returns every op with its `side_effecting` flag; enforcement stays in per-op validation + identity permissions | settled |
|
|||
|
|
|
|||
|
|
## Risks / validation (to fill as decisions settle)
|
|||
|
|
|
|||
|
|
- Full suite: 235–244 tests (count varies run to run), 3–4 failures, all
|
|||
|
|
in `test_approvals` / `test_copy_actions`, which import only
|
|||
|
|
`approvals` / `gravity` / `muse_tui` — none of this record's modules.
|
|||
|
|
Pre-existing/environmental, unrelated to the directive changes.
|
|||
|
|
Focused suites green (38 tool-call + 32 docs/prompts tests).
|