diff --git a/CHANGELOG.md b/CHANGELOG.md index a06257f..02914ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +- **OpenCode wake documentation matches the shipped adapters (T697).** README and portability guidance describe standalone `resume: true` wakes, one shared service per machine for long-lived agents, and standalone/service-hosted recovery after MCP eviction (T659/T688). + ## 0.5.47 (2026-10-16) - **Service-hosted OpenCode sessions stay wakeable after MCP eviction (T688).** OpenCode stops an idle session's MCP about hourly, which releases its lease. T659 kept standalone sessions wakeable through their plugin's poll; a session hosted by the shared `opencode serve --service` is now a wake target too while that service process (same pid and birth) lives, and the wake posts to the service with `resume: true` and a verified receipt. A lease held by another session of the agent still blocks it. docs/OPENCODE.md recommends plain `opencode` (one service per machine, every project) for long-lived agents. diff --git a/README.md b/README.md index afff988..26cab88 100644 --- a/README.md +++ b/README.md @@ -148,13 +148,20 @@ AgentMBX gives every agent the same small set of mailbox tools. It delivers mess | CLI | Wake path | Status | |---|---|---| | Codex | `codex app-server` experimental `thread/queue/add`, `thread/queue/list`, and `thread/queue/delete`; AgentMBX tracks its owned notice and withdraws it after read/ack, release, or handover while still queued, preserving unowned items | requires a Codex build with the experimental queue API; historical live receipts | - | OpenCode | service-hosted session: the local service's session API (`/synthetic`). `--standalone` session: the plugin inside that session's own serve, over a loopback queue (see [OPENCODE.md](docs/OPENCODE.md)) | historical service-path live receipts; standalone wakes are admitted in-process, whether one starts a turn on an idle session is unproven (T544) | + | OpenCode | service-hosted session: the local service's session API (`/synthetic`, `resume: true`). `--standalone` session: its own plugin/loopback queue, also `resume: true` (T544; see [OPENCODE.md](docs/OPENCODE.md)) | recorded service-path live receipts and an idle standalone turn (T544); admission alone does not prove model execution | | Claude Code | pushed by the session's own mbx MCP server through Claude Code's per-session inbox socket (`CLAUDE_CODE_MESSAGING_SOCKET`), so a plainly started `claude` wakes on mail with no flag, setting or cron; `agentmbx claude [args]` adds the research-preview mbx channel instead | historical macOS/Fedora live receipts | | Kimi | desktop app: its local control socket (setup installs an AgentMBX plugin into the app). `kimi web`: the local server's prompts API. Terminal: a background `agentmbx watch` task the session keeps running (Kimi starts a turn when it exits) | historical terminal/desktop/web live receipts | | Hermes | one background `agentmbx watch` task with completion notification; shell hooks bind the session and add inbox context before model calls | watcher requires re-arming after each wake; shared gateway hosts aren't covered | | Grok | a background `agentmbx watch --cli grok --session ` task; exact session hooks | watcher requires re-arming after each wake | | anything else | desktop notification | no automatic model turn implied | + For long-lived OpenCode agents, run plain `opencode` against the shared service, started once with + `opencode service start`: one service per machine, with each session keeping its own project folder. + After OpenCode evicts an idle session's MCP, standalone wakes remain available while that serve's plugin + polls the local daemon (T659); service-hosted wakes remain available while the recorded service process + is alive (T688). Both paths require the recorded PID and process birth, and a lease held by a different + session blocks the old binding. See [the run-mode and eviction guide](docs/OPENCODE.md#after-opencode-evicts-the-sessions-mcp). + - **Across machines:** a small daemon per host. Hosts pair with one command each: `agentmbx pair` prints a one-time token, `agentmbx join ` on the other machine finishes it (or compare a 6-digit code instead). Hosts find each other on the LAN over mDNS. Every hop is signed. Messages to a sleeping machine wait in an outbox and retry for 72 h, and each is stored exactly once. - **Wake batching:** one atomic 30-second window per agent, plus explicit wake mute. Status messages never wake anyone. The published runtime has no hourly per-thread or daily per-agent hard cap; loop detection is observational, so batching alone doesn't bound an automated conversation's token use. - **Full-text search** (SQLite FTS5) and an audit log. `mbx:@` references can be cited from tickets and notes. diff --git a/docs/PORTABILITY.md b/docs/PORTABILITY.md index 057abe1..f7319e8 100644 --- a/docs/PORTABILITY.md +++ b/docs/PORTABILITY.md @@ -43,13 +43,20 @@ detection/wiring remains a separate boundary. An arbitrary MCP client can wire |---|---|---|---| | Claude Code | MCP; SessionStart, UserPromptSubmit, PermissionRequest, Stop, PostToolUse, SessionEnd | Its own MCP server sends a no-body hint through the per-session messaging socket; optional `agentmbx claude` channel launcher | Socket/channel support and exact-session binding; historical macOS/Linux receipts aren't proof of every current frontend | | Codex | MCP; SessionStart, UserPromptSubmit, PermissionRequest, Stop | `codex app-server` experimental `thread/queue/add`, `thread/queue/list`, and `thread/queue/delete`; tracks owned notices and withdraws them after read/ack, release, or handover while still queued; unowned items are preserved | Requires a Codex build with the experimental queue API and hooks. Consumed notices cannot be recalled. Startup, same-thread resume, and new-thread isolation are separate live gates | -| OpenCode | MCP; plugin session-created, post-tool, and idle hooks; sidebar plugin | Service sessions use their API; standalone sessions use their own plugin/loopback queue | Standalone in-process admission doesn't prove an idle model turn. Shared-service permission coverage doesn't establish standalone coverage | +| OpenCode | MCP; plugin session-created, post-tool, and idle hooks; sidebar plugin | Service sessions use their API; standalone sessions use their own plugin/loopback queue. Both daemon wake paths use `resume: true` (T544) | An idle standalone turn was observed with T544; a receipt alone still doesn't prove model execution. Shared-service permission coverage doesn't establish standalone coverage | | Kimi terminal | MCP, skill, SessionStart/UserPromptSubmit/PermissionRequest/Stop hooks | One background `agentmbx watch` task exits with a hint and starts the next turn | Re-arm the watcher after handling mail. `MBX_SELF_WATCH` opts into a periodic self-check. Terminal permission hooks can't approve prompts | | Kimi web/rc/desktop | MCP and hosted-session hooks; one-time conversation bind ticket | Web prompts API or desktop control socket | Restart a hosted server started before setup; verify the current exact conversation. Approval API coverage applies to hosted sessions | | Hermes terminal/TUI | MCP; `on_session_start` and `pre_llm_call` shell hooks with exact hook approvals | Background `agentmbx watch` task with completion notifications | Re-arm after each wake. Hooks load at session start; a shared gateway/desktop host isn't covered. No Hermes permission-approval adapter is claimed | | Grok | MCP, status line, SessionStart/UserPromptSubmit/PostToolUse/Stop hooks | Background `agentmbx watch --cli grok --session ` | Re-arm each completion; verify exact session ID and provider background-task notification | | Other MCP clients | Manual MCP configuration | Desktop notification fallback | No automatic model turn or permission adapter implied | +For long-lived OpenCode agents, prefer plain `opencode` against the shared service, started once with +`opencode service start`: one service per machine, not per project. After MCP eviction, standalone +bindings remain wakeable while their plugin polls the local daemon (T659); service-hosted bindings +remain wakeable while their recorded service process lives (T688). Both paths verify the recorded PID +and process birth, and refuse an old binding when a different session holds the mailbox lease. +See [OpenCode run modes and eviction recovery](OPENCODE.md#after-opencode-evicts-the-sessions-mcp). + Setup preserves other tools' hook groups, backs up files before editing, and uninstall removes AgentMBX-owned entries. Modified/foreign configuration can require manual review. See [the wake reference](SPEC.md#waking-recipients).